Pydantic 中 URL 类型的序列化行为解析

在 Python 数据验证库 Pydantic 的最新版本中，URL 类型字段在模型序列化为字典时的表现行为发生了一些变化，这可能会影响开发者对数据结构的预期和处理方式。

URL 类型的序列化表现

当使用 Pydantic 模型处理包含 URL 字段的数据时，从版本 2.10.2 开始，URL 类型字段在序列化为字典时会保留其类型信息。例如，一个包含 AnyUrl 字段的模型在调用 model_dump() 方法后，输出结果会显示为 AnyUrl('实际URL') 的形式，而不是直接输出字符串形式的 URL。

这种行为变化源于 Pydantic 对 URL 类型处理方式的改进。新版本更倾向于保持与具体 Python 类一致的行为，使得序列化输出能够反映原始数据类型信息。

对开发者的影响

这种变化主要影响以下场景：

1. 单元测试比较：当开发者需要将模型序列化结果与预期字典进行比较时，类型信息的保留可能导致比较失败
2. API 响应：如果直接将序列化结果作为 API 响应返回，客户端可能需要额外处理这些类型信息
3. 数据持久化：存储序列化结果时可能包含不必要的类型信息

解决方案

Pydantic 提供了多种方式来自定义序列化行为：

1. 使用 PlainSerializer

可以通过类型注解配合 PlainSerializer 来定制序列化行为：

from typing import Annotated
from pydantic import BaseModel, AnyUrl, PlainSerializer

class UrlModel(BaseModel):
    url: Annotated[AnyUrl, PlainSerializer(lambda x: str(x))]

2. 使用字段序列化器

也可以通过 field_serializer 装饰器实现相同效果：

from pydantic import BaseModel, AnyUrl, field_serializer

class UrlModel(BaseModel):
    url: AnyUrl
    
    @field_serializer('url')
    def serialize_url(self, url: AnyUrl):
        return str(url)

3. 模型配置

对于需要全局处理的情况，可以在模型配置中指定序列化排除规则：

class UrlModel(BaseModel):
    url: AnyUrl
    
    class Config:
        json_encoders = {
            AnyUrl: str
        }

最佳实践建议

1. 在需要与其他系统交互的场景下，建议显式地将 URL 转换为字符串形式
2. 对于内部处理逻辑，可以保留类型信息以便于调试和类型检查
3. 在编写单元测试时，考虑使用专门的比较函数或预处理步骤来处理类型差异
4. 对于大型项目，建议统一序列化策略以保持一致性

理解这些序列化行为的变化有助于开发者更好地利用 Pydantic 的强大功能，同时避免在数据处理过程中出现意外问题。