【FastAPI 學習筆記 EP.27】欄位驗證器

什麼是欄位驗證器？

Pydantic 的 @field_validator 與 @model_validator 裝飾器允許你為模型欄位編寫自訂驗證邏輯。@field_validator 針對單一欄位進行驗證（例如：確認格式、轉換輸入值），@model_validator 則在所有欄位解析完成後運作，適合需要跨欄位比對的情境（例如：確認兩次密碼是否一致）。

欄位驗證器基礎語法

1. 使用 @field_validator("欄位名稱") 搭配 @classmethod 裝飾一個類別方法，在方法內驗證值，不符合則 raise ValueError。
2. mode="before" 可在型別轉換前攔截原始輸入值（適合資料清理），mode="after"（預設值）在型別轉換後執行。
3. 驗證通過時務必 return 值，回傳值會作為最終的欄位值，可在此同時對資料進行轉換（例如：將字串統一轉為小寫）。
4. 使用 @model_validator(mode="after") 裝飾一個方法，可在所有欄位解析完後對整個模型做跨欄位驗證。

from fastapi import FastAPI
from pydantic import BaseModel, field_validator, model_validator

app = FastAPI()

class RegisterForm(BaseModel):
    username: str
    email: str
    password: str
    confirm_password: str

    @field_validator("username")
    @classmethod
    def validate_username(cls, v: str) -> str:
        if len(v) < 3:
            raise ValueError("使用者名稱至少需要 3 個字元")
        if not v.isalnum():
            raise ValueError("使用者名稱只能包含英文字母與數字")
        return v.lower()  # 統一轉為小寫儲存

    @field_validator("email")
    @classmethod
    def validate_email(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError("Email 格式不正確")
        return v.lower()

    @model_validator(mode="after")
    def passwords_must_match(self) -> "RegisterForm":
        if self.password != self.confirm_password:
            raise ValueError("兩次輸入的密碼不一致")
        return self

@app.post("/register/")
def register(form: RegisterForm):
    return {"message": f"使用者 {form.username} 註冊成功"}