Python中json.dump报错时如何优化TypeError提示信息？

Python标准库的json.dump/json.dumps在遇到无法序列化的值时，只会抛出模糊的TypeError，不会告知无效值对应的键或所在路径，调试大型JSON对象时非常麻烦。可以通过以下几种方式优化错误提示：

方法一：自定义递归序列化函数，追踪路径 #

手动遍历对象结构，记录当前处理的键或索引路径，遇到序列化失败时抛出带路径的错误：

import json

def serialize_with_path(obj, path=""):
    if isinstance(obj, dict):
        result = {}
        for key, value in obj.items():
            current_path = f"{path}.{key}" if path else str(key)
            try:
                result[key] = serialize_with_path(value, current_path)
            except TypeError as e:
                raise TypeError(f"无法序列化键 '{current_path}' 的值: {e}") from e
        return result
    elif isinstance(obj, list):
        result = []
        for idx, item in enumerate(obj):
            current_path = f"{path}[{idx}]"
            try:
                result.append(serialize_with_path(item, current_path))
            except TypeError as e:
                raise TypeError(f"无法序列化列表索引 '{current_path}' 的值: {e}") from e
        return result
    else:
        # 测试当前值是否可序列化
        try:
            json.dumps(obj)
            return obj
        except TypeError as e:
            raise TypeError(f"无法序列化路径 '{path}' 的值: {e}") from e

# 测试示例
data = {
    "normal": "hello",
    "invalid_set": set([1,2,3]),
    "nested": {
        "items": [1, 2, object()]
    }
}

try:
    serialized = serialize_with_path(data)
    json.dumps(serialized)
except TypeError as e:
    print(e)

运行后会输出明确的错误位置，比如：

无法序列化键 'invalid_set' 的值: Object of type set is not JSON serializable
无法序列化列表索引 'nested.items[2]' 的值: Object of type object is not JSON serializable

方法二：继承JSONEncoder，添加路径追踪 #

通过自定义JSONEncoder子类，在序列化过程中维护当前路径栈，失败时抛出带路径的错误：

import json

class PathTrackingEncoder(json.JSONEncoder):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._path_stack = []

    def default(self, obj):
        current_path = ".".join(self._path_stack)
        try:
            return super().default(obj)
        except TypeError as e:
            raise TypeError(f"无法序列化路径 '{current_path}' 的值（类型: {type(obj).__name__}）: {e}") from e

    def iterencode(self, obj, _one_shot=False):
        if isinstance(obj, dict):
            for key, value in obj.items():
                self._path_stack.append(str(key))
                yield from super().iterencode(value, _one_shot)
                self._path_stack.pop()
        elif isinstance(obj, list):
            for idx, item in enumerate(obj):
                self._path_stack.append(f"[{idx}]")
                yield from super().iterencode(item, _one_shot)
                self._path_stack.pop()
        else:
            yield from super().iterencode(obj, _one_shot)

# 测试示例
data = {"a": set(), "b": [1, object()]}
try:
    json.dumps(data, cls=PathTrackingEncoder)
except TypeError as e:
    print(e)

方法三：使用第三方库（可选） #

如果允许引入第三方依赖，像pydantic这类库在验证/序列化失败时，会自动提供包含路径的详细错误信息；jsonpickle也能处理更多类型并给出更清晰的提示。

通过以上方法，就能让序列化失败时的错误信息直接指向问题所在的键或索引路径，大幅降低大型JSON对象的调试成本。

内容的提问来源于stack exchange，提问作者Mikko Ohtamaa