Python 现代工程实践工具选择依赖管理 uv / uv.lock 构建配置 pyproject.toml 环境变量

工具选择


依赖管理	`uv` / `uv.lock`
构建配置	`pyproject.toml`
环境变量	`Pydantic Settings`
代码检查	`Ruff`

工具安装

安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh

初始化项目

uv init my_app 
cd my_app

或者在已有项目里执行：

uv init

修改 pyproject.toml 的配置

Python 版本

requires-python = ">=3.11"

添加依赖

dependencies = [  
    "requests>=2.31.0",  
    "numpy",  
]

添加/删除依赖还可以通过命令行（也会同步更新 pyproject.toml）

uv add requests numpy pandas
uv remove requests

让修改生效

uv sync

选择什么样的第三方库版本

[!TIP] 要写 >= 或者更智能的范围符号而非 ==，每次你执行 uv sync 甚至重新安装时，工具都能在不破坏你代码的前提下，默默帮你升级到最安全的补丁版本。

更推荐的写法：波浪号 ~= 或者脱字符 ^。例如 requests = "^2.31.0"，它的意思是： “大于等于 2.31.0，但必须小于 3.0.0”（允许安全和特性更新，但拒绝破坏性的大版本更新）。

最小工程结构

my_agent_system/
├── app/
│   ├── __init__.py
│   ├── core/
│   │   ├── __init__.py
│   │   └── config.py        # 环境变量，用 BaseSettings 代替 constants.py
│   └── main.py
├── .env                     # 绝密文件：存真实的 API Key（绝对不能进 Git！）
├── .env.example             # 模板文件：告诉同事需要配哪些变量（提交到 Git）
├── .gitignore               # 门神：必须在这里面写上 .env
├── pyproject.toml           # 工程依赖和配置
└── uv.lock

.env

铁律：这个文件永远、永远、永远不能被 git commit 提交到代码仓库！

# .env 文件内容示例
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxx"
MAX_RETRIES=5

.gitignore

为了防止你手滑把 .env 传上去，你必须在根目录的 .gitignore 文件里加上一行：

# .gitignore 文件内容
.env
.venv/
__pycache__/****

.env.example

既然 .env 不能传给别人，那新同事拉取代码后，怎么知道项目需要配哪些环境变量才能跑起来呢？这就是 .env.example 的作用。它是一个空模板，必须提交到 Git。

# .env.example 文件内容示例
DATABASE_URL=""
OPENAI_API_KEY="在这里填入你的 API Key"
MAX_RETRIES=3

app/core/config.py

# app/core/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    # 如果没配这俩，项目启动瞬间直接报错崩溃，防止带着残缺的配置运行！
    DATABASE_URL: str
    OPENAI_API_KEY: str 
    
    # 带有默认值，如果在 .env 里配了，就会被覆盖。而且自动把字符串转成 int！
    MAX_RETRIES: int = 3 

    class Config:
        # 告诉 Pydantic 去哪里找配置
        env_file = ".env" 

# 全局实例化一次
settings = Settings()

最小 `pyproject.toml` 模板

[project]
name = "project name"
version = "0.1.0"
description = "my project description"
readme = "README.md"
requires-python = ">=3.11" # 锁定最低 Python 版本

dependencies = [
	# --- 1. 核心基建底座 ---
    "pydantic>=2.6.0",          # 数据校验
    "pydantic-settings>=2.2.0", # 环境变量
    "httpx>=0.27.0",            # 网络请求
    "loguru>=0.7.0",            # 日志系统
    
    # --- 2. Web 服务基座 ---
    "fastapi>=0.110.0",
    "granian>=0.9.0",           # (或 uvicorn) Rust 驱动的极速 Web 服务器
    "sse-starlette>=2.0.0",     # 让 FastAPI 支持大模型打字机流式输出
    "python-multipart>=0.0.9",  # 允许 Agent 接收用户上传的 PDF/图片
    #...
    
    # --- 3. AI Agent ---
    "langgraph>=0.0.30",
    "langchain-core>=0.1.30",   # 提供标准的消息结构 (HumanMessage等)
    "langsmith>=0.1.0",         # Agent 思考链路的调试透视镜
	#...
]

[dependency-groups]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.3.0",
]

Python 现代工程实践