在日常 FastAPI 開發中，我們經常需要定義接口的路徑參數（比如用戶狀態、類型、等級等）。這些參數雖然可以定義為 str，但用戶傳什么你就接收什么，接口既不安全也不優雅。

今天我們來介紹一個簡單又實用的技巧 —— 使用 Python 的 Enum 枚舉類限制路徑參數，讓你的接口從“裸奔”變得類型安全 + 文檔清晰 + 自動校驗！

場景復現：你是否遇到過這些問題？

假設我們有一個接口 /user/{status}，要根據用戶狀態查詢用戶列表。

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

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

看似沒問題，但其實有以下幾個弊端：

• 沒有類型限制，傳錯值只有運行時才報錯
• 路徑中該傳啥，接口文檔沒提示
• 不方便維護，校驗寫死在代碼中

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

FastAPI 支持原生 Python Enum，用起來很絲滑：

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"篩選狀態為：{status.value}"}

• 訪問 /user/active、/user/banned 沒問題
• 訪問 /user/unknown 會自動拋出 422 錯誤

為什么它很香？優勢如下：

還能配合 Query 使用！

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

from fastapi import Query

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

Enum 的最佳實踐技巧

(1) 繼承 str + Enum

class MyEnum(str, Enum) 會讓枚舉成員在 FastAPI 自動轉為字符串響應，推薦這么寫！

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

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

(3) 用于模型字段校驗

class User(BaseModel):
    status: UserStatus

枚舉也能在 Pydantic 模型中使用，自動校驗字段值是否合法！

總結

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

• 參數校驗的安全性
• API 文檔的提示友好度
• 接口代碼的可維護性和清晰度

可以說，這是每個 FastAPI 項目必學的技巧之一。