JSON可序列化类型的安全标注：定义递归TypeAlias实现mypy兼容

本文介绍如何为接受任意JSON可序列化对象的函数参数提供准确、安全且mypy友好的类型提示，通过递归TypeAlias精准覆盖json.dumps原生支持及自定义编码器扩展的全部合法输入类型。

本文介绍如何为接受任意json可序列化对象的函数参数提供准确、安全且mypy友好的类型提示，通过递归`typealias`精准覆盖`json.dumps`原生支持及自定义编码器扩展的全部合法输入类型。

在Python类型系统中，为接收JSON可序列化数据的函数（如内部调用json.dumps）标注类型，既需满足运行时灵活性，又需通过静态检查器（如mypy）验证安全性。使用Union[List[Any], Dict[Any, Any]]不仅不完整（遗漏None、int、str、bool等基础类型），还会触发Explicit "Any" is not allowed错误，破坏类型严谨性。

推荐方案是采用递归类型别名（Recursive TypeAlias），精确建模JSON的嵌套结构。自Python 3.12起，typing.TypeAlias被正式标准化；在较新版本mypy（≥0.990）中，即使使用旧版Python，该语法也已获完善支持：

from typing import Union, List, Dict, TypeAlias

# ✅ 完整、安全、无Any的JSON可序列化类型定义
JsonType: TypeAlias = Union[
    None,
    bool,
    int,
    float,
    str,
    List["JsonType"],
    Dict[str, "JsonType"]
]

⚠️ 注意：List["JsonType"] 和 Dict[str, "JsonType"] 中的字符串字面量引用（forward reference）是必需的，避免未定义名称错误；float 也应包含——json.dumps 原生支持浮点数（如 3.14, inf, -inf, nan 会按JSON规范处理，尽管nan/inf需显式启用allow_nan=True）。

更新你的函数签名后，类型检查将严格而准确：

Find JSON Path Online

Easily find JSON paths within JSON objects using our intuitive Json Path Finder

import json
from typing import Any, **kwargs as JsonKwargs
from datetime import date

def my_function_doing_stuff_then_serializing(
    input: JsonType, 
    **kwargs: JsonKwargs
) -> None:
    json.dumps(input, **kwargs)

# ✅ 以下全部通过mypy检查：
my_function_doing_stuff_then_serializing([date.today()])  # ❌ 类型错误！
# 但——等等，`date`本身不是JsonType？没错！这正是类型安全的体现。
# 若需支持`date`，必须配合自定义`JSONEncoder`，且**类型提示不应放宽到`Any`**，
# 而应保持`JsonType`不变，并在文档或运行时做明确约定：
"""
Note: This function accepts only JSON-native types (per JsonType).
Custom objects (e.g., date) require a compatible JSONEncoder passed via `cls=...`,
and are *not* part of the static type contract.
"""

关键设计原则总结：

• ✅ JsonType 仅描述json.dumps无需额外编码器即可处理的原生类型结构，确保类型系统真实反映JSON规范；
• ✅ 自定义类型（如date）的序列化能力属于运行时扩展行为，由cls参数动态注入，不应污染静态类型定义；
• ✅ 避免Any、object或过度宽泛的Union——它们放弃类型检查价值；
• ✅ 若需更严格的浮点控制（如排除nan），可派生子类型或添加运行时校验，但类型定义仍以JSON标准为准。

此方案平衡了表达力、安全性和工具链兼容性，是构建健壮序列化接口的现代Python实践。