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 應用。