Python 工程指南

现代 Python 开发不仅仅是编写代码，更是构建可复现、可维护且高性能的系统。本指南重点介绍现代的 Astral (uv/Ruff) 技术栈。

现代技术栈 (2024+)

我们推荐使用统一的工具链，以减少“工具蔓延”并最大限度地提高性能。

类别	工具	理由
包管理器	uv	比 pip/poetry 快 10-100 倍；统一的虚拟环境和 Python 版本管理器。
Linter/格式化	Ruff	用单一的 Rust 编写工具替换 Flake8、Black、isort 和 Bandit。
类型检查器	MyPy	静态类型分析的行业标准。
测试	pytest	功能丰富、模块化的测试框架。
配置	pyproject.toml	项目元数据和工具配置的单一事实来源。

---

项目结构

标准化的布局确保团队成员和工具可以轻松导航代码库。

project-name/
├── pyproject.toml      # 配置（项目的核心）
├── uv.lock             # 确定性锁文件（务必提交！）
├── .python-version     # 指定 Python 版本（如 3.12）
├── src/                # 源代码（使用 src-layout）
│   └── my_package/
│       ├── __init__.py
│       └── main.py
├── tests/              # 测试套件
│   ├── conftest.py
│   └── test_main.py
└── .github/            # CI/CD 工作流
    └── workflows/ci.yml

---

使用 uv 管理依赖

uv 是 pip、pip-tools 和 poetry 的现代替代品。

核心工作流

# 初始化新项目
uv init --lib

# 添加依赖
uv add requests fastapi
uv add --dev pytest ruff mypy

# 根据锁文件同步环境
uv sync

锁文件 (Lockfiles)

始终提交 uv.lock。它确保每位开发者和 CI 运行器都使用完全相同的依赖版本（包括间接依赖）。

---

代码质量 (Ruff & MyPy)

Ruff 配置

Ruff 用单一、极快的工具替代了 Flake8、isort、Black 和 Bandit。在 pyproject.toml 中整合所有规则：

[tool.ruff]
line-length = 88
target-version = "py312"

[tool.ruff.lint]
select = [
    "E", "F", "W",   # 默认 flake8
    "I",             # isort (导入排序)
    "UP",            # pyupgrade
    "S",             # bandit (安全)
    "B",             # bugbear
]

# 导入相关配置
[tool.ruff.lint.isort]
known-first-party = ["my_package"]
force-sort-within-sections = true  # 在导入组内排序
combine-as-imports = true           # 合并：from x import a; from x import b -> from x import a, b
lines-after-imports = 2             # PEP 8 标准

导入规则

"I" 规则启用自动导入排序（替代 isort）：

• 分组：标准库 → 第三方 → 本地
• 组内按字母顺序排序
• 检测未使用的导入（F401）
• 标记 from module import *（F403）

类型检查

使用 MyPy 在进入生产环境前捕获逻辑错误：

uv run mypy src/

---

持续集成 (GitHub Actions)

自动化你的质量门槛。使用 setup-uv 的典型 ci.yml：

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - name: 安装与检查
        run: |
          uv sync
          uv run ruff check .
          uv run mypy src/
          uv run pytest

---

代码组织

Python 导入系统

理解 Python 的导入机制对于构建可扩展应用程序至关重要。核心概念包括：

• 绝对导入 vs 相对导入：清晰使用绝对导入，包内使用相对导入
• __init__.py：控制包级 API 和初始化
• 避免循环导入：使用 TYPE_CHECKING 或重构依赖
• 导入性能：考虑对重型依赖使用延迟导入

# ✅ 推荐：绝对导入
from my_package.utils import load_config
from my_package.core import Engine

# ✅ 可接受：显式相对导入
from .utils import load_config
from ..core import Engine

提示

配置 Ruff 自动执行 PEP 8 导入排序并检测循环依赖。

---

工程资源

• 📄 Python 导入系统 — 导入、模块和最佳实践综合指南。
• 📄 uv 完整指南 — 深入了解包管理。
• 📄 pyproject.toml 指南 — 详尽的配置参考。
• 📄 工具介绍 — 生态系统对比。
• 📄 基础架构设置 — 部署 Python 应用。