SuperAPI AI 工具集

python-configuration

编程与开发

查看项目

更新于 10-16 07:30

技能介绍

用途

该技能用于 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()  # 从环境加载

基本模式

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

创建一个中心化设置类,加载并校验所有配置。

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

class Settings(BaseSettings):
    """从环境变量加载的应用配置。"""

    # 数据库
    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 密钥
    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # 特性开关
    enable_new_feature: bool = Field(default=False, alias="ENABLE_NEW_FEATURE")

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

# 在模块加载时创建单例实例
try:
    settings = Settings()
except ValidationError as e:
    print(f"配置错误:\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):
    # 必需 - 无默认值意味着必须设置
    api_key: str = Field(alias="API_KEY")
    database_url: str = Field(alias="DATABASE_URL")

    # 可选并带默认值
    log_level: str = Field(default="INFO", alias="LOG_LEVEL")

try:
    settings = Settings()
except ValidationError as e:
    print("=" * 60)
    print("配置错误")
    print("=" * 60)
    for error in e.errors():
        field = error["loc"][0]
        print(f"  - {field}: {error['msg']}")
    print("\n请设置必需的环境变量。")
    sys.exit(1)

启动时的清晰错误优于请求处理中途神秘的 None 失败。

模式 3:本地开发默认值

为本地开发提供合理默认值,同时对密钥要求显式传值。

class Settings(BaseSettings):
    # 有本地默认值,但生产环境会覆盖
    db_host: str = Field(default="localhost", alias="DB_HOST")
    db_port: int = Field(default=5432, alias="DB_PORT")

    # 始终必需 - 密钥无默认值
    db_password: str = Field(alias="DB_PASSWORD")
    api_secret_key: str = Field(alias="API_SECRET_KEY")

    # 开发便利项
    debug: bool = Field(default=False, alias="DEBUG")

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

为本地开发创建 .env 文件(切勿提交):

# .env (添加到 .gitignore)
DB_PASSWORD=local_dev_password
API_SECRET_KEY=dev-secret-key
DEBUG=true

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

为相关变量加前缀,便于理解和调试。

# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp
DB_USER=admin
DB_PASSWORD=secret

# Redis 配置
REDIS_URL=redis://localhost:6379
REDIS_MAX_CONNECTIONS=10

# 认证
AUTH_SECRET_KEY=your-secret-key
AUTH_TOKEN_EXPIRY_SECONDS=3600
AUTH_ALGORITHM=HS256

# 特性开关
FEATURE_NEW_CHECKOUT=true
FEATURE_BETA_UI=false

使 env | grep DB_ 在调试时有用。

更详细的工作示例与模式位于 references/details.md(从 ## Advanced Patterns 开始的详细章节)。当上方导航摘要不足时阅读该文件。

最佳实践总结

  • 绝不硬编码配置 - 所有环境相关值来自环境变量
  • 使用类型化设置 - 用 pydantic-settings 进行校验
  • 快速失败 - 启动时缺失必需配置就崩溃
  • 提供开发默认值 - 让本地开发更轻松
  • 绝不提交密钥 - 使用 .env 文件(加入 gitignore)或密钥管理器
  • 为变量加命名空间 - DB_HOST、REDIS_URL 更清晰
  • 导入 settings 单例 - 不要在代码各处调用 os.getenv()
  • 记录所有变量 - README 应列出必需的环境变量
  • 尽早校验 - 在启动时检查配置正确性
  • 使用 secrets_dir - 支持容器中挂载的密钥

限制

除上述模式与最佳实践外,关于具体框架集成、平台支持范围、付费或价格等信息暂未提供。