Pydantic V2.10.x 中 HttpUrl 类型的 OpenAPI 模式生成问题解析

在 Pydantic V2.10.x 版本中，开发者发现了一个关于 HttpUrl 类型在 OpenAPI 模式生成中的行为变化。这个问题影响了 FastAPI 等依赖 Pydantic 进行 API 文档生成的框架。

问题现象

在 Pydantic V2.9.2 版本中，HttpUrl 类型会正确生成包含以下约束条件的 OpenAPI 模式：

• 字符串类型
• URI 格式
• 最小长度 1
• 最大长度 2083

然而升级到 V2.10.x 后，这些约束条件（maxLength、minLength 和 format）从生成的 OpenAPI 模式中消失了，仅保留了基本的字符串类型声明。

技术背景

HttpUrl 是 Pydantic 提供的一个特殊类型，用于验证和表示 HTTP/HTTPS URL。它继承自 AnyUrl 类型，并添加了额外的验证规则。在内部实现上，Pydantic 会将这些验证规则转换为对应的 JSON Schema 约束条件。

问题根源

经过技术分析，这个问题与 Pydantic 的模式生成模式（mode='serialization'）有关。在序列化模式下，Pydantic 会生成不同的模式表示，这导致了约束条件的丢失。

影响范围

这个问题主要影响：

1. 使用 FastAPI 等框架自动生成 OpenAPI/Swagger 文档的场景
2. 依赖 OpenAPI 文档进行客户端代码生成的工具链
3. 前端开发者依赖 API 文档中的约束条件进行表单验证的情况

临时解决方案

对于受影响的用户，可以考虑以下临时方案：

1. 暂时回退到 Pydantic V2.9.2 版本
2. 手动为 API 端点添加 OpenAPI 模式描述
3. 在模型中使用 Field 注解显式指定约束条件

技术建议

对于需要严格 API 文档的项目，建议：

1. 在升级 Pydantic 版本前进行全面测试
2. 实现 API 契约测试，确保文档生成的一致性
3. 关注 Pydantic 项目的更新，等待官方修复

总结

这个问题的出现提醒我们，在依赖自动生成的 API 文档时，需要特别注意底层库版本升级可能带来的行为变化。对于关键项目，建立完善的 API 契约测试体系是保证稳定性的重要手段。