一个真实场景API 传参引发的幽灵数据先看一段再普通不过的代码——这种 Filter 类在 FastAPI 接口和 Service 层传参中随处可见from datetime import date from pydantic import Field class RetrievalFilters(APIModel): document_ids: list[str] Field(default_factorylist) topic: str | None None effective_before: date | None None字段说明字段作用document_ids限制只从指定文档中检索topic限制只检索某个主题effective_before限制只检索某个日期之前生效的政策你可能会问document_ids那行为什么不直接写成list[str] []更简洁啊答案就四个字可变默认值。两种写法对比from pydantic import BaseModel, Field # 写法1推荐 class ModelA(BaseModel): document_ids: list[str] Field(default_factorylist) # 写法2不推荐 class ModelB(BaseModel): document_ids: list[str] []看起来功能一样但底层机制完全不同。[]的致命问题所有实例共享同一个列表[]是在类定义阶段就创建的一个全局列表对象所有实例共享同一个 list。用原生 Python 类来演示这个 bugclass ModelB: document_ids: list[str] [] b1 ModelB() b2 ModelB() b1.document_ids.append(doc1) print(b1.document_ids) # [doc1] print(b2.document_ids) # [doc1] ❗ b2 也被修改了共享同一个列表b1 往列表里加了个doc1结果 b2 的列表里也出现了doc1——这就是经典的可变默认值共享 bug。放到实际业务里如果两个并发请求各自实例化RetrievalFilters请求 A 往document_ids里 append 了文档 ID请求 B 就会莫名其妙地多出 A 的文档限制。数据串了排查起来要命。Pydantic 帮你兜了一层底但别依赖这个魔法好消息是Pydantic v1/v2 会对直接写[]的字段做特殊处理——底层自动翻译成default_factorylist所以实际不会发生跨实例污染。但这不意味着你可以放心写[]原因有三1. 可读性差团队困惑同事看到list[str] []第一反应是这是不是会有共享可变对象的 bug 他得去翻 Pydantic 源码确认白白浪费时间。而Field(default_factorylist)一眼看懂意图——每次实例化都生成新列表。2. 复制到 dataclass 直接炸如果你把这段代码复制到 Python 标准库的dataclass里class ModelB: document_ids: list[str] [] b1 ModelB() b2 ModelB() b1.document_ids.append(doc1) print(b1.document_ids) # [doc1] print(b2.document_ids) # [doc1] ❗ b2 也被修改了共享同一个列表原生 dataclass没有Pydantic 的魔法保护[]一定会导致跨实例共享。Python 解释器甚至会直接抛出ValueError: mutable default ... is not allowed。3. Pydantic 版本迁移风险Pydantic v1 到 v2 经历了大量底层重写。虽然 v2 目前帮你兜底了但未来版本行为是否会变化谁也说不准。显式写default_factory才是最安全的做法。正确写法总结场景写法说明Pydantic 模型推荐list[str] Field(default_factorylist)可读性最好意图清晰复制到 dataclass 也不会出错Pydantic 模型不推荐list[str] []虽然能跑但团队阅读会疑惑且有迁移风险标准库 dataclassfield(default_factorylist)绝对禁止直接写[]必须用field(default_factorylist)所有可变容器类型list/dict/set都适用这条规则# Pydantic tags: list[str] Field(default_factorylist) config: dict[str, Any] Field(default_factorydict) ids: set[int] Field(default_factoryset) # dataclass from dataclasses import dataclass, field dataclass class MyModel: tags: list[str] field(default_factorylist) config: dict field(default_factorydict)一句话记住可变默认值永远用 factory。Pydantic 帮你兜底是情分dataclass 不兜是本分。显式写default_factory才是对所有人和所有场景都负责的写法。如果这篇文章帮到了你点个赞收藏一下下次写模型类的时候翻出来看一眼省得踩坑。有问题欢迎评论区交流