JSON序列化安全类型的精准类型标注实践
本文介绍如何为支持json.dumps的函数参数设计严谨、可静态检查的类型提示，解决Union[List[Any], Dict[Any, Any]]不完整且违反mypy规范的问题，推荐使用递归TypeAlias定义完整的JSON可序列化类型。
本文介绍如何为支持`json.dumps`的函数参数设计严谨、可静态检查的类型提示，解决`union[list[any], dict[any, any]]`不完整且违反`mypy`规范的问题，推荐使用递归`typealias`定义完整的json可序列化类型。
在Python类型系统中，为接受任意JSON可序列化对象的函数（如内部调用json.dumps）提供精确类型标注，是提升代码健壮性与可维护性的关键一步。原始写法 Union[List[Any], Dict[Any, Any]] 存在三大缺陷：一是遗漏None、int、str、bool等基础JSON原子类型；二是Any显式使用被mypy严格禁止（违反PEP 484）；三是无法表达嵌套结构（如List[Dict[str, List[int]]]）的递归合法性。
现代Python（3.12+）及主流类型检查器（如mypy ≥ 1.0）已原生支持递归类型别名（Recursive TypeAlias），这是目前最准确、最符合JSON规范的解决方案。标准JSON可序列化值仅包含以下六类：null（对应None）、number（int/float）、string（str）、boolean（bool）、array（list）、object（dict），其中array和object可无限嵌套。
因此，推荐定义如下类型别名：
from typing import List, Dict, Union, TypeAlias, Optional
# ✅ 推荐：显式、递归、符合JSON规范的TypeAlias（支持mypy 1.0+）
JsonType: TypeAlias = Union[
None,
bool,
int,
float,
str,
List["JsonType"], # 注意字符串字面量引用，避免前向引用错误
Dict[str, "JsonType"], # 键必须为str（JSON object key限制）
]
⚠️ 注意事项：
- float需显式加入——尽管json.dumps支持浮点数，但int无法覆盖它；
- 使用带引号的字符串字面量（如"JsonType"）解决前向引用问题，这是PEP 695前的标准做法；
- Dict的键类型必须为str，因JSON object不允许非字符串键，否则json.dumps会抛出TypeError；
- 若需兼容自定义JSONEncoder（如处理date），类型标注仍应基于原始输入结构，而非编码后形态——date本身不可直接序列化，须由cls参数在运行时转换，因此不应将date加入JsonType；类型系统只保证json.dumps不因类型错误提前崩溃，不替代编码逻辑。
修正后的函数签名如下：
Find JSON Path Online
Easily find JSON paths within JSON objects using our intuitive Json Path Finder
import json
from typing import Any, **kwargs
def my_function_doing_stuff_then_serializing(
input: JsonType,
**kwargs: Any
) -> None:
json.dumps(input, **kwargs)
该签名可安全接收：
- 基础值：None, 42, "hello", True
- 容器：[1, "a", True], {"id": 1, "tags": ["x"]}
- 深度嵌套：[{"users": [{"name": "Alice", "active": True}]}]
同时完全兼容自定义JSONEncoder：
from datetime import date
class DateEncoder(json.JSONEncoder):
def default(self, obj: Any) -> Any:
if isinstance(obj, date):
return obj.isoformat()
return super().default(obj)
# ✅ 类型检查通过：date对象不在JsonType中，但被DateEncoder处理
my_function_doing_stuff_then_serializing([date.today()], cls=DateEncoder)
总结：使用递归TypeAlias定义JsonType，既满足静态类型检查的完备性要求，又严格遵循JSON数据模型约束，是当前Python生态下最专业、可持续的实践方案。避免滥用Any或不完整的联合类型，让类型系统真正成为JSON序列化逻辑的守护者。