Pydantic V2中自定义类型Schema生成的最佳实践

问题背景

在Pydantic V2.11版本中，用户在使用自定义类型EventTasks生成JSON Schema时遇到了"class not fully defined"的错误。这个问题在V2.10版本中工作正常，但在V2.11版本中出现了兼容性问题。

技术分析

旧版实现的问题

在V2.10及之前版本中，用户通过直接访问__pydantic_core_schema__属性并手动构建核心Schema的方式能够正常工作。具体实现是：

1. 从TaskConfigA和TaskConfigB模型中获取核心Schema
2. 手动构建一个字典Schema，键为枚举类型Event
3. 值为包含上述两个任务配置Schema的联合类型列表

这种实现方式在V2.10中可行，但在V2.11中失效，原因是Pydantic内部对Schema定义的处理机制发生了变化。

V2.11的改进

Pydantic V2.11对Schema定义的处理进行了优化，主要变化包括：

1. 定义引用机制：Pydantic现在会为重复使用的Schema创建引用，避免重复定义
2. 性能优化：不再递归查找所有层级的定义，改为仅在Schema根部存储定义
3. 严格性增强：要求所有类型必须完整定义后才能使用

这些改进导致了直接访问__pydantic_core_schema__的方式不再可靠，因为手动构建的Schema可能无法正确处理内部的引用定义。

解决方案

推荐实现方式

正确的做法是使用Pydantic提供的handler.generate_schema()方法，让框架自动处理Schema的生成和引用管理：

@classmethod
def __get_pydantic_core_schema__(
    cls, source_type: Any, handler: "GetCoreSchemaHandler"
) -> pydantic_core.CoreSchema:
    return handler.generate_schema(dict[Event, TaskConfigA | TaskConfigB])

这种方法有以下优势：

1. 自动处理引用：Pydantic会自动管理Schema之间的引用关系
2. 维护简单：代码更简洁，不需要手动构建复杂Schema
3. 版本兼容：使用官方API，确保未来版本的兼容性

完整实现示例

结合JSON Schema生成的需求，完整的解决方案如下：

class EventTasks(UserDict[Event, list[TaskConfig]]):
    @classmethod
    def __get_pydantic_core_schema__(
        cls, source_type: Any, handler: "GetCoreSchemaHandler"
    ) -> pydantic_core.CoreSchema:
        return handler.generate_schema(dict[Event, list[TaskConfigA | TaskConfigB]])

    @classmethod
    def __get_pydantic_json_schema__(
        cls, core_schema: pydantic_core.CoreSchema, handler: "GetJsonSchemaHandler"
    ) -> "JsonSchemaValue":
        new_core = pydantic_core.core_schema.typed_dict_schema(
            {
                str(event): pydantic_core.core_schema.typed_dict_field(
                    core_schema["values_schema"],
                )
                for event in Event
            },
            total=False,
            extra_behavior="forbid",
        )
        json_schema = handler(new_core)
        json_schema = handler.resolve_ref_schema(json_schema)
        return json_schema

最佳实践建议

1. 避免直接访问内部属性：如__pydantic_core_schema__这样的属性可能会变化，应使用官方API
2. 利用类型注解：Python的类型注解系统已经足够强大，可以表达大多数Schema需求
3. 保持简单：尽量使用框架提供的功能，而非手动构建复杂Schema
4. 测试多版本兼容性：特别是跨主要版本升级时，要全面测试自定义类型的表现

总结

Pydantic V2.11对Schema处理机制的改进虽然带来了一些兼容性变化，但也提供了更健壮和高效的解决方案。通过使用官方推荐的handler.generate_schema()方法，开发者可以构建出更可靠、更易维护的自定义类型实现。这一变化体现了Pydantic框架向更加规范化和标准化方向发展的趋势。