Pydantic Core教程：自定义逻辑（装饰器与Annotated辅助工具）-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00280/article/details/148440413

Pydantic Core教程：自定义逻辑（装饰器与Annotated辅助工具）

Tutorial-Codebase-Knowledge Turns Codebase into Easy Tutorial with AI 项目地址: https://gitcode.com/gh_mirrors/tu/Tutorial-Codebase-Knowledge

引言

在现代Python开发中，数据验证和序列化是构建健壮应用程序的关键环节。Pydantic作为Python生态中最受欢迎的数据验证库之一，提供了强大的工具来处理这些任务。本教程将深入探讨Pydantic Core中自定义逻辑的实现方式，包括装饰器和Annotated辅助工具的使用。

为什么需要自定义逻辑？

Pydantic的标准类型提示（如str、int）和字段配置（如Field(gt=0)）能够处理大多数常见场景。但在实际开发中，我们经常遇到需要更复杂验证规则的情况：

业务规则验证（如用户名不能包含空格）
字段间关系验证（如结束日期必须晚于开始日期）
自定义序列化格式（如日期字段的特殊格式化）
数据转换（如自动将用户名转为小写）

这些需求超出了基本验证的范围，需要开发者注入自定义逻辑。

装饰器方式实现自定义逻辑

装饰器是Python中一种强大的语法特性，Pydantic利用它来标记模型中的特定方法，使其成为验证器或序列化器。

字段验证器（@field_validator）

@field_validator允许为特定字段添加验证逻辑，在Pydantic完成基本类型检查后执行。

示例：验证用户名不包含空格

from pydantic import BaseModel, field_validator, ValidationError

class UserRegistration(BaseModel):
    username: str
    email: str

    @field_validator('username')
    @classmethod
    def check_username_spaces(cls, v: str) -> str:
        if ' ' in v:
            raise ValueError('用户名不能包含空格')
        return v

关键点：

使用@classmethod装饰器
接收字段值作为参数
验证失败时抛出ValueError
必须返回处理后的值

模型验证器（@model_validator）

当验证涉及多个字段的交互时，可以使用@model_validator。

示例：验证日期范围

from datetime import date
from pydantic import BaseModel, model_validator

class Trip(BaseModel):
    start_date: date
    end_date: date
    destination: str

    @model_validator(mode='after')
    def check_dates(self) -> 'Trip':
        if self.start_date >= self.end_date:
            raise ValueError('结束日期必须晚于开始日期')
        return self

模式说明：

mode='after'：在所有字段验证完成后执行
mode='before'：在字段验证前执行，接收原始输入数据

字段序列化器（@field_serializer）

控制字段在序列化时的输出格式。

示例：自定义日期序列化格式

from datetime import date
from pydantic import BaseModel, field_serializer

class Event(BaseModel):
    name: str
    event_date: date

    @field_serializer('event_date')
    def serialize_date(self, dt: date) -> str:
        return dt.strftime('%Y-%m-%d')

模型序列化器（@model_serializer）

控制整个模型的序列化行为。

示例：添加计算字段

from datetime import date, timedelta
from pydantic import BaseModel, model_serializer
from typing import Dict, Any

class Trip(BaseModel):
    start_date: date
    end_date: date
    destination: str

    @model_serializer
    def serialize_with_duration(self) -> Dict[str, Any]:
        data = self.model_dump()
        data['duration_days'] = (self.end_date - self.start_date).days
        return data

Annotated辅助工具

Python的typing.Annotated允许将元数据附加到类型提示上，Pydantic利用这一特性实现了另一种自定义逻辑的方式。

验证器辅助工具

示例：使用AfterValidator验证用户名

from typing import Annotated
from pydantic import BaseModel
from pydantic.functional_validators import AfterValidator

def check_no_spaces(v: str) -> str:
    if ' ' in v:
        raise ValueError('用户名不能包含空格')
    return v

class UserRegistrationAnnotated(BaseModel):
    username: Annotated[str, AfterValidator(check_no_spaces)]
    email: str

序列化器辅助工具

示例：使用PlainSerializer格式化日期

from typing import Annotated
from datetime import date
from pydantic import BaseModel
from pydantic.functional_serializers import PlainSerializer

def format_date(dt: date) -> str:
    return dt.strftime('%Y-%m-%d')

class EventAnnotated(BaseModel):
    name: str
    event_date: Annotated[date, PlainSerializer(format_date)]

装饰器与Annotated的选择

适用场景对比

| 特性 | 装饰器 | Annotated | |------|--------|-----------| | 代码组织 | 逻辑与模型类紧密耦合 | 逻辑可独立定义，更模块化 | | 复用性 | 限于当前模型 | 可在多个模型/字段间复用 | | 可读性 | 方法定义清晰可见 | 类型提示可能变得冗长 | | 访问模型 | 可访问类(cls)或实例(self) | 仅能访问字段值 |