Pydantic字段验证器模式详解：before、after、wrap与plain

2025-05-09 20:07:46作者：董斯意

在Python的数据验证库Pydantic中，字段验证器(Field Validator)提供了四种不同的验证模式，这些模式决定了验证逻辑何时执行以及如何处理输入值。本文将深入解析这四种验证模式的工作原理和使用场景。

字段验证器基础

Pydantic的字段验证器通过@field_validator装饰器实现，它允许开发者为模型中的特定字段定义自定义验证逻辑。与模型验证器不同，字段验证器专注于单个字段的值处理。

四种验证模式详解

1. after模式（默认模式）

after模式是字段验证器的默认行为。在这种模式下，验证器会在Pydantic完成基础类型转换后执行。这意味着：

输入值已经经过了类型转换（如字符串转数字）
验证器接收的是转换后的值
适合执行业务逻辑验证

from pydantic import BaseModel, field_validator

class UserModel(BaseModel):
    age: int
    
    @field_validator('age')  # 默认就是after模式
    def check_age(cls, v):
        if v < 18:
            raise ValueError('年龄必须大于18岁')
        return v

2. before模式

before模式验证器会在Pydantic进行任何类型转换之前执行：

接收原始输入值
可以在类型转换前进行预处理或验证
返回的值会继续进行常规的类型转换

class UserModel(BaseModel):
    age: int
    
    @field_validator('age', mode='before')
    def preprocess_age(cls, v):
        if isinstance(v, str) and v.lower() == 'unknown':
            return 0  # 将特定字符串转换为默认值
        return v

3. wrap模式

wrap模式验证器将原始验证逻辑包装在自定义逻辑中：

接收一个验证函数作为参数
可以完全控制验证过程
需要手动调用原始验证逻辑

class UserModel(BaseModel):
    name: str
    
    @field_validator('name', mode='wrap')
    def wrap_validation(cls, v, handler):
        print(f"验证前的值: {v}")
        result = handler(v)  # 调用原始验证逻辑
        print(f"验证后的值: {result}")
        return result

4. plain模式

plain模式是字段验证器特有的模式，它：

完全绕过Pydantic的标准验证流程
需要自行处理所有验证逻辑
不会自动进行类型转换
适合需要完全自定义验证的场景

class UserModel(BaseModel):
    password: str
    
    @field_validator('password', mode='plain')
    def validate_password(cls, v, info):
        # 需要自行处理所有验证逻辑
        if len(v) < 8:
            raise ValueError('密码长度至少8个字符')
        if not any(c.isupper() for c in v):
            raise ValueError('密码必须包含大写字母')
        return v