Pydantic 序列化时排除默认值字段的完整实践指南

本文详解如何在 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 做业务兜底，兼顾灵活性与可读性。