用途
该技能用于 Python 配置管理,通过环境变量与类型化设置将配置从代码中外部化。良好管理的配置使同一份代码无需修改即可在任意环境中运行。
适用时机包括:搭建新项目的配置系统;从硬编码值迁移到环境变量;实现 pydantic-settings 类型化配置;管理密钥与敏感值;创建按环境区分的设置(dev/staging/prod);在应用启动时校验配置。
核心概念
-
外部化配置:所有环境相关值(URL、密钥、特性开关)来自环境变量,而不是代码。
-
类型化设置:在启动时将配置解析并校验为类型化对象,而不是散落在代码各处。
-
快速失败:在应用启动时校验所有必需配置。缺失的配置应立即以清晰信息崩溃。
-
合理默认值:为本地开发提供合理默认值,同时对敏感设置要求显式传值。
快速开始
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 - 支持容器中挂载的密钥
限制
除上述模式与最佳实践外,关于具体框架集成、平台支持范围、付费或价格等信息暂未提供。