Ruff 是什么
Ruff 是用 Rust 实现的 Python 检查与格式化工具：它把 flake8、isort、pyupgrade 等工具的常用规则聚合进一个二进制，并提供格式化能力，因此启动与执行速度明显快于纯 Python 实现的多工具链。落地时通常的策略是先选一个规则子集，再按收益逐步扩大。
基本信息
| 能力 | 检查（lint）与格式化 |
|---|---|
| 规则前缀 | E/W 风格与告警、F 逻辑问题、I 导入排序、B 缺陷模式、UP 现代化、S 安全检查等 |
| 配置位置 | pyproject.toml 的 [tool.ruff] 段 |
| 迁移方式 | 可替代 flake8、isort 与部分 pyupgrade 场景 |
常用命令
常用命令
ruff check . # 检查当前项目
ruff check --fix . # 自动修复可修复项
ruff format . # 格式化（风格与 Black 高度接近）
ruff check --select E,F,B . # 临时只启用某个规则子集落地要点
- 先启用基础子集（如 E、F），再按收益逐步扩展规则集合。
- 历史代码先用忽略清单放行，新代码纳入检查，避免一次改动过大。
- 与 Black 同时使用时明确分工：只让一个工具负责格式化。
- 把规则选择与忽略写进配置文件并注释原因，方便后来人复查。
规则子集与收益
| 子集 | 主要覆盖 | 启用建议 |
|---|---|---|
| E、W | 风格与告警 | 起步即启用，噪声可控 |
| F | 未使用导入、未定义名称 | 起步即启用，收益直接 |
| I | 导入排序与分组 | 替代 isort，先全库跑一次 |
| B | 常见缺陷模式 | 对旧代码噪声较大，分目录推进 |
| UP | 语法现代化 | 适合持续小步清理 |
自动修复后仍要人工看一遍：可修复项往往涉及导入移除与写法替换，需要确认没有改变语义。
把检查接入 CI 或提交钩子：靠人记得手动执行，规则早晚会失效。
迁移中的常见问题
- 与旧工具并存导致重复报告：先确认旧工具已在配置与 CI 中停用。
- 格式化结果与原格式差异较大：把重新格式化单独提交，避免与逻辑改动混在一起。
- 编辑器插件版本与项目依赖不一致：以项目依赖版本为准，避免两边结论不同。
- 检查范围没有排除生成代码：报错集中在自动生成的文件上，掩盖真实问题。