FastAPI `Response` 类参考：参数注入与直接返回的完整解析

2026-09-06 17:50:31作者：侯霆垣

Response 是 FastAPI 提供的核心响应基类，也是整个响应体系的根基：你既可以把 Response 类型声明为路径操作函数或依赖的参数，在请求处理过程中动态修改响应头、Cookie 和状态码，也可以直接创建并返回 Response（或其子类）实例，完全绕过 FastAPI 的数据序列化流程。读完本文，你将掌握 Response 的两种官方用法、其在 FastAPI 源码中的注入与直通机制（fastapi/dependencies/utils.py、fastapi/routing.py 中的关键调用链），以及直接返回 Response 与使用 Response Model 之间的性能取舍。

1. `Response` 是什么：来自 Starlette 的响应基类

FastAPI 本身不定义 Response 的实现，而是从 Starlette 直接再导出。在 fastapi/responses.py 中可以看到：

from starlette.responses import FileResponse as FileResponse  # noqa
from starlette.responses import HTMLResponse as HTMLResponse  # noqa
from starlette.responses import JSONResponse as JSONResponse  # noqa
from starlette.responses import PlainTextResponse as PlainTextResponse  # noqa
from starlette.responses import RedirectResponse as RedirectResponse  # noqa
from starlette.responses import Response as Response  # noqa
from starlette.responses import StreamingResponse as StreamingResponse  # noqa

官方参考文档给出的导入方式就是从 fastapi 直接导入：

from fastapi import Response

从源码结构看，fastapi.responses 与 fastapi.Response 只是对 Starlette 同名类的便捷再导出（FastAPI 文档在返回 Response 指南中也明确说明“FastAPI 提供的 starlette.responses 就是 fastapi.responses，只是方便开发者”），因此 Response 的构造参数遵循 Starlette 的约定：

参数	说明
`content`	响应体，通常为 `bytes`（如 `b""`）；直接返回时由你自行负责编码与格式
`status_code`	HTTP 状态码，默认为 `200`，可任意设置为合法值（如 `201`、`204`）
`headers`	响应头，`dict` 形式
`media_type`	媒体类型（如 `application/xml`），会写入 `Content-Type`
`background`	后台任务对象，响应发送完成后执行

由于它是所有具体响应类（JSONResponse、HTMLResponse 等）的基类，FastAPI 用 isinstance(x, Response) 来判断一个路径操作的返回值是否为“直接返回的响应”。

2. 用法一：作为参数注入，动态修改响应

官方参考文档 Response class 的第一种用法是：在 路径操作函数 或依赖中声明一个类型为 Response 的参数，然后修改响应数据，如 headers 或 cookies。

from fastapi import Depends, FastAPI, Response

app = FastAPI()


def set_cookie(response: Response) -> None:
    response.set_cookie(key="session", value="abc123")


def set_header(response: Response) -> None:
    response.headers["X-Custom-Header"] = "my-value"


@app.get("/", dependencies=[Depends(set_cookie), Depends(set_header)])
async def read():
    return {"msg": "Hello World"}

依赖函数中设置的 Cookie 和响应头会随最终响应一起发出。这条链路的源码依据在 fastapi/dependencies/utils.py：

参数识别：add_non_field_param_to_dependency() 在分析函数签名时，发现类型注解是 Response 的子类，就记录参数名——

elif lenient_issubclass(type_annotation, Response):
    dependant.response_param_name = param_name
    return True

实例创建：solve_dependencies() 在解析依赖树之前，如果没有现成的响应对象，会创建一个占位实例，并先移除 content-length 头、把 status_code 置空（此时响应体尚未确定，长度未知），保证所有层级的依赖共享同一个对象——

if response is None:
    response = Response()
    del response.headers["content-length"]
    response.status_code = None  # type: ignore

参数注入：解析完成后，把该实例按名字塞进调用参数——

if dependant.response_param_name:
    values[dependant.response_param_name] = response

正因为依赖与路径操作拿到的是同一个 Response 实例，依赖里改的头、状态码、Cookie 才能对最终响应生效。仓库测试 tests/test_response_change_status_code.py 正是这样验证的：依赖 response_status_setter 中执行 response.status_code = 201，最终 TestClient 收到的响应状态码即为 201，而响应体仍是路径操作返回的 {"msg": "Hello World"}。这些头部最终是在 fastapi/routing.py 中与真正要发送的响应合并的：

response.headers.raw.extend(solved_result.response.headers.raw)

即：依赖/路径操作里注入的那个 Response 对象上累积的所有原始头部，都会被合并进最终响应的头部。

3. 用法二：直接返回 `Response` 实例

参考文档的第二种用法是：直接创建 Response（或其子类）实例并从路径操作返回。

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")

这个示例完整保留自仓库官方教程源码 docs_src/response_directly/tutorial002_py310.py：把 XML 字符串放进 Response，指定 media_type="application/xml" 后直接返回。

路由层的处理逻辑在 fastapi/routing.py 的 get_route_handler() 生成的 app() 中，路径操作调用结束后：

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

这揭示了三个关键行为：

直通机制：只要返回值是 Response 实例（包括 JSONResponse、HTMLResponse 等所有子类），FastAPI 原样把它作为最终响应，不做任何 Pydantic 模型转换、不经过 response_model 校验，也不做 jsonable_encoder 编码——这正是文档所说“带来很大灵活性，也带来很大责任”；
后台任务接管：如果返回的 Response 没有设置 background，FastAPI 会把依赖层积累的 BackgroundTasks 挂到它上面，保证依赖中注册的后台任务在直接返回 Response 时依然执行；
状态码约束：对非直接返回的响应，FastAPI 还会检查 is_body_allowed_for_status_code(response.status_code)，例如 204、304 这类不允许携带响应体的状态码会把 response.body 置为 b""。

4. 直接返回 `JSONResponse`：配合 `jsonable_encoder`

当返回的是 dict/Pydantic 模型而非 Response 实例时，FastAPI 默认会用 jsonable_encoder 转成 JSONResponse。如果你需要手动构造 JSONResponse（例如要控制状态码和头部同时返回 JSON），先把不可 JSON 序列化的数据（datetime、UUID 等）转好即可。以下示例来自 docs_src/response_directly/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 包含 datetime 字段，直接塞进 JSONResponse 会失败；jsonable_encoder(item) 先将其转换为 JSON 兼容的 dict，再由 JSONResponse 序列化。注意 JSONResponse 本身就是 Response 的子类，因此它同样走上面第 3 节的“直通”分支。

5. 取舍：直接返回 `Response` vs. 声明 Response Model

直接返回 Response 意味着数据不会被校验、不会被转换（序列化）、也不会自动写入 OpenAPI 文档（OpenAPI 中仍可手动补充说明，参考 Additional Responses in OpenAPI）。因此需要权衡：

选 Response Model（返回类型或 response_model）：性能更好。从 fastapi/routing.py 的响应序列化分支可以看到，当存在带 TypeAdapter 的响应字段且未设置自定义响应类时，FastAPI 会走 Pydantic dump_json 快速路径，把数据直接序列化为 JSON 字节（Rust 核心完成），跳过“中间 Python dict + json.dumps()”这一步，然后用原生 Response(content=..., media_type="application/json") 返回：

# Use the fast path (dump_json) when no custom response
# class was set and a response field with a TypeAdapter
# exists. Serializes directly to JSON bytes via Pydantic's
# Rust core, skipping the intermediate Python dict +
# json.dumps() step.
use_dump_json = response_field is not None and isinstance(
    response_class, DefaultPlaceholder
)
...
if use_dump_json:
    response = Response(
        content=content,
        media_type="application/json",
        **response_args,
    )

这也解释了官方文档的提示：通常使用 Response Model 的性能要高于直接返回 JSONResponse。仓库测试 tests/test_dump_json_fast_path.py 专门覆盖了这条快速路径。

选直接返回 Response：当你需要返回非 JSON 数据（XML、纯文本、文件、流）、需要自定义媒体类型、或要完全控制序列化格式时，直接返回是最直接的方式。

依赖注入式用法（第 2 节）与二者都不冲突：无论最终响应是模型序列化产物还是直接返回的 Response，依赖中设置的响应头都会被 response.headers.raw.extend(...) 合并进最终响应。

6. 同模块中可用的其他响应类

fastapi/responses.py 除了 Response 外还再导出了一整套 Starlette 响应类，导入方式与 Response 一致：

from fastapi.responses import JSONResponse, HTMLResponse, PlainTextResponse
from fastapi.responses import RedirectResponse, StreamingResponse, FileResponse
from fastapi.responses import EventSourceResponse

另外需要留意的是：同文件中的 UJSONResponse 与 ORJSONResponse 两个 JSONResponse 子类已被标记弃用（带 @deprecated 装饰器），原因是“FastAPI 现在在设置了返回类型或 response model 时会通过 Pydantic 直接把数据序列化为 JSON 字节，速度更快且无需自定义响应类”。因此在当前版本中，若追求更快的 JSON 序列化，应优先依赖 Response Model / 返回类型机制，而不是引入已弃用的响应类。

7. 小结与延伸阅读

Response 类参考的核心要点可以归纳为：

Response 直接从 starlette.responses 再导出，是 FastAPI 所有响应类的基类；
注入用法：声明 Response 类型参数即可在路径操作或依赖中设置 headers、cookies、状态码，底层依赖 fastapi/dependencies/utils.py 的参数识别与单实例共享机制；
直返用法：返回 Response 实例时 FastAPI 原样透传、不校验不序列化，但会自动接管后台任务，并对不允许携带响应体的状态码清空 body；
优先用 Response Model 获得 Pydantic Rust 核心的直接序列化性能，仅在需要控制传输细节时直接返回 Response。