FastAPI中request.body()只能调用一次,因底层ASGI流为单次消费;需先await读取bytes再解码为字符串,并缓存至request.state供复用,避免二次调用返回空值。

FastAPI 默认不缓存原始请求体,直接读取 request.body() 会消耗流,后续再调用就会返回空字节;要安全获取 Raw 字符串,必须主动读取并缓存,且注意编码和异步特性。
request.body() 只能调用一次
FastAPI 的 request 对象底层是 Starlette 的 Request,其 body() 方法返回 bytes,但内部使用的是单次消费的 ASGI 接收流。第二次调用会返回 b'',不是 bug,是设计使然。
- 常见错误现象:
await request.body()调用两次,第二次拿到空值,导致解析失败或字段丢失 - 如果你在中间件里读了一次 body,又在路由函数里再读 —— 后者一定为空
- Pydantic 模型自动解析 JSON 时也依赖 body 流,所以它和你手动读 body 是互斥的
正确获取 raw body 字符串的三步法
必须显式解码,并处理可能的编码异常;推荐在中间件或路由入口统一处理,避免重复读取。
- 先
await request.body()得到bytes - 再用
.decode("utf-8", errors="replace")转字符串(不用text(),它内部也只调一次 body) - 如果需要多次使用,把结果存进
request.state,例如:request.state.raw_body = raw_str
示例:
from fastapi import Request, FastAPI
app = FastAPI()
@app.post("/echo")
async def echo_raw(request: Request):
raw_bytes = await request.body()
try:
raw_str = raw_bytes.decode("utf-8")
except UnicodeDecodeError:
raw_str = raw_bytes.decode("utf-8", errors="replace")
return {"raw": raw_str}
Content-Type 不匹配时 raw body 更关键
当 PHP 或其他客户端发来 Content-Type: text/plain 的 JSON 字符串(如 '{"a":1}'),FastAPI 不会自动解析 —— 它只对 application/json 做 JSON 解析。此时你必须手动 decode + json.loads(),否则 Pydantic 会报 dict_type 错误。
- 别依赖
request.json():它只在Content-Type是application/json时才安全可用 - 用
json.loads(raw_str)替代,更可控 - 若 body 是空或非法 JSON,
json.loads会抛JSONDecodeError,需捕获
最易被忽略的一点:ASGI 生命周期里 body 流不可 rewind,没有“重置指针”机制。一旦读过,就没了 —— 所以要么只读一次、存起来复用,要么明确放弃自动解析、全程自己 handle raw 字符串。


















