FastAPI 響應狀態碼：管理和自定義 HTTP Status Code
本文介紹了如何在 FastAPI 中聲明、使用和修改 HTTP 狀態碼，涵蓋了常見的 HTTP 狀態碼分類，如信息響應（1xx）、成功狀態（2xx）、客戶端錯誤（4xx）和服務器錯誤（5xx）。通過 status_code 參數和 fastapi.status 常量簡化開發，并提供了如何根據業務需求動態調整狀態碼的方法。此外，還介紹了如何通過 Response 參數在路徑操作函數內部修改響應狀態碼，以實現更精確的控制和更好的客戶端交互體驗。
文章目錄
- FastAPI 響應狀態碼：管理和自定義 HTTP Status Code
- 一 聲明 HTTP 狀態碼
- 二 HTTP 協議狀態碼
- 三 使用 `fastapi.status` 中的變量
- 四 使用 `Response` 參數更改狀態碼
- 五 完整代碼示例
- 六 源碼地址
- 七 參考
在 FastAPI 中，正確設置和管理 HTTP 狀態碼對于API的準確性和響應性至關重要。
一 聲明 HTTP 狀態碼
from fastapi import FastAPI, statusapp = FastAPI()@app.post("/items/", status_code=201)
async def create_item(name: str):return {"name": name}
status_code 參數屬于裝飾器中的參數，而非 路徑操作函數 的參數。它接收一個表示 HTTP 狀態碼的數字，或支持 IntEnum 類型，例如 Python 的 http.HTTPStatus。運行代碼文件 chapter17.py 來啟動應用：
$ uvicorn chapter17:app --reload
在 SwaggerUI 中可以查看在線文檔：http://127.0.0.1:8000/docs 。在文檔中會code會有顯示：
二 HTTP 協議狀態碼
在 HTTP 協議中，狀態碼是響應的一部分，通常由三位數字組成，并有便于識別的名稱，但關鍵仍是數字。常用狀態碼如下：
-
1xx（信息）：返回信息，通常不包含響應體，使用較少。
-
2xx
（成功）：表示請求成功，是最常用的狀態碼。
200：成功，默認狀態碼，表示一切正常。201：已創建，通常在創建新資源時使用。204：無內容，表示沒有響應體。
-
3xx
（重定向）：表示重定向請求，響應不一定包含內容。
304：未修改，表示資源未改變，不返回響應體。
-
4xx
（客戶端錯誤）：表示請求有誤。
400：一般客戶端錯誤。404：未找到資源。
-
5xx（服務器錯誤）：表示服務器問題，通常由服務器或應用錯誤引發，極少直接使用。
詳解見 Web HTTP Status 。
在開發應用軟件時，有時會自定義非標準響應碼，這些響應碼與標準的 HTTP 響應碼不同。
三 使用 fastapi.status 中的變量
@app.post("/items01/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):return {"name": name}
可以使用 fastapi.status 中預定義的變量，或通過 from starlette import status 導入。為了簡化開發，FastAPI 提供了與 starlette.status 相同的 fastapi.status，該變量直接來源于 Starlette。以下是已定義的 HTTP status code 變量：
HTTP_100_CONTINUE = 100
HTTP_101_SWITCHING_PROTOCOLS = 101
HTTP_102_PROCESSING = 102
HTTP_103_EARLY_HINTS = 103
HTTP_200_OK = 200
HTTP_201_CREATED = 201
HTTP_202_ACCEPTED = 202
HTTP_203_NON_AUTHORITATIVE_INFORMATION = 203
HTTP_204_NO_CONTENT = 204
HTTP_205_RESET_CONTENT = 205
HTTP_206_PARTIAL_CONTENT = 206
HTTP_207_MULTI_STATUS = 207
HTTP_208_ALREADY_REPORTED = 208
HTTP_226_IM_USED = 226
HTTP_300_MULTIPLE_CHOICES = 300
HTTP_301_MOVED_PERMANENTLY = 301
HTTP_302_FOUND = 302
HTTP_303_SEE_OTHER = 303
HTTP_304_NOT_MODIFIED = 304
HTTP_305_USE_PROXY = 305
HTTP_306_RESERVED = 306
HTTP_307_TEMPORARY_REDIRECT = 307
HTTP_308_PERMANENT_REDIRECT = 308
HTTP_400_BAD_REQUEST = 400
HTTP_401_UNAUTHORIZED = 401
HTTP_402_PAYMENT_REQUIRED = 402
HTTP_403_FORBIDDEN = 403
HTTP_404_NOT_FOUND = 404
HTTP_405_METHOD_NOT_ALLOWED = 405
HTTP_406_NOT_ACCEPTABLE = 406
HTTP_407_PROXY_AUTHENTICATION_REQUIRED = 407
HTTP_408_REQUEST_TIMEOUT = 408
HTTP_409_CONFLICT = 409
HTTP_410_GONE = 410
HTTP_411_LENGTH_REQUIRED = 411
HTTP_412_PRECONDITION_FAILED = 412
HTTP_413_REQUEST_ENTITY_TOO_LARGE = 413
HTTP_414_REQUEST_URI_TOO_LONG = 414
HTTP_415_UNSUPPORTED_MEDIA_TYPE = 415
HTTP_416_REQUESTED_RANGE_NOT_SATISFIABLE = 416
HTTP_417_EXPECTATION_FAILED = 417
HTTP_418_IM_A_TEAPOT = 418
HTTP_421_MISDIRECTED_REQUEST = 421
HTTP_422_UNPROCESSABLE_ENTITY = 422
HTTP_423_LOCKED = 423
HTTP_424_FAILED_DEPENDENCY = 424
HTTP_425_TOO_EARLY = 425
HTTP_426_UPGRADE_REQUIRED = 426
HTTP_428_PRECONDITION_REQUIRED = 428
HTTP_429_TOO_MANY_REQUESTS = 429
HTTP_431_REQUEST_HEADER_FIELDS_TOO_LARGE = 431
HTTP_451_UNAVAILABLE_FOR_LEGAL_REASONS = 451
HTTP_500_INTERNAL_SERVER_ERROR = 500
HTTP_501_NOT_IMPLEMENTED = 501
HTTP_502_BAD_GATEWAY = 502
HTTP_503_SERVICE_UNAVAILABLE = 503
HTTP_504_GATEWAY_TIMEOUT = 504
HTTP_505_HTTP_VERSION_NOT_SUPPORTED = 505
HTTP_506_VARIANT_ALSO_NEGOTIATES = 506
HTTP_507_INSUFFICIENT_STORAGE = 507
HTTP_508_LOOP_DETECTED = 508
HTTP_510_NOT_EXTENDED = 510
HTTP_511_NETWORK_AUTHENTICATION_REQUIRED = 511
四 使用 Response 參數更改狀態碼
@app.put("/get-or-create-task/{task_id}", status_code=200)
def get_or_create_task(task_id: str, response: Response):if task_id not in tasks:tasks[task_id] = "This didn't exist before"response.status_code = status.HTTP_201_CREATEDreturn tasks[task_id]
在路徑操作函數中聲明一個 Response 類型的參數，根據業務邏輯修改狀態碼 response.status_code = status.HTTP_201_CREATED 。
五 完整代碼示例
from fastapi import FastAPI, status, Responseapp = FastAPI()@app.post("/items/", status_code=201)
async def create_item(name: str):return {"name": name}@app.post("/items01/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):return {"name": name}tasks = {"foo": "Listen to the Bar Fighters"}@app.put("/get-or-create-task/{task_id}", status_code=200)
def get_or_create_task(task_id: str, response: Response):if task_id not in tasks:tasks[task_id] = "This didn't exist before"response.status_code = status.HTTP_201_CREATEDreturn tasks[task_id]六 源碼地址
詳情見：GitHub FastApiProj
七 參考
[1] FastAPI 文檔
