跳到主要内容
Ed. notes

Python 工程:uv、src layout 与质量门

长文 · 2026-11-11 · 合集第 3 / 11 篇

  • Python
  • uv
  • 工程化
第 3 / 11 篇 · 查看全部章节 → 当前:Python 工程:uv、src layout 与质量门

结论

把 backend/ 当成独立的 npm 项目看:pyproject.toml 是 package.json 加工具配置,uv.lock 是锁文件,uv run 保证命令在项目虚拟环境里执行。src layout 解决的是导入不确定:import backend 必须指向安装后的包,而不是当前目录里碰巧同名的文件夹。

问题与设计

Python 项目常见的三个不确定性:

  1. 系统里有多个 Python,python app.py 用哪个取决于 PATH。
  2. 依赖装到全局环境,换机器就不可复现。
  3. 从不同目录运行,import 可能命中不同文件。

uv + pyproject.toml + src layout 分别对应解释器、依赖和导入路径。环境安装只需要:

cd backend
uv sync

uv.lock 提交,.venv/ 不提交。之后所有命令统一用 uv run ...。

关键代码

pyproject.toml 里最重要的是三块:

[project]
name = "ednotes-backend"
requires-python = ">=3.12"
dependencies = [
  "fastapi>=0.115",
  "uvicorn[standard]>=0.30",
  "psycopg[binary]>=3.2",
  "pgvector>=0.3",
  "markdown-it-py>=3.0",
  "python-frontmatter>=1.1",
  "langchain-core>=0.3",
  "langchain-openai>=0.3",
  "langgraph>=0.2",
]

[dependency-groups]
dev = ["pytest>=8.0", "httpx>=0.27", "ruff>=0.6"]

[tool.hatch.build.targets.wheel]
packages = ["src/backend"]

最后一行决定了包根是 src/backend,所以目录必须是:

backend/
  pyproject.toml
  uv.lock
  src/backend/
    __init__.py
    app.py
    config.py
    agent/
  tests/

uv sync 以 editable 方式安装这个包。开发时改 src/backend 立即生效,但导入路径始终经过安装后的包,不依赖当前工作目录。

质量门也只保留必要项:

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

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B"]

[tool.pytest.ini_options]
markers = [
  "integration: 需要 PostgreSQL 的集成测试",
  "live: 需要真实模型服务的冒烟测试,默认跳过",
]

E/F 查错误与未使用名字,I 排 import,UP 用现代语法,B 查常见坑。测试 marker 让本地默认只跑无外部依赖的用例。

验证

uv run python -c "import sys; print(sys.executable)"
uv run python -c "import backend; print(backend.__file__)"
uv run ruff check .
<backend>/.venv/bin/python
backend/src/backend/__init__.py
All checks passed!

如果第二行打印的是仓库根下另一个 backend/,说明 src layout 没生效,或者用了系统 Python。

边界

  • requires-python = ">=3.12" 是下限,不是精确锁;CI 与本地最好一致。
  • ruff check 只检查不格式化;当前没有把 ruff format 纳入质量门。
  • pytest marker 只是分类,不会自动隔离外部依赖;集成测试仍要求显式提供测试库地址。

下一篇看配置:怎样让缺失的环境变量在进程启动时失败,而不是等第一个请求。