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

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

場景復(fù)現(xiàn)：你是否遇到過這些問題？

假設(shè)我們有一個接口 /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}

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

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

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

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

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

為什么它很香？優(yōu)勢如下：

還能配合 Query 使用！

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

from fastapi import Query

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

Enum 的最佳實踐技巧

(1) 繼承 str + Enum

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

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

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

(3) 用于模型字段校驗

class User(BaseModel):
    status: UserStatus

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

總結(jié)

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

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

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