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

在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

模式选择指南

1. 优先使用after模式：适用于大多数业务逻辑验证场景
2. 需要预处理时使用before模式：当输入值需要清理或转换时
3. 需要完全控制时使用wrap模式：当需要包装或修改标准验证行为时
4. 特殊需求使用plain模式：当标准验证流程不适用时

注意事项

• 字段验证器的函数签名不会因模式不同而改变（与模型验证器不同）
• plain模式需要开发者自行处理所有验证逻辑
• 验证器的返回值会影响最终模型中的字段值

理解这些验证模式的区别和适用场景，可以帮助开发者更有效地利用Pydantic构建健壮的数据验证逻辑。