应定义泛型BaseResponse模型统一包裹data字段，所有路由返回BaseResponse[T]而非裸字典或JSONResponse，以保留类型校验、IDE提示和OpenAPI文档生成能力。
FastAPI 返回 JSON 时字段不统一，怎么强制套一层 data 包裹？
直接用 Response 或 JSONResponse 会绕过 FastAPI 的序列化流程，丢失类型校验和文档生成。正确做法是定义一个通用响应模型，再让所有路由返回它。
常见错误是手动拼 dict：{"code": 0, "msg": "ok", "data": user} —— 这会导致 Pydantic 模型失效、OpenAPI 文档里看不到 data 结构、IDE 无法提示字段。
- 定义
BaseResponse模型，泛型约束data类型（如BaseResponse[User]） - 所有接口返回
BaseResponse[xxx]，而不是裸 dict 或dict - 别在路由函数里用
return JSONResponse(...)，除非你明确要跳过验证
from pydantic import BaseModel
from typing import Generic, TypeVar
T = TypeVar("T")
class BaseResponse(BaseModel, Generic[T]):
code: int = 0
msg: str = "ok"
data: T | None = None
为什么用 ResponseModel 而不是中间件统一包装？
中间件改 Response body 是最常踩的坑：它发生在序列化之后，你拿到的是已转成字符串的 JSON，再解析再包一层，性能差、易出错、类型信息全丢，OpenAPI 文档里也只显示 str。
真正需要统一格式的地方，是类型定义层，不是传输层。
立即学习“Python免费学习笔记（深入）”；
- 中间件适合处理日志、CORS、压缩，不适合改业务响应结构
- 用模型泛型能保证 IDE 补全、mypy 检查、文档自动推导
data字段结构 - 如果真要用中间件（比如兼容老客户端），必须配合
response_class=Response并手动序列化，但会失去所有 FastAPI 的便利性
status_code 和 code 字段容易混淆，怎么避免？
HTTP 状态码（status_code）是协议层概念，应该由 FastAPI 根据异常或返回值自动设；业务码（code）是应用层约定，比如 1001 表示“用户不存在”。混用会导致前端不敢信状态码，后端不敢信业务码。
- 正常成功一律用
status_code=200（FastAPI 默认），把业务逻辑判断放进code字段 - 只有真正需要 HTTP 语义时才改
status_code，例如404对应资源未找到、422对应参数校验失败 - 不要为了“统一”把所有成功都写成
200却在code里塞500—— 这违背 REST 原则，代理、CDN、浏览器缓存都会出问题
异步接口返回 BaseResponse[AsyncIterator] 报错怎么办？
Pydantic 不支持直接序列化异步生成器，BaseResponse[AsyncIterator[Item]] 会卡在模型初始化阶段，报 TypeError: object AsyncGenerator can't be used in 'await' expression。
这不是 FastAPI 的 bug，是类型系统和运行时的错位。
- 流式响应（SSE、streaming JSON）必须用
StreamingResponse，不能走BaseResponse泛型路径 - 如果只是想“假装”是流但实际一次性返回，就用
List[Item]或list[Item]替代AsyncIterator - 真要流式 + 统一格式，得自己写
StreamingResponse的迭代器包装逻辑，把每条记录包进{"code":0,"msg":"ok","data":...}再 yield
