FastAPI 请求体：Web 表单背后的“数据包裹”

你在网上填过注册信息吗？输入用户名、密码、邮箱、手机号，点击提交，后台就帮你创建好了账号。

你有没有想过：这些数据是怎么“打包”发送给后端服务器的？

如果你的答案是“通过 URL 地址传过去的”，那你可能会遇到一个问题——假设密码是 123456，注册时 URL 变成 /register?username=张三&password=123456&email=xxx，密码直接暴露在浏览器的地址栏和历史记录里，这无异于把家门钥匙贴在快递盒上寄出去。

显然，这种轻量级的方式根本无法承载海量、敏感的结构化数据。这时候就需要一个更大的“集装箱”来装载这些数据——这就是 请求体（Request Body） 的用武之地。

本文将站在普通 Web 用户的视角，彻底讲清楚什么是请求体、为什么需要它，以及 FastAPI 是如何利用 Pydantic 模型让你优雅地处理请求体的。

一、什么是请求体？（搬家公司的集装箱类比）
想象你要从旧家搬家到新家。

路径参数（Path Parameter）：像你告诉搬家公司：“目的地是 阳光花园3栋502室”（/house/502）。这是房子的地址（资源定位）。

查询参数（Query Parameter）：像你嘱咐搬家公司：“走高速，下午三点后再来”（?time=afternoon&route=highway）。这是搬家的附加条件（过滤/排序）。

请求体（Request Body）：像装着沙发、冰箱、床垫的巨型集装箱。里面是搬家内容的核心——所有的大件物品（表单数据、JSON 对象），装在车厢里（HTTP 消息体），而不是写在车身上的小纸条（URL）上。

请求体（Request Body），就是 HTTP 请求中位于消息体内、独立于 URL 之外的那部分数据。在 Web 开发中，它通常用于传输 JSON 格式 的结构化数据，大小可以达到几 MB 甚至几十 MB。

最关键的区别：路径参数和查询参数都在 URL 里（有长度限制，通常 2048 字符，且会留在浏览器历史中），而请求体在 HTTP 请求的“肚子”里（无大小硬上限，且 HTTPS 下是加密的）。

二、没有请求体的混乱现场（原始方式）
如果不用请求体（或者说不使用框架提供的请求体解析），直接操作原生的 HTTP 请求，代码会极其痛苦。

假设我们要处理一个用户注册的 API：

from fastapi import FastAPI, Request import json app = FastAPI() @app.post("/register") async def register(request: Request): # 1. 手动读取 HTTP 消息体（痛苦1：异步读流） raw_body = await request.body() # 2. 手动解码并解析 JSON（痛苦2：可能抛出异常） try: data = json.loads(raw_body) except json.JSONDecodeError: return {"error": "无效的 JSON 格式"} # 3. 手动检查字段是否存在（痛苦3：繁琐的 if/else） if "username" not in data or "password" not in data: return {"error": "缺少必填字段"} # 4. 手动校验类型和规则（痛苦4：重复劳动） if len(data["username"]) < 3: return {"error": "用户名太短"} if len(data["password"]) < 6: return {"error": "密码太短"} # 5. 终于...开始真正的业务逻辑 return {"message": f"欢迎, {data['username']}"}

痛点不言而喻：你明明只是想做注册，结果却写了 20 行处理“怎么把数据从包裹里拆出来”的代码。这在大型项目中会成为一场灾难。

三、FastAPI 的救赎：声明请求体
FastAPI 结合 Pydantic，让处理请求体的代码变得极其优雅。

1. 基础用法：定义模型即可用
你只需要做两件事：

用 Pydantic 定义数据的“蓝图”（结构）。

在路由函数的参数中声明它。

from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() # 1. 定义请求体蓝图（就像做一套标准模具） class UserRegister(BaseModel): username: str password: str email: str age: int = 0 # 带默认值，选填 # 2. 在路由参数里声明使用这个蓝图 @app.post("/register") async def register(user: UserRegister): # 到这行代码为止，FastAPI 已经替你干完了以下所有事： # - 读取 HTTP 消息体 # - 解析 JSON # - 校验 username 是不是字符串 # - 校验 password 存不存在 # - 校验 age 是不是整数（如果是 "18" 字符串，自动转数字） # - 如果失败，自动返回 422 错误并告知前端具体哪个字段错了 # 现在，只需专注于纯业务逻辑！ return { "message": f"欢迎 {user.username}", "email": user.email, "age": user.age }

前端只需要发送一个标准的 JSON 请求体：

POST /register Content-Type: application/json { "username": "张三", "password": "secure123", "email": "zhangsan@example.com", "age": 25 }

后端拿到的 user 就是一个标准的 Pydantic 对象，可以 .username、.password 直接点号访问，非常清爽。

四、请求体的三大核心作用（站在用户视角）
为什么大多数 Web 应用在提交数据时强制使用 POST 请求并附带请求体？因为用户和业务需要它来做三件关键的事。

1. 创建新资源（C in CRUD）
用户注册账号、发布一篇文章、上传一个商品——这些都是“从无到有”的操作。数据量大、结构复杂，必须用请求体携带。

场景：你在博客后台写新文章，标题、正文、标签、分类，一次性打包发给服务器。

请求方法：POST（最常用，语义为“创建”）。

2. 更新现有资源（U in CRUD）
用户修改个人信息、编辑文章、更新订单状态。虽然是更新，但往往需要携带完整的新的数据实体（或部分字段）。

场景：你在个人中心修改头像和签名。

请求方法：PUT（全量替换）或 PATCH（部分更新）。

3. 传输复杂的结构化数据
查询参数只能传扁平的键值对（key=value）。但现实业务中，数据往往是嵌套的。

场景：电商下单时，订单包含 { "user": { "id": 1, "address": {...} }, "items": [{ "sku": "A1", "qty": 2 }] }。这种层级关系只有请求体能完美表达。

五、高级用法：打造工业级的请求体验收
1. 结合 Field 添加约束
为了安全，我们不能完全信任前端传过来的数据。利用 pydantic.Field 可以在请求体验收时加上“硬门槛”：

from pydantic import BaseModel, Field, EmailStr class UserRegister(BaseModel): username: str = Field(..., min_length=3, max_length=20, description="用户名3-20位") password: str = Field(..., min_length=8, regex=r"^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$", description="至少8位含字母数字") email: EmailStr = Field(..., description="必须是有效的邮箱格式") age: int = Field(18, ge=0, le=150, description="年龄0-150岁")

如果前端传 {"username":"李四","password":"123","email":"invalid"}，FastAPI 会自动返回清晰的错误：

{ "detail": [ {"loc": ["body", "password"], "msg": "字符串长度不足8位", "type": "value_error"}, {"loc": ["body", "email"], "msg": "无效的邮箱地址", "type": "value_error"} ] }

2. 请求体与路径/查询参数混用（多源输入）
一个路由函数可以同时从三个地方获取数据：

从 路径 拿 user_id

从 查询参数 拿 token

从 请求体 拿更新内容

from fastapi import FastAPI, Query class UserUpdate(BaseModel): name: str age: int @app.put("/users/{user_id}") async def update_user( user_id: int, # 路径参数：更新哪个用户 token: str = Query(...), # 查询参数：权限校验 update_data: UserUpdate # 请求体：要更新的数据 ): return { "user_id": user_id, "token_verified": token == "secret", "new_name": update_data.name, "new_age": update_data.age }

3. 多模型和嵌套模型
真实业务中，请求体往往非常复杂：

from pydantic import BaseModel from typing import List class Address(BaseModel): city: str street: str zip_code: str class OrderItem(BaseModel): product_id: str quantity: int = Field(..., ge=1) price: float class OrderCreate(BaseModel): user_id: int shipping_address: Address # 嵌套模型 items: List[OrderItem] # 模型列表 remark: str = None

前端发送这样的 JSON，后端直接用 order.shipping_address.city 就能访问，Pydantic 会自动递归校验内部所有字段。

六、典型的 Web 应用场景（用户实际感知）
1. 用户注册 / 登录（最常见的个人体验）
你在任何 App 点“注册”，填写的用户名、密码、手机号通过 POST 请求的 Body 发送给后端，绝不暴露在 URL 里。

2. 购物车下单（电商场景）
点击“提交订单”，购物车商品列表、收货地址、优惠券 ID、支付方式，全部打包在一个巨大的 JSON 对象里通过请求体发出。

3. 内容发布（社交媒体 / CMS）
你发一条微博、一篇公众号文章，正文、图片 URL 列表、话题标签，都在请求体里。

4. AI 对话与 Agent 交互（现代应用）
向 ChatGPT 或 AI Agent 发送对话消息时，请求体包含 messages 数组（用户消息、系统指令、工具调用结果）、temperature、max_tokens 等参数，全是 JSON 格式。

POST /v1/chat/completions { "model": "gpt-4", "messages": [{"role": "user", "content": "介绍一下FastAPI"}], "temperature": 0.7 }

七、最佳实践与避坑指南
1. 请求体不要用在 GET 请求里
虽然 HTTP 规范没有严格禁止 GET 带 Body，但浏览器和大部分代理服务器会忽略或拒绝它。GET 请求只用路径和查询参数，POST/PUT/PATCH 才用请求体。

2. 区分 response_model 和请求模型
请求体是接收数据的模型（包含密码），响应模型是返回给前端的模型（不含密码）。务必分开定义，防止敏感字段泄露。

class UserIn(BaseModel): username: str password: str # 接收明文 class UserOut(BaseModel): username: str # 返回时隐藏密码 @app.post("/users", response_model=UserOut) async def create_user(user: UserIn): # user 包含了 password，但返回时 UserOut 会自动过滤掉 return {"username": user.username}

3. 严格指定 Content-Type
客户端请求头必须包含 Content-Type: application/json。如果传了 text/plain，FastAPI 会返回 415 错误（不支持的媒体类型）。

4. 限制请求体大小
为了防止恶意攻击（超大 JSON 撑爆内存），可以在中间件或 Nginx 层限制请求体大小（例如限制 10MB）。

八、结语
对于普通 Web 用户而言，请求体就是每一次点击“提交”、“确认”、“发布”按钮时，默默打包好所有个人隐私、商品信息和操作指令的“数据集装箱”。它把用户名、密码、订单详情这些核心内容藏在了加密的 HTTPS 隧道里（而不是暴露在浏览器地址栏），守护着你每一次互联网操作的安全。

对于 FastAPI 开发者而言，请求体是框架给予我们最慷慨的赋能之一。你再也无需与 request.body() 的原始字节流搏斗，也无需写海量的 if "key" in dict 来判断参数是否存在。你只需要像填写表格一样写好 class UserIn(BaseModel)，剩下的解析、校验、转换、文档生成，全部由框架替你优雅地完成。