python 格式化利器

工具

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

工具	作用	是否必须
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  # 检查所有文件