本文介绍 Pydantic 内置的 JsonValue 类型，用于严格校验符合 JSON 规范的嵌套数据结构（如字典、列表、基本类型），避免使用宽松类型（如 Dict[str, Any]）导致非 JSON 值（如 datetime、set、自定义对象）意外通过验证。
本文介绍 pydantic 内置的 `jsonvalue` 类型，用于严格校验符合 json 规范的嵌套数据结构（如字典、列表、基本类型），避免使用宽松类型（如 `dict[str, any]`）导致非 json 值（如 `datetime`、`set`、自定义对象）意外通过验证。
在构建 API 或处理外部输入（如 Webhook、配置文件、前端 JSON payload）时，常需确保某字段是真正可被 JSON 序列化的字典——即其键为字符串，值仅限于 str、int、float、bool、None、list 或 dict，且所有嵌套层级均满足该约束。若误用 Dict[str, Any]，虽能接受任意 Python 对象，却可能隐含不可序列化的值（如 datetime.now()、Decimal('3.14') 或自定义类实例），导致后续 json.dumps() 报错，破坏系统健壮性。
Pydantic 从 v2.5 起正式提供 JsonValue 类型（位于 pydantic.types.JsonValue），专为此场景设计。它是一个递归联合类型，精确对应 JSON 的语法规范：
from pydantic.types import JsonValue
from pydantic import BaseModel, ValidationError
class MyModel(BaseModel):
config: JsonValue # ✅ 支持任意合法 JSON 结构：{}、[]、"str"、123、true、null 等JsonValue 的完整定义等价于：
JsonValue = Union[
List["JsonValue"],
Dict[str, "JsonValue"],
str,
bool,
int,
float,
None,
]⚠️ 注意：JsonValue 不包含 bytes、decimal.Decimal、datetime、UUID、Enum 等非原生 JSON 类型；也不允许 tuple（会被转为 list，但类型校验失败）、set 或自定义对象。
实际校验示例
# 正确输入（全部通过）
valid_cases = [
{"name": "Alice", "scores": [95.5, 87], "active": True},
{"meta": None, "tags": ["v1", "prod"]},
42,
"hello",
[1, "two", {"nested": True}],
]
for data in valid_cases:
try:
model = MyModel(config=data)
print(f"✅ Valid: {data}")
except ValidationError as e:
print(f"❌ Invalid: {data} → {e}")
# 错误输入（全部抛出 ValidationError）
invalid_cases = [
{"created_at": datetime.now()}, # datetime 不可 JSON 序列化
{"value": decimal.Decimal("3.14")}, # Decimal 不在 JsonValue 范围内
{"items": (1, 2, 3)}, # tuple 不被允许（即使内容合法）
{"data": {b"key": "value"}}, # bytes key 非 str
]
for data in invalid_cases:
try:
MyModel(config=data)
except ValidationError as e:
print(f"❌ Rejected: {data} → {e.errors()[0]['msg']}")若仅需“JSON 字典”（非任意 JSON 值）
如业务明确要求字段必须是 dict（而非 str/int 等其他 JSON 类型），可组合使用：
from typing import Dict
from pydantic.types import JsonValue
class StrictDictModel(BaseModel):
payload: Dict[str, JsonValue] # ✅ 必须是 dict，且每个 value 满足 JSON 规范这比 Dict[str, Any] 更安全，也比手动递归定义 Json = Union[...] 更简洁可靠（后者易因前向引用或循环定义引发 RecursionError 或 IDE 类型推导失败）。
总结与最佳实践
- ✅ 首选 JsonValue：当字段需承载任意合法 JSON 数据（对象、数组、原子值）时，直接使用 JsonValue，语义清晰且开箱即用。
- ✅ 组合 Dict[str, JsonValue]：当业务强约束为“必须是字典”时，显式声明键类型与值类型边界。
- ❌ 避免 Dict[str, Any]：除非你主动承担序列化风险并自行后处理，否则会丧失类型安全与早期错误拦截能力。
- ? 注意版本兼容性：JsonValue 自 Pydantic v2.5 引入，确保 pydantic>=2.5.0；旧版本可考虑 pydantic.json_schema.JsonSchemaValue（非运行时校验）或自定义验证器，但推荐升级。
通过 JsonValue，你能在模型层就筑牢 JSON 兼容性防线，让数据契约更明确、错误更早暴露、API 更加可靠。
