工具
✅ 一站式推荐方案（轻量 + 快速）
| 工具 | 作用 | 是否必须 |
|---|---|---|
| ruff | 格式化 + lint + isort 一体化 | ✅ 必须 |
| mypy | 静态类型检查，适配 SQLAlchemy 2.0 | ✅ 推荐 |
| pytest + pytest-cov | 测试 + 覆盖率 | ✅ 推荐 |
| bandit | 安全审查 | 可选 |
| pre-commit | 本地提交前自动检查 | ✅ 强烈推荐 |
相关步骤
🧰 步骤一：用 uv 安装依赖
uv pip install -U ruff mypy pytest pytest-cov bandit pre-commit
🧼 步骤二：使用 Ruff 进行格式化 + Lint（核心）
✅ 创建 pyproject.toml 配置文件（Ruff + Mypy 一起放）
# pyproject.toml
[tool.ruff]
line-length = 100
extend-select = ["I"] # 自动 import 排序（isort）
fix = true # 自动修复
[tool.mypy]
plugins = ["sqlalchemy.ext.mypy.plugin"]
ignore_missing_imports = true
strict_optional = true
disallow_untyped_defs = true
check_untyped_defs = true
warn_unused_ignores = true
✅ 执行 Ruff 格式化和检查：
# 格式化（相当于 black + isort）
ruff format .
# 检查代码规范（相当于 flake8）
ruff check .
🧪 步骤三：类型检查（尤其适配 SQLAlchemy 2.0）
mypy app/ # 假设你的代码放在 app/ 目录
🧹 步骤四：配置 pre-commit（自动检查）
# .pre-commit-config.yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.3.3
hooks:
- id: ruff
- id: ruff-format
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.8.0
hooks:
- id: mypy
- repo: https://github.com/PyCQA/bandit
rev: 1.7.4
hooks:
- id: bandit
✅ 安装并激活
pre-commit install
🧰 步骤五（可选）：CI 自动检查（GitHub Actions）
# .github/workflows/code-quality.yml
name: Code Quality
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install deps
run: |
pip install ruff mypy bandit
- name: Ruff Check
run: ruff check .
- name: Mypy Check
run: mypy app/
- name: Bandit Check
run: bandit -r app/
| 任务 | 命令 |
|---|---|
| 格式化代码 | ruff format . |
| 检查代码规范 | ruff check . |
| 类型检查 | mypy app/ |
| 安全检查 | bandit -r app/ |
| 启用 git 提交检查 | pre-commit install |
| 一键清洗 | pre-commit run –all-files |
Makefile 模板
✅ 推荐 Makefile 模板（FastAPI + SQLAlchemy + Ruff + Mypy 专用）
# Makefile for FastAPI code style and quality
# 格式化代码（ruff format）
format:
ruff format .
# Lint 检查（ruff check）
lint:
ruff check .
# 类型检查（mypy）
typecheck:
mypy app/
# 安全检查（bandit）
security:
bandit -r app/
# 一键检查所有内容（格式、风格、类型）
check: format lint typecheck
# 运行测试（可选）
test:
pytest -v --cov=app tests/
# 一键执行所有质量控制
all: check test
✅ 你现在可以使用的命令：
| 命令 | 说明 |
|---|---|
| make format | 自动格式化所有代码 |
| make lint | 使用 ruff 检查代码规范 |
| make typecheck | 用 mypy 做类型检查 |
| make security | 用 bandit 做安全扫描 |
| make check | 格式化 + Lint + 类型检查 一键执行 |
| make test | 运行测试（可选） |
| make all | 执行所有检查 + 测试 ✅ |
✅ 回答：只要你有 Makefile 文件，并且系统上安装了 make 命令，就可以直接用：
使用make 命令
✅ 为什么要先 format，再 lint？
| 顺序 | 原因 |
|---|---|
| ✅ 先 ruff format | 自动修复空格、缩进、import 顺序等格式问题 |
| ✅ 再 ruff check | 才能看到真正“逻辑/语法层面”的 lint 问题 |
| ❌ 如果先 check，再 format | 会先报一堆格式错误，format 后再跑 check 没意义（重复跑） |
安装钩子
pre-commit install # 安装 Git 钩子
pre-commit run --all-files # 检查所有文件
