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

與指定響應(yīng)模型的方式相同，你也可以在以下任意的路徑操作中使用 status_code 參數(shù)來(lái)聲明用于響應(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 等）的一個(gè)參數(shù)。不像之前的所有參數(shù)和請(qǐng)求體，它不屬于路徑操作函數(shù)。

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

Info

status_code 也能夠接收一個(gè) IntEnum 類(lèi)型，比如 Python 的 http.HTTPStatus。

它將會(huì)：

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

Note

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

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

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

Note

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

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

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

簡(jiǎn)而言之：

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

Tip

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

記住名稱的捷徑

讓我們?cè)俅慰纯粗暗睦樱?/p>

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)碼。

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

你可以使用來(lá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ù)字代碼，但是這樣使用你就可以使用編輯器的自動(dòng)補(bǔ)全功能來(lái)查找它們：

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

你也可以使用 from starlette import status。

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

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

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