Ruff 指南：Rust 打造的超快 Python Linter
Ruff 是用 Rust 写的 Python 代码检查与格式化工具，整合常用 lint 规则与格式化流程。本文讲解安装配置、规则集选择、格式化器用法与 pre-commit 集成。
直接回答：Ruff 是 Rust 编写的 Python linter 与 formatter：整合多种来源的规则（包括部分 Flake8/Pylint/isort/pyupgrade 规则），并提供面向 Black 风格的格式化器；它不替代类型检查与测试。
为什么是 Ruff
Python 代码质量工具链曾经需要四五个工具拼装：Flake8 检查、isort 排导入、Black 格式化、pyupgrade 升级语法。Ruff 用 Rust 把它们重写为一个二进制：减少多个工具的安装与配置成本。执行耗时取决于项目规模、启用规则、缓存及运行环境，本文没有进行性能对照测试。
快速上手
pip install ruff # 或 pipx install ruff / uv tool install ruff
ruff check . # 检查
ruff check . --fix # 自动修复能修的
ruff format . # 格式化（Black 兼容）
--fix 只修复启用且可修复的规则；默认不应用 unsafe fixes。导入排序需启用 I 规则，修改后仍应审查差异并运行测试。
配置
# pyproject.toml
[tool.ruff]
line-length = 120
target-version = "py312"
[tool.ruff.lint]
select = [
"E", "W", # pycodestyle
"F", # pyflakes
"I", # isort
"UP", # pyupgrade
"B", # flake8-bugbear
"SIM", # flake8-simplify
]
ignore = ["E501"] # 行宽交给 formatter 管
select 的艺术：从核心集（E/F/I/UP/B）起步，团队适应后按需加；一次全开几千条告警只会被集体无视。
格式化器
ruff format 以 Black 风格兼容为目标，但存在已记录的格式差异：
ruff format --check . # CI 里只检查不修改
ruff format --diff . # 看会改什么
Black 用户应先用 --check/--diff 检查差异、核对配置和 lint 冲突，再统一格式化器与版本。
pre-commit 集成
# .pre-commit-config.yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.16.9 # 官方集成文档示例版本；项目升级时需审查差异
hooks:
- id: ruff-check
args: [--fix]
- id: ruff-format
提交即检查、能修则修——本地 hook 可被跳过，因此还需 CI 执行同样的检查。编辑器再配 Ruff 插件（VS Code/PyCharm 都有），保存时自动 fix + format，在日常编辑时及早发现可检查的问题。
Ruff 的生态位
Ruff 接管了"检查 + 修复 + 格式化"，但它不做深度类型检查——那仍是 Mypy/Pyright/Pyrefly 的地盘。一种可选工具组合是：Ruff（风格与错误）+ Mypy/Pyrefly（类型）+ pytest（测试），三件套各司其职。
常见问题（FAQ）
Q：Ruff 能完全替代 Pylint 吗？
A：不能按固定覆盖率判断可替换性，应逐项核对团队启用的 Pylint 规则。Pylint 少数深度检查（循环依赖、设计指标）Ruff 没有，依赖这些的团队可保留 Pylint 做补充。
Q：老项目接入的正确姿势？
A：先 ruff check --fix + ruff format 一次性大清扫（单独一个 PR），然后 pre-commit 锁住增量。大清扫 PR 要和功能 PR 分开，否则 review 地狱。
Q：和 Black 冲突吗？
A：不冲突，是替代关系。ruff format 设计目标就是 Black 兼容；两个 formatter 别混用（互相打架）。
官方参考
本文基于官方文档整理，未进行运行时或性能测试。示例中的业务函数、数据模型和部署地址需结合项目补全；局部片段不等同于完整生产应用。
