python-configuration

来源声明：本技能内容源自 wshobson/agents （MIT License, Copyright (c) 2024 Seth Hobson；完整许可文本见同目录 LICENSE.txt）。 使用、修改与再分发须遵守该 MIT 许可条款并保留版权声明。

中文描述

本技能提供全栈开发相关的最佳实践和模式指导。

---

name: python-configuration description: 通过环境变量和类型化设置管理 Python 配置。适用于外置配置、设置 pydantic-settings、管理机密信息或实现特定环境行为。

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. 导入设置单例 - 不要在代码中到处调用 os.getenv()
8. 记录所有变量 - README 应列出必需的环境变量
9. 尽早验证 - 在启动时检查配置是否正确
10. 使用 secrets_dir - 支持容器中挂载的机密信息

能力边界

✅ 擅长处理

• 全栈开发相关的最佳实践
• 代码架构设计指导
• 性能优化建议

⚠️ 需要素材

• 具体的项目上下文
• 技术栈信息

❌ 超出范围

• 非技术领域的业务决策
• 具体的代码实现（仅提供指导）

工作流程

步骤 1：需求分析

理解项目需求和技术约束

步骤 2：架构设计

设计系统架构和组件划分

步骤 3：实现指导

提供具体的实现建议和代码模式

步骤 4：代码审查

审查代码质量和最佳实践遵循情况

步骤 5：优化建议

提供性能优化和改进建议

注意事项

1. 过度设计

避免在简单场景中使用复杂的设计模式

2. 忽视性能

不要忽视性能优化，特别是在生产环境中

3. 安全考虑

始终考虑安全性和数据保护

4. 测试覆盖

确保有足够的测试覆盖，特别是边界情况

5. 文档维护

保持文档与代码同步更新