ruff-linting

ruff 检查

掌握如何使用 ruff check，将其作为一款速度极快、规则支持全面且可自动修复问题的 Python 检查工具。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用针对性更强的同类技能……
运行 ruff check、选择规则集或自动修复检查问题	运行 ruff format 以规范代码风格——请使用 ruff-formatting
在 pyproject.toml 中配置 [tool.ruff.lint] 规则和按文件忽略项	从技术栈层面比较 ruff、类型检查器和格式化工具——请使用 python-code-quality
将 ruff 接入编辑器、pre-commit、CI/CD、Docker 或构建系统	请参阅下方 CI/CD 集成 中的快速配置；完整的编辑器/CI/Docker/迁移配置示例见 REFERENCE.md
从 Flake8/pylint/isort/pyupgrade 迁移到 ruff 的组合规则集	运行 ruff format 以规范代码风格——请使用 ruff-formatting

核心优势

ruff 的优势

• 速度极快（比 Flake8 快 10-100 倍）
• 使用 Rust 编写，性能出色
• 可取代多个工具（Flake8、pylint、isort、pyupgrade 等）
• 许多规则支持自动修复
• 兼容现有配置
• 内置规则超过 800 条

基本用法

简单检查

# Lint current directory
ruff check

# Lint specific files or directories
ruff check path/to/file.py
ruff check src/ tests/

# IMPORTANT: Pass directory as parameter to stay in repo root
# ✅ Good
ruff check services/orchestrator

# ❌ Bad
cd services/orchestrator && ruff check

自动修复

# Show what would be fixed (diff preview)
ruff check --diff

# Apply safe automatic fixes
ruff check --fix

# Fix specific files
ruff check --fix src/main.py

# Fix with preview (see changes before applying)
ruff check --diff services/orchestrator
ruff check --fix services/orchestrator

输出格式

# Default output
ruff check

# Show statistics
ruff check --statistics

# JSON output for tooling
ruff check --output-format json

# GitHub Actions annotations
ruff check --output-format github

# GitLab Code Quality report
ruff check --output-format gitlab

# Concise output
ruff check --output-format concise

规则选择

常见规则代码

代码	说明	规则示例
E	pycodestyle 错误	E501（行过长）
F	Pyflakes	F401（未使用的导入）
W	pycodestyle 警告	W605（无效转义）
B	flake8-bugbear	B006（可变默认值）
I	isort	I001（导入未排序）
UP	pyupgrade	UP006（已弃用的类型）
SIM	flake8-simplify	SIM102（嵌套 if）
D	pydocstyle	D100（缺少文档字符串）
N	pep8-naming	N806（变量命名）
S	flake8-bandit（安全）	S101（使用 assert）
C4	flake8-comprehensions	C400（不必要的生成器）

选择规则

# Select specific rules at runtime
ruff check --select E,F,B,I

# Extend default selection
ruff check --extend-select UP,SIM

# Ignore specific rules
ruff check --ignore E501,E402

# Show which rules would apply
ruff rule --all

# Explain a specific rule
ruff rule F401

查询规则

# List all available rules
ruff rule --all

# Search for rules by pattern
ruff rule --all | grep "import"

# Get detailed rule explanation
ruff rule F401
# Output: unused-import (F401)
#   Derived from the Pyflakes linter.
#   Checks for unused imports.

# List all linters
ruff linter

# JSON output for automation
ruff rule F401 --output-format json

配置

pyproject.toml

[tool.ruff]
# Line length limit (same as Black)
line-length = 88

# Target Python version
target-version = "py311"

# Exclude directories
exclude = [
    ".git",
    ".venv",
    "__pycache__",
    "build",
    "dist",
]

[tool.ruff.lint]
# Enable specific rule sets
select = [
    "E",   # pycodestyle errors
    "F",   # Pyflakes
    "B",   # flake8-bugbear
    "I",   # isort
    "UP",  # pyupgrade
    "SIM", # flake8-simplify
]

# Disable specific rules
ignore = [
    "E501",  # Line too long (handled by formatter)
    "B008",  # Function calls in argument defaults
]

# Allow automatic fixes
fixable = ["ALL"]
unfixable = ["B"]  # Don't auto-fix bugbear rules

# Per-file ignores
[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401", "E402"]
"tests/**/*.py" = ["S101"]  # Allow assert in tests

ruff.toml（独立配置）

# Same options as pyproject.toml but without [tool.ruff] prefix
line-length = 100
target-version = "py39"

[lint]
select = ["E", "F", "B"]
ignore = ["E501"]

[lint.isort]
known-first-party = ["myapp"]
force-single-line = true

高级用法

按文件覆盖配置、针对性检查规则，以及仅检查已更改文件／并行调用模式，见 references/command-recipes.md。

CI/CD 集成

快速配置——在 GitHub Actions 中运行检查并添加 PR 注释：

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v3
        with:
          args: 'check --output-format github'

快速配置——pre-commit 钩子：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.0
    hooks:
      - id: ruff-check
        args: [--fix]
      - id: ruff-format

完整的集成配置示例包括编辑器设置（VS Code、Neovim、Zed、Helix）、高级 pre-commit 配置、GitLab/CircleCI/Jenkins、Make/Just/Task/tox、Docker、LSP 服务设置，以及 Flake8/Black/pylint 迁移指南，详见 REFERENCE.md。

常见模式

用于查找特定问题、逐步采用和辅助重构的配置示例见 references/command-recipes.md。

插件配置

各插件的 [tool.ruff.lint.<plugin>] 设置（isort、flake8-quotes、pydocstyle、 pylint）见 references/plugin-configuration.md。

最佳实践

何时使用 ruff check

• 强制执行代码质量要求
• 提交前验证
• CI/CD 流水线
• 辅助重构
• 安全扫描
• 整理导入语句

关键：目录参数

• ✅ 始终将目录作为参数传入：ruff check services/orchestrator
• ❌ 切勿使用 cd：cd services/orchestrator && ruff check
• 原因：支持并行执行、输出更清晰、兼容工具

规则选择策略

1. 从最小集合开始：select = ["E", "F"]（错误 + pyflakes）
2. 添加 bugbear：select = ["E", "F", "B"]
3. 添加导入规则：select = ["E", "F", "B", "I"]
4. 添加 pyupgrade：select = ["E", "F", "B", "I", "UP"]
5. 考虑安全规则：select = ["E", "F", "B", "I", "UP", "S"]

可自动修复与不可自动修复

• 将不确定的规则标记为 unfixable，以便人工审查
• 常见的不可自动修复规则：B（bugbear）、F（pyflakes F401）
• 让 ruff 修复安全的规则：I（isort）、UP（pyupgrade）

应避免的常见错误

• 使用 cd，而不是传入目录参数
• 立即启用所有规则（应逐步采用）
• 在使用 --fix 前不使用 --diff
• 忽略规则说明（ruff rule <code>）
• 未针对特殊情况配置按文件忽略规则

快速参考

必备命令

# Basic operations
ruff check                          # Lint current directory
ruff check path/to/dir              # Lint specific directory
ruff check --diff                   # Show fix preview
ruff check --fix                    # Apply fixes

# Rule management
ruff rule --all                     # List all rules
ruff rule F401                      # Explain rule F401
ruff linter                         # List all linters

# Output formats
ruff check --statistics             # Show violation counts
ruff check --output-format json     # JSON output
ruff check --output-format github   # GitHub Actions format

# Selection
ruff check --select E,F,B          # Select rules
ruff check --ignore E501           # Ignore rules
ruff check --extend-select UP      # Extend selection

配置层级

1. 命令行参数（优先级最高）
2. 当前目录中的 ruff.toml
3. 当前目录中的 pyproject.toml
4. 父目录配置（递归查找）
5. 用户配置：~/.config/ruff/ruff.toml

常见规则组合

# Minimal safety
ruff check --select E,F

# Good default
ruff check --select E,F,B,I

# Comprehensive
ruff check --select E,F,B,I,UP,SIM

# Security-focused
ruff check --select E,F,B,S

# Docstring enforcement
ruff check --select D --config '[lint.pydocstyle]\nconvention = "google"'

这使 ruff check 成为快速、全面地检查 Python 代码的首选工具。