DRF-Spectacular 中 Pydantic 2 的 @computed_field 字段处理问题解析

在 Python 生态系统中，DRF-Spectacular 是一个优秀的工具，用于为 Django REST Framework 生成 OpenAPI 3.0 规范文档。近期在使用过程中，开发者发现了一个与 Pydantic 2 的 @computed_field 装饰器相关的问题，值得深入探讨。

问题现象

当开发者使用 Pydantic 2 的 @computed_field 装饰器定义计算字段时，发现这些字段没有被正确地包含在最终生成的 OpenAPI 规范中。例如：

from pydantic import BaseModel, computed_field

class TestModel(BaseModel):
    number: int

    @computed_field
    @property
    def twice(self) -> int:
        return self.number * 2

在上述代码中，twice 字段作为计算字段，预期应该出现在 API 文档中，但实际上却被遗漏了。

技术背景

Pydantic 2 引入了 @computed_field 装饰器，用于标记那些不存储在模型中，但需要通过计算得到的字段。这些字段在模型序列化时会被包含在输出中。DRF-Spectacular 在处理 Pydantic 模型时，默认使用 model_json_schema 函数来获取模型的 JSON Schema。

问题根源

经过深入分析，发现问题出在 model_json_schema 函数的调用方式上。默认情况下，该函数工作在"验证"模式（validation mode），而计算字段需要在"序列化"模式（serialization mode）下才会被包含在输出中。

解决方案

解决方法很简单：在调用 model_json_schema 时显式指定 mode='serialization' 参数。这个修改确保了计算字段能够正确地出现在生成的 OpenAPI 规范中。

schema = model_json_schema(
    self.target,
    mode='serialization',  # 关键修改
    ref_template="#/components/schemas/{model}"
)

潜在影响

虽然这个修改看起来很小，但需要考虑以下方面：

1. 向后兼容性：确保修改不会影响现有代码的行为
2. 性能影响：序列化模式可能需要处理更多字段
3. 文档一致性：确保所有计算字段都能被正确包含

最佳实践

对于使用 DRF-Spectacular 和 Pydantic 2 的开发者，建议：

1. 明确区分验证和序列化需求
2. 对于计算字段，始终使用 @computed_field 装饰器
3. 定期检查生成的 OpenAPI 文档是否完整

结论

通过这个案例，我们可以看到 API 文档生成工具与数据验证库之间的微妙交互。理解这些底层机制有助于开发者更好地利用这些工具，构建更健壮、文档更完善的 API 系统。对于 DRF-Spectacular 用户来说，这个问题的解决将确保 Pydantic 2 的计算字段能够被正确地包含在 API 文档中。