python-configuration

Python 配置管理

使用环境变量和类型化设置将配置从代码中外部化。管理良好的配置使同一份代码无需修改即可在任何环境中运行。

何时使用本技能

• 为新项目搭建配置系统
• 从硬编码值迁移到环境变量
• 使用 pydantic-settings 实现类型化配置
• 管理密钥和敏感值
• 创建特定于环境的设置（dev/staging/prod）
• 在应用启动时验证配置

核心概念

1. 外部化配置

所有特定于环境的值（URL、密钥、功能开关）都来自环境变量，而非代码。

2. 类型化设置

在启动时将配置解析并验证为类型化对象，而不是散落在代码各处。

3. 快速失败

在应用启动时验证所有必需的配置。缺失配置应立即崩溃并给出清晰的错误信息。

4. 合理的默认值

为本地开发提供合理的默认值，同时要求敏感设置必须显式提供值。

快速开始

from pydantic_settings import BaseSettings
from pydantic import Field

class Settings(BaseSettings):
    database_url: str = Field(alias="DATABASE_URL")
    api_key: str = Field(alias="API_KEY")
    debug: bool = Field(default=False, alias="DEBUG")

settings = Settings()  # Loads from environment

基本模式

模式 1：使用 Pydantic 的类型化设置

创建一个集中的设置类，用于加载并验证所有配置。

from pydantic_settings import BaseSettings
from pydantic import Field, PostgresDsn, ValidationError
import sys

class Settings(BaseSettings):
    """Application configuration loaded from environment variables."""

    # Database
    db_host: str = Field(alias="DB_HOST")
    db_port: int = Field(default=5432, alias="DB_PORT")
    db_name: str = Field(alias="DB_NAME")
    db_user: str = Field(alias="DB_USER")
    db_password: str = Field(alias="DB_PASSWORD")

    # Redis
    redis_url: str = Field(default="redis://localhost:6379", alias="REDIS_URL")

    # API Keys
    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # Feature flags
    enable_new_feature: bool = Field(default=False, alias="ENABLE_NEW_FEATURE")

    model_config = {
        "env_file": ".env",
        "env_file_encoding": "utf-8",
    }

# Create singleton instance at module load
try:
    settings = Settings()
except ValidationError as e:
    print(f"Configuration error:\n{e}")
    sys.exit(1)

在应用中各处导入 settings：

from myapp.config import settings

def get_database_connection():
    return connect(
        host=settings.db_host,
        port=settings.db_port,
        database=settings.db_name,
    )

模式 2：配置缺失时快速失败

必需的设置应立即使应用崩溃，并给出清晰的错误。

from pydantic_settings import BaseSettings
from pydantic import Field, ValidationError
import sys

class Settings(BaseSettings):
    # Required - no default means it must be set
    api_key: str = Field(alias="API_KEY")
    database_url: str = Field(alias="DATABASE_URL")

    # Optional with defaults
    log_level: str = Field(default="INFO", alias="LOG_LEVEL")

try:
    settings = Settings()
except ValidationError as e:
    print("=" * 60)
    print("CONFIGURATION ERROR")
    print("=" * 60)
    for error in e.errors():
        field = error["loc"][0]
        print(f"  - {field}: {error['msg']}")
    print("\nPlease set the required environment variables.")
    sys.exit(1)

启动时给出清晰的错误，胜过请求中途出现隐晦的 None 失败。

模式 3：本地开发默认值

为本地开发提供合理的默认值，同时要求密钥必须显式提供值。

class Settings(BaseSettings):
    # Has local default, but prod will override
    db_host: str = Field(default="localhost", alias="DB_HOST")
    db_port: int = Field(default=5432, alias="DB_PORT")

    # Always required - no default for secrets
    db_password: str = Field(alias="DB_PASSWORD")
    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # Development convenience
    debug: bool = Field(default=False, alias="DEBUG")

    model_config = {"env_file": ".env"}

为本地开发创建 .env 文件（切勿提交此文件）：

# .env (add to .gitignore)
DB_PASSWORD=local_dev_password
API_SECRET_KEY=dev-secret-key
DEBUG=true

模式 4：带命名空间的环境变量

为相关变量添加前缀，以便清晰辨识和轻松调试。

# Database configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_USER=admin
DB_PASSWORD=secret

# Redis configuration
REDIS_URL=redis://localhost:6379
REDIS_MAX_CONNECTIONS=10

# Authentication
AUTH_SECRET_KEY=your-secret-key
AUTH_TOKEN_EXPIRY_SECONDS=3600
AUTH_ALGORITHM=HS256

# Feature flags
FEATURE_NEW_CHECKOUT=true
FEATURE_BETA_UI=false

让 env | grep DB_ 成为有用的调试手段。

详细示例与模式

详细章节（以 ## Advanced Patterns 开头）位于 references/details.md。当上方的导航摘要不够用时，请阅读该文件。

最佳实践总结

1. 切勿硬编码配置 - 所有特定于环境的值都来自环境变量
2. 使用类型化设置 - 使用带验证的 Pydantic-settings
3. 快速失败 - 启动时缺少必需配置即崩溃
4. 提供开发默认值 - 让本地开发更轻松
5. 切勿提交密钥 - 使用 .env 文件（已加入 gitignore）或密钥管理器
6. 为变量添加命名空间 - 使用 DB_HOST、REDIS_URL 以保持清晰
7. 导入 settings 单例 - 不要在代码各处调用 os.getenv()
8. 记录所有变量 - README 应列出必需的环境变量
9. 尽早验证 - 在启动时检查配置的正确性
10. 使用 secrets_dir - 支持容器中挂载的密钥