在日常 FastAPI 開發(fā)中，我們經(jīng)常需要定義接口的路徑參數(shù)（比如用戶狀態(tài)、類型、等級(jí)等）。這些參數(shù)雖然可以定義為 str，但用戶傳什么你就接收什么，接口既不安全也不優(yōu)雅。

今天我們來(lái)介紹一個(gè)簡(jiǎn)單又實(shí)用的技巧 —— 使用 Python 的 Enum 枚舉類限制路徑參數(shù)，讓你的接口從“裸奔”變得類型安全 + 文檔清晰 + 自動(dòng)校驗(yàn)！

場(chǎng)景復(fù)現(xiàn)：你是否遇到過(guò)這些問(wèn)題？

假設(shè)我們有一個(gè)接口 /user/{status}，要根據(jù)用戶狀態(tài)查詢用戶列表。

不使用枚舉，你可能這么寫：

@app.get("/user/{status}")
def get_users(status: str):
    if status not in ["active", "inactive"]:
        raise HTTPException(status_code=400, detail="非法狀態(tài)值")
    return {"status": status}

看似沒(méi)問(wèn)題，但其實(shí)有以下幾個(gè)弊端：

• 沒(méi)有類型限制，傳錯(cuò)值只有運(yùn)行時(shí)才報(bào)錯(cuò)
• 路徑中該傳啥，接口文檔沒(méi)提示
• 不方便維護(hù)，校驗(yàn)寫死在代碼中

正確打開方式：用 Enum 限定參數(shù)取值！

FastAPI 支持原生 Python Enum，用起來(lái)很絲滑：

from enum import Enum
from fastapi import FastAPI

app = FastAPI()

class UserStatus(str, Enum):
    active = "active"
    inactive = "inactive"
    banned = "banned"

@app.get("/user/{status}")
def get_users(status: UserStatus):
    return {"msg": f"篩選狀態(tài)為：{status.value}"}

• 訪問(wèn) /user/active、/user/banned 沒(méi)問(wèn)題
• 訪問(wèn) /user/unknown 會(huì)自動(dòng)拋出 422 錯(cuò)誤

為什么它很香？?jī)?yōu)勢(shì)如下：

還能配合 Query 使用！

枚舉不僅能用在路徑參數(shù)，也能用在查詢參數(shù)：

from fastapi import Query

@app.get("/product/")
def get_product(category: UserStatus = Query(...)):
    return {"分類": category}

Enum 的最佳實(shí)踐技巧

(1) 繼承 str + Enum

class MyEnum(str, Enum) 會(huì)讓枚舉成員在 FastAPI 自動(dòng)轉(zhuǎn)為字符串響應(yīng)，推薦這么寫！

(2) 使用 .value 提取枚舉值

status.value 獲取枚舉實(shí)際字符串，不然是 <UserStatus.active> 這種對(duì)象

(3) 用于模型字段校驗(yàn)

class User(BaseModel):
    status: UserStatus

枚舉也能在 Pydantic 模型中使用，自動(dòng)校驗(yàn)字段值是否合法！

總結(jié)

使用 Enum 限定參數(shù)值，雖然是一個(gè)小技巧，但它極大提升了：

• 參數(shù)校驗(yàn)的安全性
• API 文檔的提示友好度
• 接口代碼的可維護(hù)性和清晰度

可以說(shuō)，這是每個(gè) FastAPI 項(xiàng)目必學(xué)的技巧之一。