附加状态码¶

默认情况下，FastAPI 将使用 JSONResponse 返回响应，并将你在路径操作中返回的内容放入该 JSONResponse 中。

它将使用默认状态码或你在路径操作中设置的状态码。

附加状态码¶

如果你想在主要状态码之外返回其他附加状态码，可以直接返回一个 Response（例如 JSONResponse），并直接设置附加状态码。

例如，假设你有一个允许更新项目的路径操作，成功时返回 HTTP 状态码 200 "OK"。

但你也希望它能接受新项目。如果项目之前不存在，则创建它们，并返回 HTTP 状态码 201 "Created"。

要实现这一点，导入 JSONResponse，直接返回你的内容，并设置所需的 status_code

Python 3.10+

from typing import Annotated

from fastapi import Body, FastAPI, status
from fastapi.responses import JSONResponse

app = FastAPI()

items = {"foo": {"name": "Fighters", "size": 6}, "bar": {"name": "Tenders", "size": 3}}


@app.put("/items/{item_id}")
async def upsert_item(
    item_id: str,
    name: Annotated[str | None, Body()] = None,
    size: Annotated[int | None, Body()] = None,
):
    if item_id in items:
        item = items[item_id]
        item["name"] = name
        item["size"] = size
        return item
    else:
        item = {"name": name, "size": size}
        items[item_id] = item
        return JSONResponse(status_code=status.HTTP_201_CREATED, content=item)

🤓 其他版本和变体

Python 3.10+ - 非 Annotated

提示

如果可能，请优先使用 Annotated 版本。

from fastapi import Body, FastAPI, status
from fastapi.responses import JSONResponse

app = FastAPI()

items = {"foo": {"name": "Fighters", "size": 6}, "bar": {"name": "Tenders", "size": 3}}


@app.put("/items/{item_id}")
async def upsert_item(
    item_id: str,
    name: str | None = Body(default=None),
    size: int | None = Body(default=None),
):
    if item_id in items:
        item = items[item_id]
        item["name"] = name
        item["size"] = size
        return item
    else:
        item = {"name": name, "size": size}
        items[item_id] = item
        return JSONResponse(status_code=status.HTTP_201_CREATED, content=item)

警告

当你像上面的例子那样直接返回一个 Response 时，它将直接被返回。

它不会被模型序列化等。

请确保它包含你想要的数据，并且这些值是合法的 JSON（如果你使用的是 JSONResponse）。

技术细节

你也可以使用 from starlette.responses import JSONResponse。

FastAPI 提供了与 starlette.responses 相同的 fastapi.responses，这只是为了方便开发者使用。但大多数可用的响应都直接来自 Starlette。status 也是如此。

OpenAPI 和 API 文档¶

如果你直接返回附加状态码和响应，它们将不会包含在 OpenAPI 模式（API 文档）中，因为 FastAPI 无法预先知道你要返回什么。

但你可以在代码中通过以下方式记录它们：附加响应。