工具

✅ 一站式推荐方案（轻量 + 快速）

工具	作用	是否必须
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-commitrev: v0.3.3hooks:- id: ruff- id: ruff-format- repo: https://github.com/pre-commit/mirrors-mypyrev: v1.8.0hooks:- id: mypy- repo: https://github.com/PyCQA/banditrev: 1.7.4hooks:- id: bandit

✅ 安装并激活

pre-commit install

🧰 步骤五（可选）：CI 自动检查（GitHub Actions）

# .github/workflows/code-quality.yml
name: Code Qualityon: [push, pull_request]jobs:lint:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v3- name: Setup Pythonuses: actions/setup-python@v4with:python-version: '3.11'- name: Install depsrun: |pip install ruff mypy bandit- name: Ruff Checkrun: ruff check .- name: Mypy Checkrun: mypy app/- name: Bandit Checkrun: 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  # 检查所有文件