响应状态码¶

与指定响应模型的方式相同，您还可以使用参数 status_code 在任何 路径操作 中声明用于响应的 HTTP 状态码

@app.get()
@app.post()
@app.put()
@app.delete()
等等。

from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

注意

请注意，status_code 是“装饰器”方法（get、post 等）的参数。而不是您的 路径操作函数 的参数，就像所有参数和主体一样。

status_code 参数接收一个包含 HTTP 状态码的数字。

信息

status_code 还可以接收 IntEnum，例如 Python 的 http.HTTPStatus。

它将

在响应中返回该状态码。
在 OpenAPI 模式（以及用户界面）中记录它。

注意

一些响应代码（请参见下一节）指示响应没有主体。

FastAPI 知道这一点，并将生成声明没有响应主体的 OpenAPI 文档。

关于 HTTP 状态码¶

注意

如果您已经知道 HTTP 状态码是什么，请跳到下一节。

在 HTTP 中，您将一个 3 位数字的状态码作为响应的一部分发送。

这些状态码都有一个关联的名称来识别它们，但重要的部分是数字。

简而言之

100 及以上用于“信息”。您很少直接使用它们。具有这些状态码的响应不能有主体。
200 及以上用于“成功”响应。这些是您最常使用的响应。
- 200 是默认状态码，表示一切“正常”。
- 另一个示例是 201，“已创建”。它通常在数据库中创建新记录后使用。
- 一个特例是 204，“无内容”。当没有内容返回给客户端时，将使用此响应，因此响应不得有主体。
300 及以上用于“重定向”。具有这些状态码的响应可能具有或不具有主体，但 304，“未修改”除外，后者不得具有主体。
400 及以上用于“客户端错误”响应。这些可能是您最常使用的第二种类型。
- 例如，404 用于“未找到”响应。
- 对于来自客户端的通用错误，您可以只使用 400。
500 及以上用于服务器错误。您几乎从不直接使用它们。当应用程序代码或服务器的某些部分出现问题时，它将自动返回这些状态码之一。

提示

要了解有关每个状态码的更多信息以及哪个代码用于什么，请查看 MDN 关于 HTTP 状态码的文档。

记住名称的快捷方式¶

让我们再次看看前面的示例

from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

201 是“已创建”的状态码。

但您不必记住这些代码的含义。

您可以使用 fastapi.status 中的便捷变量。

from fastapi import FastAPI, status

app = FastAPI()


@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}

它们只是一个便利，它们包含相同的数字，但这样您就可以使用编辑器的自动完成功能来找到它们

“技术细节”

您也可以使用 from starlette import status。

FastAPI 提供与 fastapi.status 相同的 starlette.status，仅作为开发人员的便利。但它直接来自 Starlette。

更改默认值¶

稍后，在高级用户指南中，您将了解如何返回与您在此处声明的默认值不同的状态代码。