回應狀態碼¶

🌐 AI 與人類共同完成的翻譯

此翻譯由人類指導的 AI 完成。🤝

可能會有對原意的誤解，或讀起來不自然等問題。🤖

就像你可以指定回應模型一樣，你也可以在任一個「路徑操作（path operation）」的參數 status_code 中宣告回應所使用的 HTTP 狀態碼：

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

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


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

注意

請注意，status_code 是「裝飾器（decorator）」方法（get、post 等等）的參數，而不是你的「路徑操作函式」的參數，就像所有的參數與 body 一樣。

參數 status_code 接受一個數字作為 HTTP 狀態碼。

資訊

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

它會：

在回應中傳回該狀態碼。
在 OpenAPI 結構中如此記錄（因此也會反映在使用者介面中）：

注意

有些回應碼（見下一節）表示回應不包含本文（body）。

FastAPI 知道這點，並會產生聲明「無回應本文」的 OpenAPI 文件。

關於 HTTP 狀態碼¶

注意

如果你已經知道什麼是 HTTP 狀態碼，可以直接跳到下一節。

在 HTTP 中，你會在回應的一部分傳回 3 位數的狀態碼。

這些狀態碼有對應的名稱以便辨識，但重點是數字本身。

簡而言之：

100 - 199 表示「資訊」。你很少會直接使用它們。這些狀態碼的回應不可包含本文。
200 - 299 表示「成功」。這是你最常使用的一組。
- 200 是預設狀態碼，表示一切「OK」。
- 另一個例子是 201，代表「已建立」。常用於在資料庫中建立新紀錄之後。
- 一個特殊情況是 204，代表「無內容」。當沒有內容要回傳給用戶端時使用，因此回應不得有本文。
300 - 399 表示「重新導向」。這些狀態碼的回應可能有或沒有本文，唯獨 304（「未修改」）必須沒有本文。
400 - 499 表示「用戶端錯誤」。這大概是你第二常用的一組。
- 例如 404，代表「找不到」。
- 對於一般性的用戶端錯誤，你可以使用 400。
500 - 599 表示伺服器錯誤。你幾乎不會直接使用它們。當你的應用程式或伺服器某處出錯時，會自動回傳其中一個狀態碼。

提示

想深入瞭解各狀態碼與其用途，請參考 MDN 關於 HTTP 狀態碼的文件。

快速記住名稱¶

再看一次前面的範例：

Python 3.10+

from fastapi import FastAPI

app = FastAPI()


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

201 是「已建立（Created）」的狀態碼。

但你不需要背下每個代碼代表什麼。

你可以使用 fastapi.status 提供的便利變數。

Python 3.10+

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。

變更預設值¶

稍後在進階使用者指南中，你會看到如何回傳一個不同於此處所宣告預設值的狀態碼。