pydantic 2 默认将 `set` 序列化为无序列表，导致 json 输出不稳定；本文介绍通过 `@field_serializer` 实现字段级可控排序，并提供可复用的基类方案，避免重复定义，兼顾简洁性与可扩展性。
在 Pydantic 2 中，set 类型字段虽能自动转为 JSON 列表，但其元素顺序由 Python 内部哈希实现决定，不保证跨实例或跨运行的一致性——这会破坏缓存、签名、diff 比较等依赖确定性序列化的场景。虽然 Pydantic 1 支持全局 json_encoders 配置，但该机制已在 v2 中移除；而 model_serializer 虽通用，却需手动遍历字段、类型判断与委托序列化，违背“利用 Pydantic 类型系统”的初衷。
最推荐、最轻量且符合 Pydantic 2 设计哲学的解法是：使用 @field_serializer 配合类型提示和 when_used='json'。它精准作用于目标字段，在序列化流程的合适时机介入，无需侵入模型逻辑，也无需自定义类型：
from typing import Set, Any
from pydantic import BaseModel, field_serializer
class SortedSetModel(BaseModel):
tags: Set[str]
ids: Set[int]
@field_serializer('tags', 'ids', when_used='json')
def _serialize_sets(self, value: Any) -> list:
# 支持泛型 set（str/int/...），自动排序（仅限可比较元素）
if isinstance(value, set):
return sorted(value)
return list(value) # fallback（如 None 或非 set）调用 SortedSetModel(tags={'z', 'a', 'm'}, ids={42, 7, 100}).model_dump_json() 将稳定输出：
{"tags": ["a", "m", "z"], "ids": [7, 42, 100]}✅ 优势明确：
- ✅ 类型安全：value: Any + isinstance 保障运行时健壮性，IDE 仍可推导参数类型；
- ✅ 复用友好：可抽象为基类，供所有需排序 set 的模型继承；
- ✅ 子类兼容：子类新增的 Set[...] 字段只需额外传入字段名到装饰器即可；
- ✅ 语义清晰：when_used='json' 确保仅影响 model_dump_json() 和 model.json()，不影响 model_dump()（Python dict）等其他序列化路径。
⚠️ 注意事项：
- sorted() 要求集合内元素可比较且同构（如不能混用 str 和 int），否则抛 TypeError；生产环境建议搭配 try/except 或预校验；
- 若需深度嵌套结构（如 Set[CustomModel]）的确定性序列化，应为 CustomModel 实现 __lt__ 或自定义 field_serializer 处理其 model_dump_json() 输出；
- 避免在 @field_serializer 中修改原字段值（如 self.tags = ...），它仅用于序列化转换，非数据验证或赋值钩子。
综上，@field_serializer 是 Pydantic 2 中平衡简洁性、可维护性与确定性的首选方案——它不试图“重写序列化引擎”，而是优雅地在框架预留的扩展点上施加最小干预，让 set 的 JSON 表现真正可靠。
