【FastAPI】バリデーションを理解するField・Annotated・Validator の使い分け

Copy
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    quantity: int

Copy
Pydantic / FastAPIの入力検証
├─ Field
│  └─ フィールドに制約やメタデータを付ける
│     └─ 文字数、数値範囲、説明、デフォルト値など
│
├─ Annotated
│  └─ 型にメタデータを付ける
│     ├─ Fieldを型に結びつける
│     └─ Validatorを型に結びつける
│
├─ AnnotatedパターンのValidator
│  ├─ BeforeValidator
│  │  └─ Pydanticの型検証前に動く
│  │     └─ 入力値の正規化に使う
│  │
│  ├─ AfterValidator
│  │  └─ Pydanticの型検証後に動く
│  │     └─ 型確定後の追加チェックに使う
│  │
│  ├─ WrapValidator
│  │  └─ Pydanticの検証処理を包む
│  │     └─ 前処理と後処理をまとめて制御する
│  │
│  └─ PlainValidator
│     └─ Pydanticの標準検証を置き換える
│        └─ 独自の変換・検証に使う
│
└─ デコレータパターンのValidator
   ├─ @field_validator
   │  └─ モデル内のフィールドを検証する
   │
   └─ @model_validator
      └─ モデル全体を検証する
         └─ 複数フィールドの関係チェックなどに使う

Copy
Annotatedパターン
├─ BeforeValidator
├─ AfterValidator
├─ WrapValidator
└─ PlainValidator

デコレータパターン
├─ @field_validator(mode="before")
├─ @field_validator(mode="after")
├─ @field_validator(mode="wrap")
└─ @field_validator(mode="plain")

Copy
BeforeValidator
↔ @field_validator(mode="before")

AfterValidator
↔ @field_validator(mode="after")

WrapValidator
↔ @field_validator(mode="wrap")

PlainValidator
↔ @field_validator(mode="plain")

Copy
型にValidatorを結びつける
→ Annotatedパターン

モデルクラス内のフィールドにValidatorを定義する
→ デコレータパターン

Copy
from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(min_length=1, max_length=20)
    age: int = Field(ge=0, le=120)

Copy
from pydantic import BaseModel, Field

class User(BaseModel):
    name: str = Field(
        min_length=1,
        max_length=20,
        description="ユーザー名",
    )

Copy
Annotated[元の型, メタデータ]

Copy
from typing import Annotated

from pydantic import Field

UserName = Annotated[
    str,
    Field(min_length=1, max_length=20),
]

Copy
UserName
├─ 型: str
└─ メタデータ: Field(min_length=1, max_length=20)

Copy
from pydantic import BaseModel

class UserCreateRequest(BaseModel):
    name: UserName

Copy
from pydantic import BaseModel, Field

class UserCreateRequest(BaseModel):
    name: str = Field(min_length=1, max_length=20)

Copy
from typing import Annotated

from pydantic import BaseModel, Field

UserName = Annotated[
    str,
    Field(min_length=1, max_length=20),
]

class UserCreateRequest(BaseModel):
    name: UserName

Copy
class UserCreateRequest(BaseModel):
    name: str = Field(min_length=1, max_length=20)

class CompanyCreateRequest(BaseModel):
    contact_name: str = Field(min_length=1, max_length=20)

Copy
UserName = Annotated[
    str,
    Field(min_length=1, max_length=20),
]

class UserCreateRequest(BaseModel):
    name: UserName

class CompanyCreateRequest(BaseModel):
    contact_name: UserName

Copy
そのフィールドだけで使う制約
→ Fieldをモデル内に直接書く

複数箇所で使い回したい制約
→ Annotatedで型として切り出す

Copy
入力値
↓
BeforeValidator
↓
Pydantic本体の型検証・型変換
↓
AfterValidator
↓
最終値

Copy
from typing import Any, Annotated

from pydantic import BaseModel, BeforeValidator

def trim(v: Any) -> Any:
    if isinstance(v, str):
        return v.strip()
    return v

TrimmedStr = Annotated[
    str,
    BeforeValidator(trim),
]

class UserCreateRequest(BaseModel):
    name: TrimmedStr

Copy
{
  "name": "  taro  "
}

Copy
入力値 "  taro  "
↓
BeforeValidator(trim)
↓
"taro"
↓
Pydanticのstr検証
↓
最終値 "taro"

Copy
def trim(v: str) -> str:
    return v.strip()

Copy
from typing import Any

def trim(v: Any) -> Any:
    if isinstance(v, str):
        return v.strip()
    return v

Copy
from typing import Annotated

from pydantic import BaseModel, AfterValidator

def must_be_positive(v: int) -> int:
    if v <= 0:
        raise ValueError("正の整数である必要があります")
    return v

PositiveInt = Annotated[
    int,
    AfterValidator(must_be_positive),
]

class Item(BaseModel):
    quantity: PositiveInt

Copy
入力値
↓
Pydanticのint検証・変換
↓
AfterValidator(must_be_positive)
↓
最終値

Copy
from typing import Any, Annotated

from pydantic import BaseModel, BeforeValidator, AfterValidator

def trim(v: Any) -> Any:
    if isinstance(v, str):
        return v.strip()
    return v

def not_empty(v: str) -> str:
    if v == "":
        raise ValueError("空文字は不可")
    return v

NonEmptyStr = Annotated[
    str,
    BeforeValidator(trim),
    AfterValidator(not_empty),
]

class UserCreateRequest(BaseModel):
    name: NonEmptyStr

Copy
入力値 "  taro  "
↓
BeforeValidator(trim)
↓
"taro"
↓
Pydanticのstr検証
↓
AfterValidator(not_empty)
↓
最終値 "taro"

Copy
class UserCreateRequest(BaseModel):
    name: NonEmptyStr

Copy
class TagRequest(BaseModel):
    tags: list[NonEmptyStr]

Copy
WrapValidator開始
↓
前処理
↓
handler(v)でPydantic本体の検証
↓
後処理
↓
返却

Copy
from typing import Any, Annotated

from pydantic import BaseModel, ValidatorFunctionWrapHandler, WrapValidator

def wrap_trim(
    v: Any,
    handler: ValidatorFunctionWrapHandler,
) -> str:
    # 前処理
    if isinstance(v, str):
        v = v.strip()

    # Pydantic本体の検証
    value = handler(v)

    # 後処理
    if value == "":
        raise ValueError("空文字は不可")

    return value

NonEmptyStr = Annotated[
    str,
    WrapValidator(wrap_trim),
]

class User(BaseModel):
    name: NonEmptyStr

Copy
from typing import Any, Annotated

from pydantic import BaseModel, PlainValidator

def parse_int(v: Any) -> int:
    if isinstance(v, int):
        return v

    if isinstance(v, str) and v.isdecimal():
        return int(v)

    raise ValueError("整数に変換できません")

MyInt = Annotated[
    int,
    PlainValidator(parse_int),
]

class Item(BaseModel):
    count: MyInt

Copy
PlainValidator開始
↓
入力値を受け取る
↓
自分で変換・検証する
↓
Pydantic本体の型検証は行わない
↓
Validator関数の戻り値を最終値として扱う
↓
返却

Copy
Fieldで表現できるか
↓
BeforeValidator / AfterValidatorで表現できるか
↓
WrapValidatorで制御する必要があるか
↓
PlainValidatorで標準検証を置き換える必要があるか

Copy
from typing import Any

from pydantic import BaseModel, field_validator

class UserCreateRequest(BaseModel):
    first_name: str
    last_name: str

    @field_validator("first_name", "last_name", mode="before")
    @classmethod
    def trim_name(cls, v: Any) -> Any:
        if isinstance(v, str):
            return v.strip()
        return v

Copy
NonEmptyStr = Annotated[
    str,
    BeforeValidator(trim),
    AfterValidator(not_empty),
]

Copy
型として複数箇所で再利用したい
→ Annotatedパターン

特定モデル固有のフィールド検証として定義したい
→ @field_validator

Copy
from typing_extensions import Self

from pydantic import BaseModel, model_validator

class UserCreateRequest(BaseModel):
    password: str
    password_confirm: str

    @model_validator(mode="after")
    def check_passwords_match(self) -> Self:
        if self.password != self.password_confirm:
            raise ValueError("パスワードが一致しません")
        return self

Copy
def not_empty(v: str) -> str:
    if v == "":
        raise ValueError("空文字は不可")
    return v

Copy
def not_empty(v: str) -> str:
    if v == "":
        raise ValueError("空文字は不可")

Copy
その検証は特定のデータモデル内だけで使うか
├─ はい
│  ├─ 宣言的な単純な制約か
│  │  └─ Field
│  │
│  ├─ 特定フィールドの変換・検証か
│  │  └─ @field_validator
│  │
│  └─ 複数フィールドの関係を検証するか
│     └─ @model_validator
│
└─ いいえ
   └─ 複数のモデルやフィールドで再利用したい
      └─ Annotatedパターンで制約付き型として定義する
         ├─ 宣言的な制約
         │  └─ Field
         │
         ├─ 型検証前に入力を整える
         │  └─ BeforeValidator
         │
         ├─ 型検証後に追加チェックする
         │  └─ AfterValidator
         │
         ├─ 検証処理の前後をまとめて制御する
         │  └─ WrapValidator
         │
         └─ Pydanticの標準検証を置き換える
            └─ PlainValidator