响应状态码¶

与指定响应模型的方式相同，您还可以使用路径操作中的参数 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}

Note

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

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

Info

status_code 也可以接收一个 IntEnum，例如 Python 的 http.HTTPStatus。

它将：

在响应中返回该状态码。
在 OpenAPI 模式中（以及用户界面中）将其记录为如此：

Note

某些响应代码（见下一节）表示响应没有主体。

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

关于 HTTP 状态码¶

Note

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

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

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

简而言之：

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

Tip

要了解有关每个状态码以及哪个代码用于什么的更多信息，请查看 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。

更改默认值¶

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