回應狀態碼¶

如同您可以指定回應模型一樣，您也可以在任何路徑操作中使用參數 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}

注意事項

請注意，status_code 是「裝飾器」方法（get、post 等）的參數。而不是像所有參數和主體一樣，屬於您的路徑操作函式的參數。

status_code 參數接收一個包含 HTTP 狀態碼的數字。

資訊

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

它將

在回應中返回該狀態碼。
在 OpenAPI 結構描述（以及使用者介面）中將其記錄下來。

注意事項

某些回應碼（請參閱下一節）表示回應沒有主體。

FastAPI 知道這一點，並且會產生說明沒有回應主體的 OpenAPI 文件。

關於 HTTP 狀態碼¶

注意事項

如果您已經了解 HTTP 狀態碼，請跳到下一節。

在 HTTP 中，您會在回應中傳送一個 3 位數的狀態碼。

這些狀態碼都有一個相關聯的名稱以便識別，但重要的部分是數字。

簡而言之

100 和以上表示「資訊」。您很少直接使用它們。具有這些狀態碼的回應不能包含主體。
200 和以上表示「成功」的回應。這些是您最常使用的。
- 200 是預設狀態碼，表示一切「正常」。
- 另一個例子是 201，「已建立」。它通常在資料庫中建立新記錄後使用。
- 一個特殊情況是 204，「無內容」。當沒有內容要返回給客戶端時，就會使用此回應，因此回應不能包含主體。
300 和以上表示「重新導向」。具有這些狀態碼的回應可能包含也可能不包含主體，但 304，「未修改」除外，它不能包含主體。
400 和以上表示「客戶端錯誤」回應。這些是您可能第二常使用的類型。
- 一個例子是 404，表示「找不到」回應。
- 對於來自客戶端的通用錯誤，您可以直接使用 400。
500 和以上表示伺服器錯誤。您幾乎從不直接使用它們。當您的應用程式程式碼或伺服器的某個部分出現問題時，它會自動返回其中一個狀態碼。

提示

要進一步了解每個狀態碼以及哪個程式碼代表什麼，請查看 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 提供了與 starlette.status 相同的 fastapi.status，僅為了方便開發者使用。但它實際上直接來自 Starlette。

變更預設值¶

稍後，在進階使用者指南中，您將會看到如何返回與您在此處宣告的預設值不同的狀態碼。