本文详解如何在 pydantic v2+ 中序列化模型时自动省略具有默认值的字段（如 `tails: int = 1`），避免冗余 json 输出，同时保证反序列化后语义正确。核心方法是使用 `model_dump(exclude_defaults=true)`，并推荐结合 `field(default=...)` 显式建模可选性。
在 Pydantic v2 及以上版本中，json.dumps(..., default=pydantic_encoder) 已被弃用，推荐统一使用模型内置的 .model_dump() 方法进行序列化控制。要实现“仅在字段值不等于默认值时才输出”的效果，最直接、可靠的方式是启用 exclude_defaults=True 参数：
import json
from typing import List
from pydantic import BaseModel, Field
class Animal(BaseModel):
name: str
legs: int
tails: int = 1 # 默认值为 1
class AnimalList(BaseModel):
animals: List[Animal]
animals = AnimalList(animals=[
Animal(name='dog', legs=4), # tails 使用默认值 1
Animal(name='human', legs=2, tails=0) # tails 显式设为 0
])
# ✅ 正确做法：使用 model_dump 并排除默认值
data = animals.model_dump(exclude_defaults=True)
j = json.dumps(data)
print(j)
# 输出：{"animals": [{"name": "dog", "legs": 4}, {"name": "human", "legs": 2, "tails": 0}]}该方式在序列化时会自动跳过所有值等于其声明默认值的字段（包括 Field(default=...)、= 赋值、Field(default_factory=...) 等情形），且反序列化完全兼容：
restored = AnimalList.model_validate_json(j)
for animal in restored.animals:
print(f"The {animal.name} has {animal.legs} legs and {animal.tails} tails.")
# 输出：
# The dog has 4 legs and 1 tails.
# The human has 2 legs and 0 tails.⚠️ 注意事项：
- exclude_defaults=True 仅影响序列化输出，不影响模型实例内部状态：Animal(name='dog', legs=4) 的 tails 属性仍为 1，只是不写入 JSON；
- 若字段逻辑上“可选”（即业务中允许缺失），更推荐显式使用 Optional + Field(default=None)，例如 tails: int | None = Field(default=None)，此时 exclude_defaults=True 会自然排除 None 值，语义更清晰；
- 避免混用旧式 json.dumps(..., default=pydantic_encoder) 与新 API —— 它不支持 exclude_defaults 等高级参数，且已被标记为遗留。
✅ 最佳实践建议（面向可维护性）：
from pydantic import BaseModel, Field
from typing import Optional
class Animal(BaseModel):
name: str
legs: int
tails: Optional[int] = Field(default=None) # 明确表达“非必需”
# 序列化时自动省略 None 字段（等效 exclude_defaults）
print(Animal(name='dog', legs=4).model_dump())
# → {'name': 'dog', 'legs': 4}这种方式让数据契约更严谨：JSON 中缺失 tails 表示“未指定”，而非隐含默认值；模型层仍可安全访问 .tails or 1 做业务兜底，兼顾灵活性与可读性。
