FastAPI教程 響應(yīng)狀態(tài)碼

與指定響應(yīng)模型的方式相同，你也可以在以下任意的路徑操作中使用 status_code 參數(shù)來聲明用于響應(yīng)的 HTTP 狀態(tài)碼：

• @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 等）的一個參數(shù)。不像之前的所有參數(shù)和請求體，它不屬于路徑操作函數(shù)。

status_code 參數(shù)接收一個表示 HTTP 狀態(tài)碼的數(shù)字。

Info

status_code 也能夠接收一個 IntEnum 類型，比如 Python 的 http.HTTPStatus。

它將會：

• 在響應(yīng)中返回該狀態(tài)碼。
• 在 OpenAPI 模式中（以及在用戶界面中）將其記錄為：

Note

一些響應(yīng)狀態(tài)碼（請參閱下一部分）表示響應(yīng)沒有響應(yīng)體。

FastAPI 知道這一點，并將生成表明沒有響應(yīng)體的 OpenAPI 文檔。

關(guān)于 HTTP 狀態(tài)碼

Note

如果你已經(jīng)了解什么是 HTTP 狀態(tài)碼，請?zhí)较乱徊糠帧?/p>

在 HTTP 協(xié)議中，你將發(fā)送 3 位數(shù)的數(shù)字狀態(tài)碼作為響應(yīng)的一部分。

這些狀態(tài)碼有一個識別它們的關(guān)聯(lián)名稱，但是重要的還是數(shù)字。

簡而言之：

• 100 及以上狀態(tài)碼用于「消息」響應(yīng)。你很少直接使用它們。具有這些狀態(tài)代碼的響應(yīng)不能帶有響應(yīng)體。
• 200 及以上狀態(tài)碼用于「成功」響應(yīng)。這些是你最常使用的。200 是默認(rèn)狀態(tài)代碼，它表示一切「正常」。另一個例子會是 201，「已創(chuàng)建」。它通常在數(shù)據(jù)庫中創(chuàng)建了一條新記錄后使用。一個特殊的例子是 204，「無內(nèi)容」。此響應(yīng)在沒有內(nèi)容返回給客戶端時使用，因此該響應(yīng)不能包含響應(yīng)體。
• 300 及以上狀態(tài)碼用于「重定向」。具有這些狀態(tài)碼的響應(yīng)可能有或者可能沒有響應(yīng)體，但 304「未修改」是個例外，該響應(yīng)不得含有響應(yīng)體。
• 400 及以上狀態(tài)碼用于「客戶端錯誤」響應(yīng)。這些可能是你第二常使用的類型。一個例子是 404，用于「未找到」響應(yīng)。對于來自客戶端的一般錯誤，你可以只使用 400。
• 500 及以上狀態(tài)碼用于服務(wù)器端錯誤。你幾乎永遠(yuǎn)不會直接使用它們。當(dāng)你的應(yīng)用程序代碼或服務(wù)器中的某些部分出現(xiàn)問題時，它將自動返回這些狀態(tài)代碼之一。

Tip

要了解有關(guān)每個狀態(tài)代碼以及適用場景的更多信息，請查看 MDN 關(guān)于 HTTP 狀態(tài)碼的文檔。

記住名稱的捷徑

讓我們再次看看之前的例子：

from fastapi import FastAPI

app = FastAPI()


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

201 是表示「已創(chuàng)建」的狀態(tài)碼。

但是你不必去記住每個代碼的含義。

你可以使用來自 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}

它們只是一種便捷方式，它們具有同樣的數(shù)字代碼，但是這樣使用你就可以使用編輯器的自動補全功能來查找它們：

技術(shù)細(xì)節(jié)

你也可以使用 from starlette import status。

為了給你（即開發(fā)者）提供方便，F(xiàn)astAPI 提供了與 starlette.status 完全相同的 fastapi.status。但它直接來自于 Starlette。

更改默認(rèn)狀態(tài)碼

稍后，在高級用戶指南中你將了解如何返回與在此聲明的默認(rèn)狀態(tài)碼不同的狀態(tài)碼。