Pydantic v2 设置类加载 YAML 配置的正确方式-Python教程-PHP中文网

Pydantic v2 设置类加载 YAML 配置的正确方式

本文详解如何在 Pydantic v2（pydantic-settings==2.4.0）中正确通过 YAML 文件初始化 BaseSettings 子类，避免 AttributeError: 'object has no attribute '__fields_set__' 错误，并提供可复用的配置合并方案。

本文详解如何在 pydantic v2（`pydantic-settings==2.4.0`）中正确通过 yaml 文件初始化 `basesettings` 子类，避免 `attributeerror: 'object has no attribute '__fields_set__'` 错误，并提供可复用的配置合并方案。

在 Pydantic v2 中，BaseSettings 的初始化机制已发生重大变更：不再支持在自定义 __init__ 中直接赋值实例属性（如 self.kafka_host = ...），因为此时 Pydantic 的内部状态（如 __fields_set__、验证器、默认值处理等）尚未完成初始化，强行赋值会破坏模型一致性，触发 AttributeError。

正确做法是：将 YAML 解析后的键值对预处理为字典，再通过 `super().init(merged_data)交由 Pydantic 原生初始化流程统一处理**。这确保了字段校验、类型转换、默认值填充及__fields_set__` 正确构建。

以下是完整、健壮的实现方案：

✅ 正确实现步骤

使用 pydantic-settings 替代 pydantic.v1
pydantic-settings 是 Pydantic v2 官方推荐的设置管理包，提供 BaseSettings 和 SettingsConfigDict。
定义配置模型并声明 model_config
显式配置编码、环境变量前缀等（非必需但推荐）：

from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import AnyHttpUrl, Field
from typing import List, Optional
import yaml

class ServiceSettingsYaml(BaseSettings):
    model_config = SettingsConfigDict(env_file_encoding='utf-8')

    backend_cors_origins: List[AnyHttpUrl] = []
    file_encoding: str = "utf-8"

    # Kafka
    kafka_host: Optional[str] = None
    kafka_port: Optional[str] = None
    kafka_topics: Optional[str] = None
    kafka_instance: Optional[str] = None

    # Database
    db_user: Optional[str] = None
    db_password: Optional[str] = None
    db_host: Optional[str] = None
    db_port: Optional[str] = None
    db_name: Optional[str] = None
    sqlalchemy_database_url: Optional[str] = None

安全加载 YAML 并结构化映射
注意：YAML 中嵌套结构（如 kafka_consumer）需手动扁平化为顶层字段：

def load_yaml_config(config_file_path: str) -> dict:
    """安全加载 YAML 配置文件，返回 Python 字典"""
    with open(config_file_path, 'r', encoding='utf-8') as f:
        return yaml.safe_load(f) or {}

class ServiceSettingsYaml(BaseSettings):
    # ... 字段定义同上 ...

    def __init__(self, config_file_path: str = "configs/dev-config.yaml", **kwargs):
        config = load_yaml_config(config_file_path)
        merged_data = {}

        # 提取 kafka_consumer 部分并映射到顶层字段
        if kafka := config.get('kafka_consumer'):
            merged_data.update({
                'kafka_host': kafka.get('host'),
                'kafka_port': str(kafka.get('port', '')),
                'kafka_topics': kafka.get('kafka_topics'),
                'kafka_instance': kafka.get('instance'),  # 若 YAML 中有此字段
            })

        # 提取 database 部分（示例）
        if db := config.get('database'):
            merged_data.update({
                'db_host': db.get('host'),
                'db_user': db.get('user'),
                'db_password': db.get('password'),
                'db_port': str(db.get('port', '')),
                'db_name': db.get('name'),
            })

        # 合并传入的额外参数（如覆盖环境变量）
        merged_data.update(kwargs)

        # ✅ 关键：交由父类完成初始化
        super().__init__(**merged_data)

实例化与使用

settings = ServiceSettingsYaml("configs/dev-config.yaml")
print(settings.kafka_host)  # ✅ 安全访问，已通过 Pydantic 校验

⚠️ 注意事项

禁止在 __init__ 中直接 self.xxx = yyy：Pydantic v2 的 __setattr__ 依赖 __fields_set__，而该属性在 super().__init__() 执行前未创建。
类型提示需与字段实际值匹配：例如 kafka_port 在 YAML 中为 int，但模型中声明为 str，需显式 str(...) 转换，否则校验失败。
推荐使用 Optional[T] + None 默认值：明确表达字段可选性，避免 Field(default=None) 的冗余写法（Pydantic v2 中 Optional[T] = None 即隐含默认）。
环境变量优先级高于 YAML：若同时启用 .env 文件，Pydantic 默认按 env > YAML > default 顺序覆盖；可通过 model_config = SettingsConfigDict(env_file='.env', env_file_encoding='utf-8') 控制。

✅ 总结

Pydantic v2 的核心原则是 “声明式建模 + 声明式初始化”。YAML 配置应作为数据源，经预处理后统一注入 BaseSettings.__init__，而非绕过框架逻辑手动赋值。此举不仅解决 __fields_set__ 报错，更保障了验证、序列化、文档生成等全部功能正常工作。