【Pydantic】BaseSetting 使用教程与实践

引言

在 Python 项目开发中，应用配置管理是一个常见但容易被忽视的问题。数据库连接信息、第三方 API 密钥、应用运行参数……这些配置散落在代码各处，不仅难以维护，还存在安全隐患。

传统做法通常是在代码中硬编码配置值，或者手动读取环境变量：

python

import os

DATABASE_URL = os.getenv("DATABASE_URL", "postgresql://localhost:5432/mydb")
SECRET_KEY = os.getenv("SECRET_KEY")
DEBUG = os.getenv("DEBUG", "False").lower() == "true"

这种做法虽然能用，但存在明显的问题：

• 类型不安全：环境变量都是字符串，需要手动转换
• 缺乏校验：必须的配置缺失时，程序可能到运行时才报错
• 代码冗余：每个配置项都要写一遍读取逻辑

Pydantic BaseSettings 就是解决这些问题的利器。它是 Pydantic 官方提供的配置管理工具，基于 Pydantic 的类型校验能力，让配置管理变得类型安全、自动验证、优雅简洁。

本文核心内容：

• BaseSettings 的核心概念与 v1/v2 版本差异
• 环境变量与 .env 文件的自动加载
• 配置优先级与字段别名
• 嵌套配置与复杂数据类型
• 命令行参数支持
• FastAPI 集成与测试技巧

本文基于 Pydantic Settings v2 版本，v2 已将配置管理功能拆分到独立的 pydantic-settings 包中，需要单独安装。

---

一、BaseSettings 是什么？

1.1 核心概念

BaseSettings 是 Pydantic 专门用于应用配置管理的基类。它的核心能力是：

1. 自动从环境变量读取配置：无需手动调用 os.getenv()
2. 类型自动转换：字符串 "true" 自动转为布尔值 True
3. 配置校验：缺失必要配置或格式错误时立即报错
4. 支持 .env 文件：本地开发时方便管理配置
5. 支持命令行参数：快速覆写配置项

1.2 BaseModel vs BaseSettings

在开始之前，快速回顾一下两者的区别：

维度	BaseModel	BaseSettings
用途	定义业务数据（用户、订单）	定义应用配置（数据库连接、密钥）
数据来源	代码传入（字典、JSON）	环境变量、.env 文件、命令行
导入方式	from pydantic import BaseModel	from pydantic_settings import BaseSettings
适用场景	API 请求/响应、数据库记录	应用配置、环境管理

1.3 v1 → v2 版本变化

Pydantic v2 对配置管理做了重要调整：

版本	导入方式	配置方式
v1	from pydantic import BaseSettings	使用内部 Config 类
v2	from pydantic_settings import BaseSettings	使用 model_config = SettingsConfigDict(...)

# ❌ v1 旧方式（已废弃）
from pydantic import BaseSettings

class Settings(BaseSettings):
    app_name: str = "MyApp"
    
    class Config:
        env_file = ".env"

# ✅ v2 新方式
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    app_name: str = "MyApp"
    
    model_config = SettingsConfigDict(env_file=".env")

注意：v2 中 BaseSettings 已从主库移出，需要单独安装 pydantic-settings 包。

---

二、快速上手：第一个 Settings

2.1 安装

pip install pydantic-settings

2.2 定义配置模型

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    # 应用配置
    app_name: str = "MyApp"
    debug: bool = False
    
    # 数据库配置
    database_url: str
    database_pool_size: int = 5
    
    # 安全配置
    secret_key: str
    
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8"
    )

# 创建配置实例（自动从环境变量和 .env 加载）
settings = Settings()
print(settings.database_url)

2.3 使用 .env 文件

在项目根目录创建 .env 文件：

# .env
APP_NAME="My Awesome API"
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
SECRET_KEY="your-secret-key-here-make-it-long-and-random"
DEBUG=true

Pydantic 会自动读取并解析 .env 文件中的变量。

2.4 使用环境变量

.env 文件的优先级低于系统环境变量：

# 设置环境变量，覆盖 .env 中的值
export DATABASE_URL="postgresql://prod-user:prod-pass@prod-db:5432/proddb"
python main.py

环境变量名称与字段名大小写不敏感匹配。APP_NAME、app_name、App_Name 都会映射到 app_name 字段。

---

三、字段与配置详解

3.1 字段约束

与 BaseModel 一样，BaseSettings 也支持 Field 添加约束：

from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    app_name: str = Field(default="MyApp", min_length=1, max_length=50)
    
    # 必填字段：没有默认值，必须从环境变量或 .env 提供
    secret_key: str = Field(min_length=32, description="至少32位")
    
    database_port: int = Field(default=5432, ge=1, le=65535)
    
    debug: bool = Field(default=False)
    
    model_config = SettingsConfigDict(env_file=".env")

3.2 配置参数（SettingsConfigDict）

SettingsConfigDict 支持以下常用参数：

参数	说明	示例
env_file	.env 文件路径	".env"
env_file_encoding	文件编码	"utf-8"
env_prefix	环境变量前缀	"MYAPP_"
env_nested_delimiter	嵌套字段分隔符	"__"
case_sensitive	是否区分大小写	False
extra	额外字段处理策略	"forbid" / "ignore"
populate_by_name	是否支持字段名和别名	True

3.3 使用 env_prefix 前缀

当环境变量较多时，使用前缀避免冲突：

class Settings(BaseSettings):
    database_url: str
    database_pool_size: int = 5
    
    model_config = SettingsConfigDict(
        env_prefix="MYAPP_"
    )

# 环境变量应为：
# MYAPP_DATABASE_URL=...
# MYAPP_DATABASE_POOL_SIZE=10

3.4 extra 配置的注意事项

在 Pydantic Settings v2 中，extra 的默认值是 forbid（禁止额外字段）。如果 .env 文件中包含未定义的变量，会抛出 ValidationError。

# .env 文件
# APP_NAME=MyApp
# UNKNOWN_VAR=something  # 这个未定义字段会导致报错

class Settings(BaseSettings):
    app_name: str
    
    model_config = SettingsConfigDict(
        env_file=".env"
        # extra 默认为 "forbid"
    )

# 报错：ValidationError: Extra inputs are not permitted

解决方案：如果希望忽略未定义的变量（兼容 v1 行为），设置 extra="ignore"：

model_config = SettingsConfigDict(
    env_file=".env",
    extra="ignore"  # 忽略 .env 中未定义的变量
)

---

四、嵌套配置与复杂类型

4.1 嵌套模型

BaseSettings 支持模型嵌套，适合分层组织配置：

from pydantic_settings import BaseSettings, SettingsConfigDict

class DatabaseConfig(BaseModel):
    host: str = "localhost"
    port: int = 5432
    username: str
    password: str
    database: str

class RedisConfig(BaseModel):
    host: str = "localhost"
    port: int = 6379
    db: int = 0

class Settings(BaseSettings):
    app_name: str
    debug: bool = False
    database: DatabaseConfig
    redis: RedisConfig
    
    model_config = SettingsConfigDict(env_file=".env")

# 环境变量格式（使用 __ 作为嵌套分隔符）：
# APP_NAME=MyApp
# DATABASE__HOST=postgres.example.com
# DATABASE__USERNAME=admin
# DATABASE__PASSWORD=secret
# DATABASE__DATABASE=mydb
# REDIS__HOST=redis.example.com

4.2 列表与字典类型

支持列表、字典等复杂类型，可通过 JSON 字符串加载：

from typing import List, Dict
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    allowed_hosts: List[str] = ["localhost"]
    api_keys: Dict[str, str]
    
    model_config = SettingsConfigDict(env_file=".env")

# 环境变量：
# ALLOWED_HOSTS='["example.com", "api.example.com"]'
# API_KEYS='{"google": "xxx", "openai": "yyy"}'

---

五、命令行参数支持

Pydantic Settings v2 内置了命令行参数解析功能，无需额外安装 argparse：

import sys
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    app_name: str = "MyApp"
    debug: bool = False
    database_url: str
    
    model_config = SettingsConfigDict(
        cli_parse_args=True,  # 启用命令行解析
        env_file=".env"
    )

# 使用方式：
# python main.py --app_name "CLI App" --debug true --database_url "postgresql://..."

settings = Settings()
print(settings.app_name)  # "CLI App"

命令行参数支持的列表格式：

class Settings(BaseSettings):
    allowed_hosts: List[str] = []
    
    model_config = SettingsConfigDict(cli_parse_args=True)

# 支持三种格式：
# 1. JSON: --allowed_hosts='["example.com", "api.com"]'
# 2. 多个参数: --allowed_hosts example.com --allowed_hosts api.com
# 3. 逗号分隔: --allowed_hosts=example.com,api.com

命令行参数的优先级高于环境变量和 .env 文件。

---

六、FastAPI 集成实践

6.1 基本集成

在 FastAPI 中使用 BaseSettings 管理配置是最常见的场景：

# config.py
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    app_name: str = "My FastAPI App"
    admin_email: str
    database_url: str
    secret_key: str = Field(min_length=32)
    debug: bool = False
    
    model_config = SettingsConfigDict(env_file=".env")

settings = Settings()

# main.py
from fastapi import FastAPI
from config import settings

app = FastAPI(title=settings.app_name, debug=settings.debug)

@app.get("/info")
async def info():
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email,
        "debug": settings.debug
    }

6.2 使用依赖注入（推荐）

将 Settings 作为依赖注入，方便测试和覆写：

# config.py
from functools import lru_cache
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "MyApp"
    admin_email: str
    debug: bool = False

@lru_cache
def get_settings():
    """使用 lru_cache 确保 Settings 只加载一次[citation:1]"""
    return Settings()

# main.py
from fastapi import Depends, FastAPI
from config import get_settings, Settings

app = FastAPI()

@app.get("/info")
async def info(settings: Settings = Depends(get_settings)):
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email
    }

6.3 测试覆写

依赖注入方式让测试更加简单：

# test_main.py
from fastapi.testclient import TestClient
from main import app, get_settings
from config import Settings

def get_test_settings():
    return Settings(
        app_name="Test App",
        admin_email="test@example.com"
    )

app.dependency_overrides[get_settings] = get_test_settings

client = TestClient(app)

def test_info():
    response = client.get("/info")
    assert response.status_code == 200
    assert response.json()["admin_email"] == "test@example.com"

---

七、配置加载优先级

BaseSettings 的配置来源按优先级从高到低为：

1. 命令行参数（如果启用了 cli_parse_args）
2. 系统环境变量
3. .env 文件
4. 字段默认值

命令行参数 > 环境变量 > .env 文件 > 默认值

这意味着，本地开发用 .env，生产环境用环境变量或命令行参数覆写，非常灵活。

---

八、多环境配置

8.1 多个 .env 文件

不同环境使用不同的配置文件：

class Settings(BaseSettings):
    app_name: str
    database_url: str
    
    model_config = SettingsConfigDict(
        env_file=(".env", ".env.prod"),  # 后面的覆盖前面的
    )

# .env        - 本地开发默认值
# .env.prod   - 生产环境特定值（优先级更高）

8.2 运行时指定文件

实例化时传入 _env_file 参数覆盖配置：

# 开发环境
settings_dev = Settings(_env_file=".env.dev")

# 生产环境
settings_prod = Settings(_env_file=".env.prod")

---

九、常见问题与避坑指南

9.1 .env 文件中的未定义字段报错

问题：v2 默认 extra="forbid"，未在模型中定义的字段会导致 ValidationError。

解决：设置 extra="ignore"：

model_config = SettingsConfigDict(env_file=".env", extra="ignore")

9.2 字段别名与环境变量

使用 Field(validation_alias="...") 指定环境变量名时，字段名将无法用于匹配环境变量：

class Settings(BaseSettings):
    # 这个字段会匹配环境变量 FOO_ALIAS，而不是 foo
    foo: str = Field(validation_alias="FOO_ALIAS")

9.3 环境变量名大小写

BaseSettings 默认大小写不敏感匹配环境变量名。APP_NAME、app_name、App_Name 都会映射到 app_name 字段。

9.4 populate_by_name 与别名冲突

当同时存在环境变量和构造参数时，可能触发 Extra inputs are not permitted 错误。建议：

• 避免同时使用字段名和别名构造实例
• 如需覆写环境变量，直接设置环境变量值

---

十、总结

核心概念	说明
BaseSettings	配置管理基类（需从 pydantic_settings 导入）
SettingsConfigDict	配置参数（替代 v1 的 Config 类）
env_file	.env 文件路径
env_prefix	环境变量前缀
cli_parse_args	启用命令行参数解析
extra	额外字段处理策略（forbid / ignore）

什么时候用 BaseSettings？

✅ 推荐使用：

• 应用配置管理（数据库、Redis、外部服务）
• 多环境部署（dev/staging/production）
• 需要类型安全的配置
• FastAPI 等 Web 应用

❌ 不推荐：

• 业务数据验证（应该用 BaseModel）
• 临时、一次性的配置

---

扩展阅读：

• Pydantic Settings 官方文档
• FastAPI Settings Guide