文章目录前言一、阶段学习目标二、核心概念查询参数 vs 请求体2\.1 核心区别新手必记2\.2 FastAPI识别规则三、核心实战Pydantic请求体3\.1 基础请求体单层级3\.2 运行测试3\.3 嵌套请求体复杂业务必备四、核心重点响应模型与数据脱敏生产必备4\.1 入参、出参模型分层生产规范4\.2 响应模型实战脱敏4\.3 响应模型进阶配置4\.3\.1 exclude\_unset只返回赋值字段4\.3\.2 手动指定排除/包含字段五、混合传参三种参数同时使用六、Header 与 Cookie 参数获取七、生产级统一响应体封装八、阶段综合实战完整用户CRUD脱敏\统一返回九、新手高频避坑指南十、阶段核心总结前言上一阶段我们掌握了FastAPI基础接口、路径参数、查询参数、RESTful规范与自动文档能快速编写基础查询接口。但真实业务中新增、修改、编辑数据几乎都需要传递复杂JSON数据单纯的查询参数完全无法满足需求。这就需要用到FastAPI核心核心能力请求体 响应模型。本阶段最大优势100%复用你已精通的Pydantic知识。FastAPI的请求校验、数据序列化、字段约束、脱敏返回全部基于Pydantic v2实现无需学习新语法无缝衔接旧知识。本文耗时1天学完彻底解决业务核心问题1. 复杂JSON请求参数接收、自动校验、类型转换2. 接口返回数据脱敏、字段过滤、统一格式化3. 路径参数、查询参数、请求体混合传参4. Header、Cookie请求头参数获取5. 生产级DTO分层入参模型/出参模型分离。一、阶段学习目标1. 彻底分清查询参数与请求体的使用场景与区别2. 熟练使用Pydantic BaseModel定义POST/PUT请求体掌握字段校验、默认值、必填规则3. 掌握嵌套请求体模型适配复杂多层JSON参数场景4. 精通response_model响应模型实现密码脱敏、字段过滤、数据格式化5. 掌握三种参数混合使用路径参数 查询参数 请求体6. 学会获取Header请求头、Cookie参数7. 搭建生产级统一接口返回体实现前后端格式统一8. 完成用户新增、编辑、脱敏查询完整实战接口。二、核心概念查询参数 vs 请求体2.1 核心区别新手必记上一阶段的路径参数、查询参数仅适用于简单少量参数、查询场景而请求体专门用于复杂JSON、大批量数据、新增/修改场景。参数类型传输位置适用请求方法数据格式业务场景查询参数URL ? 后拼接GET 为主简单键值对分页、筛选、搜索、ID查询请求体HTTP 请求体POST/PUT/PATCH复杂JSON、嵌套结构新增数据、编辑数据、批量提交2.2 FastAPI识别规则这是FastAPI的核心智能规则无需手动声明1. 普通基础类型int/str/bool自动识别为查询参数2. Pydantic模型类型继承BaseModel自动识别为请求体。三、核心实战Pydantic请求体所有请求体基于Pydantic BaseModel定义你之前学的所有校验规则长度、正则、邮箱、数值范围全部通用。3.1 基础请求体单层级实现用户新增接口接收JSON请求体自动完成参数校验。fromfastapiimportFastAPI,statusfrompydanticimportBaseModel,EmailStr,field_validator appFastAPI(title请求体与响应模型实战)# 定义请求体模型用户新增入参classUserCreate(BaseModel):# 必填字段username:stremail:EmailStr password:str# 可选字段带默认值age:int|NoneNoneis_active:boolTrue# 自定义字段校验复用Pydantic能力field_validator(username)defcheck_username(cls,v):iflen(v)3:raiseValueError(用户名长度不能小于3位)returnvfield_validator(password)defcheck_password(cls,v):iflen(v)6:raiseValueError(密码长度不能小于6位)returnv# POST接口接收JSON请求体app.post(/users,summary新增用户,status_codestatus.HTTP_201_CREATED)defcreate_user(user:UserCreate):# 自动校验参数非法参数直接返回422错误# 直接返回请求数据后续改造为脱敏响应模型returnuser3.2 运行测试启动项目uvicorn main:app --reload访问http://127.0.0.1:8000/docs调试正确请求体示例{username:zhangsan,email:zhangsanqq.com,password:123456,age:22}非法场景自动拦截邮箱格式错误、用户名过短、密码位数不足无需手写if判断。3.3 嵌套请求体复杂业务必备真实业务常出现多层嵌套JSON如用户绑定收货地址FastAPIPydantic完美支持嵌套模型。# 嵌套子模型收货地址classAddress(BaseModel):province:strcity:strdetail:str# 父模型用户新增嵌套地址classUserCreateWithAddr(BaseModel):username:stremail:EmailStr password:straddress:Address# 嵌套子模型age:int|NoneNone# 嵌套请求体接口app.post(/users/addr,summary新增用户绑定地址)defcreate_user_with_addr(user:UserCreateWithAddr):returnuser请求体支持多层嵌套自动递归校验所有字段适配复杂业务参数。四、核心重点响应模型与数据脱敏生产必备最大生产坑点直接返回数据库/请求原始数据会泄露密码、密钥等敏感信息。解决方案使用response_model响应模型实现字段过滤、敏感数据脱敏、返回格式统一。4.1 入参、出参模型分层生产规范严格分层禁止同一模型既做入参又做出参- UserCreate新增入参模型包含密码- UserPublic返回出参模型剔除密码、脱敏字段4.2 响应模型实战脱敏# 响应模型用户公开信息脱敏classUserPublic(BaseModel):id:intusername:stremail:EmailStr age:int|NoneNoneis_active:bool# 关键配置支持ORM/字典对象自动转换classConfig:from_attributesTrue# 模拟数据库fake_user_db[]# 改造新增接口添加响应模型脱敏app.post(/users,summary新增用户脱敏返回,response_modelUserPublic,status_codestatus.HTTP_201_CREATED)defcreate_user(user:UserCreate):# 模拟生成用户ID、存入数据库new_useruser.model_dump()new_user[id]len(fake_user_db)1fake_user_db.append(new_user)# 返回完整数据响应模型自动剔除password字段returnnew_user核心效果前端传入密码后端存储后返回数据自动剔除password字段彻底杜绝敏感信息泄露。4.3 响应模型进阶配置4.3.1 exclude_unset只返回赋值字段适用于局部更新场景不返回默认空字段app.post(/users,response_modelUserPublic,response_model_exclude_unsetTrue)4.3.2 手动指定排除/包含字段# 仅返回指定字段app.get(/users/{user_id},response_modelUserPublic,response_model_include{id,username,email})# 排除指定敏感字段app.get(/users/{user_id},response_model_exclude{password})五、混合传参三种参数同时使用真实业务高频场景路径参数 查询参数 请求体混合传参FastAPI可智能区分、互不冲突。场景根据用户ID路径参数分页查询参数更新用户信息请求体# 用户更新入参模型classUserUpdate(BaseModel):username:str|NoneNoneemail:EmailStr|NoneNoneage:int|NoneNone# 混合传参接口app.put(/users/{user_id},summary更新用户信息混合传参,response_modelUserPublic)defupdate_user(# 1. 路径参数用户IDuser_id:int,# 2. 查询参数分页/附加筛选is_validate:boolTrue,# 3. 请求体更新数据JSONuser:UserUpdate):return{user_id:user_id,is_validate:is_validate,**user.model_dump(exclude_unsetTrue)}FastAPI自动识别三类参数无需手动区分极大简化开发。六、Header 与 Cookie 参数获取业务常用获取请求头Token、设备信息、Cookie会话IDFastAPI原生支持。fromfastapiimportHeader,Cookieapp.get(/headers,summary获取请求头参数)defget_headers(# 获取自定义请求头token:str|NoneHeader(defaultNone),# 获取浏览器UAuser_agent:str|NoneHeader(defaultNone),# 获取Cookiesession_id:str|NoneCookie(defaultNone)):return{token:token,user_agent:user_agent,session_id:session_id}常用场景接口鉴权获取Token、统计客户端设备、会话状态校验。七、生产级统一响应体封装原生返回格式杂乱前端对接繁琐我们封装泛型统一返回体适配所有接口前后端统一规范。fromtypingimportGeneric,TypeVar,Optional# 泛型定义TTypeVar(T)# 统一响应模型classApiResp(BaseModel,Generic[T]):code:int200msg:str请求成功data:Optional[T]None# 快捷工具函数defsuccess_resp(data:T|NoneNone,msg:str请求成功)-ApiResp[T]:returnApiResp(datadata,msgmsg)deffail_resp(msg:str请求失败,code:int400)-ApiResp:returnApiResp(codecode,msgmsg)# 改造接口使用统一返回体app.get(/users/{user_id},summary查询用户详情,response_modelApiResp[UserPublic])defget_user(user_id:int):ifuser_idlen(fake_user_db):returnfail_resp(msg用户不存在,code404)returnsuccess_resp(datafake_user_db[user_id-1])统一返回格式{code, msg, data}前端无需适配多种返回结构生产项目必备。八、阶段综合实战完整用户CRUD脱敏统一返回整合本阶段所有知识点实现可直接上线的用户新增、查询、更新接口包含参数校验、嵌套模型、数据脱敏、统一响应、混合传参。fromfastapiimportFastAPI,Header,Cookie,statusfrompydanticimportBaseModel,EmailStr,field_validatorfromtypingimportGeneric,TypeVar,Optional# 1. 统一响应封装 TTypeVar(T)classApiResp(BaseModel,Generic[T]):code:int200msg:str请求成功data:Optional[T]Nonedefsuccess_resp(dataNone,msg请求成功):returnApiResp(datadata,msgmsg)deffail_resp(msg请求失败,code400):returnApiResp(codecode,msgmsg)# 2. 模型分层入参/出参 classUserCreate(BaseModel):username:stremail:EmailStr password:strage:int|NoneNonefield_validator(username)defcheck_username(cls,v):iflen(v)3:raiseValueError(用户名至少3位)returnvclassUserUpdate(BaseModel):username:str|NoneNoneemail:EmailStr|NoneNoneage:int|NoneNoneclassUserPublic(BaseModel):id:intusername:stremail:EmailStr age:int|NoneNoneclassConfig:from_attributesTrue# 3. 项目初始化 appFastAPI(title第二阶段综合实战)fake_db[]# 4. 业务接口 app.post(/users,summary新增用户,response_modelApiResp[UserPublic],status_codestatus.HTTP_201_CREATED)defcreate_user(user:UserCreate):新增用户自动脱敏返回new_useruser.model_dump()new_user[id]len(fake_db)1fake_db.append(new_user)returnsuccess_resp(datanew_user)app.get(/users/{user_id},summary查询用户,response_modelApiResp[UserPublic])defget_user(user_id:int):根据ID查询脱敏用户信息ifuser_id1oruser_idlen(fake_db):returnfail_resp(用户不存在,404)returnsuccess_resp(datafake_db[user_id-1])app.put(/users/{user_id},summary更新用户,response_modelApiResp[UserPublic])defupdate_user(user_id:int,user:UserUpdate):局部更新用户信息ifuser_id1oruser_idlen(fake_db):returnfail_resp(用户不存在,404)update_datauser.model_dump(exclude_unsetTrue)fake_db[user_id-1].update(update_data)returnsuccess_resp(datafake_db[user_id-1])九、新手高频避坑指南1. ❌GET接口使用请求体HTTP规范禁止GET携带请求体查询参数只用查询参数2. ❌入参出参共用一个模型必然导致密码、密钥泄露必须分层DTO3. ❌忽略from_attributes配置ORM对象无法转换为响应模型直接报错4. ❌不做数据脱敏直接返回原始数据生产重大安全漏洞5. ❌混合传参参数名冲突路径参数、查询参数、请求体参数建议命名区分6. ✅严格分层模型Create/Update/Public三类模型各司其职7. ✅所有生产接口统一响应体杜绝返回格式混乱8. ✅复杂参数一律用请求体简单筛选用查询参数。十、阶段核心总结1.参数区分基础类型查询参数Pydantic模型请求体GET无请求体、POST/PUT核心用请求体2.请求体核心完全复用Pydantic校验能力支持单层/嵌套复杂JSON自动参数校验3.响应模型核心response_model实现字段过滤、敏感数据脱敏、返回格式标准化生产必备4.混合传参FastAPI支持路径查询请求体HeaderCookie多参数共存智能解析5.工程规范入参出参模型分层、统一泛型响应体贴合企业后端开发标准。
FastAPI 零基础教程（二）- 请求体与响应模型，1天吃透Pydantic无缝衔接
文章目录前言一、阶段学习目标二、核心概念查询参数 vs 请求体2\.1 核心区别新手必记2\.2 FastAPI识别规则三、核心实战Pydantic请求体3\.1 基础请求体单层级3\.2 运行测试3\.3 嵌套请求体复杂业务必备四、核心重点响应模型与数据脱敏生产必备4\.1 入参、出参模型分层生产规范4\.2 响应模型实战脱敏4\.3 响应模型进阶配置4\.3\.1 exclude\_unset只返回赋值字段4\.3\.2 手动指定排除/包含字段五、混合传参三种参数同时使用六、Header 与 Cookie 参数获取七、生产级统一响应体封装八、阶段综合实战完整用户CRUD脱敏\统一返回九、新手高频避坑指南十、阶段核心总结前言上一阶段我们掌握了FastAPI基础接口、路径参数、查询参数、RESTful规范与自动文档能快速编写基础查询接口。但真实业务中新增、修改、编辑数据几乎都需要传递复杂JSON数据单纯的查询参数完全无法满足需求。这就需要用到FastAPI核心核心能力请求体 响应模型。本阶段最大优势100%复用你已精通的Pydantic知识。FastAPI的请求校验、数据序列化、字段约束、脱敏返回全部基于Pydantic v2实现无需学习新语法无缝衔接旧知识。本文耗时1天学完彻底解决业务核心问题1. 复杂JSON请求参数接收、自动校验、类型转换2. 接口返回数据脱敏、字段过滤、统一格式化3. 路径参数、查询参数、请求体混合传参4. Header、Cookie请求头参数获取5. 生产级DTO分层入参模型/出参模型分离。一、阶段学习目标1. 彻底分清查询参数与请求体的使用场景与区别2. 熟练使用Pydantic BaseModel定义POST/PUT请求体掌握字段校验、默认值、必填规则3. 掌握嵌套请求体模型适配复杂多层JSON参数场景4. 精通response_model响应模型实现密码脱敏、字段过滤、数据格式化5. 掌握三种参数混合使用路径参数 查询参数 请求体6. 学会获取Header请求头、Cookie参数7. 搭建生产级统一接口返回体实现前后端格式统一8. 完成用户新增、编辑、脱敏查询完整实战接口。二、核心概念查询参数 vs 请求体2.1 核心区别新手必记上一阶段的路径参数、查询参数仅适用于简单少量参数、查询场景而请求体专门用于复杂JSON、大批量数据、新增/修改场景。参数类型传输位置适用请求方法数据格式业务场景查询参数URL ? 后拼接GET 为主简单键值对分页、筛选、搜索、ID查询请求体HTTP 请求体POST/PUT/PATCH复杂JSON、嵌套结构新增数据、编辑数据、批量提交2.2 FastAPI识别规则这是FastAPI的核心智能规则无需手动声明1. 普通基础类型int/str/bool自动识别为查询参数2. Pydantic模型类型继承BaseModel自动识别为请求体。三、核心实战Pydantic请求体所有请求体基于Pydantic BaseModel定义你之前学的所有校验规则长度、正则、邮箱、数值范围全部通用。3.1 基础请求体单层级实现用户新增接口接收JSON请求体自动完成参数校验。fromfastapiimportFastAPI,statusfrompydanticimportBaseModel,EmailStr,field_validator appFastAPI(title请求体与响应模型实战)# 定义请求体模型用户新增入参classUserCreate(BaseModel):# 必填字段username:stremail:EmailStr password:str# 可选字段带默认值age:int|NoneNoneis_active:boolTrue# 自定义字段校验复用Pydantic能力field_validator(username)defcheck_username(cls,v):iflen(v)3:raiseValueError(用户名长度不能小于3位)returnvfield_validator(password)defcheck_password(cls,v):iflen(v)6:raiseValueError(密码长度不能小于6位)returnv# POST接口接收JSON请求体app.post(/users,summary新增用户,status_codestatus.HTTP_201_CREATED)defcreate_user(user:UserCreate):# 自动校验参数非法参数直接返回422错误# 直接返回请求数据后续改造为脱敏响应模型returnuser3.2 运行测试启动项目uvicorn main:app --reload访问http://127.0.0.1:8000/docs调试正确请求体示例{username:zhangsan,email:zhangsanqq.com,password:123456,age:22}非法场景自动拦截邮箱格式错误、用户名过短、密码位数不足无需手写if判断。3.3 嵌套请求体复杂业务必备真实业务常出现多层嵌套JSON如用户绑定收货地址FastAPIPydantic完美支持嵌套模型。# 嵌套子模型收货地址classAddress(BaseModel):province:strcity:strdetail:str# 父模型用户新增嵌套地址classUserCreateWithAddr(BaseModel):username:stremail:EmailStr password:straddress:Address# 嵌套子模型age:int|NoneNone# 嵌套请求体接口app.post(/users/addr,summary新增用户绑定地址)defcreate_user_with_addr(user:UserCreateWithAddr):returnuser请求体支持多层嵌套自动递归校验所有字段适配复杂业务参数。四、核心重点响应模型与数据脱敏生产必备最大生产坑点直接返回数据库/请求原始数据会泄露密码、密钥等敏感信息。解决方案使用response_model响应模型实现字段过滤、敏感数据脱敏、返回格式统一。4.1 入参、出参模型分层生产规范严格分层禁止同一模型既做入参又做出参- UserCreate新增入参模型包含密码- UserPublic返回出参模型剔除密码、脱敏字段4.2 响应模型实战脱敏# 响应模型用户公开信息脱敏classUserPublic(BaseModel):id:intusername:stremail:EmailStr age:int|NoneNoneis_active:bool# 关键配置支持ORM/字典对象自动转换classConfig:from_attributesTrue# 模拟数据库fake_user_db[]# 改造新增接口添加响应模型脱敏app.post(/users,summary新增用户脱敏返回,response_modelUserPublic,status_codestatus.HTTP_201_CREATED)defcreate_user(user:UserCreate):# 模拟生成用户ID、存入数据库new_useruser.model_dump()new_user[id]len(fake_user_db)1fake_user_db.append(new_user)# 返回完整数据响应模型自动剔除password字段returnnew_user核心效果前端传入密码后端存储后返回数据自动剔除password字段彻底杜绝敏感信息泄露。4.3 响应模型进阶配置4.3.1 exclude_unset只返回赋值字段适用于局部更新场景不返回默认空字段app.post(/users,response_modelUserPublic,response_model_exclude_unsetTrue)4.3.2 手动指定排除/包含字段# 仅返回指定字段app.get(/users/{user_id},response_modelUserPublic,response_model_include{id,username,email})# 排除指定敏感字段app.get(/users/{user_id},response_model_exclude{password})五、混合传参三种参数同时使用真实业务高频场景路径参数 查询参数 请求体混合传参FastAPI可智能区分、互不冲突。场景根据用户ID路径参数分页查询参数更新用户信息请求体# 用户更新入参模型classUserUpdate(BaseModel):username:str|NoneNoneemail:EmailStr|NoneNoneage:int|NoneNone# 混合传参接口app.put(/users/{user_id},summary更新用户信息混合传参,response_modelUserPublic)defupdate_user(# 1. 路径参数用户IDuser_id:int,# 2. 查询参数分页/附加筛选is_validate:boolTrue,# 3. 请求体更新数据JSONuser:UserUpdate):return{user_id:user_id,is_validate:is_validate,**user.model_dump(exclude_unsetTrue)}FastAPI自动识别三类参数无需手动区分极大简化开发。六、Header 与 Cookie 参数获取业务常用获取请求头Token、设备信息、Cookie会话IDFastAPI原生支持。fromfastapiimportHeader,Cookieapp.get(/headers,summary获取请求头参数)defget_headers(# 获取自定义请求头token:str|NoneHeader(defaultNone),# 获取浏览器UAuser_agent:str|NoneHeader(defaultNone),# 获取Cookiesession_id:str|NoneCookie(defaultNone)):return{token:token,user_agent:user_agent,session_id:session_id}常用场景接口鉴权获取Token、统计客户端设备、会话状态校验。七、生产级统一响应体封装原生返回格式杂乱前端对接繁琐我们封装泛型统一返回体适配所有接口前后端统一规范。fromtypingimportGeneric,TypeVar,Optional# 泛型定义TTypeVar(T)# 统一响应模型classApiResp(BaseModel,Generic[T]):code:int200msg:str请求成功data:Optional[T]None# 快捷工具函数defsuccess_resp(data:T|NoneNone,msg:str请求成功)-ApiResp[T]:returnApiResp(datadata,msgmsg)deffail_resp(msg:str请求失败,code:int400)-ApiResp:returnApiResp(codecode,msgmsg)# 改造接口使用统一返回体app.get(/users/{user_id},summary查询用户详情,response_modelApiResp[UserPublic])defget_user(user_id:int):ifuser_idlen(fake_user_db):returnfail_resp(msg用户不存在,code404)returnsuccess_resp(datafake_user_db[user_id-1])统一返回格式{code, msg, data}前端无需适配多种返回结构生产项目必备。八、阶段综合实战完整用户CRUD脱敏统一返回整合本阶段所有知识点实现可直接上线的用户新增、查询、更新接口包含参数校验、嵌套模型、数据脱敏、统一响应、混合传参。fromfastapiimportFastAPI,Header,Cookie,statusfrompydanticimportBaseModel,EmailStr,field_validatorfromtypingimportGeneric,TypeVar,Optional# 1. 统一响应封装 TTypeVar(T)classApiResp(BaseModel,Generic[T]):code:int200msg:str请求成功data:Optional[T]Nonedefsuccess_resp(dataNone,msg请求成功):returnApiResp(datadata,msgmsg)deffail_resp(msg请求失败,code400):returnApiResp(codecode,msgmsg)# 2. 模型分层入参/出参 classUserCreate(BaseModel):username:stremail:EmailStr password:strage:int|NoneNonefield_validator(username)defcheck_username(cls,v):iflen(v)3:raiseValueError(用户名至少3位)returnvclassUserUpdate(BaseModel):username:str|NoneNoneemail:EmailStr|NoneNoneage:int|NoneNoneclassUserPublic(BaseModel):id:intusername:stremail:EmailStr age:int|NoneNoneclassConfig:from_attributesTrue# 3. 项目初始化 appFastAPI(title第二阶段综合实战)fake_db[]# 4. 业务接口 app.post(/users,summary新增用户,response_modelApiResp[UserPublic],status_codestatus.HTTP_201_CREATED)defcreate_user(user:UserCreate):新增用户自动脱敏返回new_useruser.model_dump()new_user[id]len(fake_db)1fake_db.append(new_user)returnsuccess_resp(datanew_user)app.get(/users/{user_id},summary查询用户,response_modelApiResp[UserPublic])defget_user(user_id:int):根据ID查询脱敏用户信息ifuser_id1oruser_idlen(fake_db):returnfail_resp(用户不存在,404)returnsuccess_resp(datafake_db[user_id-1])app.put(/users/{user_id},summary更新用户,response_modelApiResp[UserPublic])defupdate_user(user_id:int,user:UserUpdate):局部更新用户信息ifuser_id1oruser_idlen(fake_db):returnfail_resp(用户不存在,404)update_datauser.model_dump(exclude_unsetTrue)fake_db[user_id-1].update(update_data)returnsuccess_resp(datafake_db[user_id-1])九、新手高频避坑指南1. ❌GET接口使用请求体HTTP规范禁止GET携带请求体查询参数只用查询参数2. ❌入参出参共用一个模型必然导致密码、密钥泄露必须分层DTO3. ❌忽略from_attributes配置ORM对象无法转换为响应模型直接报错4. ❌不做数据脱敏直接返回原始数据生产重大安全漏洞5. ❌混合传参参数名冲突路径参数、查询参数、请求体参数建议命名区分6. ✅严格分层模型Create/Update/Public三类模型各司其职7. ✅所有生产接口统一响应体杜绝返回格式混乱8. ✅复杂参数一律用请求体简单筛选用查询参数。十、阶段核心总结1.参数区分基础类型查询参数Pydantic模型请求体GET无请求体、POST/PUT核心用请求体2.请求体核心完全复用Pydantic校验能力支持单层/嵌套复杂JSON自动参数校验3.响应模型核心response_model实现字段过滤、敏感数据脱敏、返回格式标准化生产必备4.混合传参FastAPI支持路径查询请求体HeaderCookie多参数共存智能解析5.工程规范入参出参模型分层、统一泛型响应体贴合企业后端开发标准。
