本文详解如何在 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.v1pydantic-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__ 报错，更保障了验证、序列化、文档生成等全部功能正常工作。
