罗罗编程学习记录
本页内容 展开查看

04.7.15.2 Pydantic 校验与数据模型

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.7 Python / 04.7.15 FastAPI 框架

覆盖范围

  • Pydantic 2.x 与 v1 结构性差异:validator→field_validator、Config→model_config、parse_obj→model_validate
  • BaseModel 与 Rust core 校验流程、类型转换与 Strict、Annotated 与 Field 约束
  • field_validator/model_validator 的 before/after 模式、跨字段校验
  • response_model 与 response_model_exclude_unset、from_attributes ORM 模式
  • 泛型模型、RootModel、Discriminated Union、TypeAdapter、自定义类型 core schema
  • 序列化 model_dump/model_dump_json、别名体系、校验错误结构与 422 定制、性能与迁移坑

04.7.15.2-001 Pydantic 2.x 相对 1.x 的核心架构变化?

一句话结论

Pydantic 2.x 把校验核心从纯 Python 重写为 Rust 实现的 pydantic-core,模型先从类型注解编译成 core schema,再由 Rust 执行校验与序列化;API 层随之调整:配置进 model_config,校验器改名,序列化方法改名。整体校验速度显著提升,部分 v1 行为(宽松转换、旧配置项)有破坏性变更。

概念解释

  • v1 校验逻辑分散在 Python 类与类方法中;v2 是“schema 编译 + Rust 执行”两层结构。
  • 迁移时除 API 改名外,还要核对类型转换严格度、默认值处理与错误结构差异。

原理流程

  1. 定义 BaseModel 子类,注解与约束被收集。
  2. 首次使用时编译为 pydantic-core 的 schema(可缓存复用)。
  3. 实例化/序列化时由 Rust core 按 schema 执行转换、校验、序列化。

代码或图示

from pydantic import BaseModel, ConfigDict

class Item(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    name: str
    price: float

常见误区

  • 以为 v2 只是 v1 的性能补丁:API 与行为都有破坏性变更,不能只升依赖版本不跑测试。
  • 忽略 pydantic-core 平台 wheel:纯 Python 回退不存在,部署环境需有对应 Rust core wheel。

追问

  • v2 性能主要提升在哪?答:校验与序列化在 Rust 层执行,减少 Python 对象遍历与反射开销。
  • v1 模型能直接跑在 v2 吗?答:官方提供迁移指南与兼容层思路,但旧 API 需逐项改造。
  • schema 编译发生在什么时候?答:模型类定义后首次实例化/构建 schema 时编译并缓存。

04.7.15.2-002 @validator 迁移到 @field_validator 的写法与参数差异?

一句话结论

v1 的 @validator("field", pre=True, allow_reuse=True) 在 v2 改为 @field_validator("field", mode="before"|"after"|"plain");pre 对应 mode="before",always/whole 等旧概念被新模式取代。校验函数签名也调整:类方法第一个参数是 cls,值通过 info 访问上下文,不再用 values 位置参数。

概念解释

  • field_validator 只作用于声明的字段,跨字段逻辑用 model_validator。
  • v2 校验器抛 ValueError 即可,错误位置自动绑定到当前字段。

原理流程

  1. 把旧 @validator 字段列表搬到 @field_validator 第一参数。
  2. pre=True 改为 mode="before";默认 mode="after"。
  3. 校验函数内通过 ValidationInfo 读取已校验字段与上下文,返回清洗后的值。

代码或图示

from pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str

    @field_validator("name", mode="before")
    @classmethod
    def strip_name(cls, v):
        return str(v).strip() if v is not None else v

常见误区

  • 保留 v1 的 allow_reuse/pre 关键字:v2 不识别,迁移后报参数错误。
  • 在 after 校验器里读取尚未校验的兄弟字段:after 模式当前字段已校验,兄弟字段状态通过 info.data 读取。

追问

  • mode="plain" 是什么?答:完全接管该字段校验,不做默认类型转换(待确认:验证点:plain 模式与 before/after 的精确语义)。
  • 校验器必须是类方法吗?答:field_validator 装饰的函数需为 classmethod 形式。
  • 旧 each_item 怎么迁移?答:容器元素校验由 schema 递归处理,元素级约束用字段内类型或 field_validator 配合容器结构。

04.7.15.2-003 inner class Config 迁移到 model_config = ConfigDict(...)?

一句话结论

v1 在模型内写 class Config: 配置项;v2 改为类属性 model_config = ConfigDict(...)。常用项对应迁移:orm_mode→from_attributes、allow_population_by_field_name→populate_by_name、extra 保持同名。配置集中在一处,类型检查友好。

概念解释

  • ConfigDict 是带类型提示的字典类型,替代旧内部 Config 类。
  • 模型继承时 model_config 可被子类覆盖合并,旧 Config 继承行为需重新核对。

原理流程

  1. 把 class Config 内的键值逐项搬到 ConfigDict。
  2. 改名项按 v2 新键名书写。
  3. 模型编译 schema 时读取 model_config 生成对应行为。

代码或图示

from pydantic import BaseModel, ConfigDict

class Product(BaseModel):
    model_config = ConfigDict(
        from_attributes=True,
        populate_by_name=True,
        extra="forbid",
    )
    sku: str

常见误区

  • 混用 class Config 与 model_config:v2 以 model_config 为准,旧内部类不被读取。
  • 配置键名照抄 v1:orm_mode、allow_population_by_field_name 等旧键在 v2 无效。

追问

  • 全局默认配置怎么设?答:模型级 model_config 为主;跨模型公共配置可定义基类模型继承。
  • extra 取值有哪些?答:"ignore"(默认)、"forbid"、"allow"。
  • 配置能在实例化时覆盖吗?答:实例化参数不覆盖模型配置,行为以模型 model_config 为准。

04.7.15.2-004 parse_obj/parse_raw/parse_file 迁移到 model_validate/model_validate_json?

一句话结论

v1 的 Model.parse_obj(data) 在 v2 改为 Model.model_validate(data);parse_raw 按输入类型拆为 model_validate(dict/对象)与 model_validate_json(JSON 字符串/字节);parse_file 读取文件后再调用对应方法。类方法名统一为 model_validate* 前缀。

概念解释

  • model_validate 接收 Python 对象(dict、ORM 实例等);model_validate_json 接收 JSON 文本。
  • v1 一个方法按输入类型猜测,v2 按入口明确区分,行为更可预期。

原理流程

  1. 拿到输入:dict/对象走 model_validate,JSON 串走 model_validate_json。
  2. core schema 执行转换与校验。
  3. 成功返回模型实例,失败抛 ValidationError。

代码或图示

from pydantic import BaseModel

class Item(BaseModel):
    name: str

Item.model_validate({"name": "x"})
Item.model_validate_json('{"name": "x"}')

常见误区

  • 把 JSON 字符串传给 model_validate:它按 Python 对象处理,不会先解析 JSON,应使用 model_validate_json。
  • 继续调用 parse_obj:v2 已移除,运行时 AttributeError。

追问

  • 从 ORM 对象校验用哪个?答:model_validate(orm_obj),需 from_attributes=True。
  • 校验失败抛什么异常?答:pydantic.ValidationError,含错误列表。
  • 有异步校验入口吗?答:model_validate 同步;含 async 校验器时用 model_validate 配套异步入口(待确认:验证点:当前版本异步校验方法名)。

04.7.15.2-005 orm_mode 迁移到 from_attributes?

一句话结论

v1 Config.orm_mode = True 在 v2 为 model_config = ConfigDict(from_attributes=True)。开启后模型可从带属性的对象(ORM 实例、dataclass 等)读取字段,按属性名而非字典键取值;关闭时只接受 dict 映射。

概念解释

  • “ORM 模式”改名强调通用属性读取,不限于 ORM 框架。
  • 读取顺序:先按字段名取属性;别名场景配合 alias/validation_alias。

原理流程

  1. 配置 from_attributes=True。
  2. model_validate(orm_obj) 遍历模型字段,从对象同名属性取值。
  3. 属性值再按字段类型校验转换。

代码或图示

from pydantic import BaseModel, ConfigDict

class UserOut(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    name: str

# user 是 ORM 实例,有 id/name 属性
UserOut.model_validate(user)

常见误区

  • 没开 from_attributes 就传 ORM 实例:v2 按 dict 映射取值,属性访问失败报错。
  • 以为开启后会自动做关系懒加载:属性读取触发 ORM 懒加载,注意 N+1 与会话生命周期。

追问

  • 字段名与属性名不一致怎么办?答:用 validation_alias 声明源属性名。
  • from_attributes 影响序列化吗?答:只影响输入读取;输出仍按模型字段序列化。
  • 能从嵌套 ORM 对象递归读取吗?答:嵌套模型同样开启 from_attributes 后递归取值。

04.7.15.2-006 root_validator 对应 model_validator?

一句话结论

v1 的 @root_validator(pre=True) 在 v2 对应 @model_validator(mode="before"|"after")。before 在字段校验前处理整体输入 dict,after 在所有字段校验后读取已构造的模型做跨字段校验;函数首参分别为 cls(before)或 self(after)。

概念解释

  • 跨字段一致性校验(密码确认、起止时间)放在 after 模式,可访问 self 上已校验字段。
  • before 模式用于清洗整体输入、补默认键、重命名字段。

原理流程

  1. mode="before":拿到原始 dict,清洗/补键后返回 dict。
  2. 字段逐一校验。
  3. mode="after":读取 self 字段做一致性检查,返回 self;失败抛 ValueError。

代码或图示

from pydantic import BaseModel, model_validator

class Range(BaseModel):
    start: int
    end: int

    @model_validator(mode="after")
    def check_order(self):
        if self.start > self.end:
            raise ValueError("start 不能大于 end")
        return self

常见误区

  • 在 after 模式里修改输入 dict:after 阶段模型已构造,应改 self 属性或返回新模型。
  • 用 model_validator 做单字段清洗:单字段逻辑用 field_validator,职责更清晰。

追问

  • before 模式返回什么?答:返回供字段校验使用的 dict(或兼容映射)。
  • 跨字段校验错误挂在哪个字段?答:model_validator 抛出的错误位置为模型根,loc 不含单字段名。
  • 旧 root_validator 的 values 参数还在吗?答:v2 通过模型实例/info 访问,不再是位置 values。

04.7.15.2-007 dict/json 方法迁移到 model_dump/model_dump_json?

一句话结论

v1 的 model.dict() 在 v2 为 model.model_dump();model.json() 为 model.model_dump_json()。两者参数体系重新整理:by_alias、exclude_unset、exclude_defaults、exclude_none、exclude/include 等语义保留但归入新方法签名。

概念解释

  • model_dump() 返回 Python dict;model_dump_json() 返回 JSON 字符串。
  • 序列化配置与输入校验配置分离,字段别名在输出侧由 serialization_alias 控制。

原理流程

  1. 模型实例按字段遍历。
  2. 应用序列化选项:别名、排除未设置/默认/None、include/exclude 集合。
  3. model_dump 产出 dict;model_dump_json 再编码为 JSON 字符串。

代码或图示

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

item = Item(name="x", price=9.9)
item.model_dump()
item.model_dump_json(by_alias=True, exclude_none=True)

常见误区

  • 继续调用 .dict()/.json():v2 已移除,运行时报错。
  • 混淆 model_dump 与 model_validate 方向:前者输出,后者输入。

追问

  • exclude_unset 依据什么判断?答:依据实例化时是否显式传入该字段(未设置用默认值的不计入)。
  • 序列化日期/Decimal 怎么处理?答:按 schema 编码规则输出;自定义编码用模型层配置或序列化器。
  • 能 dump 成嵌套 dict 还是扁平结构?答:默认嵌套结构,与模型字段层级一致。

04.7.15.2-008 allow_population_by_field_name 在 v2 怎么写?

一句话结论

v1 Config.allow_population_by_field_name = True 在 v2 为 ConfigDict(populate_by_name=True)。开启后模型既能按别名填充,也能按字段原名填充;关闭时只接受别名输入。它只影响输入填充,输出别名由序列化别名控制。

概念解释

  • 字段有 alias 时,默认输入只认别名;populate_by_name 放开字段名作为备用键。
  • 典型场景:外部 API 用驼峰别名,内部代码用蛇形字段名,两侧都要能构造模型。

原理流程

  1. 字段声明 alias="userName",配置 populate_by_name=True。
  2. 输入 dict 查找时先匹配别名,再回退字段名。
  3. 命中后赋值给对应字段。

代码或图示

from pydantic import BaseModel, ConfigDict, Field

class User(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    user_name: str = Field(alias="userName")

User.model_validate({"userName": "a"})
User.model_validate({"user_name": "b"})

常见误区

  • 以为 populate_by_name 让输出也用字段名:输出用哪个别名由 serialization_alias/by_alias 决定。
  • 别名与字段名相同还配置此项:无实际影响,属于冗余配置。

追问

  • 关闭时传字段名会怎样?答:字段被视为缺失,按必填/默认值规则报错或填默认值。
  • populate_by_name 与 validation_alias 冲突吗?答:validation_alias 定义输入别名,配置只控制是否放开原名。
  • 输出默认用字段名还是别名?答:默认输出字段名;by_alias=True 时用序列化别名。

04.7.15.2-009 v2 Strict 类型与 v1 严格模式差异?

一句话结论

v2 严格类型(StrictStr、StrictInt、StrictBool 等)来自 pydantic.types,关闭宽松类型转换:字符串 "123" 不会转成 123,1 不会转成 True。v1 也有 Strict 类型,但 v2 严格度由 core schema 统一执行,配合 Annotated[int, Strict()] 可给普通注解加严格约束。

概念解释

  • 默认(宽松)模式允许常见转换:数字字符串转数值、int 转 float;严格模式要求类型字面匹配。
  • 对外边界模型建议严格,避免“字符串数字”被静默接受导致下游问题。

原理流程

  1. 字段标注为 Strict 类型或 Annotated[T, Strict()]。
  2. core schema 生成严格校验规则:类型不符直接报错,不做 coercion。
  3. 校验失败进入 ValidationError。

代码或图示

from typing import Annotated
from pydantic import BaseModel, StrictInt, StrictStr

class A(BaseModel):
    code: StrictStr
    count: Annotated[int, Strict()]

# A(code="1", count=2) 通过;count="2" 报错

常见误区

  • 严格模式下仍传 JSON 数字文本:JSON 解析后类型由 JSON 决定,字符串与数字在 JSON 层就已区分。
  • 把 Strict 当成只校验不转换:严格模式拒绝转换,不是“先转换再检查”。

追问

  • 宽松模式会把 "true" 转 bool 吗?答:宽松模式识别常见布尔字面量;严格模式要求 bool 类型。
  • 严格模式能按字段单独开启吗?答:能,字段级 Strict 类型/注解与模型级配置并存。
  • v1 的 Config.strict 还在吗?答:v2 严格度以类型标注为准(待确认:验证点:模型级 strict 配置项名称)。

04.7.15.2-010 Rust core 带来哪些性能与行为变化?

一句话结论

pydantic-core 用 Rust 实现 schema 执行:校验、转换、序列化在原生层完成,大 payload 与高频请求下 CPU 占用与延迟明显下降;行为上错误类型名、校验顺序、部分转换规则以 Rust 实现为准,v1 时期依赖 Python 子类覆写的扩展点需要改用 v2 扩展机制。

概念解释

  • 性能收益在序列化/校验密集的 API 服务最明显,纯小对象场景差距有限。
  • 行为回归要靠测试套件覆盖:类型转换边界、默认值、错误信息文案。

原理流程

  1. 模型注解编译为 core schema。
  2. 每次校验/序列化调用 Rust core 函数,避免逐层 Python 反射。
  3. 错误结果回填为 Python 异常与错误结构。

代码或图示

# 业务侧无 Rust 代码,定义方式仍是 Python 模型
from pydantic import BaseModel

class Batch(BaseModel):
    items: list["Item"]

常见误区

  • 认为 Rust core 会自动优化模型设计:模型过深、字段过多仍有 schema 与对象构建成本。
  • 依赖 v1 覆写 __get_validators__ 等钩子:v2 自定义类型走 core schema 协议,旧钩子不再生效。

追问

  • schema 编译开销算在哪?答:首次使用时一次性编译并缓存,重复实例化不再重复编译。
  • 错误结构还能在 Python 侧定制吗?答:可通过自定义校验器与错误类型调整,core 层产出基础错误。
  • 部署需要装 Rust 工具链吗?答:不需要,pydantic-core 发布预编译 wheel,运行时不依赖 Rust 编译器。

04.7.15.2-011 BaseModel 实例化校验流程分哪几步?

一句话结论

实例化 Model(**data) 大致分:收集输入 → 按字段查找来源(dict 键/属性/别名)→ core schema 做类型转换与约束校验 → 运行 before/after 校验器 → 填充模型字段;任一步失败抛 ValidationError。默认值在输入缺失时由 schema 填充。

概念解释

  • 校验顺序:字段级 before 校验 → 类型转换/约束 → 字段级 after 校验 → 模型级 after 校验。
  • 嵌套模型递归走同一流程。

原理流程

  1. 构造函数接收输入 dict(或配合 from_attributes 的对象)。
  2. 编译好的 schema 逐字段取值、转换、约束校验。
  3. 执行字段/模型校验器,最终形成不可变语义的模型实例。

代码或图示

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float = 0.0

Item(name="x", price="9.9")  # 宽松模式下字符串转 float

常见误区

  • 以为字段校验并行/乱序:字段按声明顺序处理,跨字段一致性在模型 after 校验器统一检查。
  • 校验失败后仍拿到部分实例:失败即抛异常,不返回半成品模型。

追问

  • 实例化时能跳过校验吗?答:model_construct 可跳过校验直接填充,属于高级用法。
  • 默认值什么时候填?答:输入缺失字段时由 schema 填默认值/default_factory。
  • 嵌套模型什么时候校验?答:外层字段取值后递归校验内层模型。

04.7.15.2-012 core schema 如何从类型注解编译生成?

一句话结论

Pydantic 读取模型的字段注解、Field 约束、model_config 与校验器声明,把它们翻译为 pydantic-core 的 schema 节点(字符串、数值、模型、列表、联合等),首次使用时编译并绑定到模型类。注解解析依赖 typing introspection,复杂泛型与前向引用需先完成解析。

概念解释

  • schema 是“类型 + 约束 + 配置”的中间表示,core 按它执行校验。
  • 前向引用(字符串注解)在模型定义后通过重建 schema 解析。

原理流程

  1. 收集字段注解、默认值、Field 约束与配置。
  2. 递归把注解类型映射为 core schema 节点。
  3. 编译缓存到模型,供后续 model_validate/序列化复用。

代码或图示

from pydantic import BaseModel, Field

class Tag(BaseModel):
    label: str = Field(min_length=1, max_length=20)

class Article(BaseModel):
    title: str
    tags: list[Tag]

常见误区

  • 注解写成字符串且未触发重建:前向引用无法解析,schema 构建报错。
  • 运行时动态修改字段约束:已编译 schema 不会自动重算,需 model_rebuild。

追问

  • 泛型参数何时解析进 schema?答:具体泛型实例化时绑定类型参数再编译。
  • schema 能导出查看吗?答:可通过模型 schema/核心 schema 调试接口检查(待确认:验证点:当前版本公开的 schema 导出方法名)。
  • 多个同类模型会重复编译吗?答:不同模型类各自编译;相同结构复用模型类可共享 schema。

04.7.15.2-013 类型转换 coercion 规则:哪些类型会自动转换?

一句话结论

宽松模式下常见转换会自动发生:数字字符串转 int/float、int 转 float、字符串转 Decimal/UUID/datetime、列表与集合互转等;不可解析或语义不符(如字符串 "abc" 转数值)则报错。严格类型关闭这些转换。具体可转换集合以 pydantic-core 实现为准。

概念解释

  • coercion 是“可安全解释为目标类型”的转换,不是任意字符串映射。
  • 对外接口建议明确哪些转换被允许,避免脏数据静默进入业务层。

原理流程

  1. 输入值按目标类型进入 core 校验节点。
  2. 节点先尝试字面匹配,再尝试允许的 coercion。
  3. 转换失败记录类型错误,进入 ValidationError。

代码或图示

from pydantic import BaseModel

class Demo(BaseModel):
    n: int
    f: float
    flag: bool

Demo(n="42", f="3.14", flag=1)  # 宽松模式通过

常见误区

  • 以为所有字符串都能转数值:非数字字面量直接报错,不会截取前缀。
  • 把宽松转换当成业务清洗:格式规范化应在校验器或业务层显式完成。

追问

  • int 能转 bool 吗?答:严格/宽松规则不同,v2 中数值到布尔的转换以 core 规则为准(待确认:验证点:当前版本 int→bool 是否允许)。
  • 大整数转 float 会丢精度吗?答:会,超出 float 精度范围时损失低位,敏感金额用 Decimal。
  • 转换失败错误类型名是什么?答:错误 type 形如 int_parsing、float_parsing 等 core 错误标识。

04.7.15.2-014 严格模式 StrictStr/StrictInt 与 Annotated[Strict,...]?

一句话结论

Strict 类型有两种等价表达方式:直接用 StrictStr/StrictInt 等内置类型,或 Annotated[int, Strict()] 给原生注解加严格约束。两者都在 schema 层关闭 coercion;Strict() 来自 pydantic,可与其他元数据组合在同一注解里。

概念解释

  • 内置 Strict 类型语义直观;Annotated[..., Strict()] 便于在不改写基础类型的情况下叠加严格度。
  • 严格约束可字段级使用,模型其余字段保持宽松。

原理流程

  1. 字段标注 Strict 类型或叠加 Strict() 元数据。
  2. schema 生成严格校验节点,类型不符即拒绝。
  3. 校验通过后字段持有原生类型值。

代码或图示

from typing import Annotated
from pydantic import BaseModel, StrictStr, Strict, StrictInt

class Card(BaseModel):
    serial: StrictStr
    level: Annotated[StrictInt, Strict()]

常见误区

  • 在 Annotated 里同时放宽松与严格元数据:规则冲突时以 core 实际解析为准,应避免叠加矛盾约束。
  • 以为 Strict 类型会做格式规范化:它只拒绝不匹配输入,不裁剪/补零。

追问

  • 严格模式下 None 怎么处理?答:Optional[StrictInt] 接受 None,非 None 值仍需严格匹配。
  • 容器元素能加 Strict 吗?答:list[StrictInt] 对每个元素生效。
  • 严格类型序列化成什么?答:输出原生类型值,与普通类型序列化格式一致。

04.7.15.2-015 field_validator 的 before/after/plain 模式区别?

一句话结论

mode="before" 在类型转换前执行,接收原始输入值,负责清洗、解析、兜底;mode="after"(默认)在转换与约束校验后执行,拿到已类型化的值做二次检查;mode="plain" 完全接管字段校验,跳过默认转换流程。before 适合入参清洗,after 适合业务规则校验。

概念解释

  • before 拿到的可能是任意类型,需要自行判空与类型兜底。
  • after 值已是目标类型,可直接做范围、格式、一致性检查。

原理流程

  1. 字段输入进入 schema,按模式调用校验器。
  2. before:返回清洗后的值交给后续转换。
  3. after:转换完成后校验器检查值,返回最终字段值。

代码或图示

from pydantic import BaseModel, field_validator

class Phone(BaseModel):
    number: str

    @field_validator("number", mode="before")
    @classmethod
    def clean(cls, v):
        return v.strip() if isinstance(v, str) else v

    @field_validator("number", mode="after")
    @classmethod
    def check(cls, v):
        if len(v) < 7:
            raise ValueError("号码过短")
        return v

常见误区

  • 在 before 模式里假设值已是字符串:原始输入可能是数字、None、列表,需先判类型。
  • after 校验器抛 TypeError 而非 ValueError:校验失败应抛 ValueError,错误才能正确绑定到字段。

追问

  • 一个字段能挂多个校验器吗?答:能,按装饰器/声明顺序依次执行。
  • plain 模式何时用?答:自定义类型完全接管解析时使用,需自行保证校验与返回类型。
  • 校验器能访问兄弟字段吗?答:通过 ValidationInfo.data 读取已校验字段;before 阶段兄弟字段可能尚未校验。

04.7.15.2-016 model_validator 的 before/after 与 cls/self 区别?

一句话结论

@model_validator(mode="before") 是类方法,首参 cls,接收原始输入映射,用于整体清洗、补键、重命名;mode="after" 是实例方法,首参 self,读取已校验字段做跨字段一致性检查并返回 self。before 改输入结构,after 校验业务规则。

概念解释

  • after 模式可访问模型全部已填充字段,适合密码确认、时间区间、金额勾稽等跨字段规则。
  • before 模式返回 dict/映射;after 模式返回模型实例。

原理流程

  1. 原始输入先进入 before 模型校验器,清洗后交给字段校验。
  2. 字段逐一转换校验。
  3. after 模型校验器读取 self,做一致性检查,失败抛 ValueError。

代码或图示

from pydantic import BaseModel, model_validator

class Signup(BaseModel):
    password: str
    confirm: str

    @model_validator(mode="after")
    def passwords_match(self):
        if self.password != self.confirm:
            raise ValueError("两次密码不一致")
        return self

常见误区

  • after 模式里修改输入 dict 而不是 self:after 阶段没有原始 dict,应改实例属性。
  • before 模式返回非映射对象:字段校验期望映射结构,返回类型不符会报错。

追问

  • 跨字段错误挂在哪个字段?答:模型级错误 loc 为根层级,不绑定单字段;需要字段级定位可在字段校验器内比较。
  • before 能做默认值补充吗?答:能,缺失键在此阶段补上再进入字段校验。
  • 模型校验器能访问上下文吗?答:通过 ValidationInfo 参数读取校验上下文与已校验数据。

04.7.15.2-017 validation_alias 与 before 校验如何配合?

一句话结论

validation_alias 声明输入时使用的别名,框架按别名从输入映射取值;mode="before" 校验器在转换前拿到原始值,可在取值后再做格式清洗。两者分层:alias 解决“从哪个键取”,before 校验器解决“取到的值如何清洗”。

概念解释

  • 与 Field(alias=...) 相比,validation_alias 明确区分输入别名;输出别名用 serialization_alias。
  • 别名映射在 schema 编译期固定,before 校验器不改变键名查找。

原理流程

  1. 输入 dict 按 validation_alias(或字段名)查找取值。
  2. 命中值进入 before 字段校验器清洗。
  3. 清洗结果进入类型转换与约束校验。

代码或图示

from pydantic import BaseModel, Field, field_validator

class Address(BaseModel):
    city: str = Field(validation_alias="cityName")

    @field_validator("city", mode="before")
    @classmethod
    def trim(cls, v):
        return v.strip() if isinstance(v, str) else v

常见误区

  • 用 before 校验器手动改键名替代 alias:别名查找由 schema 完成,手写键名映射容易遗漏配置。
  • 混淆 validation_alias 与 serialization_alias:前者管输入,后者管输出,混用会导致文档与响应字段错位。

追问

  • 一个字段能接受多个输入别名吗?答:可用 AliasChoices 声明多个候选输入名(待确认:验证点:当前版本 AliasChoices 用法与导出行为)。
  • 别名区分大小写吗?答:按输入映射原样匹配,建议前后端统一大小写约定。
  • populate_by_name 与 alias 关系?答:开启后除别名外字段名也可作为输入键。

04.7.15.2-018 嵌套模型递归校验与默认值填充时机?

一句话结论

外层模型字段取值后,嵌套字段按其模型定义递归走完整校验流程;嵌套层缺失的字段在该层填充默认值/default_factory,不会借用外层默认值。列表、字典内的模型元素同样逐个递归校验。

概念解释

  • 嵌套模型是独立 schema,错误位置沿外层字段 → 内层字段 → 列表索引记录。
  • 默认值在对应层级填充,外层无法为内层字段兜底默认。

原理流程

  1. 外层字段取出嵌套输入(dict/对象)。
  2. 调用内层模型 model_validate 递归校验。
  3. 内层缺失字段填默认值,嵌套结果挂回外层实例。

代码或图示

from pydantic import BaseModel

class Geo(BaseModel):
    lat: float
    lng: float
    radius: int = 100

class Place(BaseModel):
    name: str
    geo: Geo

常见误区

  • 以为内层字段缺省会用外层默认值填充:各层默认值独立,内层缺失无默认则报错。
  • 嵌套对象传 None 给非 Optional 字段:类型校验失败,需显式 Optional[Geo]。

追问

  • 嵌套模型校验失败会中断外层吗?答:失败抛 ValidationError,外层实例不生成。
  • 嵌套 ORM 对象读取需要每层开 from_attributes 吗?答:需要,每个嵌套模型独立配置。
  • 深嵌套性能如何?答:每一层都有 schema 遍历与对象构造,过深嵌套在大请求体下是 CPU 开销点。

04.7.15.2-019 Extra 字段处理 ignore/forbid/allow 配置?

一句话结论

model_config = ConfigDict(extra="...") 控制模型未声明字段的处理:"ignore"(默认)丢弃多余输入;"forbid" 遇到多余字段直接校验报错;"allow" 把多余字段保留为模型额外属性。FastAPI 请求体模型默认 ignore,严格契约场景可用 forbid 拦截脏字段。

概念解释

  • extra 只影响输入侧;序列化时 allow 的额外字段是否输出取决于序列化配置。
  • 嵌套模型各自独立处理 extra,不继承外层策略。

原理流程

  1. 输入映射中遍历到未声明键。
  2. 按 extra 配置:忽略、报错或收进额外字段集合。
  3. forbid 模式错误位置指向多余键名。

代码或图示

from pydantic import BaseModel, ConfigDict

class StrictModel(BaseModel):
    model_config = ConfigDict(extra="forbid")
    name: str

# StrictModel(name="a", age=1)  → 校验报错

常见误区

  • 生产 API 用默认 ignore 导致前端拼错字段名被静默吞掉:调试期可开 forbid 暴露契约偏离。
  • allow 模式后期望额外字段进入类型化注解:额外字段无类型标注,访问需按 dict/动态属性处理。

追问

  • extra 配置能按字段覆盖吗?答:模型级配置,单字段不单独设置 extra 策略。
  • allow 的额外字段会出现在 OpenAPI 吗?答:文档以声明字段为准,额外字段不自动生成 Schema。
  • 序列化时忽略额外字段吗?答:默认 dump 包含 allow 的额外字段,可通过 exclude 选项排除。

04.7.15.2-020 默认值、可变默认值与 Field(default_factory)?

一句话结论

字段直接写可变默认值(列表/字典)在 Pydantic 中按规则处理:推荐用 Field(default_factory=工厂函数) 为每个实例生成独立可变对象;不可变默认值可直接写。default 提供静态默认,default_factory 每次实例化调用工厂生成新值。

概念解释

  • default_factory 接收零参可调用,适合空列表、uuid4()、datetime.now() 等每次需新值的场景。
  • 默认值在输入缺失时填充;显式传 None 不会被默认值覆盖(除非字段 Optional 且语义允许)。

原理流程

  1. 字段定义时记录 default 或 default_factory。
  2. 输入缺失该字段:调用工厂或取静态默认。
  3. 实例持有该默认值副本,各实例互不影响。

代码或图示

from uuid import uuid4
from pydantic import BaseModel, Field

class Ticket(BaseModel):
    tags: list[str] = Field(default_factory=list)
    uid: str = Field(default_factory=lambda: uuid4().hex)

常见误区

  • 用 = [] 作为字段默认:Pydantic 会处理可变默认,但 default_factory=list 是规范写法,跨版本行为明确。
  • 在 default_factory 里依赖全局可变状态:工厂每次执行,避免返回共享可变对象。

追问

  • default_factory 能接收参数吗?答:零参调用;需要上下文值用校验器或模型方法补充。
  • 字段必填如何表达?答:无默认值且非 Optional,输入缺失即报错。
  • 默认值参与 exclude_defaults 序列化吗?答:被视为默认值,exclude_defaults=True 时排除。

04.7.15.2-021 Field 约束 gt/ge/lt/le/min_length/max_length/pattern?

一句话结论

Field 为数值提供 gt/ge/lt/le/multiple_of,为字符串提供 min_length/max_length/pattern,为容器提供长度约束。约束既在运行时校验,也进入 JSON Schema 与 FastAPI OpenAPI 文档。

概念解释

  • 数值边界:gt 严格大于,ge 大于等于;字符串长度按字符计。
  • pattern 是正则约束,v2 替代 v1 的 regex 参数。

原理流程

  1. 字段声明时约束写入 schema 节点。
  2. 校验期值通过类型转换后逐项检查边界。
  3. 违反约束生成对应错误类型(如 string_too_short、greater_than)。

代码或图示

from pydantic import BaseModel, Field

class Book(BaseModel):
    title: str = Field(min_length=1, max_length=100, pattern=r"^\S")
    pages: int = Field(gt=0, le=10000)

常见误区

  • 把约束写成 Python 比较表达式:Field(gt=0) 传关键字,不能写 Field(>0)。
  • 正则未锚定首尾:pattern 匹配子串即可,需完整匹配时加 ^...$。

追问

  • 约束错误在 422 中如何展示?答:loc 定位字段,type 为约束错误标识,msg 为说明。
  • 列表长度约束写哪个参数?答:min_length/max_length 作用于容器长度。
  • multiple_of 支持浮点吗?答:主要用于整数;浮点倍数精度问题需业务层复核。

04.7.15.2-022 Annotated[X, Field(...)] 与 = Field(...) 写法?

一句话结论

两种写法等价:name: str = Field(min_length=1) 用默认值携带约束;name: Annotated[str, Field(min_length=1)] 把约束放进类型注解。Annotated 写法便于把“类型 + 约束”打包成可复用别名,是 v2/FastAPI 0.11x 推荐风格。

概念解释

  • Annotated 元数据可跨模块复用,统一全局字符串长度、分页大小等约束。
  • 框架从两种来源提取同一套字段元数据。

原理流程

  1. 注册期读取字段注解与默认值,合并 Field 约束。
  2. 约束进入 schema 与 OpenAPI 生成。
  3. 校验期按约束执行。

代码或图示

from typing import Annotated
from pydantic import BaseModel, Field

Name = Annotated[str, Field(min_length=1, max_length=30)]

class Person(BaseModel):
    name: Name
    email: str = Field(pattern=r"^[^@]+@[^@]+$")

常见误区

  • 同一字段在注解与默认值里重复声明冲突约束:行为以合并结果为准,易产生歧义,应只写一处。
  • 把 Field 放进 Annotated 后又依赖旧 v1 钩子:元数据提取按 v2 机制走。

追问

  • 别名能写在 Annotated 里吗?答:能,Field(alias=...) 作为元数据放入。
  • 复用别名修改约束影响面多大?答:所有引用处继承,改别名需全局评审。
  • Python 3.8 支持吗?答:需 typing_extensions.Annotated。

04.7.15.2-023 description/examples/json_schema_extra 如何进 OpenAPI?

一句话结论

Field(description=...) 生成字段描述,examples 给出示例值,json_schema_extra 注入自定义 OpenAPI 扩展键。这些元数据在生成 JSON Schema 时合并,FastAPI 再把模型 Schema 带进 /openapi.json。

概念解释

  • description 同时服务文档与代码可读性;examples 供 Swagger 展示试填值。
  • json_schema_extra 用于标准 Field 参数未覆盖的 Schema 关键字。

原理流程

  1. 字段元数据收集到模型 schema。
  2. 导出 JSON Schema 时写入对应关键字。
  3. FastAPI 端点引用模型后,Schema 出现在请求/响应组件中。

代码或图示

from pydantic import BaseModel, Field

class Product(BaseModel):
    sku: str = Field(
        description="商品 SKU,大写字母加数字",
        examples=["A001"],
        json_schema_extra={"format": "sku-code"},
    )

常见误区

  • 把业务校验规则写进 description 替代实际校验:文档说明不产生运行时约束。
  • json_schema_extra 与标准关键字重复:重复键可能被覆盖,自定义内容放在扩展位置。

追问

  • 模型级示例怎么写?答:模型 model_config 或端点 openapi_extra 补充(待确认:验证点:模型级 examples 配置键)。
  • examples 支持多个值吗?答:examples 可传列表,按 Schema 规范展示。
  • 隐藏字段不出现在文档怎么做?答:Field 标注 exclude/响应模型裁剪,或在端点参数 include_in_schema=False。

04.7.15.2-024 int/float/Decimal 在 JSON 中的转换边界?

一句话结论

JSON 数字无内置 Decimal/Date 类型:int/float 直接编码;Decimal 按配置序列化为字符串或数字(v2 默认行为以 core 实现为准);高精度金额应使用 Decimal 避免二进制浮点误差。输入侧宽松模式可把数字字符串转数值,严格模式要求字面类型匹配。

概念解释

  • float 存在精度损失,金额、计量等敏感场景不用 float 存储与计算。
  • Decimal 序列化格式需前后端约定,避免客户端按 float 解析丢精度。

原理流程

  1. 输入 JSON 数字进入字段类型校验节点。
  2. int/float 直接保留;Decimal 按十进制解析。
  3. 序列化时按类型编码:数值或字符串形式。

代码或图示

from decimal import Decimal
from pydantic import BaseModel

class Order(BaseModel):
    amount: Decimal
    quantity: int
    weight: float

常见误区

  • 金额用 float 存储:0.1+0.2 类误差累积,对账出现尾差。
  • 直接把 Decimal 转 float 再传输:精度在转换环节丢失,应保持 Decimal 字符串/定点格式。

追问

  • Decimal 能校验精度/位数吗?答:可用字段约束或校验器限制小数位;schema 基础类型不内置小数位约束。
  • JSON 字符串数字能转 Decimal 吗?答:宽松模式可解析字符串形式的十进制值。
  • 序列化输出字符串还是数字?答:v2 默认按类型规则,自定义格式通过序列化器/模型配置控制(待确认:验证点:Decimal 默认序列化形态)。

04.7.15.2-025 Enum/Literal 字段校验与序列化取值?

一句话结论

Enum 字段只接受枚举成员值(或成员名,按配置),校验通过后持有枚举实例;Literal 限定为字面量集合中的一个值。序列化时默认输出枚举成员的值(value),可配置输出成员名。str, Enum 混合类型可直接当字符串比较使用。

概念解释

  • Literal[ "a", "b" ] 是类型层面的联合字面量,无需定义枚举类。
  • 枚举取值进 OpenAPI 文档为允许值集合。

原理流程

  1. 输入值与枚举成员/字面量集合匹配。
  2. 命中后字段持有枚举实例或字面量值。
  3. 序列化按枚举序列化策略输出 value 或 name。

代码或图示

from enum import Enum
from typing import Literal
from pydantic import BaseModel

class Status(str, Enum):
    active = "active"
    archived = "archived"

class Task(BaseModel):
    status: Status
    priority: Literal["low", "mid", "high"]

常见误区

  • 枚举字段传成员名而非值导致校验失败:需确认输入约定是 value 还是 name。
  • 序列化后仍按枚举实例使用:dump 结果是纯值,下游不要再访问 .value。

追问

  • 枚举能输出成员名吗?答:通过模型/字段序列化配置调整序列化模式(待确认:验证点:v2 枚举序列化配置键名)。
  • Literal 支持混合类型吗?答:可混合字符串/数字字面量,但 JSON 交换建议保持单一类型。
  • 枚举扩展新成员需要改模型吗?答:新增成员即扩展允许值,旧客户端传入新值需版本兼容评估。

04.7.15.2-026 list/set/tuple/dict 容器字段校验?

一句话结论

容器字段按元素类型递归校验:list[T] 校验每个元素为 T,set[T] 去重并校验,tuple[T, ...] 变长元组,dict[K, V] 校验键与值。容器本身可加长度约束;元素级校验失败的错误位置带索引/键名。

概念解释

  • v2 泛型容器由 core schema 递归展开,元素类型校验与标量一致。
  • tuple[int, int] 定长;tuple[int, ...] 变长。

原理流程

  1. 输入容器进入对应容器 schema 节点。
  2. 逐个元素/键值按元素类型校验。
  3. 全部通过后构造容器实例,失败位置记录索引。

代码或图示

from pydantic import BaseModel, Field

class Batch(BaseModel):
    tags: set[str] = Field(min_length=1)
    coords: tuple[float, float]
    meta: dict[str, str]

常见误区

  • 把 list 写成无元素注解:元素按任意类型校验,失去类型约束。
  • 期望 set 保留顺序:集合无序,需要顺序用 list。

追问

  • 嵌套容器 list[list[int]] 支持吗?答:支持,递归展开 schema。
  • 元素校验失败会中断整个容器吗?答:收集所有元素错误后统一抛 ValidationError。
  • 容器长度约束参数是什么?答:min_length/max_length。

04.7.15.2-027 Optional 与 None:必填判定?

一句话结论

Optional[T] 等价 T | None:字段可填 None;是否必填取决于有无默认值。Optional[T] 无默认值时仍必填,只是允许传入 None;Optional[T] = None 才是可选、缺省为 None。输入显式传 None 与字段缺失是两种情况。

概念解释

  • 必填判定:无默认值且非带默认工厂 → 输入缺失报错。
  • None 是合法值,不等于“未设置”;exclude_unset 依据是否显式传入判断。

原理流程

  1. 字段注解标记是否接受 None。
  2. 输入缺失:查默认值/工厂,无则报错。
  3. 输入为 None:类型校验允许 None 则赋值,否则报错。

代码或图示

from typing import Optional
from pydantic import BaseModel

class Profile(BaseModel):
    nickname: Optional[str]        # 必填,但可为 None
    bio: Optional[str] = None       # 可选,缺省 None

常见误区

  • 以为 Optional 就是可选字段:Optional 只表示允许 None,可选与否看默认值。
  • 区分不清“未设置”和“显式 None”:序列化 exclude_unset 时二者表现不同。

追问

  • str | None 与 Optional[str] 等价吗?答:Python 3.10+ 语义等价,3.9 用 Optional 写法。
  • 字段缺省空列表怎么写?答:list[str] = Field(default_factory=list),不要用 Optional 表达空容器。
  • None 能通过严格类型校验吗?答:Optional[StrictInt] 接受 None,非 None 值仍严格匹配。

04.7.15.2-028 alias 与 populate_by_name 的双向行为?

一句话结论

Field(alias=...) 定义输入输出使用的别名;populate_by_name=True 放开字段名作为输入备用键。别名默认同时作用于输入与输出;需要输入/输出分离时用 validation_alias + serialization_alias。双向行为:开 populate 后两种输入键都可填充,输出仍按别名策略。

概念解释

  • 驼峰对外、蛇形对内是典型别名场景。
  • 字段名是 Python 侧标识,别名是协议侧标识。

原理流程

  1. 声明字段名与别名。
  2. 输入查找:先别名,开启 populate 后回退字段名。
  3. 输出序列化按序列化别名/字段名生成键。

代码或图示

from pydantic import BaseModel, ConfigDict, Field

class User(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    user_name: str = Field(alias="userName")

常见误区

  • 开了 populate 就以为输出也用字段名:输出由 serialization 别名/by_alias 决定。
  • 别名与字段名语义不一致导致文档困惑:对外文档以别名为契约,代码内用字段名。

追问

  • 关闭 populate 传字段名会怎样?答:字段视为缺失,按必填规则报错。
  • 一个字段能有多个输入别名吗?答:用 AliasChoices 声明候选列表。
  • 改别名需要同步前端吗?答:别名是 API 契约的一部分,变更需版本兼容。

04.7.15.2-029 serialization_alias 与 alias 的区别?

一句话结论

alias 同时设置输入与输出别名;validation_alias 只管输入取值,serialization_alias 只管输出键名。需要“外部驼峰输入、内部蛇形存储、另一种驼峰输出”或输入输出别名不同时,使用分离的两个别名声明。

概念解释

  • 输入别名服务 model_validate,输出别名服务 model_dump(by_alias=True)。
  • 分离别名避免协议变更时改动内部字段命名。

原理流程

  1. 字段分别声明 validation 与 serialization 别名。
  2. 校验期按输入别名查找;序列化期按输出别名生成键。
  3. 两者独立,可不一致。

代码或图示

from pydantic import BaseModel, Field

class Record(BaseModel):
    internal_name: str = Field(
        validation_alias="inputName",
        serialization_alias="outputName",
    )

常见误区

  • 用 alias 后想单独改输出键:旧别名已绑定输入,需拆分为 validation/serialization 别名。
  • 序列化不开 by_alias:serialization_alias 只在按别名序列化时生效,默认输出字段名。

追问

  • by_alias=True 用哪个别名?答:优先 serialization_alias,未设置回退 alias。
  • 输入别名与输出别名相同还需要分离声明吗?答:用 alias 统一即可。
  • 别名会影响 ORM 属性读取吗?答:from_attributes 按 validation 别名/字段名查找属性。

04.7.15.2-030 校验别名与序列化别名分离场景?

一句话结论

典型分离场景:第三方回调字段名与内部存储名不同、响应 DTO 对外字段名与请求 DTO 不同、版本演进中输入字段保留旧名而输出切换新名。分离后内部模型字段名稳定,协议层差异由别名吸收,避免为每个方向复制模型。

概念解释

  • 请求模型与响应模型本就建议分开;同一模型内分离别名适用于输入输出契约确实不同的场景。
  • 别名分离需在 OpenAPI 文档中保持前后端可见约定一致。

原理流程

  1. 定义内部字段名,声明输入别名兼容旧协议。
  2. 声明输出别名对应新协议字段。
  3. 校验与序列化各取所需别名,内部代码访问字段名。

代码或图示

from pydantic import BaseModel, Field

class MigrationRecord(BaseModel):
    title: str = Field(validation_alias="old_title", serialization_alias="title_v2")

常见误区

  • 一个模型同时承担请求、响应、持久化三种角色:字段与别名互相牵制,复杂场景应拆分 DTO。
  • 输出别名变更后未更新前端:响应键名属于契约,需配合版本公告与联调。

追问

  • 分离别名能做字段重命名迁移吗?答:可作为过渡,输入兼容旧名、输出新名,稳定后再收敛。
  • 别名分离影响 model_dump(by_alias=False) 吗?答:不开 by_alias 时输出字段名,忽略别名。
  • ORM 映射用哪个别名?答:输入侧 validation 别名对应属性名查找。

04.7.15.2-031 response_model 做了什么:输入校验与输出裁剪两条链路?

一句话结论

response_model 作用于响应侧:端点返回值按该模型再校验、按字段集合裁剪并序列化;请求体模型作用于输入侧。两条链路独立——输入模型约束客户端发什么,响应模型约束服务端返回什么。返回 ORM 实例或内部对象时,响应模型负责把对外字段之外的内部信息排除掉。

概念解释

  • 未声明 response_model 时,框架按返回类型注解推断;无注解则直接序列化返回值。
  • 响应模型校验失败属于输出层错误,需与输入 422 区分排查。

原理流程

  1. 端点执行返回内部对象(ORM/ dict /模型实例)。
  2. 框架用 response_model 对返回值做输出校验与字段过滤。
  3. 序列化生成最终 JSON 响应。

代码或图示

class UserIn(BaseModel):
    username: str
    password: str

class UserOut(BaseModel):
    id: int
    username: str

@app.post("/users", response_model=UserOut)
def create(user: UserIn):
    return repo.create(user)   # 密码字段不会出现在响应中

常见误区

  • 以为输入模型复用为响应模型就能自动隐藏敏感字段:同模型会暴露全部字段,敏感字段需单独响应模型。
  • 端点返回 Response 实例后响应模型仍生效:显式 Response 跳过模型裁剪,字段暴露自行负责。

追问

  • 响应模型会校验返回值类型吗?答:会做输出校验与转换,类型不符进入序列化错误处理。
  • 列表响应怎么声明模型?答:response_model=list[ItemOut] 或在返回注解中标注列表模型。
  • 响应模型与返回注解冲突时谁优先?答:显式 response_model 优先于返回类型注解推断。

04.7.15.2-032 response_model_exclude_unset/exclude_defaults/exclude_none 区别?

一句话结论

exclude_unset 排除实例化时未显式传入的字段;exclude_defaults 排除等于默认值的字段;exclude_none 排除值为 None 的字段。三者可组合,作用于响应模型序列化,控制响应体字段稀疏度。未设置、默认值、None 是三种不同判定依据。

概念解释

  • exclude_unset 依赖模型记录“哪些字段被显式传入”,适合 PATCH 部分更新回显。
  • exclude_defaults 按默认值比较;exclude_none 按空值过滤。

原理流程

  1. 响应模型遍历字段。
  2. 按各排除选项判定字段是否输出。
  3. 剩余字段序列化进响应 dict。

代码或图示

@app.get("/items/{i}", response_model=ItemOut,
         response_model_exclude_none=True,
         response_model_exclude_unset=True)
def item(i: int):
    return repo.get(i)

常见误区

  • 混淆 unset 与 None:字段缺省为 None 时,unset 排除未传字段,None 排除空值字段,判定不同。
  • 对 ORM 对象使用 exclude_unset:ORM 实例不携带“是否显式设置”的记录,unset 判定可能不符合预期。

追问

  • 三个选项能同时开吗?答:可以,字段满足任一排除条件即不输出。
  • exclude_defaults 比较什么?答:与字段默认值做相等比较,复杂对象注意相等语义。
  • 排除字段会出现在 OpenAPI 吗?答:文档 Schema 仍含全部字段,排除只影响运行时响应体。

04.7.15.2-033 端点返回 dict 时 response_model 如何再校验?

一句话结论

端点返回普通 dict 时,框架按 response_model 把 dict 当作输入走一次模型校验:缺失必填字段报错、类型做转换、多余字段按模型配置处理,然后按模型字段序列化输出。返回 dict 不等于跳过模型约束,响应模型是输出侧的第二道校验。

概念解释

  • dict 键名与模型字段/别名匹配;类型不符在输出校验阶段暴露。
  • 内部服务组装 dict 时字段名要与响应模型对齐,否则被裁剪或报错。

原理流程

  1. 端点返回 dict。
  2. 框架以响应模型 model_validate 该 dict。
  3. 校验通过后 model_dump 序列化,失败按输出错误处理。

代码或图示

@app.get("/x", response_model=ItemOut)
def x():
    return {"id": 1, "name": "demo", "internal": "secret"}
    # internal 不在 ItemOut 字段中,被裁剪

常见误区

  • 以为返回 dict 可以绕过响应模型暴露内部字段:模型裁剪仍按声明字段执行。
  • dict 值类型与模型不符导致 500/校验错误:输出校验同样做类型转换,宽松与严格行为需核对。

追问

  • 返回模型实例还会再过一次校验吗?答:实例已是模型,序列化按模型字段输出;输出模型与实例类型不同时会再校验。
  • dict 嵌套对象能递归校验吗?答:响应模型嵌套字段递归走 validate。
  • 输出校验失败默认返回什么?答:按框架错误处理流程,通常 500(待确认:验证点:当前版本响应校验失败状态码约定)。

04.7.15.2-034 from_attributes=True 如何从 ORM 对象取值?

一句话结论

开启 from_attributes 后,model_validate(orm_obj) 不再按字典键取值,而是遍历模型字段读取对象同名属性;属性值再按字段类型校验。ORM 实例、dataclass、普通带属性对象都适用,是 SQLAlchemy/ORM 实体转 DTO 的标准入口。

概念解释

  • 属性名与字段名不一致时用 validation_alias 映射源属性名。
  • 读取属性可能触发 ORM 懒加载,注意会话生命周期与 N+1。

原理流程

  1. 模型配置 from_attributes=True。
  2. 遍历字段,从输入对象读取同名属性。
  3. 属性值经类型校验后填充模型字段。

代码或图示

from pydantic import BaseModel, ConfigDict

class UserDTO(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    name: str

dto = UserDTO.model_validate(orm_user)

常见误区

  • 未开启配置就传 ORM 实例:框架按 dict 取值,属性访问失败报错。
  • 序列化阶段仍依赖 ORM 会话:模型已拷贝字段值,但嵌套懒加载属性若未读取,序列化时可能触发会话外访问。

追问

  • 嵌套 ORM 对象需要每层开启吗?答:需要,嵌套 DTO 各自配置 from_attributes。
  • 属性是可调用方法会被调用吗?答:按属性读取,方法属性需在 ORM 侧暴露为计算属性或在 DTO 校验器处理。
  • from_attributes 支持别名映射吗?答:支持,validation_alias 对应源属性名。

04.7.15.2-035 模型继承与 response_model 字段裁剪?

一句话结论

Pydantic 模型继承父类字段并可新增/覆写;响应模型裁剪基于最终模型声明的字段集合。父类公共字段抽到基类,子类扩展业务字段;对外响应只暴露响应模型自身字段,继承来的字段同样参与裁剪。

概念解释

  • 覆写字段类型需与父类兼容;model_config 子类可覆盖父类配置。
  • 基类模型可只定义公共字段,不直接作为响应模型。

原理流程

  1. 子类继承父类字段定义。
  2. 合并字段、覆写与配置。
  3. 响应序列化按合并后的字段集合裁剪输出。

代码或图示

class BaseOut(BaseModel):
    id: int
    name: str

class ProductOut(BaseOut):
    price: float

@app.get("/p/{i}", response_model=ProductOut)
def p(i: int):
    return repo.get(i)

常见误区

  • 继承后以为父类私有字段也会输出:输出以子类最终字段集合为准,未声明的父类内部字段不暴露。
  • 子类覆写字段放宽/收紧类型未评估兼容:响应契约变化需版本确认。

追问

  • 继承模型能复用 Field 约束吗?答:父类字段约束被子类继承,子类可覆写 Field。
  • 多层继承 schema 会重复编译吗?答:每个具体模型独立编译 schema。
  • 抽象基类怎么标记?答:普通基类不实例化即可,Pydantic 无专门抽象模型标记(待确认:验证点:v2 是否提供抽象模型配置)。

04.7.15.2-036 嵌套响应模型字段过滤是否递归?

一句话结论

响应模型裁剪递归作用于嵌套字段:外层模型排除的字段不输出,内层嵌套模型按其自身字段集合序列化。exclude_unset/exclude_defaults/exclude_none 等选项同样沿嵌套层级生效;嵌套模型未声明的字段不会出现在响应中。

概念解释

  • 嵌套 DTO 独立定义字段集合,外层不能通过配置把内层隐藏字段带出。
  • 嵌套 ORM 对象需内层模型开启 from_attributes 才能读取属性。

原理流程

  1. 外层响应模型遍历字段,识别嵌套模型字段。
  2. 嵌套值按内层模型校验与裁剪。
  3. 递归完成后组装嵌套 dict 输出。

代码或图示

class GeoOut(BaseModel):
    lat: float
    lng: float

class PlaceOut(BaseModel):
    name: str
    geo: GeoOut

@app.get("/place/{i}", response_model=PlaceOut)
def place(i: int):
    return repo.get(i)

常见误区

  • 以为外层 exclude 选项能影响内层字段是否存在:内层按自身模型与选项独立过滤。
  • 嵌套对象传 dict 键名与内层模型不符:内层校验失败,整个响应序列化报错。

追问

  • 列表内嵌套模型也递归裁剪吗?答:是,列表元素逐个按内层模型序列化。
  • 嵌套模型能复用外层排除选项吗?答:响应排除选项沿层级传递应用。
  • 嵌套字段为 None 时输出什么?答:按 exclude_none 配置决定是否保留 None 键。

04.7.15.2-037 response_model 与返回 BaseModel 实例的关系?

一句话结论

端点返回已是 BaseModel 实例时,若类型与 response_model 一致,框架直接按模型序列化;类型不同则按响应模型再校验转换。返回模型实例本身不绕过响应模型的字段裁剪,未在响应模型声明的字段仍不输出。

概念解释

  • 内部模型与对外 DTO 分离是常见做法:内部模型含完整字段,响应模型裁剪对外字段。
  • 直接返回内部模型且未声明响应模型时,全部字段会序列化外泄。

原理流程

  1. 端点返回模型实例。
  2. 框架比对返回类型与响应模型。
  3. 按响应模型字段集合序列化输出。

代码或图示

class InternalUser(BaseModel):
    id: int
    name: str
    password_hash: str

@app.get("/me", response_model=UserOut)
def me():
    return InternalUser(id=1, name="a", password_hash="x")
    # password_hash 不在 UserOut,被裁剪

常见误区

  • 直接返回内部模型且不设响应模型:敏感字段随序列化外泄,是常见安全问题。
  • 以为返回实例就跳过输出校验:模型类型不符时仍会触发校验转换。

追问

  • 响应模型可以是返回实例的父类吗?答:可以,按父类字段集合裁剪输出。
  • 模型实例怎么转成响应模型?答:ResponseModel.model_validate(internal) 显式转换,或依赖端点响应模型处理。
  • 序列化内部模型用哪个方法?答:model_dump()/model_dump_json(),按需要带排除选项。

04.7.15.2-038 泛型模型 GenericModel 定义与实例化?

一句话结论

Pydantic v2 泛型模型继承 BaseModel 并配合 Generic[T] 定义,类型参数在具体使用时绑定(如 Response[Item])。泛型字段类型随参数实例化,可复用分页包装、统一响应信封等结构;schema 在绑定具体类型后编译。

概念解释

  • v2 泛型写法与标准 typing.Generic 结合,不再依赖 v1 的 GenericModel 基类(待确认:验证点:当前版本泛型模型基类与导入路径)。
  • 泛型参数可约束为特定类型边界。

原理流程

  1. 定义模型类,声明 Generic[T] 并在字段注解中使用 T。
  2. 使用时 Model[ConcreteType] 绑定类型参数。
  3. core schema 按绑定后的具体类型编译校验。

代码或图示

from typing import Generic, TypeVar
from pydantic import BaseModel

T = TypeVar("T")

class Envelope(BaseModel, Generic[T]):
    code: int
    data: T

class Item(BaseModel):
    name: str

# 绑定后:Envelope[Item]

常见误区

  • 泛型模型未绑定类型就实例化:T 未解析,schema 无法确定字段类型。
  • 泛型参数在嵌套模型中丢失:嵌套引用需显式传递类型参数。

追问

  • 泛型能有多个参数吗?答:能,Generic[K, V] 配合字典/二元结构。
  • 泛型模型进 OpenAPI 会展开吗?答:FastAPI 按绑定后的具体类型生成组件 Schema。
  • 泛型默认类型怎么设?答:TypeVar 可带边界与默认值(待确认:验证点:v2 TypeVar 默认值支持情况)。

04.7.15.2-039 RootModel 单根值/列表包裹场景?

一句话结论

RootModel 用于模型根值不是对象而是单个值、列表或字典的场景:root 字段承载根数据,适合包装数组、标量集合等“非 JSON 对象”的请求/响应。普通 BaseModel 要求根是键值对象,根为数组时用 RootModel[list[Item]]。

概念解释

  • 访问根值通过 .root 属性;序列化后根值直接作为 JSON 数组/标量,不包一层对象。
  • 适合 Webhook 批量事件、纯列表接口等协议结构。

原理流程

  1. 定义 class Batch(RootModel[list[Item]]): ...。
  2. 输入校验作用于根类型(列表及其元素)。
  3. 序列化输出根值本身,而非 {"root": [...]} 包装。

代码或图示

from pydantic import RootModel

class Item(BaseModel):
    name: str

class ItemList(RootModel[list[Item]]):
    pass

parsed = ItemList.model_validate([{"name": "a"}])
parsed.root  # list[Item]

常见误区

  • 把 RootModel 当普通模型访问字段:根值在 .root,没有同名业务字段。
  • 序列化后期望外层包对象:RootModel 输出根值,需要信封结构用普通泛型模型。

追问

  • RootModel 能包标量吗?答:能,RootModel[str] 等单根类型均可。
  • RootModel 支持校验器吗?答:支持,字段/模型校验器作用于根值。
  • FastAPI 端点能直接用 RootModel 作 Body 吗?答:可以,请求体按根类型解析。

04.7.15.2-040 Discriminated Union 判别字段与性能收益?

一句话结论

可辨识联合用一个判别字段(discriminator)区分联合中的多个模型,校验时先读判别值直接选中对应模型,避免逐个尝试所有联合成员。相比普通 Union 的顺序尝试,判别联合校验更快、错误信息更明确,适合事件类型、多态请求体等场景。

概念解释

  • 判别字段在每个成员模型中声明,值唯一区分成员。
  • 用 Field(discriminator="type") 或 Discriminator 标注联合。

原理流程

  1. 输入先取判别字段值。
  2. 按判别值映射直接选中成员模型。
  3. 只校验选中模型,不再遍历其他成员。

代码或图示

from typing import Literal, Union
from pydantic import BaseModel, Field

class Cat(BaseModel):
    type: Literal["cat"]
    meow: str

class Dog(BaseModel):
    type: Literal["dog"]
    bark: str

class Packet(BaseModel):
    pet: Union[Cat, Dog] = Field(discriminator="type")

常见误区

  • 判别字段值在成员间重复:映射不唯一,选中行为不可预期。
  • 普通 Union 成员很多时不做判别:逐个尝试导致校验成本与错误信息膨胀。

追问

  • 判别字段可以是嵌套字段吗?答:支持嵌套路径判别(待确认:验证点:当前版本嵌套 discriminator 写法)。
  • 判别值缺失报什么错?答:判别字段缺失/不匹配直接报联合判别错误,定位到判别字段。
  • 判别联合能用于响应模型吗?答:可以,输出按成员模型序列化。

04.7.15.2-041 可辨识联合缺失判别字段时的错误?

一句话结论

输入缺少判别字段,或判别值不在成员映射中时,Pydantic 报判别联合错误:错误位置指向判别字段,说明期望的判别值集合。普通 Union 会把各成员错误堆叠返回;判别联合错误更聚焦,但前提是判别字段存在且取值合法。

概念解释

  • 错误 type 为判别相关错误标识,loc 沿判别字段路径记录。
  • 前端修复方向明确:补齐类型字段或使用合法类型值。

原理流程

  1. 读取判别字段值。
  2. 缺失或未命中映射:记录判别错误。
  3. 不继续尝试其他成员模型,错误进入 ValidationError。

代码或图示

{
  "detail": [
    {
      "loc": ["body", "pet", "type"],
      "msg": "Input tag 'bird' not found",
      "type": "union_tag_invalid"
    }
  ]
}

常见误区

  • 把判别字段设为 Optional 又依赖它分流:缺失时无法判别,应在协议层要求类型字段必填。
  • 错误信息暴露内部成员结构:对外错误可在处理器层收敛为通用提示。

追问

  • 判别值大小写敏感吗?答:按字面量精确匹配,注意前后端大小写一致。
  • 一个成员能有多个判别值吗?答:Literal 可列多个值映射到同一成员模型。
  • 判别联合校验失败会回退普通 Union 尝试吗?答:判别模式下按判别值选中,不做全成员回退尝试。

04.7.15.2-042 model_dump/model_dump_json 参数 by_alias/exclude/unset?

一句话结论

model_dump() 与 model_dump_json() 支持 by_alias(按序列化别名输出键)、exclude_unset(排除未显式设置字段)、exclude_defaults(排除默认值字段)、exclude_none(排除 None)、include/exclude(字段集合白/黑名单)。model_dump 产出 dict,model_dump_json 直接产出 JSON 字符串。

概念解释

  • include 与 exclude 可嵌套指定字段集合;by_alias 控制键名取自字段名还是序列化别名。
  • 序列化选项与输入校验配置独立。

原理流程

  1. 遍历模型字段,按选项判定是否输出。
  2. 命中 include 集合或未命中 exclude 集合的字段保留。
  3. model_dump 组装 dict;model_dump_json 编码为 JSON 字符串。

代码或图示

item.model_dump(by_alias=True, exclude_none=True)
item.model_dump_json(exclude={"internal_secret"})

常见误区

  • 混用 include 与 exclude 同字段:同时指定时行为以框架合并规则为准,建议二选一。
  • 以为 dump 会深拷贝嵌套模型:嵌套模型序列化为嵌套 dict/值,引用语义按序列化结果处理。

追问

  • exclude_unset 依据什么记录?答:模型实例化时记录显式传入的字段集合。
  • dump_json 能指定缩进吗?答:可传序列化参数控制 JSON 格式(待确认:验证点:当前版本缩进参数名)。
  • 排除字段后嵌套结构还保留吗?答:仅排除指定字段,其余嵌套结构完整。

04.7.15.2-043 model_copy 与 model_rebuild 用途?

一句话结论

model_copy(update=...) 浅拷贝模型实例并覆盖指定字段,用于基于已有实例派生副本;model_rebuild() 在注解前向引用、类型动态变化后重建模型 schema,确保延迟解析的类型可被编译。前者操作实例,后者重建类的 schema。

概念解释

  • model_copy 不重新校验,只复制属性并更新字段,适合无校验需求的派生场景。
  • 前向引用字符串注解在模型定义后需触发 rebuild 才能完整编译 schema。

原理流程

  1. model_copy:复制实例属性,按 update dict 覆盖字段值。
  2. model_rebuild:重新解析注解并编译 core schema,绑定到模型类。
  3. 两者作用层级不同:实例 vs 类 schema。

代码或图示

copy = item.model_copy(update={"price": 19.9})

class Node(BaseModel):
    next: "Node | None"

Node.model_rebuild()

常见误区

  • 用 model_copy 后期望重新校验更新值:copy 跳过校验,需严格校验时走 model_validate。
  • 前向引用未 rebuild 就实例化:schema 解析失败,需在类型可用后调用 rebuild。

追问

  • deep 拷贝有参数吗?答:model_copy 默认浅拷贝;深拷贝字段需自行处理嵌套对象(待确认:验证点:v2 是否提供 deep 参数)。
  • model_rebuild 能重复调用吗?答:可在类型补充后重建,重复调用以最新注解为准。
  • 动态加字段后需要 rebuild 吗?答:Pydantic 模型字段在类定义时固定,动态加字段需重新定义模型类。

04.7.15.2-044 TypeAdapter 作用:非 BaseModel 类型校验/序列化?

一句话结论

TypeAdapter 为非 BaseModel 类型(list[int]、dict[str, Item]、裸类型、联合类型)提供与模型一致的校验、序列化接口:validate_python、validate_json、dump_python、dump_json。不需要为包一层列表/字典专门定义模型类。

概念解释

  • 适用于请求体根为数组、复杂容器类型等场景,也可在业务代码内复用类型校验。
  • 适配器绑定类型后编译对应 schema。

原理流程

  1. 构造 TypeAdapter(list[Item]),类型注解编译为 schema。
  2. validate_python/validate_json 执行校验。
  3. dump_python/dump_json 输出序列化结果。

代码或图示

from pydantic import TypeAdapter

adapter = TypeAdapter(list[int])
adapter.validate_python([1, 2, 3])
adapter.dump_json([1, 2])

常见误区

  • 用 BaseModel 包裹单一根列表只为复用校验:RootModel 或 TypeAdapter 更直接。
  • 适配器持有可变状态被多线程共享:适配器本身只读 schema,校验产生新实例。

追问

  • TypeAdapter 支持泛型参数吗?答:支持,按传入注解编译对应 schema。
  • 校验失败抛什么异常?答:ValidationError,结构与模型校验一致。
  • TypeAdapter 能生成 JSON Schema 吗?答:可导出对应类型的 schema 供文档使用。

04.7.15.2-045 自定义类型 get_pydantic_core_schema 实现要点?

一句话结论

为自定义类型接入 Pydantic v2,可在类上定义 __get_pydantic_core_schema__(cls, handler),返回 core schema;通常委托 handler 处理基础类型,再包装自定义校验/序列化逻辑。这是 v2 替代 v1 __get_validators__ 的扩展点,用于实现专有格式、压缩类型等。

概念解释

  • 协议方法接收类型与 schema handler,返回 core_schema 节点。
  • 简单自定义也可用 Annotated 元数据 + 校验器,不必实现完整 core schema 协议。

原理流程

  1. 类型被模型引用时,Pydantic 调用 __get_pydantic_core_schema__。
  2. 方法借助 handler 生成基础 schema,按需加自定义校验/序列化包装。
  3. 返回 schema 进入编译流程。

代码或图示

from pydantic_core import core_schema

class Sku:
    def __init__(self, value: str):
        self.value = value

    @classmethod
    def __get_pydantic_core_schema__(cls, source_type, handler):
        return core_schema.no_info_plain_validator_function(cls._validate)

    @classmethod
    def _validate(cls, v):
        if not isinstance(v, str) or not v.startswith("A"):
            raise ValueError("非法 SKU")
        return cls(v)

常见误区

  • 沿用 v1 __get_validators__ 钩子:v2 不再调用,旧钩子静默失效。
  • 自定义 schema 不处理序列化:输入校验通过后输出无法编码,需配套序列化逻辑。

追问

  • 自定义类型需要注册到模型吗?答:字段注解使用该类型即可被协议识别。
  • 简单格式校验用 core schema 还是 field_validator?答:单字段规则用校验器更轻量;跨模型复用类型再实现协议。
  • 出错用什么异常?答:抛 ValueError 或 PydanticCustomError 携带结构化错误信息。

04.7.15.2-046 Annotated 自定义元数据提取(get_args)?

一句话结论

Annotated[X, ...] 的元数据可通过 typing.get_args 提取:首元素是基础类型,后续元素是附加元数据(Field、依赖、约束等)。框架与库按约定位置读取元数据;自定义框架可从 get_args 结果中挑出自己的标记对象。

概念解释

  • 元数据顺序与可重复元素由各库约定,提取时按类型匹配而非固定位置。
  • Annotated 不改变运行时类型,仅在注解层携带信息。

原理流程

  1. 读取字段注解,判断是否为 Annotated 形式。
  2. get_args 拆出基础类型与元数据列表。
  3. 按类型筛选出自定义标记,配置到 schema 或依赖树。

代码或图示

from typing import Annotated, get_args

def extract(annotation):
    args = get_args(annotation)
    if len(args) > 1:
        base, metadata = args[0], args[1:]
        return base, metadata
    return annotation, []

Name = Annotated[str, Field(min_length=1)]

常见误区

  • 假设元数据固定在第二个位置:多个库叠加元数据时顺序可能变化,按类型匹配更稳。
  • 运行时用 isinstance 判断 Annotated 包装类型:Annotated 是注解包装,运行时对象类型仍是基础类型。

追问

  • 元数据能重复放同一个 Field 吗?答:可以出现多个,提取时按约定合并或取首个。
  • Python 3.8 用什么?答:typing_extensions.Annotated 与 get_args。
  • 自定义标记对象需要继承基类吗?答:不需要,按类型匹配即可,约定清晰即可。

04.7.15.2-047 ValidationError 结构 loc/msg/type/input/url?

一句话结论

Pydantic 校验错误是 ValidationError,.errors() 返回错误列表,每条含 loc(位置链)、msg(可读说明)、type(错误类型标识)、input(原始输入值),部分版本带 url(错误类型文档链接)。FastAPI 422 响应基本沿用该结构。

概念解释

  • loc 是字符串/数字段列表:模型字段名、列表索引、外层 Body 键依次排列。
  • type 是机器可读标识(如 greater_than、string_type),前端可按类型分支处理。

原理流程

  1. 校验过程中各节点收集错误。
  2. 错误位置沿嵌套层级追加到 loc。
  3. 汇总后抛 ValidationError,errors() 展开为结构化列表。

代码或图示

from pydantic import BaseModel, ValidationError

class Item(BaseModel):
    price: float

try:
    Item(price=-1)
except ValidationError as e:
    for err in e.errors():
        print(err["loc"], err["type"], err["msg"])

常见误区

  • 只看 msg 不看 loc:嵌套/列表场景下同名字段多,必须按位置链定位。
  • 把 input 直接回显给外部:敏感输入可能被带出,需按字段脱敏。

追问

  • 错误能携带自定义上下文吗?答:PydanticCustomError 可传 context 进入错误结构。
  • url 字段一定存在吗?答:按版本与错误类型提供,缺失时不影响定位。
  • 一条请求会返回所有错误还是首个?答:默认收集全部字段错误后统一返回。

04.7.15.2-048 FastAPI 422 响应体如何映射 Pydantic 错误?

一句话结论

FastAPI 把请求参数/请求体校验失败包装为 RequestValidationError,默认处理器返回 422,响应体 detail 直接使用 Pydantic 错误列表:loc 前缀通常带 body/query/path 等来源段,msg、type、input 原样保留。端点函数在校验失败前不会被调用。

概念解释

  • 422 Unprocessable Entity 表示语法/编码正确但语义校验未通过;参数缺失、类型不符、约束违反都归此状态。
  • 错误列表按字段位置组织,便于前端逐字段提示。

原理流程

  1. 参数绑定阶段收集各来源原始值。
  2. Pydantic 模型校验失败,错误列表进入 RequestValidationError。
  3. 默认异常处理器生成 422 JSON 响应。

代码或图示

{
  "detail": [
    {
      "loc": ["body", "price"],
      "msg": "Input should be greater than 0",
      "type": "greater_than",
      "input": -3
    }
  ]
}

常见误区

  • 把 422 当成业务错误在端点内再抛:校验错误由框架统一产生,端点只处理通过校验后的业务规则。
  • 自定义处理器丢弃 loc:前端无法定位字段,错误响应应保留位置链。

追问

  • Query 参数错误 loc 前缀是什么?答:来源段为 query;Path 为 path,Header 为 header。
  • 422 与 400 如何选择?答:FastAPI 对 Pydantic 校验失败固定 422;框架/网关层可再转换。
  • 错误体能加错误码吗?答:自定义处理器在 detail 外包一层业务码结构。

04.7.15.2-049 RequestValidationError 处理器如何定制 422?

一句话结论

用 @app.exception_handler(RequestValidationError) 注册自定义处理器,接收 request 与 exc,从 exc.errors() 取结构化错误,重新组织响应结构(业务码、字段提示、错误类型映射),返回自定义 JSONResponse。可统一错误格式、过滤敏感输入、把英文 msg 映射为中文提示。

概念解释

  • 处理器返回的响应状态码可自定义,不强制 422;但语义上保留 422 更符合约定。
  • 替换默认处理器后,FastAPI 不再生成默认 detail 结构。

原理流程

  1. 注册异常处理器绑定 RequestValidationError。
  2. 校验失败时框架调用处理器,传入请求与异常实例。
  3. 处理器读取错误列表,组装自定义响应返回。

代码或图示

from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"code": 42201, "errors": exc.errors()},
    )

常见误区

  • 处理器内再次抛异常未兜底:错误处理失败会变成 500,处理器逻辑要保持简单。
  • 直接把 exc.errors() 中的 input 回显到公网响应:密码、令牌等敏感字段需排除或截断。

追问

  • 能按字段映射本地化提示吗?答:可按 loc 最后一段或 type 查表返回本地化 msg。
  • 自定义处理器影响 OpenAPI 文档吗?答:不影响 Schema 生成,只改变运行时错误响应格式。
  • 处理器能读取请求体吗?答:可访问 request,但 body 流可能已被消费,避免重复读取。

04.7.15.2-050 ValueError 与 PydanticCustomError 区别?

一句话结论

校验器内抛 ValueError 生成通用校验错误,消息直接作为 msg;抛 PydanticCustomError 可指定错误类型标识与上下文字典,错误结构更结构化,便于前端按类型分支。普通规则校验用 ValueError,需要机器可读错误码时用 PydanticCustomError。

概念解释

  • ValueError 简单直接,错误 type 为通用校验标识。
  • PydanticCustomError(error_code, message, context) 携带上下文进入错误 ctx。

原理流程

  1. 校验器检查规则,失败抛出对应异常。
  2. Pydantic 把异常转换为错误条目,绑定当前字段位置。
  3. 错误进入 ValidationError 列表。

代码或图示

from pydantic import BaseModel, field_validator
from pydantic_core import PydanticCustomError

class Code(BaseModel):
    value: str

    @field_validator("value")
    @classmethod
    def check(cls, v):
        if not v.startswith("A"):
            raise PydanticCustomError(
                "bad_code", "编码必须以 A 开头", {"received": v}
            )
        return v

常见误区

  • 校验器抛 TypeError/AssertionError:未被正确识别为校验错误,可能变成 500;应抛 ValueError 或自定义错误。
  • 自定义错误上下文塞入敏感值:进入错误结构后可能被 422 响应带出。

追问

  • PydanticCustomError 需要从哪里导入?答:pydantic_core(v2 核心包)。
  • 错误上下文在 errors() 中哪个字段?答:ctx 字段携带上下文字典。
  • 一个字段能抛多个错误吗?答:校验器遇到首个错误即中断该字段;收集多错误需在 schema 层组织。

04.7.15.2-051 错误中 input 字段脱敏/截断配置?

一句话结论

Pydantic 错误默认把触发错误的原始值放在 input 字段;敏感字段(密码、令牌、身份证)不希望回显时,可在自定义 422 处理器中按字段名过滤/截断 input,或在模型层用校验器避免敏感值进入错误结构。v2 提供字段级错误输入控制相关配置(具体配置键以当前版本为准)。

概念解释

  • 错误响应经公网返回,input 会成为泄露面;内部排查日志与对外响应应分开处理。
  • 结构化日志可保留完整输入,对外响应只返回字段名与错误类型。

原理流程

  1. 校验失败生成错误条目,input 记录原始值。
  2. 自定义处理器遍历错误,按 loc 识别敏感字段。
  3. 替换为掩码/截断值后再输出响应。

代码或图示

SENSITIVE = {"password", "token", "secret"}

def sanitize(errors):
    for err in errors:
        if err["loc"][-1] in SENSITIVE:
            err["input"] = "***"
    return errors

常见误区

  • 依赖前端不展示 input:响应体已下发,抓包即可见,必须在服务端脱敏。
  • 日志与响应共用一份错误结构:建议日志保留详情,响应体单独裁剪。

追问

  • v2 有内置忽略 input 的开关吗?答:可通过模型/字段配置控制错误输入包含策略(待确认:验证点:当前版本配置键名与默认行为)。
  • 嵌套敏感字段如何识别?答:按 loc 末段字段名递归判断。
  • 脱敏影响排障吗?答:对外不暴露,内部日志单独记录完整请求上下文。

04.7.15.2-052 跨字段校验在 after model_validator 读取哪些字段?

一句话结论

mode="after" 的 model_validator 中,self 持有全部已通过字段校验的字段值,可读取任意字段做一致性比较(区间、密码确认、金额勾稽)。before 模式只有原始输入映射,兄弟字段尚未校验,不能依赖字段类型化后的状态。

概念解释

  • after 校验器适合跨字段规则;读取未填充字段需考虑默认值是否已应用。
  • 校验失败抛 ValueError,错误挂在模型根层级。

原理流程

  1. 字段逐一转换校验并填充实例。
  2. after 模型校验器读取 self 各字段。
  3. 规则不通过抛错;通过返回 self 完成构造。

代码或图示

from pydantic import BaseModel, model_validator

class Range(BaseModel):
    start: int
    end: int

    @model_validator(mode="after")
    def check(self):
        if self.start > self.end:
            raise ValueError("start 不能大于 end")
        return self

常见误区

  • 在 before 模式访问类型化字段值:before 阶段值仍是原始输入,类型转换未完成。
  • after 校验器修改字段后不返回 self:实例属性修改需正确返回模型实例。

追问

  • 跨字段错误能定位到具体字段吗?答:模型级错误 loc 为根;需字段级定位时在对应字段校验器内比较兄弟字段。
  • after 校验器能改字段默认值吗?答:可在实例上修正值并返回,复杂修正建议在 before 阶段补输入。
  • 校验器能访问校验上下文吗?答:通过 ValidationInfo 参数读取 context 与已校验数据。

04.7.15.2-053 模型构造成本与 schema 编译缓存发生在哪一层?

一句话结论

模型类定义后,类型注解与约束编译为 pydantic-core schema,该 schema 绑定在模型类上并被后续所有实例化复用;每次实例化的成本是按 schema 遍历输入、转换、校验与构造对象,不再重复编译 schema。高频接口应复用模型类,避免运行时动态定义模型。

概念解释

  • 编译缓存层:模型类 → core schema;运行时层:每次 model_validate 按 schema 执行。
  • 动态生成模型(create_model)每次都会付出编译成本,不宜放在请求路径上。

原理流程

  1. 类定义/首次使用时解析注解并编译 schema。
  2. schema 缓存到模型类属性。
  3. 重复实例化只走执行层,不重新编译。

代码或图示

# 模块级定义,schema 一次编译复用
class Item(BaseModel):
    name: str
    price: float

# 请求内不要反复 create_model

常见误区

  • 在端点内动态构造模型类:每次请求重复编译 schema,启动期可完成的工作被拖到运行时。
  • 以为实例化慢是 schema 重编译:多数情况是大对象遍历与嵌套构造成本,需 profile 定位。

追问

  • schema 缓存会被配置修改失效吗?答:改模型定义后需 model_rebuild 或重启进程。
  • 泛型模型每个绑定类型都编译吗?答:具体绑定类型各自编译 schema。
  • 如何衡量构造成本?答:用计时/profile 对比模型构造与序列化耗时,定位 CPU 热点。

04.7.15.2-054 model_construct 跳过校验的使用边界与风险?

一句话结论

model_construct(**data) 绕过校验与默认值处理,直接填充模型字段,速度快但不保证数据合法。仅用于内部已校验过的数据重建、测试构造、高性能热路径;对外输入、不可信数据禁止使用。跳过校验后类型约束、约束规则、清洗逻辑全部不生效。

概念解释

  • 与 model_validate 相对:construct 是“信任输入直接装配”的逃生舱。
  • 可变默认值、default_factory 在 construct 下的行为与 validate 不同,需核对版本语义。

原理流程

  1. 调用 model_construct 传入字段值字典。
  2. 跳过 core schema 校验,直接写入实例属性。
  3. 返回模型实例,后续序列化按字段输出。

代码或图示

item = Item.model_construct(name="x", price=9.9)

常见误区

  • 用 construct 接收外部请求体:脏数据绕过校验直接进入业务层,是安全与数据一致性风险。
  • 以为 construct 会应用默认值:未传入字段按 construct 规则处理,不等同于 validate 的默认填充。

追问

  • construct 能嵌套构造模型吗?答:嵌套值需自行已是模型实例或兼容结构,不递归校验。
  • construct 失败会抛校验错误吗?答:不做校验,类型不符也不报错。
  • 性能提升有多大?答:小模型跳过校验有收益,但不可作为放松输入校验的理由。

04.7.15.2-055 高频序列化下 model_dump_json 与手动 dict 取舍?

一句话结论

model_dump_json() 在 core 层直接编码 JSON,通常比先 model_dump() 再 json.dumps() 少一层 Python dict 构造;手动组装 dict 只在需要完全自定义字段形态时使用。高频响应接口优先用模型自带序列化,避免手写 dict 遗漏字段或别名规则。

概念解释

  • model_dump() 产出嵌套 Python 对象,model_dump_json() 直接产出字符串。
  • 手动 dict 灵活但要自行维护别名、排除选项与类型编码。

原理流程

  1. 模型实例按字段遍历。
  2. dump_json 在 core 层完成类型编码与字符串生成。
  3. 手动路径先构造 dict 再走标准 JSON 编码。

代码或图示

# 高频路径:直接 JSON 字符串
body = item.model_dump_json(by_alias=True, exclude_none=True)

# 需要中间加工时:先 dump 再改 dict
data = item.model_dump()
data["extra"] = calc()

常见误区

  • 手写 dict 复制字段导致模型字段变更时响应漏字段:模型序列化与字段定义单一来源更稳。
  • 为省一次 dump 在业务层保存 dict 而非模型实例:类型约束与复用性下降。

追问

  • dump_json 能直接作为响应体吗?答:FastAPI 响应模型路径自动序列化;自定义响应可直接返回 JSON 字符串。
  • 大列表序列化瓶颈在哪?答:元素遍历与对象构造,core 编码相对快;嵌套深的对象是主要成本。
  • 能换更快的 JSON 库吗?答:响应类可选 orjson 等实现,模型序列化层仍按 Pydantic 规则。

04.7.15.2-056 深层嵌套的大对象模型校验,性能瓶颈在哪?

一句话结论

深层嵌套的大对象模型,成本主要在:每层 schema 遍历、嵌套模型对象构造、容器元素逐个校验、序列化时字段遍历。层级越深、列表元素越多,Python 对象创建与属性填充开销越大;瓶颈通常不是 Rust core 本身,而是对象层数与元素规模。

概念解释

  • 大请求体(长列表 + 嵌套对象)在校验与序列化两段都有线性以上成本。
  • 优化方向:拆分过大的模型定义、裁剪不必要字段、批量场景限制列表长度、Profile 定位热点层。

原理流程

  1. 外层模型遍历字段,取出嵌套输入。
  2. 递归校验内层模型与容器元素,逐层构造实例。
  3. 响应阶段再次遍历嵌套结构序列化。

代码或图示

# 限制列表规模,避免无界嵌套膨胀
class Batch(BaseModel):
    items: list[Item] = Field(max_length=500)

常见误区

  • 怀疑 Pydantic 慢而直接关闭校验:风险不可接受,应先profile 模型结构与字段冗余。
  • 嵌套模型携带大量未使用字段:响应/请求模型只声明需要的字段,减少遍历与构造。

追问

  • 列表过长如何保护服务?答:max_length 限制元素数,网关层限制 body 大小。
  • 嵌套 ORM 转换慢在哪?答:属性读取可能触发懒加载,DB 查询常是隐性瓶颈。
  • 缓存模型实例能复用吗?答:请求级数据各不相同,复用实例风险高;可复用的是 schema 与模型类。

04.7.15.2-057 复用模型与 Annotated 元数据避免重复定义 schema?

一句话结论

公共字段与约束抽到基类模型或 Annotated 类型别名,多个端点/模型复用同一 schema 定义,避免复制粘贴导致约束漂移。复用保证改一处全局生效,也减少 OpenAPI 中重复相似 Schema;注意别名约束被隐式继承,改动需评审影响面。

概念解释

  • 基类模型放公共字段;Annotated 别名放“类型 + 约束 + 别名”组合。
  • 复用与拆分平衡:过度抽象使模型层级难以追踪。

原理流程

  1. 识别跨模型重复字段与约束。
  2. 抽取为基类或 Annotated 别名。
  3. 各模型引用复用定义,schema 编译基于同一约束来源。

代码或图示

from typing import Annotated
from pydantic import BaseModel, Field

PageSize = Annotated[int, Field(ge=1, le=100)]

class BaseItem(BaseModel):
    id: int
    name: str

class ItemIn(BaseItem):
    page_size: PageSize

常见误区

  • 复制粘贴字段约束到多个模型:一处调整遗漏其他,行为不一致。
  • 别名别名嵌套过深:约束来源链难以追溯,保持别名语义单一。

追问

  • 复用模型会让 OpenAPI 组件合并吗?答:同一模型类引用生成同一组件定义。
  • 基类字段需要排除时怎么办?答:子类响应模型重新声明或用排除选项裁剪。
  • 复用别名能带依赖吗?答:Annotated 元数据可携带 FastAPI 依赖,类型别名与依赖别名分别维护。

04.7.15.2-058 并发下模型实例是否线程安全?

一句话结论

Pydantic 模型实例默认是普通 Python 对象:构造完成后只读访问是安全的;在多线程中修改同一实例属性会产生竞态。模型类与编译后的 schema 可被多线程共享读取;请求级模型实例应按请求隔离,不要放进全局状态跨线程共享可变数据。

概念解释

  • 线程安全问题来自可变状态共享,而非 Pydantic 本身加锁。
  • 异步协程间同理:共享可变模型需加锁或按请求隔离。

原理流程

  1. 每个请求独立构造模型实例。
  2. 实例属性在其请求线程/协程内访问。
  3. 不把实例挂到 app.state 或全局缓存供并发写入。

代码或图示

@app.post("/items")
def create(item: Item):
    # item 为本次请求实例,不跨请求共享
    return repo.save(item)

常见误区

  • 把构造好的模型实例缓存到全局字典供多请求读取修改:并发写入竞态,且模型可能含请求敏感数据。
  • 以为 Pydantic 实例不可变:默认实例属性可赋值,需要冻结行为用模型配置或自定义约定。

追问

  • 模型类方法是线程安全的吗?答:无共享可变状态的纯函数方法可并发调用。
  • 只读共享模型安全吗?答:构造后不再修改的实例可被多读访问。
  • 跨进程共享模型可行吗?答:需序列化传输(dump/JSON),进程内实例不共享内存。

04.7.15.2-059 v1 json_encoders 在 v2 如何迁移?

一句话结论

v1 的 Config.json_encoders 自定义编码器在 v2 不再使用;v2 通过模型级序列化器、字段序列化注解或类型的 core schema 序列化逻辑控制输出格式。常见场景(日期、Decimal、自定义类型)按新机制注册输出编码,迁移时逐个核对旧编码器覆盖的类型。

概念解释

  • v2 序列化由 core schema 与序列化器驱动,输入校验与输出编码分离。
  • 旧 json_encoders 按类型映射函数,新机制按字段/类型声明序列化行为。

原理流程

  1. 梳理 v1 模型中 json_encoders 覆盖的类型。
  2. 在 v2 模型/字段上用对应序列化配置或自定义类型 schema 实现同等输出。
  3. 回归核对 JSON 输出格式与旧版本一致。

代码或图示

# v1 旧写法(不再使用)
# class Config:
#     json_encoders = {datetime: lambda v: v.isoformat()}

# v2:日期默认按 ISO 序列化;自定义格式用字段序列化器/类型 schema
from pydantic import BaseModel
from datetime import datetime

class Record(BaseModel):
    created_at: datetime

常见误区

  • 升级后保留 json_encoders 配置项:v2 不识别,静默失效导致输出格式变化。
  • 自定义类型只实现输入校验不实现序列化:输出阶段无法编码,需补序列化逻辑。

追问

  • Decimal 输出格式怎么定?答:按 v2 类型规则或自定义序列化器控制字符串/数字形态。
  • 字段级序列化器怎么声明?答:使用 @field_serializer 装饰器定义输出逻辑(待确认:验证点:当前版本序列化器导入路径与签名)。
  • 迁移后如何核对输出?答:对比新旧版本同一实例的 JSON 字符串,逐字段检查格式。

04.7.15.2-060 v1→v2 迁移常见回归坑清单?

一句话结论

典型回归坑:旧 API 名残留(validator/parse_obj/dict/json/Config)、类型转换严格度变化导致宽松输入被拒、orm_mode 改名后 ORM 读取失败、可变默认值与 default_factory 行为差异、枚举序列化输出变化、自定义校验钩子失效、错误结构字段名变化。迁移需跑全量模型测试并核对请求/响应样本。

概念解释

  • 迁移不是改依赖版本:校验行为、错误结构、序列化输出都可能变化。
  • 建议按模型分批迁移,每个模型对比 validate 与 dump 结果。

原理流程

  1. 静态扫描旧 API 名并替换为 v2 对应写法。
  2. 运行测试套件,记录被拒的宽松输入与输出格式差异。
  3. 逐模型修正约束、别名、序列化器与错误处理。

代码或图示

v1 → v2 对照:
validator → field_validator
root_validator → model_validator
Config → model_config / ConfigDict
parse_obj → model_validate
parse_raw → model_validate / model_validate_json
.dict() → model_dump()
.json() → model_dump_json()
orm_mode → from_attributes

常见误区

  • 只改导入名不核对行为:转换严格度、默认值、枚举输出等行为差异仍会漏网。
  • 迁移后不回归 OpenAPI 样本:请求/响应 Schema 变化可能影响前端联调。

追问

  • 迁移期能 v1 v2 共存吗?答:依赖版本建议单一,逐模块切换;混装易产生 core 版本冲突。
  • 哪些行为最容易变严格?答:数字/字符串/布尔之间的 coercion,严格类型与宽松模式边界。
  • 迁移后重点回归什么?答:422 错误结构、枚举输出、Decimal/日期格式、ORM 读取与敏感字段裁剪。

本节高频题

  • v1→v2 架构与 API 迁移(001–007、060)
  • Config 与 model_config(003、019)
  • 校验流程与 core schema 编译(011、012、053)
  • 类型转换与 Strict 严格模式(013、014)
  • field_validator before/after(015、017)
  • model_validator 跨字段校验(016、052)
  • Field 约束与 Annotated 别名(021、022、057)
  • Optional 与必填判定(027)
  • 别名体系 alias/populate_by_name/serialization_alias(028–030)
  • response_model 输入输出两条链路(031、037)
  • exclude_unset/defaults/none(032)
  • from_attributes ORM 模式(034)
  • 泛型模型、RootModel(038、039)
  • Discriminated Union 判别联合(040、041)
  • model_dump 序列化选项(042、055)
  • TypeAdapter 与自定义类型 schema(044、045)
  • ValidationError 结构与 422 定制(047–049)
  • 自定义错误与敏感输入脱敏(050、051)
  • model_construct 性能边界(054)
  • 并发实例隔离(058)