响应状态码¶

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

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

Python 3.8+

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

Tip

要了解更多关于每个状态码及其含义的信息，请查看 MDN 关于 HTTP 状态码的文档。

记住名称的快捷方式¶

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

Python 3.8+

from fastapi import FastAPI

app = FastAPI()


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

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

但您不必记住每个代码的含义。

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

Python 3.8+

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。

更改默认值¶

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