FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

工具

客户仓库从 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 依然有用。
横向的提交历史示意图。第一步用 ruff check . 测量,不做修复,也不产生提交。之后是四个提交:1 是 --add-noqa,只拦截新代码;2 是 ruff format,只运行一次,以橙色突出;3 添加 .git-blame-ignore-revs,在 blame 中隐藏格式化提交;4 是 ruff check --fix,只应用安全修复。
在客户仓库中引入 Ruff 的做法:先测量,再把工作拆成四个小提交。格式化提交单独存在,diff 便于审查,之后在 git blame 中隐藏。来源:Ruff 官方文档,见正文引用。

到客户那里的第一周,你打开对方的 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,才能赢得他们的信任。

这篇文章对你有帮助吗?

7 个信源
路线图上的下一篇 · 阶段 1: 基础认知打开客户几 GB 的 CSV,笔记本不再卡死pandas 先把数据全部读进内存再处理;Polars 的 scan_csv 先规划查询,只读需要的列和行。