《Python 项目配置的终极方案：config.py + pyproject.toml 深度解读》

《Python 项目配置的终极方案config.py pyproject.toml 深度解读》引言前两篇文章解决了容器部署和开发自动化的问题。但应用内部是如何读取这些环境变量的依赖库又是如何管理的本文深入到 Python 代码层面解析两个核心文件app/core/config.py配置总控中心智能加载.env文件并解析为 Python 对象。pyproject.toml项目身份证明统一管理依赖和代码规范。读完本文你将彻底理解从“环境变量”到“Python 代码”的完整数据流。一、config.py配置总控中心1.1 环境识别器get_environment()pythonclass Environment(str, Enum): DEVELOPMENT development STAGING staging PRODUCTION production TEST test def get_environment() - Environment: match os.getenv(APP_ENV, development).lower(): case production | prod: return Environment.PRODUCTION case staging | stage: return Environment.STAGING case test: return Environment.TEST case _: return Environment.DEVELOPMENT读取APP_ENV环境变量支持模糊匹配prod和production都能识别。返回标准化的枚举类型供后续逻辑判断使用。1.2 智能文件加载器load_env_file()pythondef load_env_file(): env get_environment() env_files [ os.path.join(base_dir, f.env.{env.value}.local), # 最高优先级 os.path.join(base_dir, f.env.{env.value}), # 环境专属 os.path.join(base_dir, .env.local), # 通用本地覆盖 os.path.join(base_dir, .env), # 兜底 ] for env_file in env_files: if os.path.isfile(env_file): load_dotenv(dotenv_pathenv_file) return env_file return None ENV_FILE load_env_file() # 模块加载时立即执行优先级链.env.development.local.env.development.env.local.env.local文件通常被.gitignore忽略允许开发者在本地覆盖团队配置而不影响他人。该函数在模块导入时立即执行确保Settings类实例化前环境变量已被注入。1.3 辅助解析器parse_list_from_env()pythondef parse_list_from_env(env_key, defaultNone): value os.getenv(env_key) if not value: return default or [] value value.strip(\) if , not in value: return [value] return [item.strip() for item in value.split(,) if item.strip()]作用将环境变量中的http://a.com,http://b.com解析为 Python 列表[http://a.com, http://b.com]。使用场景CORS 跨域白名单ALLOWED_ORIGINS。1.4 Settings 类 —— 配置映射中心pythonclass Settings: def __init__(self): self.ENVIRONMENT get_environment() # 应用配置 self.PROJECT_NAME os.getenv(PROJECT_NAME, FastAPI LangGraph Template) self.DEBUG os.getenv(DEBUG, false).lower() in (true, 1, t, yes) # 数据库配置 self.POSTGRES_HOST os.getenv(POSTGRES_HOST, localhost) self.POSTGRES_PORT int(os.getenv(POSTGRES_PORT, 5432)) self.POSTGRES_DB os.getenv(POSTGRES_DB, food_order_db) # 应用环境专属覆盖 self.apply_environment_settings()类型转换bool、int、float、Path自动转换。默认值兜底如果环境变量未设置使用代码中的硬编码默认值如数据库默认localhost。apply_environment_settings()根据ENVIRONMENT自动设置DEBUG、LOG_LEVEL等。1.5 环境专属覆盖的防覆盖设计pythondef apply_environment_settings(self): env_settings { Environment.DEVELOPMENT: {DEBUG: True, LOG_LEVEL: DEBUG}, Environment.PRODUCTION: {DEBUG: False, LOG_LEVEL: WARNING}, } for key, value in env_settings.get(self.ENVIRONMENT, {}).items(): env_var_name key.upper() if env_var_name not in os.environ: # 关键判断 setattr(self, key, value)核心哲学只有当系统环境变量没有显式设置该值时才会覆盖。这意味着Docker 传入的变量或 Shell 手动导出的变量拥有最高优先级。二、config.py 与所有配置文件的关系数据来源如何进入 config.py优先级系统环境变量export POSTGRES_HOST1.2.3.4os.getenv()直接读取最高Docker Composeenv_file注入容器启动时注入os.environ高set_env.shsource 加载的.envShell 导出后Python 继承中load_env_file()加载的.env文件load_dotenv()写入os.environ低代码中的硬编码默认值os.getenv(KEY, default)最低兜底实战推演本地执行make devPOSTGRES_HOST的值来自.env.development中的db若想临时连接其他数据库可直接POSTGRES_HOST192.168.1.100 make dev此时系统环境变量优先级最高覆盖文件配置。三、pyproject.toml项目身份与依赖管理3.1 项目元数据与核心依赖[project]toml[project] name langgraph-fastapi-template version 0.1.0 requires-python 3.13 dependencies [ fastapi0.121.0, langchain1.0.5, langgraph1.0.2, psycopg[binary]3.3.2, python-dotenv1.1.0, uvicorn0.34.0, # ... 共 30 个库 ]身份信息项目名称、版本、最低 Python 版本。核心依赖所有运行时必需的库。config.py中的from dotenv import load_dotenv就来源于此处的python-dotenv。3.2 可选依赖与分组toml[project.optional-dependencies] dev [black, isort, flake8, ruff] cache [redis7.4.0, valkey[libvalkey]6.1.0] [dependency-groups] dev [detect-secrets, pre-commit, pyright] test [httpx, pytest]开发依赖ruff、pyright与生产依赖分离。cache组包含valkey对应config.py中的VALKEY_HOST配置缓存模块可插拔。3.3 工具统一配置[tool.*]toml[tool.ruff] line-length 119 exclude [migrations, venv] [tool.ruff.lint] select [E, F, B, ERA, D] ignore [E501, D203] [tool.pyright] typeCheckingMode standard reportDuplicateImport errorRuff行长度 119启用 Google 风格 Docstring 检查。Pyright标准严格模式reportDuplicateImport视为错误。统一配置所有代码检查工具Ruff、Black、Pyright、Pytest的配置都集中在此根目录不再有.flake8、.isort.cfg等零散文件。3.4 与 Dockerfile 的关系dockerfileCOPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-install-projectDockerfile 直接复制pyproject.tomluv sync读取dependencies列表安装依赖。如果pyproject.toml缺少psycopg容器中的程序就连接不上数据库。3.5 与 Makefile 的关系makefilelint: uv run ruff check . typecheck: uv run pyrightMakefile 调用uv run执行工具而具体检查规则如行长度 119、忽略哪些错误全部来源于pyproject.toml中的[tool.ruff]配置。四、完整配置流转闭环text┌─────────────────────────────────────────────────────────────────┐ │ 1. 开发者克隆项目 │ │ ↓ │ │ 2. 执行 source set_env.sh development │ │ → 自动从 .env.example 复制为 .env.development │ │ → 填入真实 OPENAI_API_KEY、POSTGRES_PASSWORD │ │ ↓ │ │ 3. 执行 make dev │ │ → Makefile 调用 run_with_envsource set_env.sh │ │ → set_env.sh 导出所有变量到 Shell │ │ → 启动 uvicornPython 进程继承环境变量 │ │ ↓ │ │ 4. config.py 模块加载 │ │ → load_env_file() 优先加载 .env.development.local │ │ → 若不存在加载 .env.development │ │ → Settings 类读取 os.getenv()类型转换 │ │ → apply_environment_settings() 根据环境补全默认值 │ │ ↓ │ │ 5. 业务代码使用 settings.POSTGRES_HOST │ └─────────────────────────────────────────────────────────────────┘五、总结config.py是应用层的“终点站”无论配置来自.env文件、Docker 注入还是 Shell 导出都在这里被统一为 Python 对象。pyproject.toml是项目的“物料清单”定义了所有依赖库和代码规范被Dockerfile和Makefile共同引用。整个配置体系遵循12-Factor App原则配置与代码严格分离改变配置无需重新构建镜像。至此我们从容器部署第一篇→开发自动化第二篇→应用配置第三篇完整覆盖了一个生产级 FastAPI LangGraph 项目的所有配置维度。希望这个系列能帮助你搭建出优雅、高效、可维护的后端项目。