你如何在 Pydantic 中编写自定义验证？

Question

Accepted Answer

除了内置约束外，Pydantic 允许你用 field validators（验证单个字段）和 model validators（跨多个字段验证）编写**自定义验证逻辑** — 用于简单约束无法表达的规则。（下面的语法是 Pydantic v2。）

## Field validators — 验证/转换单个字段

```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` 在一个字段上运行自定义逻辑：raise `ValueError` 以拒绝无效输入（FastAPI 将其转换为清晰的 422），或返回一个转换后的值（例如规范化为小写）。

## Model validators — 跨字段验证

```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` 约束和专用类型；对于真实业务逻辑，使用自定义 validators。

## 为什么这很重要

自定义 Pydantic 验证很重要，因为它可以强制执行超越简单类型检查和约束的业务规则 — 由于验证对**安全性和数据完整性**至关重要，能够表达任何规则都是有价值的。**Field validators** 处理单字段逻辑（自定义格式检查、规范化/转换），而 **model validators** 处理**跨字段验证**的常见需求（密码匹配、日期范围、条件性要求），这是字段级规则无法表达的。

validators 与 FastAPI 无缝集成 — 抛出的 `ValueError` 会自动变成清晰的 422 响应。

了解何时使用内置约束/类型（对于简单规则）与自定义 validators（对于真实业务逻辑），以及 field validators 与 model validators 的区别，使你能够确保传入的数据完全满足应用的需求，这对构建健壮、正确的 API 是重要的知识。