Pydanticでカスタム検証はどう書きますか?

Question

Accepted Answer

組み込み制約以上に、Pydantic は**カスタム検証ロジック**をフィールドバリデータ（1つのフィールドを検証）とモデルバリデータ（複数フィールドを検証）で記述できます — シンプルな制約では表現できないルール用です。(示されている構文は Pydantic v2 です。)

## フィールドバリデータ — 単一フィールドを検証/変換

```python
from pydantic import BaseModel, field_validator

class User(BaseModel):
    username: str
    password: str

@field_validator("username")
    @classmethod
    def username_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError("username must be alphanumeric")   # → a 422 error
        return v.lower()                                         # can also TRANSFORM the value
```

`@field_validator` はフィールドでカスタムロジックを実行します。無効な入力を拒否するために `ValueError` を発生させます (FastAPI はそれを明確な 422 に変えます)、または変換値を返します (例えば小文字への正規化)。

## モデルバリデータ — クロスフィールド検証

```python
from pydantic import model_validator

class SignupForm(BaseModel):
    password: str
    confirm_password: str

@model_validator(mode="after")
    def passwords_match(self):
        if self.password != self.confirm_password:    # compare MULTIPLE fields
            raise ValueError("passwords do not match")
        return self
```

`@model_validator(mode="after")` はすべてのフィールドが検証された後に実行され、モデル全体へのアクセスがあります — **複数フィールド**に関するルール用です (例えば、パスワードが一致することを確認する、または開始日が終了日より前であることなど)。

## 組み込み検証はしばしば最初で十分です

```python
class Product(BaseModel):
    price: float = Field(gt=0)          # use Field constraints for simple rules
    sku: str = Field(pattern=r"^[A-Z]{3}-\d+$")
    email: EmailStr                      # specialized types for formats
# reach for custom validators only when constraints/types can't express the rule
```

シンプルなルール用に `Field` 制約と特殊化された型を選択してください。本当のビジネスロジックにはカスタムバリデータを使用してください。

## なぜ重要なのか

Pydantic のカスタム検証は、シンプルな型チェックと制約を超えるビジネスルールを強制するために重要です — そして検証は**セキュリティとデータ整合性**に重要であるため、どのルールでも表現できる能力は価値があります。**フィールドバリデータ**は単一フィールドロジック (カスタム形式チェック、正規化/変換) を処理し、**モデルバリデータ**は**クロスフィールド検証** (パスワード一致、日付範囲、条件付き要件) の共通の必要性を処理します。フィールドレベルのルールは表現できません。

バリデータは FastAPI とシームレスに統合されます — 発生した `ValueError` は自動的に明確な 422 レスポンスになります。

組み込み制約/型 (シンプルなルール用) とカスタムバリデータ (本当のビジネスロジック用) をいつ使用するか、またフィールドバリデータとモデルバリデータがどう異なるかを理解することで、受け取るデータがアプリケーションの要件を完全に満たすことを保証でき、堅牢で正確な API を構築するための重要な知識となります。