FastAPI怎么修改接口响应状态码和Header头信息-Python教程-PHP中文网

最常用方式是在路由装饰器中设置status_code参数，如@app.post("/users", status_code=201)，它固定返回指定状态码、影响openapi文档和响应头，但不干扰返回值序列化；若需动态控制，则通过函数参数response: response修改，或直接return jsonresponse等子类实现完全自定义响应。

fastapi怎么修改接口响应状态码和header头信息

直接在路由装饰器里设 status_code 参数

这是最常用、最轻量的方式，适合状态码固定且不依赖运行时逻辑的场景。比如创建资源默认返回 201，而不是默认的 200。

它只影响 OpenAPI 文档生成和响应头中的状态码，不干扰返回值序列化或 response_model 的处理。

status_code 是 @app.get() 这类装饰器的参数，不是函数参数
支持数字（如 201）或枚举（如 status.HTTP_201_CREATED）
如果函数体内又通过 Response 修改了 status_code，以函数体内为准（后者覆盖前者）
注意：某些状态码（如 204、304）会自动清空响应体，即使你 return 了 dict，FastAPI 也会忽略它

示例：

Fastapi Code Review

审查 FastAPI 代码的路由模式、依赖注入、验证和异步处理器。适用于审查 FastAPI 应用、检查 APIRouter 配置、依赖注入等。

下载

@app.post("/users", status_code=201)
def create_user(name: str):
    return {"id": 123, "name": name}

用 Response 参数动态改状态码和 Header

当你需要根据业务逻辑决定状态码（比如“查不到就创建并返回 201”），或者要同时设置多个 Header，就得在函数签名里加一个 response: Response 参数。

这个 Response 是 FastAPI 注入的临时对象，你对它的修改（status_code、headers、set_cookie）会被合并进最终响应，不影响 response_model 的字段过滤。

必须显式声明类型为 Response，否则 FastAPI 不会注入
response.headers["X-Custom"] = "value" 可设任意 header，但前端能读到需配合 CORS 的 expose_headers
多个中间件或依赖项都改 response.status_code 时，最后执行的那个生效
别在依赖项里设 status_code 后，又在路径函数里覆盖——容易漏掉逻辑分支

示例：

@app.put("/tasks/{task_id}")
def get_or_create_task(task_id: str, response: Response):
    if task_id not in tasks:
        tasks[task_id] = "new"
        response.status_code = status.HTTP_201_CREATED
        response.headers["X-Resource"] = "created"
    return {"task": tasks[task_id]}

直接 return Response 子类控制更底层行为

当你要完全绕过 FastAPI 默认的 JSON 序列化流程（比如返回纯文本、XML、流式响应、重定向），就得用 return JSONResponse(...) 或 return RedirectResponse(...) 这类明确构造的响应实例。

这种方式把状态码、header、content-type 全部收归一手控制，但代价是放弃 response_model 自动校验和文档生成能力。

JSONResponse、PlainTextResponse、StreamingResponse 都来自 Starlette，FastAPI 只做了 re-export
header 必须作为构造参数传入，不能事后赋值（不像注入的 Response 参数）
如果你只改状态码和一两个 header，用注入方式更简洁；真要换 content-type 或流式传输，才值得切到这里
别混用：不要既声明 response: Response 参数，又 return JSONResponse(...)，前者会被忽略

示例：

@app.get("/health")
def health_check():
    return JSONResponse(
        content={"status": "ok"},
        status_code=200,
        headers={"Cache-Control": "no-cache"}
    )

Header 和状态码的优先级与调试要点

实际部署中，最容易出问题的是「你以为设了，其实没生效」。核心在于理解 FastAPI 响应组装顺序：路径函数返回值 → response_model 转换 → 注入的 Response 对象补全 → 最终响应。

状态码冲突时：return Response(..., status_code=N) > 函数体内 response.status_code = N > 装饰器 status_code=N
Header 冲突时：函数体内 response.headers["X"] = ... 和 return JSONResponse(..., headers={...}) 不叠加，后者完全覆盖前者
用 curl -v 或浏览器 Network 面板看真实响应头，别只信日志或文档
CORS 场景下，自定义 header 如 X-Request-ID 必须显式加到 expose_headers 列表，否则前端 JS 拿不到