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

Question

在使用 Pydantic 的 `BaseModel` 时，一个常见问题是**如何正确设置字段的默认值以避免可变对象共享**。例如，若将列表或字典设为默认值：`items: list = []`，会导致所有实例共享同一对象，造成意外的数据污染。正确的做法是使用 `Field(default_factory=list)` 或定义 `default_factory` 来生成新的可变对象实例。此外，对于不可变默认值（如字符串、数字），直接赋值即可。理解 `default` 与 `default_factory` 的区别，是确保模型行为一致性和避免隐蔽 bug 的关键。

Answer 1

1. 问题引入：Pydantic 中的默认值陷阱

在使用 Pydantic 的 BaseModel 定义数据模型时，开发者常会为字段设置默认值。然而，当默认值是可变对象（如列表、字典、集合）时，若直接赋值，例如：

class ItemModel(BaseModel):
    items: list = []

会导致所有实例共享同一个列表对象。这意味着修改一个实例的 items，会影响其他所有未显式传参的实例，造成数据污染。

2. 根本原因分析：Python 的默认参数机制

该问题并非 Pydantic 特有，而是源于 Python 函数/类定义中对默认参数的处理方式。Python 在定义函数或类时，会一次性求值默认参数表达式，并将其存储在函数或类的属性中。因此，[] 和 {} 这样的可变对象仅被创建一次。

场景	代码示例	风险等级
可变对象直接赋值	items: list = []	高
不可变对象赋值	name: str = "default"	低
使用 default_factory	items: list = Field(default_factory=list)	无

3. 解决方案一：使用 Field(default_factory=...)

Pydantic 提供了 Field 函数来精细化控制字段行为。对于可变默认值，应使用 default_factory 参数，它接受一个无参 callable，每次实例化时都会调用该 callable 来生成新对象。

from pydantic import BaseModel, Field

class User(BaseModel):
    preferences: dict = Field(default_factory=dict)
    tags: list = Field(default_factory=list)
    created_at: float = Field(default_factory=time.time)

上述代码确保每个 User 实例都有独立的 preferences 和 tags 对象。

4. 自定义工厂函数：更复杂的初始化逻辑

当需要更复杂的默认值构造逻辑时，可以定义自定义工厂函数：

def make_cache():
    return {"version": 1, "data": {}}

class ServiceConfig(BaseModel):
    cache: dict = Field(default_factory=make_cache)

此方式支持延迟计算、依赖注入准备、或基于环境的默认配置生成。

5. default 与 default_factory 的语义区别

• default：适用于不可变值（int, str, bool, tuple 等），直接赋值安全。
• default_factory：用于可变对象或需动态生成的值，保证每次新建实例时调用工厂函数。

误用两者将导致隐蔽 bug，尤其在高并发或长时间运行的服务中难以排查。

6. 实际案例对比：错误 vs 正确实现

# ❌ 错误做法
class BadExample(BaseModel):
    data: list = []

a = BadExample()
b = BadExample()
a.data.append("x")
print(b.data)  # 输出: ['x'] —— 意外共享！

# ✅ 正确做法
class GoodExample(BaseModel):
    data: list = Field(default_factory=list)

c = GoodExample()
d = GoodExample()
c.data.append("y")
print(d.data)  # 输出: [] —— 独立实例

7. 高级用法：嵌套模型与递归默认工厂

在复杂嵌套结构中，default_factory 同样适用：

class Address(BaseModel):
    city: str = "Unknown"

class Person(BaseModel):
    name: str
    addresses: list[Address] = Field(default_factory=list)

即使 Address 是模型，list[Address] 的默认值仍需通过 default_factory 创建新列表。

8. 流程图：字段默认值决策路径

graph TD A[定义 BaseModel 字段] --> B{默认值是否可变?} B -- 是 --> C[使用 Field(default_factory=...)] B -- 否 --> D[直接赋值 default=...] C --> E[确保每次实例化生成新对象] D --> F[安全使用不可变值]

9. 最佳实践总结

1. 永远不要对 list, dict, set 使用直接赋值默认值。
2. 优先使用 Field(default_factory=list) 模式。
3. 对时间戳、UUID 等动态值，使用 default_factory。
4. 在文档和团队规范中明确标注此约定。
5. 结合类型检查工具（如 mypy）与静态分析插件预防此类错误。
6. 单元测试中验证默认值是否真正独立。
7. 考虑封装常用 factory 到基类或工具模块。
8. 避免在 default_factory 中传递参数，保持无副作用。
9. 注意性能影响：频繁创建小对象通常可忽略。
10. 升级 Pydantic v2 后语法略有变化，但核心理念一致。