额外的状态码

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

English version

FastAPI 默认使用 JSONResponse 返回一个响应，将你的 路径操作 中的返回内容放到该 JSONResponse 中。

FastAPI 会自动使用默认的状态码或者使用你在 路径操作 中设置的状态码。

额外的状态码

如果你想要返回主要状态码之外的状态码，你可以通过直接返回一个 Response 来实现，比如 JSONResponse，然后直接设置额外的状态码。

例如，假设你想有一个 路径操作 能够更新条目，并且更新成功时返回 200 「成功」 的 HTTP 状态码。

但是你也希望它能够接受新的条目。并且当这些条目不存在时，会自动创建并返回 201 「创建」的 HTTP 状态码。

要实现它，导入 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)

🤓 Other versions and variants

Python 3.10+ - non-Annotated

Tip

Prefer to use the Annotated version if possible.

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)

Warning

当你直接返回一个像上面例子中的 Response 对象时，它会直接返回。

它不会用模型等进行序列化。

确保其中有你想要的数据，且返回的值为合法的 JSON（如果你使用 JSONResponse 的话）。

技术细节

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

出于方便，FastAPI 为开发者提供同 starlette.responses 一样的 fastapi.responses。但是大多数可用的响应都是直接来自 Starlette。status 也是一样。

OpenAPI 和 API 文档

如果你直接返回额外的状态码和响应，它们不会包含在 OpenAPI 方案（API 文档）中，因为 FastAPI 没办法预先知道你要返回什么。

但是你可以使用 额外的响应 在代码中记录这些内容。