BaseModel类中字段默认值如何正确设置？

Question

在使用 Pydantic 的 `BaseModel` 定义数据模型时，一个常见问题是：**如何正确为字段设置默认值，尤其是在涉及可变类型（如 list、dict）时避免潜在陷阱？** 直接使用 `field: List[int] = []` 会导致所有实例共享同一对象，引发意外的数据污染。正确的做法是使用 `Field(default_factory=list)` 或定义 `default_factory` 来生成独立的默认实例。此外，对于不可变默认值（如 int、str），可直接赋值。理解 `default` 与 `default_factory` 的适用场景，是确保模型安全性和预期行为的关键。

Answer 1

1. 问题背景与常见误区

在使用 Pydantic 的 BaseModel 定义数据模型时，字段默认值的设置是一个看似简单却极易出错的环节。许多开发者习惯于像普通 Python 类一样直接赋值：

from pydantic import BaseModel
from typing import List

class User(BaseModel):
    name: str = "Unknown"
    items: List[int] = []  # ❌ 危险！

这种写法对不可变类型（如 str、int、float）是安全的，但对可变对象（如 list、dict、set）则会引发严重问题——所有实例将共享同一个默认对象引用。

2. 可变默认值陷阱的本质分析

行为	代码示例	结果分析
错误方式	items: List[int] = []	所有实例共享同一列表对象
正确方式	items: List[int] = Field(default_factory=list)	每次创建新实例时生成独立列表
不可变类型	count: int = 0	安全，整数不可变，无共享风险

根本原因在于 Python 函数/类定义时，默认参数是在定义时刻求值一次，并存储为函数属性。因此 [] 被创建一次，后续所有调用都复用该对象。

3. 正确解决方案：default 与 default_factory 的分工

• default：适用于不可变常量，如 None, 42, "default"
• default_factory：用于需要动态生成的对象，确保每次调用返回新实例

from pydantic import BaseModel, Field
from typing import Dict, List, Optional
from datetime import datetime

class Profile(BaseModel):
    username: str = "guest"
    tags: List[str] = Field(default_factory=list)
    metadata: Dict = Field(default_factory=dict)
    created_at: datetime = Field(default_factory=datetime.now)
    config: Optional[Dict] = Field(default_factory=lambda: {"theme": "light"})

上述代码中，tags 和 metadata 每次实例化都会获得全新的空容器，避免了数据污染。

4. 进阶实践：自定义 default_factory 函数

当需要更复杂的初始化逻辑时，可以传入可调用对象作为 default_factory：

def make_id_list() -> List[int]:
    return [0]

def get_default_settings():
    return {"retry": 3, "timeout": 30}

class Task(BaseModel):
    task_ids: List[int] = Field(default_factory=make_id_list)
    settings: dict = Field(default_factory=get_default_settings)

这种方式不仅解决了可变默认值问题，还提升了代码可测试性和可维护性。

5. 架构级影响与设计建议

1. 始终检查模型中是否存在可变类型的直接赋值
2. 建立团队代码规范，强制使用 Field(default_factory=...) 处理 list/dict/set
3. 结合 MyPy 或静态分析工具进行类型和模式检测
4. 在大型系统中，考虑封装基础模型基类预设安全默认行为
5. 文档化常见陷阱并在新成员培训中强调
6. 利用单元测试验证默认值是否真正隔离

6. 流程图：默认值决策路径

graph TD
    A[定义字段默认值] --> B{类型是否可变?}
    B -- 是 --> C[使用 Field(default_factory=factory_func)]
    B -- 否 --> D[直接赋值 default_value]
    C --> E[工厂函数返回新实例]
    D --> F[使用常量或不可变值]
    E --> G[实例间无状态共享]
    F --> G

该流程清晰地指导开发者在不同场景下做出正确选择。