261 lines
6.4 KiB
Markdown
261 lines
6.4 KiB
Markdown
---
|
||
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` 必填字段模板
|
||
|
||
```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` 中配置：
|
||
|
||
```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（静态类型检查）
|
||
|
||
```toml
|
||
[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（依赖审计）
|
||
|
||
```toml
|
||
[tool.deptry]
|
||
ignore_notebooks = true
|
||
```
|
||
|
||
- 检测未使用、缺失、重复的依赖。
|
||
- **运行方式**：`uv run deptry .`
|
||
|
||
---
|
||
|
||
## 4. 测试规范
|
||
|
||
### 4.1 Pytest 配置
|
||
|
||
```toml
|
||
[tool.pytest.ini_options]
|
||
testpaths = ["tests"]
|
||
pythonpath = ["."]
|
||
```
|
||
|
||
### 4.2 测试要求
|
||
|
||
- 测试文件命名：`test_*.py`，放在 `tests/` 目录。
|
||
- 测试函数/类命名：以 `test_` 或 `Test` 开头。
|
||
- 使用 `pytest.fixture` 管理测试资源。
|
||
- 必须使用 `pytest-cov` 生成覆盖率报告。
|
||
- **运行方式**：
|
||
```bash
|
||
uv run python -m pytest --cov --cov-config=pyproject.toml --cov-report=term-missing
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Pre-commit Hooks
|
||
|
||
`.pre-commit-config.yaml` 必须包含：
|
||
|
||
```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）
|
||
|
||
```makefile
|
||
.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. 开发工作流
|
||
|
||
新项目初始化顺序：
|
||
|
||
1. 创建 `pyproject.toml`，声明项目元数据和依赖。
|
||
2. 运行 `uv sync` 创建虚拟环境。
|
||
3. 创建 `.pre-commit-config.yaml`，运行 `uv run pre-commit install`。
|
||
4. 创建 `src/` 目录和入口文件。
|
||
5. 创建 `tests/` 目录和基础测试。
|
||
6. 创建 `Makefile` + `tasks.py`。
|
||
7. 运行 `make check` 或 `python tasks.py check` 验证代码质量。
|
||
8. 运行 `make test` 或 `python tasks.py test` 验证测试通过。
|
||
|
||
日常开发顺序：
|
||
|
||
1. `uv run ruff check --fix .` — 先修复 lint 问题。
|
||
2. `uv run ruff format .` — 格式化代码。
|
||
3. `uv run mypy src/` — 类型检查。
|
||
4. `uv run python -m pytest` — 运行测试。
|
||
5. 提交前 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 操作 |