FastAPI 教程翻译 - 用户指南 17 - 响应状态码

FastAPI 教程翻译 - 用户指南 17 - 响应状态码

FastAPI Tutorial - User Guide - Response Status Code

The same way you can specify a response model, you can also declare the HTTP status code used for the response with the parameter status_code in any of the path operations:

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

• @app.get()

• @app.post()

• @app.put()

• @app.delete()

• etc.

  等等

from fastapi import FastAPI

app = FastAPI()


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

Note

注意

Notice that status_code is a parameter of the “decorator” method (get, post, etc). Not of your path operation function, like all the parameters and body.

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

The status_code parameter receives a number with the HTTP status code.

status_code 参数接收带有 HTTP 状态码的数字。

It will:

它会：

• Return that status code in the response.

  在响应中返回该状态码。

• Document it as such in the OpenAPI schema (and so, in the user interfaces):

  在 OpenAPI 模式中（在用户界面中）将其记录为：

Note

注意

Some response codes (see the next section) indicate that the response does not have a body.

某些响应码（请参阅下一部分）指示响应没有主体。

FastAPI knows this, and will produce OpenAPI docs that state there is no response body.

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

About HTTP status codes

关于 HTTP 状态码

Note

注意

If you already know what HTTP status codes are, skip to the next section.

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

In HTTP, you send a numeric status code of 3 digits as part of the response.

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

These status codes have a name associated to recognize them, but the important part is the number.

这些状态码具有关联的名称以识别它们，但重要的是数字。

In short:

简而言之：

• 100 and above are for “Information”. You rarely use them directly. Responses with these status codes cannot have a body.

  100 及以上表示『信息』。您很少直接使用它们。具有这些状态码的响应不能带有主体。

• 200 and above are for “Successful” responses. These are the ones you would use the most.

  200 及以上表示『成功』响应。这些是您最常使用的。

  • 200 is the default status code, which means everything was “OK”.

    默认状态码为 200，表示一切正常。

  • Another example would be 201, “Created”. It is commonly used after creating a new record in the database.

    另一个示例是 201，『已创建』。通常在数据库中创建新记录后使用。

  • A special case is 204, “No Content”. This response is used when there is no content to return to the client, and so the response must not have a body.

    特殊情况是 204，『无内容』。当没有内容返回给客户端时使用此响应，因此该响应没有主体。

• 300 and above are for “Redirection”. Responses with these status codes may or may not have a body, except for 304, “Not Modified”, which must not have one.

  300 及更高版本用于『重定向』。具有这些状态码的响应可能带有或可能没有主体，但除了 304『未修改』，它不带有主体。

• 400 and above are for “Client error” responses. These are the second type you would probably use the most.

  400 及更高版本用于『客户端错误』响应。这些是您可能第二最常使用的类型。

  • An example is 404, for a “Not Found” response.

    例如 404，表示『未找到』响应。

  • For generic errors from the client, you can just use 400.

    对于来自客户端的一般错误，你可以只使用 400。

• 500 and above are for server errors. You almost never use them directly. When something goes wrong at some part in your application code, or server, it will automatically return one of these status codes.

  500 及更高版本用于服务器错误。您几乎永远不会直接使用它们。当您的应用程序码或服务器中的某些部分出现问题时，它将自动返回这些状态码之一。

Tip

提示

To know more about each status code and which code is for what, check the MDN documentation about HTTP status codes.

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

Shortcut to remember the names

记住名字的快捷方式

Let’s see the previous example again:

让我们再次看前面的例子：

from fastapi import FastAPI

app = FastAPI()


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

201 is the status code for “Created”.

201 是『已创建』的状态码。

But you don’t have to memorize what each of these codes mean.

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

You can use the convenience variables from fastapi.status.

您可以使用来自 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}

They are just a convenience, they hold the same number, but that way you can use the editor’s autocomplete to find them:

它们只是一种便利，它们拥有相同的编号，这么一来，您可以使用编辑器的自动完成功能来查找它们：

Technical Details

技术细节

You could also use from starlette import status.

您也可以使用 from starlette import status。

FastAPI provides the same starlette.status as fastapi.status just as a convenience for you, the developer. But it comes directly from Starlette.

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

Changing the default

更改默认值

Later, in the Advanced User Guide, you will see how to return a different status code than the default you are declaring here.

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