6.4 KiB
6.4 KiB
last_reviewed
| last_reviewed |
|---|
| 2026-06-09 |
工程实践指南
创建或修改任何 Python 项目时，必须严格遵守以下工程规范。
1. 包管理与虚拟环境
- 唯一包管理器：使用
uv，不使用pip、pipenv、poetry。 - 依赖声明：所有依赖统一在
pyproject.toml中管理，遵循 PEP 621 + PEP 735。[project].dependencies仅放运行时依赖。[dependency-groups].dev放开发依赖（测试、lint、类型检查等）。
- 版本锁定：使用
uv.lock锁定依赖版本，提交到版本控制。 - 安装命令：
uv sync创建虚拟环境并安装所有依赖。 - 运行命令：所有 Python 命令通过
uv run前缀执行，确保使用项目虚拟环境。 - 禁止：全局安装 Python 包、手动
python -m venv、使用requirements.txt作为主要依赖文件。
pyproject.toml 必填字段模板
[project]
name = "<project-name>"
version = "0.1.0"
description = "<项目描述>"
requires-python = ">=3.12"
dependencies = [
# 运行时依赖
]
[dependency-groups]
dev = [
"pytest>=8.0",
"pytest-cov>=5.0",
"ruff>=0.9",
"mypy>=1.14",
"deptry>=0.22",
"pre-commit>=4.0",
]
2. 目录结构
<project-root>/
├── pyproject.toml # 项目配置（依赖 + 工具配置）
├── uv.lock # 依赖锁定文件
├── .pre-commit-config.yaml # 提交前检查配置
├── Makefile # Unix 任务脚本
├── tasks.py # Windows/跨平台任务脚本
├── .cursorignore # IDE 忽略配置
├── src/ # 源代码目录
│ └── main.py
├── tests/ # 测试目录
│ └── test_main.py
└── logs/ # 运行时产物（不提交）
- 源码统一放在
src/下，不直接在根目录放业务代码。 - 测试统一放在
tests/下。 - 运行时产物（日志、缓存、临时文件）不提交到版本控制。
3. 代码质量工具链
3.1 Ruff（Lint + Format）
在 pyproject.toml 中配置：
[tool.ruff]
target-version = "py312"
line-length = 120
[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "B"]
ignore = ["E501"]
- 规则覆盖：格式错误(E/F/W)、导入排序(I)、命名规范(N)、语法升级(UP)、常见 Bug(B)。
- 格式化：使用
ruff format替代 Black。 - 运行方式：
uv run ruff check .— 检查问题uv run ruff check --fix .— 自动修复uv run ruff format .— 格式化代码uv run ruff format --check .— 仅检查格式
3.2 MyPy（静态类型检查）
[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
warn_unused_configs = true
ignore_missing_imports = true
[[tool.mypy.overrides]]
module = "tests.*"
ignore_errors = true
- 启用严格模式，测试文件豁免。
- 运行方式：
uv run mypy src/main.py
3.3 Deptry（依赖审计）
[tool.deptry]
ignore_notebooks = true
- 检测未使用、缺失、重复的依赖。
- 运行方式：
uv run deptry .
4. 测试规范
4.1 Pytest 配置
[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["."]
4.2 测试要求
- 测试文件命名：
test_*.py，放在tests/目录。 - 测试函数/类命名：以
test_或Test开头。 - 使用
pytest.fixture管理测试资源。 - 必须使用
pytest-cov生成覆盖率报告。 - 运行方式：
uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing
5. Pre-commit Hooks
.pre-commit-config.yaml 必须包含：
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.9.6
hooks:
- id: ruff
args: [--fix]
- id: ruff-format
- 安装：
uv run pre-commit install - 手动运行：
uv run pre-commit run --all-files
6. 任务运行器
6.1 Makefile（Unix）
.PHONY: install check test run clean
install:
@uv sync
@uv run pre-commit install
check:
@uv lock --locked
@uv run ruff check .
@uv run ruff format --check .
@uv run mypy src/main.py
@uv run deptry .
test:
@uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing
run:
@uv run python src/main.py
clean:
@rm -rf .venv __pycache__ .pytest_cache .mypy_cache .ruff_cache
6.2 tasks.py（跨平台）
提供 tasks.py 作为 Windows 兼容的任务运行器，支持相同任务名：install、check、test、run、clean。
7. 版本控制忽略
.cursorignore / .gitignore 必须排除：
.venv/
__pycache__/
.pytest_cache/
.mypy_cache/
.ruff_cache/
*.pyc
logs/
8. 开发工作流
新项目初始化顺序：
- 创建
pyproject.toml，声明项目元数据和依赖。 - 运行
uv sync创建虚拟环境。 - 创建
.pre-commit-config.yaml，运行uv run pre-commit install。 - 创建
src/目录和入口文件。 - 创建
tests/目录和基础测试。 - 创建
Makefile+tasks.py。 - 运行
make check或python tasks.py check验证代码质量。 - 运行
make test或python tasks.py test验证测试通过。
日常开发顺序：
uv run ruff check --fix .— 先修复 lint 问题。uv run ruff format .— 格式化代码。uv run mypy src/— 类型检查。uv run python -m pytest— 运行测试。- 提交前 pre-commit 会自动执行检查和格式化。
9. 编码风格
- Python 3.12+ 语法，使用现代特性（如
match/case、类型合并X | Y）。 - 函数和模块必须有 docstring。
- 优先使用类型注解，返回值类型必须标注。
- 行长度限制 120 字符。
- 导入按标准库 → 第三方 → 本地模块分组排序。
- 偏好函数式编程风格，避免不必要的面向对象封装。
- 配置与代码分离，使用常量或配置模块管理可变参数。
10. 强制检查清单
在提交代码或声明任务完成前，必须确认：
uv lock --locked通过（锁定文件与 pyproject.toml 一致）uv run ruff check .无错误uv run ruff format --check .无差异uv run mypy src/无类型错误uv run deptry .无依赖问题uv run python -m pytest --cov全部通过且覆盖率合理- 所有命令使用
uv run前缀，无全局 pip 操作