FastAPI 动态修改响应状态码：用 `Response` 参数在运行时返回 200 / 201 等不同 HTTP 状态码

通过声明在 path operation function（路径操作函数）中的 Response 类型参数，FastAPI 允许你在请求处理过程中按运行结果临时改写响应状态码，例如默认返回 200 OK，而当数据不存在需要新建时返回 201 Created；同时返回的数据仍会经过 response_model 的过滤与转换。本文将结合 FastAPI 仓库中官方文档（英文原版 与对应印地语译文）及源码实现，完整讲解这一机制的使用场景、写法与底层原理。

典型场景：默认状态码之外的“按需返回”

FastAPI 允许你在路由装饰器中声明一个固定的默认状态码：

@app.put("/items/{item_id}", status_code=200)

该基础能力在 Response Status Code 教程中已有说明，其中指出 status_code 是装饰器方法的参数，而非路径操作函数的参数；它最终会被记录进 OpenAPI schema，并作为响应的默认 HTTP 状态码返回。

然而现实中常出现一种需求：大多数情况下返回默认状态码，特定条件下返回另一种状态码。文档给出的场景非常典型：

• 默认情况下，接口返回 200 OK；
• 但如果请求的数据并不存在，接口需要先创建它，并返回 201 Created（“已创建”）；
• 与此同时，你仍然希望返回的数据能被声明的 response_model 做过滤与转换。

这类“get-or-create”（有则取、无则建）语义在 PUT 幂等接口中非常常见。解决它，就可以使用本文的核心工具——Response 参数。

核心写法：在路径操作函数中声明 Response 参数

正如你可以在函数中声明参数来直接操作 cookies 与 headers 一样，你也可以声明一个类型为 Response 的参数，并在需要时设置它（一个“临时”响应对象）的 status_code。

官方教程对应的完整示例代码位于 docs_src/response_change_status_code/tutorial001_py310.py：

from fastapi import FastAPI, Response, status

app = FastAPI()

tasks = {"foo": "Listen to the Bar Fighters"}


@app.put("/get-or-create-task/{task_id}", status_code=200)
def get_or_create_task(task_id: str, response: Response):
    if task_id not in tasks:
        tasks[task_id] = "This didn't exist before"
        response.status_code = status.HTTP_201_CREATED
    return tasks[task_id]

关键点如下：

• 第 1 行：Response 需要从 fastapi 导入（from fastapi import Response），而 status 模块提供了语义化的状态码常量（from fastapi import status）。
• 第 8 行：装饰器 @app.put(..., status_code=200) 声明接口默认返回 200 OK，这也决定了 OpenAPI 文档中该操作的默认响应。
• 第 9 行：在函数签名中声明 response: Response。FastAPI 会为它注入一个临时响应对象，你不需要（也不应该）自己创建它。
• 第 12 行：当 task_id 尚不存在时，把任务写入内存字典，同时把临时响应的 status_code 改为 status.HTTP_201_CREATED（即 201）。
• 第 13 行：之后依旧像普通情况一样返回任意对象——这里是一个 str，实际中可以是 dict、数据库模型等。

status.HTTP_201_CREATED 只是数字 201 的可读别名，直接写 response.status_code = 201 效果相同；使用常量可以享受编辑器的自动补全，避免记忆大量魔法数字。

为什么这里要使用常量而非魔法数字

在 Response Status Code 教程中明确说明：fastapi.status 提供了一批便捷常量，例如 HTTP_200_OK、HTTP_201_CREATED、HTTP_404_NOT_FOUND 等，它们本质上就是对应的数字，但让代码意图更清晰。

返回值仍可被 response_model 过滤与转换

这是该方案与“直接返回一个自定义 Response 对象”之间最核心的差异。文档特别强调：

如果你声明了 response_model，它依然会用于过滤和转换你返回的对象。

也就是说，这里的 response.status_code 只是对临时响应对象上状态码的修改，你最后仍返回普通数据对象（dict、模型等）。FastAPI 的处理逻辑是：

1. 从临时响应中提取状态码（同时还有 cookies 和 headers）；
2. 把你返回的值按 response_model 进行过滤、转换与序列化；
3. 将两者合并到最终发送给客户端的响应里。

因此你既获得了“运行时决定状态码”的灵活性，又没有放弃 response_model 带来的数据约束、字段过滤与 OpenAPI 文档自动生成能力。

源码视角：Response 参数是如何工作的

1. 临时响应对象的创建与注入

在 fastapi/dependencies/utils.py 的 solve_dependencies 中，如果调用路径上没有传入响应对象，FastAPI 会创建一个 Starlette 的 Response() 实例，并将其状态码初始化为 None：

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

随后在解析完每个依赖与参数后，若路径操作函数（或依赖）中声明了 response 参数，就把它注入到调用参数中（见 fastapi/dependencies/utils.py）：

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

正是这一步，让函数体里的 response.status_code = ... 落到了这个贯穿请求生命周期的临时对象上。

2. 临时状态码如何覆盖默认状态码

在请求处理完成后，fastapi/routing.py 中的 _build_response_args 负责挑选最终的状态码：

def _build_response_args(
    *, status_code: int | None, solved_result: Any
) -> dict[str, Any]:
    response_args: dict[str, Any] = {
        "background": solved_result.background_tasks,
    }
    # If status_code was set, use it, otherwise use the default from the
    # response class, in the case of redirect it's 307
    current_status_code = (
        status_code if status_code else solved_result.response.status_code
    )
    if current_status_code is not None:
        response_args["status_code"] = current_status_code
    if solved_result.response.status_code:
        response_args["status_code"] = solved_result.response.status_code
    return response_args

其中 status_code 参数来自装饰器上声明的默认值（如示例中的 200），而 solved_result.response 正是前面注入的临时响应对象。可以看到：临时响应对象上的 status_code 一旦被设置（非空），就会覆盖装饰器声明的默认值。这与文档中“最后一个被设置的生效”的描述完全一致。

3. 普通数据对象与最终响应

在 fastapi/routing.py 中，当路径操作函数返回的不是一个 Response 实例，而是普通数据对象时，FastAPI 会：

• 使用 _build_response_args 得到（可能被覆盖后的）状态码；
• 把返回值交给 serialize_response，按 response_model（对应源码中的 response_field）完成校验、过滤与序列化；
• 用 actual_response_class（默认 JSONResponse）构造最终响应，并把临时响应上的 headers 一并合并进去。

由此可以直观印证：返回普通对象 + 用 Response 参数改状态码，是一个“两者兼顾”的通道。

在依赖（Dependencies）中设置状态码：最后一次设置生效

文档还提示：你同样可以在依赖函数中声明 Response 参数并设置状态码。但需要注意——由于依赖与路径操作函数共享同一个临时响应对象，最后设置的那个人会赢（the last one to be set will win）。

从源码看，这一行为的根因在于 solve_dependencies 会递归解析子依赖并把同一个 response 对象继续向下传递（fastapi/dependencies/utils.py），所有层级最终读取和写入的是同一个临时响应。因此：

from fastapi import Depends, FastAPI, Response

app = FastAPI()

def set_created_if_new(response: Response):
    # 这里的设置会被路径操作函数中更晚的设置覆盖
    response.status_code = 202

@app.put("/example/{item_id}")
def example(item_id: str, response: Response, _=Depends(set_created_if_new)):
    # 如果这里又设置了 response.status_code，则以这里的为准
    ...
    return {...}

在设计多层依赖时，务必清楚“后写覆盖先写”的语义，避免依赖与路径操作函数对状态码的期望互相冲突。

用测试用例验证实际行为

仓库为上述示例提供了完整的测试，见 tests/test_tutorial/test_response_change_status_code/test_tutorial001.py：

from fastapi.testclient import TestClient

from docs_src.response_change_status_code.tutorial001_py310 import app

client = TestClient(app)


def test_path_operation():
    response = client.put("/get-or-create-task/foo")
    print(response.content)
    assert response.status_code == 200, response.text
    assert response.json() == "Listen to the Bar Fighters"
    response = client.put("/get-or-create-task/bar")
    assert response.status_code == 201, response.text
    assert response.json() == "This didn't exist before"

测试精确覆盖了两种分支：

• PUT /get-or-create-task/foo：任务已存在，返回默认 200，正文为既有的 "Listen to the Bar Fighters"；
• PUT /get-or-create-task/bar：任务不存在被创建，返回运行时修改后的 201，正文为新写入的 "This didn't exist before"。

这直接验证了“装饰器默认 200 + 运行时改 201”的组合在实际请求链路中工作正常，且正文仍按普通返回值序列化。

实用提示与易混淆点

1. 与直接返回 Response 对象的区别：如果你让路径操作函数直接返回 JSONResponse(status_code=201, content=...) 之类的对象，该响应会原样透传，response_model 的过滤将不再介入。而本文方案返回普通数据对象，response_model 依旧生效，二者适用的取舍点即在于你是否还需要模型层的数据约束与文档生成。

2. 状态码会进入 OpenAPI 文档吗：装饰器上声明的默认 status_code 决定 OpenAPI 中的声明内容；运行时通过 Response 参数动态设置的状态码属于请求时行为，不会改动 schema 层面该操作声明的响应。

3. 结合数据库“有则更新 / 无则创建”：把示例中的内存字典换成数据库后，if item not in ... 的判断可替换为对数据库的查询结果判断，再配合 status.HTTP_201_CREATED 或 status.HTTP_200_OK 返回不同状态码，即可轻松实现 REST 语义中标准的 upsert 接口。

关联阅读

• 状态码基础：默认响应状态码的声明方式，见 Response Status Code；
• 官方英文原版进阶文档：docs/en/docs/advanced/response-change-status-code.md；
• 示例源码：docs_src/response_change_status_code/tutorial001_py310.py；
• 行为验证测试：tests/test_tutorial/test_response_change_status_code/test_tutorial001.py。

综上，Response 参数为 FastAPI 提供了一条轻量而完整的“运行时改状态码”通道：它复用依赖注入框架，将临时响应贯穿整个请求链路，最终由路由层决定是否覆盖装饰器默认值。掌握它，你就能在保留 response_model 能力的同时，灵活地向客户端传达“创建成功”“内容已存在”等不同语义。