核心概念 响应：接口返回给前端的全部内容，包含返回数据、HTTP 状态码、响应头。

区分两个概念：

1. 业务返回模型（Pydantic）：类似 Java 的Result<T>，用于规范 JSON 数据结构，业务开发必用。
2. 底层响应对象（XXResponse）：控制 HTTP 层，修改状态码、响应头、返回文件 /html，大部分业务接口不需要。

FastAPI 两种返回模式：

1. 返回普通数据（dict、list、Pydantic 实例）→ FastAPI自动封装成 JSONResponse。日常主流
2. 直接返回底层响应对象（JSONResponse、HTMLResponse 等）→ 完全手动控制 HTTP。特殊场景使用

---

一、自动响应

直接 return 字典、列表、Pydantic 对象，框架自动序列化为 JSON。

1. 基础返回示例

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List, Generic, TypeVar, Optional

app = FastAPI()

# 业务输出DTO
class UserDTO(BaseModel):
    id: int
    username: str

# 1 返回字典（简单demo用，正式项目不推荐裸字典）
@app.get("/demo")
def demo():
    return {"id": 1, "username": "小明"}

# 2 返回列表
@app.get("/user/list")
def user_list():
    return [{"id":1,"username":"a"},{"id":2,"username":"b"}]

2. response_model 参数（装饰器上使用）

作用：

1. 对输出数据做校验；
2. 过滤不需要返回的字段；
3. 在 /docs 自动生成正确接口文档。

常用配套参数：

• response_model_exclude={"字段名"}：返回时排除某些字段
• response_model_include={"id","name"}：只返回指定字段

@app.get("/user/{uid}", response_model=UserDTO)
def get_user(uid:int):
    # 即使数据库返回password，也不会输出出去，被model过滤
    return {"id":uid, "username":"小明", "password":"123456"}

3. 生产环境：统一泛型返回模型（对标 Java Result<T>）

真实业务项目，不会直接返回 DTO，外层统一套一层{code, msg, data}。

# 定义泛型统一返回体，全项目复用
T = TypeVar("T")
class ApiResp(BaseModel, Generic[T]):
    code: int
    msg: str
    data: Optional[T] = None

    @classmethod
    def success(cls, data: T, msg: str = "请求成功"):
        return cls(code=200, msg=msg, data=data)

    @classmethod
    def fail(cls, code: int, msg: str):
        return cls(code=code, msg=msg, data=None)

业务接口写法：

# response_model写外层泛型 ApiResp[内部DTO]
@app.get("/user/{uid}", response_model=ApiResp[UserDTO])
def get_user(uid: int):
    fake_db_data = {"id": uid, "username": "小明"}
    return ApiResp.success(data=fake_db_data)

# 返回列表场景 ApiResp[list[UserDTO]]
@app.get("/users", response_model=ApiResp[list[UserDTO]])
def get_users():
    return ApiResp.success(data=[{"id":1,"username":"a"},{"id":2,"username":"b"}])

返回前端结果：

{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "id": 1,
    "username": "小明"
  }
}

⚠️重要：返回的是ApiResp实例，不是 JSONResponse 对象，response_model才能生效，文档、输出校验正常工作。

---

二、底层显式响应对象（特殊场景才用，大部分业务接口不要用）

导入：from fastapi.responses import JSONResponse, HTMLResponse, PlainTextResponse, RedirectResponse, FileResponse

注意：一旦直接 return 这些响应对象，response_model全部失效，不会校验输出，文档 schema 也不会自动生成。

1）JSONResponse（相对最常用的底层响应）

适用场景：需要手动指定 HTTP 状态码、自定义响应头。

@app.post("/create")
def create():
    # 示例：创建资源返回201状态码
    return JSONResponse(
        content=ApiResp.success(data=None).model_dump(),
        status_code=201
    )

2）其余响应（了解即可，业务接口极少用到）

1. HTMLResponse：返回 html 页面，做简单页面渲染；
2. PlainTextResponse：返回纯文本；
3. RedirectResponse：页面跳转重定向；
4. FileResponse：文件下载，返回磁盘文件。

这些一般用于后台简单页面、文件下载接口，普通 CRUD 业务基本碰不到。

辅助工具 jsonable_encoder

导入：from fastapi.encoders import jsonable_encoder 作用：数据库 ORM 对象不能直接序列化，转成字典。

现在 Pydantic v2 对 ORM 支持已经很好，这个工具使用频率下降，遇到对象序列化报错时再用。

obj = UserDTO(id=1, username="test")
data = jsonable_encoder(obj)

---

三、响应相关总结表

方式	本质	是否常用	使用场景	关键点
return dict/list/Pydantic 实例	自动包装 JSONResponse	✅非常常用	绝大多数业务接口	配合response_model做输出校验
ApiResp[T]泛型模型	Pydantic 模型	✅生产必用	全项目统一返回格式，对标 Java Result	接口 return 模型实例，不要返回底层响应对象
JSONResponse	底层 HTTP 响应	⭕少量场景	需要自定义 HTTP 状态码、响应头	使用后 response_model 失效
HTMLResponse / FileResponse 等	底层 HTTP 响应	❌极少	返回网页、文件下载	普通业务 CRUD 不用