FastAPI 直接返回 Response：JSONResponse、自定义响应与 Response Model 的底层机制

在 FastAPI 中，path operation（路径操作函数）默认会把你返回的任何数据——dict、list、Pydantic model 乃至数据库模型——自动转换成 HTTP 响应。但官方文档同样提供了一条"旁路"：你可以直接构造并返回一个 Response（或其任意子类），此时 FastAPI 会对它原样透传，不做任何转换。本文以仓库文档 response-directly.md 为主线，结合 routing.py、responses.py、encoders.py 等源码实现，讲清直接返回 Response 的适用场景、与 jsonable_encoder 的配合方式、自定义响应的写法，以及声明 Response Model 时内部走的高性能"快路径"，帮助你判断什么时候该直接返回、什么时候该依赖自动序列化。

路径操作函数的返回与 FastAPI 的默认处理

在 FastAPI 中创建 path operation 时，你可以返回几乎任何数据：dict、list、Pydantic model、数据库对象等。FastAPI 对返回值采用了两级处理策略：

1. 如果你声明了 Response Model（返回类型），FastAPI 会借助 Pydantic（底层运行在 Rust 的 pydantic-core 上）把数据序列化为 JSON；
2. 如果你没有声明 response model，FastAPI 会调用 JSON 兼容编码器 中介绍的 jsonable_encoder，把数据转换成 JSON 可序列化的结构，再封装进 JSONResponse。

而你也可以跳过这两条路径，直接创建一个 JSONResponse 并把它作为函数返回值。

默认返回时的实际处理链路

在源码层面，默认行为可以在 routing.py 的请求处理主流程中看到：函数执行结束后，如果返回内容不是 Response 实例，FastAPI 会调用 serialize_response 进行序列化，再经由默认响应类（通常是 JSONResponse）包装；而在没有任何返回类型声明时，jsonable_encoder 就负责把 datetime、UUID 等特殊类型先"翻译"成 JSON 兼容的基础类型。

直接返回 Response：透传与自由度

你随时可以返回一个 Response 或者它的任意子类——请注意 JSONResponse 本身就是 Response 的子类。

关键在于：当你返回一个 Response 时，FastAPI 不会再用 Pydantic 转换数据，也不会把内容转换成其它类型。在 routing.py 中可以看到这条分支逻辑：

raw_response = await run_endpoint_function(...)
if isinstance(raw_response, Response):
    if raw_response.background is None:
        raw_response.background = solved_result.background_tasks
    response = raw_response

也就是说，只要返回值是 Response 实例，路由层就把它直接当作最终响应（仅补充后台任务引用），完全跳过序列化环节。

这种设计带来两方面影响：

• 更高的灵活性：你可以返回任意数据形态，甚至可以覆盖掉任何数据声明或校验逻辑，例如直接返回 RedirectResponse、StreamingResponse、HTMLResponse 等更底层的响应对象；
• 更多的责任：既然框架不做加工，你就必须自己保证返回的数据是正确的、格式正确的、可被序列化的——一旦出错，错误会直接暴露给客户端。

在 Response 中使用 jsonable_encoder

正因为 FastAPI 不会对你手动返回的 Response 做任何修改，你必须提前保证其内容是"就绪"的。

例如：你不能直接把一个 Pydantic model 塞进 JSONResponse，除非先把 datetime、UUID 等类型全部转换成 JSON 兼容类型（也就是先变成普通的 dict/list）。针对这类需求，官方推荐在构造响应前先用 jsonable_encoder 转换数据。仓库示例见 tutorial001_py310.py：

from datetime import datetime

from fastapi import FastAPI
from fastapi.encoders import jsonable_encoder
from fastapi.responses import JSONResponse
from pydantic import BaseModel


class Item(BaseModel):
    title: str
    timestamp: datetime
    description: str | None = None


app = FastAPI()


@app.put("/items/{id}")
def update_item(id: str, item: Item):
    json_compatible_item_data = jsonable_encoder(item)
    return JSONResponse(content=json_compatible_item_data)

这里 Item.timestamp 是 datetime 类型。直接把它放入 JSONResponse 会触发序列化失败，而 jsonable_encoder(item) 会先把它转换成一个所有值都可 JSON 序列化的 dict，随后再交给 JSONResponse(content=...) 渲染。

jsonable_encoder 到底转换了什么

查看 encoders.py 中维护的类型映射表 ENCODERS_BY_TYPE，可以看到它针对如下常见类型的内置规则：

• datetime.date / datetime.datetime / datetime.time：通过 isoformat() 转为字符串；
• datetime.timedelta：转为 total_seconds() 对应的秒数；
• UUID / IP 地址 / Path / Url：转为字符串；
• Decimal：无小数指数时转 int，否则转 float；
• Enum：取其 value；
• bytes：解码为字符串；
• set / frozenset / deque：转为 list。

同时，encoders.py 对 Pydantic model 的处理方式是先调用 model_dump(mode="json", ...) 得到字典，再做递归转换；对 dataclass 则先 dataclasses.asdict。默认 sqlalchemy_safe=True，会剔除 SQLAlchemy 内部以 _sa 开头的属性（这类属性无法也不应被序列化）。此外它还透传 Pydantic 的 include、exclude、by_alias、exclude_unset、exclude_none 等过滤参数，你可以按需控制输出的字段范围。

该示例同时被 tests/test_tutorial/test_response_directly/test_tutorial001.py 中的 test_path_operation 覆盖：向 PUT /items/1 提交包含 timestamp: "2023-01-01T12:00:00" 的 JSON 后，返回体中的时间戳与字段被完整保留，验证了"手动编码 + 手动 JSONResponse"链路是可用且稳定的。

技术细节：fastapi.responses 与 starlette.responses

文档中还给出一个技术细节：你也可以写 from starlette.responses import JSONResponse。这是因为 responses.py 里以 re-export 的方式把 Starlette 中的 Response、JSONResponse、PlainTextResponse、HTMLResponse、RedirectResponse、StreamingResponse、FileResponse、EventSourceResponse 等一并暴露为 fastapi.responses，纯粹是给开发者图方便——绝大多数可用的响应类实际上直接来自 Starlette。

返回自定义 Response：以 XML 为例

上述 jsonable_encoder 示例虽然涵盖了所有必需部件，但实际用途不大——毕竟你可以直接返回 item，让 FastAPI 默认帮你放进 JSONResponse 并转成 dict。真正体现"直接返回 Response"价值的是返回框架不认识的自定义格式。

假设你要返回一段 XML。可以把 XML 内容放进一个字符串，包进 Response 再返回，见仓库示例 tutorial002_py310.py：

from fastapi import FastAPI, Response

app = FastAPI()


@app.get("/legacy/")
def get_legacy_data():
    data = """<?xml version="1.0"?>
    <shampoo>
    <Header>
        Apply shampoo here.
    </Header>
    <Body>
        You'll have to use soap here.
    </Body>
    </shampoo>
    """
    return Response(content=data, media_type="application/xml")

这里的关键是 media_type="application/xml"——由于内容不再经过默认的 JSON 序列化，你必须显式声明正确的媒体类型。对应测试 tests/test_tutorial/test_response_directly/test_tutorial002.py 中的断言恰好验证了两点：

• 响应状态码为 200，且响应头 content-type 等于 application/xml；
• 响应正文与原始的 XML 字符串完全一致，未发生任何二次转换。

值得注意的是，同一测试中 /openapi.json 的快照显示：该接口的 200 响应在 OpenAPI 文档里仍然被登记为 application/json（schema 为空对象）。这正是"直接返回 Response 时数据不会被自动文档化"的直接证据——如果你希望文档如实反映 application/xml，就需要借助附加响应的声明手段。

Response Model 的工作原理：为何更快

作为对照，文档专门解释了声明 Response Model（返回类型） 时内部到底发生了什么。仓库示例 tutorial001_01_py310.py：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: list[str] = []


@app.post("/items/")
async def create_item(item: Item) -> Item:
    return item


@app.get("/items/")
async def read_items() -> list[Item]:
    return [
        Item(name="Portal Gun", price=42.0),
        Item(name="Plumbus", price=32.0),
    ]

当声明了 response_model 或返回类型注解时，FastAPI 的序列化流程与普通 Python 截然不同：

1. 它不会调用 jsonable_encoder（该过程较慢）；
2. 它也不会使用 JSONResponse 类去渲染；
3. 相反，它直接拿 Pydantic（Rust 侧）依据 response model 生成的 JSON bytes，包进一个 media type 为 application/json 的 Response 后返回。

这一"快路径"在 routing.py 中有非常直白的代码注释佐证：当设置了响应字段且 response_class 仍是默认占位符时，use_dump_json 为真，FastAPI 会走 serialize_response(..., dump_json=True)，由 Pydantic 的 TypeAdapter 直接把数据序列化成 JSON 字节，跳过"Python dict 中转 + json.dumps"这一中间步骤；最终响应也是直接用 Response(content=content, media_type="application/json") 构造，而非经过 JSONResponse 的二次渲染。

这也是为什么官方建议在大多数场景下优先声明 Response Model 而不是手动返回 JSONResponse——前者把序列化下沉到 Pydantic 的 Rust 内核完成，性能通常明显更好。仓库中 responses.py 里被标记为 deprecated 的 UJSONResponse、ORJSONResponse 也印证了同样的演进方向：其弃用说明明确指出，FastAPI 在设置了返回类型或 response model 后已能直接经 Pydantic 序列化为 JSON 字节，不再需要自定义响应类来提速。

注意事项：自动校验与自动文档化的边界

直接返回 Response 时，必须清楚以下边界：

• 其数据不会被自动校验、转换（序列化）或文档化；
• 数据正确性、格式合法性、可序列化性全部由你负责；
• 不过你仍然可以把它声明进 OpenAPI，具体方法见文档 OpenAPI 中的附加响应。

在后续的 advanced 章节（例如 custom-response.md）中，你可以进一步看到如何在保留自动数据转换与自动文档化的前提下声明和使用这些自定义 Response。这也正是理解本主题的意义所在：把"何时直接返回"与"何时交给框架"这两条路径分清楚，才能写出既灵活又不失严谨的 FastAPI 应用。