客户仓库从 Black 换到 Ruff,不必提上千行的 PR
Astral 称 Ruff 对 Black 格式代码兼容度超 99.9%,diff 小到客户团队能真正审完。
要点速览
- 在已用 Black 格式化的仓库上,Ruff 格式化器按改动行数计兼容度超过 99.9%,速度比 Black 快 30 倍以上。
- 默认情况下,ruff check 不修复任何问题。修复需要加 --fix,不安全的修复还要另外用 --unsafe-fixes 开启。
- 用 --add-noqa 和 per-file-ignores 暂缓处理旧债,再在后续提交中把格式化提交的哈希写进 .git-blame-ignore-revs,让 git blame 依然有用。
到客户那里的第一周,你打开对方的 Python 仓库,一下子看到三样东西:一个 Flake8 配置文件、一个 isort 钩子,还有 CI 里一行 Black,没人说得清它是否还在运行。你想清理一下,但一个改动几千行的“统一代码风格”PR,足以让客户团队一上来就对你起疑。
Ruff 适合这种场景,因为它的格式化器本就是作为 Black 的替代品设计的,在已用 Black 格式化的代码上,输出几乎完全一致。
Astral 的 Charlie Marsh 表示,在这类项目上,按改动行数计算,Ruff 的兼容度超过 99.9%。换句话说,工具换了,代码几乎不用动。
对前线部署工程师(FDE)来说,这一点比速度更重要。几十行的 PR,客户能读完再批准;几千行的 PR,客户只能选择信任或拒绝。
一个二进制文件替代一堆工具
Ruff 是用 Rust 编写的代码检查与格式化工具,采用 MIT 许可证发布,由打造 uv 和 ty 的 Astral 团队开发。官方文档称,Ruff 可以替代 Flake8 及其数十个插件,以及 Black、isort、pydocstyle、pyupgrade、autoflake 等工具。
同一份文档称,Ruff 比现有的代码检查和格式化工具快 10 到 100 倍,并内置缓存,未改动的文件不会重新分析。单看格式化器,Astral 报告的速度是 Black 的 30 倍以上。
在客户仓库里,这样的速度让你可以和对方团队坐在一起,当场检查整个代码库,不必等 CI。不过更大的好处是,仓库最终只有一个地方放配置,不再是每个工具一个文件。
先测量,再做四个小提交
设想一个内部仓库:legacy/ 目录没人敢碰,services/ 目录还在活跃开发。稳妥的做法是先测量再动手,然后把工作拆成四个提交,每个只做一件事。
测量不产生提交。ruff check . 只列出违规项,不做任何修复,因为只有传入 --fix 参数时 Ruff 才会修复。输出结果就是一张技术债地图,可以直接带到和客户的会上。
第一个提交加入 Ruff 配置,并标记已有技术债,而不是去修。ruff check . --add-noqa 会在每一行当前违规的代码上插入 noqa 注释。从此只有新代码会被拦下。需要长期豁免的目录,在 pyproject.toml 中用 per-file-ignores:
[tool.ruff.lint.per-file-ignores]
"legacy/*" = ["E501"]
第二个提交是 ruff format,单独提交,不夹带其他改动。这个提交存在之后才有它的哈希,所以第三个提交是后续提交:添加一个 .git-blame-ignore-revs 文件,写入这个哈希,让 GitHub 的 blame 视图跳过格式化提交。
这样,任何人查看历史时,看到的仍是每行代码的作者,而不是运行格式化工具的人。
最后一个提交是 ruff check --fix。默认情况下,Ruff 只应用被归为安全的修复。可能改变代码行为的修复还需要加上 --unsafe-fixes。在客户仓库里,这个参数只留给小型、逐个审查的 PR。
什么时候 diff 仍会暴涨?
99.9% 以上这个数字,只适用于已用 Black 格式化的代码。Ruff 文档明确说明,格式化器在少数地方有意与 Black 不同,比如代码块开头的空行、f-string 和单元素元组。如果客户仓库从没用过 Black,第一次格式化可能产生相当大的 diff。
所以要先问客户的是“CI 真的在跑 Black 吗?”,而不是“你们用什么代码检查工具?”。如果在跑,可以预期 diff 很小;如果没有,就提前告知对方可能会有一个很大的格式化提交,这也正是需要 .git-blame-ignore-revs 的原因。
monorepo 的配置陷阱
Ruff 通过分层配置支持 monorepo,配置可写在 pyproject.toml、ruff.toml 或 .ruff.toml 中。有一个细节很容易让你白白耗掉一个下午:对每个文件,Ruff 使用目录树中离它最近的配置文件,不会跨文件合并设置。
假设 services/billing/ 有自己的 ruff.toml,只为了改行宽。那么你在根目录 pyproject.toml 中设置的所有规则,对这个目录都不再生效。在下结论说“Ruff 漏报了”之前,先确认这个文件实际用的是哪份配置。
先学什么
先学“测量 + 四个提交”这套流程,再去学规则清单。客户仓库里的风险在于推行过程,而不在于选了哪些规则。之后读一读列出 Ruff 与 Black 差异的那一页,客户问某一行为什么变了,答案就在那里。
写在简历上,“将一个 Python 仓库从 Flake8、isort 和 Black 迁移到 Ruff,格式化 diff 控制在 X 行以内,且未破坏 git blame”这样一行,远比简单写“精通 Ruff”有分量。
快的工具能帮你省几分钟。一个客户能读懂的小 PR,才能赢得他们的信任。
这篇文章对你有帮助吗?
感谢你的反馈!