附加状态码¶

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

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

附加状态码¶

如果您想返回除主状态码之外的其他状态码，可以通过直接返回一个 Response（例如 JSONResponse）来实现，并直接设置附加状态码。

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

但您也想让它接受新项目。当项目以前不存在时，它会创建它们，并返回 201 "Created" 的 HTTP 状态码。

要实现这一点，导入 JSONResponse，然后直接在那里返回您的内容，并设置您想要的状态码。

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.9+Python 3.10+ - 非 AnnotatedPython 3.9+ - 非注解

from typing import Annotated, Union

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[Union[str, None], Body()] = None,
    size: Annotated[Union[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)

提示

如果可能，请优先使用 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)

提示

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

from typing import Union

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: Union[str, None] = Body(default=None),
    size: Union[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 以 fastapi.responses 的形式提供与 starlette.responses 相同的响应，只是为了方便您（开发者）。但大多数可用的响应都直接来自 Starlette。status 也是如此。

OpenAPI 和 API 文档¶

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

但您可以在代码中使用以下方式记录下来：附加响应。