pydantic_settings 的用法

1. 引言pydantic_settings 是 Pydantic 官方提供的配置管理库用于从环境变量、文件、命令行参数等来源加载配置并利用 Pydantic 的校验能力对配置进行类型检查和验证。它适合在 Python 项目中统一管理应用配置减少手写 os.environ 解析的样板代码。2. 安装使用 pip 安装 pydantic-settingspip install pydantic-settings3. 基础用法定义一个继承自 BaseSettings 的配置类字段默认值即配置项的默认值。默认情况下pydantic_settings 会自动从环境变量读取配置字段名与环境变量名一一对应不区分大小写。from pydantic_settings import BaseSettings class Settings(BaseSettings): app_name: str MyApp debug: bool False database_url: str sqlite:///default.db settings Settings() print(settings.app_name) print(settings.debug) print(settings.database_url)运行程序时可以通过环境变量覆盖默认值export APP_NAMEMyProdApp export DEBUGtrue export DATABASE_URLpostgresql://user:passlocalhost/db python main.py4. 从 .env 文件加载配置pydantic_settings 支持从 .env 文件读取配置需要安装 python-dotenv 依赖pip install python-dotenv在项目根目录创建 .env 文件APP_NAMEMyDotenvApp DEBUGtrue DATABASE_URLmysql://user:passlocalhost/mydb然后在 Settings 类中指定 env_file 参数from pydantic_settings import BaseSettings class Settings(BaseSettings): app_name: str MyApp debug: bool False database_url: str sqlite:///default.db model_config SettingsConfigDict(env_file.env) settings Settings() print(settings.app_name) print(settings.debug) print(settings.database_url)注意环境变量的优先级高于 .env 文件中的配置。5. 自定义环境变量前缀当项目需要区分不同环境如开发、测试、生产时可以为环境变量添加统一前缀避免命名冲突。通过 SettingsConfigDict 的 env_prefix 参数实现from pydantic_settings import BaseSettings, SettingsConfigDict class Settings(BaseSettings): app_name: str MyApp debug: bool False model_config SettingsConfigDict(env_prefixMYAPP_) settings Settings() print(settings.app_name) print(settings.debug)此时环境变量名需要写成 MYAPP_APP_NAME、MYAPP_DEBUGexport MYAPP_APP_NAMEPrefixedApp export MYAPP_DEBUGtrue python main.py6. 嵌套配置配置类支持嵌套模型适合组织复杂的配置结构。嵌套模型同样可以从环境变量读取字段名使用双下划线分隔from pydantic_settings import BaseSettings, SettingsConfigDict from pydantic import BaseModel class DatabaseConfig(BaseModel): host: str localhost port: int 5432 name: str default_db class Settings(BaseSettings): app_name: str MyApp database: DatabaseConfig DatabaseConfig() model_config SettingsConfigDict(env_nested_delimiter__) settings Settings() print(settings.database.host) print(settings.database.port) print(settings.database.name)对应的环境变量写法export DATABASE__HOSTdb.example.com export DATABASE__PORT5433 export DATABASE__NAMEprod_db python main.py7. 从命令行参数读取配置pydantic_settings 还支持从命令行参数读取配置适合 CLI 工具场景。需要安装 pydantic-extra-types 或使用内置的 cli 支持from pydantic_settings import BaseSettings, SettingsConfigDict class Settings(BaseSettings): app_name: str MyApp debug: bool False model_config SettingsConfigDict(cli_parse_argsTrue) settings Settings() print(settings.app_name) print(settings.debug)运行方式python main.py --app_name CliApp --debug true8. 配置优先级pydantic_settings 的配置来源优先级从高到低依次为命令行参数如果启用环境变量.env 文件字段默认值这一优先级设计让开发者可以在不同场景下灵活覆盖配置例如生产环境通过环境变量注入敏感信息开发环境使用 .env 文件。9. 实际项目示例下面是一个完整的 FastAPI 项目配置示例综合使用 .env 文件、环境变量前缀和嵌套配置from pydantic_settings import BaseSettings, SettingsConfigDict from pydantic import BaseModel class DatabaseConfig(BaseModel): host: str localhost port: int 3306 user: str root password: str name: str app_db class RedisConfig(BaseModel): host: str localhost port: int 6379 db: int 0 class Settings(BaseSettings): app_name: str FastAPI App debug: bool False database: DatabaseConfig DatabaseConfig() redis: RedisConfig RedisConfig() model_config SettingsConfigDict( env_file.env, env_prefixAPP_, env_nested_delimiter__, ) settings Settings() print(settings.app_name) print(settings.database.host) print(settings.redis.port)对应的 .env 文件APP_APP_NAMEProduction API APP_DEBUGfalse APP_DATABASE__HOSTdb.internal.example.com APP_DATABASE__PORT3306 APP_DATABASE__USERapp_user APP_DATABASE__PASSWORDsecret APP_DATABASE__NAMEprod_db APP_REDIS__HOSTredis.internal.example.com APP_REDIS__PORT6379 APP_REDIS__DB110. 总结pydantic_settings 的核心价值在于把配置声明、类型校验和来源管理统一起来。通过继承 BaseSettings开发者可以用声明式的方式定义配置项并自动获得环境变量、.env 文件、命令行参数等多来源支持。对于需要区分开发、测试、生产环境的项目结合 env_prefix 和嵌套配置可以显著减少配置管理的复杂度。