跳转到主内容
趣航编程网 - 趣学编程,启航技术之路!

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

本文详解如何在 pydantic v2+ 中序列化模型时自动省略具有默认值的字段(如 `tails: int = 1`),避免冗余 js on 输出,同时保证反序列化后语义正确。核心方法是使用 `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.
⚠️ 注意事项: Find JSON Path Online Easily find JSON paths within JSON objects using our intuitive Json Path Finder 下载 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 做业务兜底,兼顾灵活性与可读性。

相关文章