第2章 请求建模与数据验证
第 2 章 · 请求建模与数据验证
章节摘要：API 开发的地基是把"外部输入"变成"可信数据"。本章把路径参数、查询参数、请求体三类输入在 FastAPI 中的声明方式与 Flask 手写解析逐项对照，然后深入 Pydantic 的建模机制——嵌套模型、字段约束、自定义校验器，以及 v1 与 v2 两个大版本在校验器写法、性能模型、错误结构上的关键差异。读完本章，"任何进入业务层的数据都已通过验证"这句话对你而言不再是口号，而是可以指着代码说清楚的事实。
学习目标
阅读完本章，你应当能够：
- 用一套签名语法声明路径参数、查询参数、请求体，并解释框架如何区分它们；
- 设计带嵌套与列表的请求体模型，并理解解析顺序与错误定位；
- 写出字段约束与自定义校验器，说明它们各自适合的规则类型；
- 指出 Pydantic v1 与 v2 校验器写法的差异，并完成存量代码迁移；
- 用 response_model 收紧输出契约，避免敏感字段泄漏。
核心概念速览
一句金句：验证逻辑写在签名里，就永远不会被忘记；写在函数体里，总有一个接口会漏掉。
子章节导航
2.1 路径操作与参数声明：FastAPI 与 Flask 路由范式对比
从装饰器语法的表面相似讲到参数语义的深层差异：路径参数的类型转换与枚举约束、查询参数的默认值与范围、参数元数据如何流进自动文档。Flask 的 request 对象取值方式与 FastAPI 签名声明方式的逐项对照是本节主线。
2.2 请求体建模：Pydantic 模型与手写解析的对比
请求体是 API 最复杂的输入面。本节用"订单创建"这个贯穿案例，对比 Flask 手写字典校验、marshmallow Schema 与 Pydantic 模型三种方案，展开嵌套模型、列表字段、可选字段的处理，并给出模型设计的三条工程准则。
2.3 数据验证与 Pydantic：v1 与 v2 的关键差异
Pydantic 2 是近年 FastAPI 项目最大的变量。校验器从 @validator 到 @field_validator 的迁移、dict() 到 model_dump() 的 API 更替、Rust 内核带来的性能变化、错误结构从嵌套字典到 loc 列表的演进——本节逐条对比，并给出存量项目迁移的检查清单。
子章节之间的逻辑关系
三节沿"输入的复杂度"递进：
2.1 标量参数（路径 + 查询） │ ▼ 2.2 结构化请求体（Pydantic 建模） │ ▼ 2.3 验证引擎内幕（v1 与 v2 差异）
2.1 处理一个值，2.2 处理一棵树，2.3 打开引擎盖看这棵树是怎么被校验的。2.2 建立的模型概念是第 4 章响应模型与第 6 章 OpenAPI 文档的直接基础；2.3 的版本知识则影响你读到的每一份旧教程与新文档。
一个贯穿全章的视角：错误应该在哪里被发现
三类输入对应三种典型错误发现时机。路径参数错了，网关层就能发现（404 或 422）；查询参数错了，框架层发现；请求体的业务规则错了，只有校验层能发现。传统写法里这三层发现点分散在 URL 设计、视图开头、散落的 if 语句里；FastAPI 把它们全部收敛到签名与模型定义这一处。本章所有对比最终都在论证同一件事：发现错误的位置越靠前、越集中，修复成本越低。一个在 422 阶段拦住的非法邮箱，成本是一次请求重试；一个漏进数据库的非法邮箱，成本可能是一整次数据清洗。
再给这个视角补一个量化感受：假设一个接口每天十万次调用，上游系统有百分之一的概率传错参数。校验缺失时，这些脏数据每天一千条地渗进数据库，某天报表数字对不上时，排查范围是"全部历史数据"；校验前置时，422 日志里每天一千条记录，第一次出现就能定位到上游的某个发布——两者的差距不是代码量，是问题暴露的时间常数。签名即契约的全部价值，就是把这个时间常数从"月"压到"天"甚至"分钟"。
阅读本章时建议手边开着第 1 章搭好的开发服务器与文档页：每学一种参数声明或模型写法，立刻在文档页上试一次非法输入，看 422 的结构与定位——本章的每个知识点都对应一次"看得见的拒绝"，这种即时反馈是建立校验直觉最快的方式。
前置知识与后续延伸
- 前置：第 1 章的环境已搭好、能运行开发服务器；了解 HTTP 请求的基本结构（方法、路径、查询串、body）。
- 为后续铺垫：本章的 Pydantic 模型将直接用于第 4 章的 response_model、第 5 章测试中的构造样例与第 6 章 OpenAPI 文档的生成来源；嵌套模型的思维也会在第 7 章项目结构里以"分层模型"的形态重现。
学习本章的三种路径
按背景选读法效率最高。Flask 老手可以只精读 2.1 的三个迁移陷阱与 2.3 的版本差异，2.2 的建模思想快速过（手写校验的痛你已经懂）；全新读者按节序通读，每一节末尾的要点回顾当复习提纲；赶时间的读者读 2.2 的三模型方案与 2.3 的更名表——前者是日常最高频的设计动作，后者是当下最踩坑的版本断层。无论哪种路径，动笔写一个带嵌套模型的接口并故意传错数据，是把本章知识转为所有的最短仪式。