---
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 操作