Python 工程:uv、src layout 与质量门
结论
把 backend/ 当成独立的 npm 项目看:pyproject.toml 是 package.json 加工具配置,uv.lock 是锁文件,uv run 保证命令在项目虚拟环境里执行。src layout 解决的是导入不确定:import backend 必须指向安装后的包,而不是当前目录里碰巧同名的文件夹。
问题与设计
Python 项目常见的三个不确定性:
- 系统里有多个 Python,
python app.py用哪个取决于 PATH。 - 依赖装到全局环境,换机器就不可复现。
- 从不同目录运行,
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 只是分类,不会自动隔离外部依赖;集成测试仍要求显式提供测试库地址。
下一篇看配置:怎样让缺失的环境变量在进程启动时失败,而不是等第一个请求。