Pydantic中computed_field在JSON Schema中的使用注意事项

在Pydantic V2中，@computed_field装饰器是一个非常实用的功能，它允许开发者将模型中的计算属性包含在序列化输出中。然而，这个功能在使用model_json_schema方法生成JSON Schema时有一个容易被忽视的重要细节。

computed_field的基本用法

@computed_field装饰器主要用于标记那些需要通过计算得到的模型属性。例如，我们可以创建一个简单的Box模型，其中包含一个计算体积的属性：

from pydantic import BaseModel, computed_field

class Box(BaseModel):
    width: float
    height: float
    depth: float

    @computed_field
    @property  
    def volume(self) -> float:
        return self.width * self.height * self.depth

这个计算属性volume会在模型实例被序列化为JSON时自动包含在输出中。

JSON Schema生成的特殊行为

当使用model_json_schema()方法生成JSON Schema时，默认情况下计算字段不会出现在输出中。这是因为Pydantic区分了"验证模式"和"序列化模式"：

1. 验证模式（默认）：只包含需要验证的字段
2. 序列化模式：包含所有会在序列化时输出的字段，包括计算字段

要包含计算字段，需要显式指定模式参数：

# 默认情况下不包含计算字段
print(Box.model_json_schema())  

# 指定序列化模式后包含计算字段
print(Box.model_json_schema(mode="serialization"))

实际应用建议

1. API文档生成：如果你使用Pydantic模型生成OpenAPI/Swagger文档，确保在生成Schema时使用mode="serialization"，这样文档中才会显示计算字段。

2. 前后端协作：前端开发者需要知道哪些字段是计算得到的，因此在共享Schema时应考虑使用序列化模式。

3. 性能考虑：计算字段虽然方便，但每次访问都会触发计算。对于复杂计算，考虑使用@cached_property而不是普通的@property。

总结

Pydantic的@computed_field是一个强大的功能，但在生成JSON Schema时需要特别注意模式参数的使用。理解验证模式和序列化模式的区别，可以帮助开发者更准确地控制Schema的输出内容，确保API文档和实际行为的一致性。