Python自定义JSONDecoder重写decode方法完整指南

脚本专家

在之前的文章中，我们详细讲解过自定义 JSONEncoder 的实现。今天换一个方向，聚焦 JSON 的反向过程：通过继承 JSONDecoder 并重写 decode() 方法，把 JSON 字符串精准还原成自定义 Python 对象。很多场景下，json.loads() 默认只能解析出 dict、list 这类基础类型，比如：

2. import json
4. json_str = '{"name": "\u5f20\u4e09", "age": 25}'
5. data = json.loads(json_str)
6. print(type(data))  # <class 'dict'>

复制代码

如果我们希望 JSON 数据能自动还原为 Person 实例，直接访问 person.name、person.age，就需要自定义 JSONDecoder。

一、JSONDecoder 的核心骨架

JSONDecoder 有两个关键方法：

__init__()：构造方法，可接收 object_hook、parse_float 等参数；
decode(s)：核心方法，负责把 JSON 字符串解析成 Python 对象；
raw_decode(s)：底层解析方法，返回 (对象, 索引) 元组。

自定义解码器最直接的方式就是重写 decode() 方法，完全控制解析流程。

二、重写 decode 方法完成基础还原

假设我们有 Person 类和配套的 PersonEncoder，序列化时写入了一个 __type__ 字段来标记类型。接下来编写 PersonDecoder：

2. import json
3. from datetime import datetime
4. from typing import Any
6. class Person:
7.     def __init__(self, name: str, age: int, created_at: datetime = None):
8.         self.name = name
9.         self.age = age
10.         self.created_at = created_at or datetime.now()
12.     def __repr__(self):
13.         return f"Person(name={self.name}, age={self.age}, created_at={self.created_at})"
15. class PersonEncoder(json.JSONEncoder):
16.     def default(self, obj):
17.         if isinstance(obj, Person):
18.             return {
19.                 "__type__": "Person",
20.                 "name": obj.name,
21.                 "age": obj.age,
22.                 "created_at": obj.created_at.isoformat()
23.             }
24.         if isinstance(obj, datetime):
25.             return {"__type__": "datetime", "value": obj.isoformat()}
26.         return super().default(obj)
28. class PersonDecoder(json.JSONDecoder):
29.     def decode(self, s: str) -> Any:
30.         # 先按标准 JSON 解析成 Python 基础对象
31.         data = super().decode(s)
32.         return self._convert(data)
34.     def _convert(self, data):
35.         if isinstance(data, dict):
36.             if data.get("__type__") == "Person":
37.                 created_at = data.get("created_at")
38.                 if created_at:
39.                     created_at = datetime.fromisoformat(created_at)
40.                 return Person(
41.                     name=data["name"],
42.                     age=data["age"],
43.                     created_at=created_at
44.                 )
45.             if data.get("__type__") == "datetime":
46.                 return datetime.fromisoformat(data["value"])
47.             # 递归处理字典中的每个值
48.             return {k: self._convert(v) for k, v in data.items()}
49.         elif isinstance(data, list):
50.             return [self._convert(item) for item in data]
51.         return data

复制代码

测试一下：

2. p = Person("\u5f20\u4e09", 25)
3. json_str = json.dumps(p, cls=PersonEncoder, ensure_ascii=False)
4. print("\u5e8f\u5217\u5316:", json_str)
6. restored = json.loads(json_str, cls=PersonDecoder)
7. print("\u8fd8\u539f:", restored)
8. print("\u7c7b\u578b:", type(restored))
9. print("\u59d3\u540d:", restored.name)
10. print("\u521b\u5efa\u65f6\u95f4\u7c7b\u578b:", type(restored.created_at))

复制代码

输出可以看到，restored 已经是 Person 实例，created_at 也还原成了 datetime 类型。

三、扩展解码器支持多种自定义类型

如果项目中有多个模型类，比如 Person、Student、Address，可以在同一个解码器里通过 __type__ 字段区分，并递归转换嵌套对象：

2. class Address:
3.     def __init__(self, city: str, district: str):
4.         self.city = city
5.         self.district = district
7.     def __repr__(self):
8.         return f"Address(city={self.city}, district={self.district})"
10. class Student:
11.     def __init__(self, name: str, age: int, address: Address = None):
12.         self.name = name
13.         self.age = age
14.         self.address = address
16.     def __repr__(self):
17.         return f"Student(name={self.name}, age={self.age}, address={self.address})"
19. class MultiDecoder(json.JSONDecoder):
20.     def decode(self, s: str) -> Any:
21.         data = super().decode(s)
22.         return self._convert(data)
24.     def _convert(self, data):
25.         if isinstance(data, dict):
26.             obj_type = data.get("__type__")
27.             if obj_type == "Person":
28.                 return Person(
29.                     name=data["name"],
30.                     age=data["age"],
31.                     created_at=self._convert(data.get("created_at"))
32.                 )
33.             if obj_type == "Student":
34.                 return Student(
35.                     name=data["name"],
36.                     age=data["age"],
37.                     address=self._convert(data.get("address"))
38.                 )
39.             if obj_type == "Address":
40.                 return Address(
41.                     city=data["city"],
42.                     district=data["district"]
43.                 )
44.             if obj_type == "datetime":
45.                 return datetime.fromisoformat(data["value"])
46.             return {k: self._convert(v) for k, v in data.items()}
47.         elif isinstance(data, list):
48.             return [self._convert(item) for item in data]
49.         return data
51. class MultiEncoder(json.JSONEncoder):
52.     def default(self, obj):
53.         if isinstance(obj, Person):
54.             return {"__type__": "Person", "name": obj.name, "age": obj.age, "created_at": obj.created_at}
55.         if isinstance(obj, Student):
56.             return {"__type__": "Student", "name": obj.name, "age": obj.age, "address": obj.address}
57.         if isinstance(obj, Address):
58.             return {"__type__": "Address", "city": obj.city, "district": obj.district}
59.         if isinstance(obj, datetime):
60.             return {"__type__": "datetime", "value": obj.isoformat()}
61.         return super().default(obj)

复制代码

这里的关键点在于 _convert() 方法会递归处理 dict 和 list。遇到带 __type__ 标记的字典，就根据类型名称构造对应的 Python 对象；遇到普通字典或列表，则继续向下递归。这样即使 JSON 结构里嵌套了多层对象，也能正确还原。

四、把序列化能力封装进类体系

在实际业务中，我们经常需要让多个模型类具备统一的行为。可以将基础属性和能力封装成多个混合类，再通过 Python 多继承组合出具体业务类。

2. class Life:
3.     def __init__(self, name, age):
4.         self.name = name
5.         self.age = age
7.     def __str__(self):
8.         return f"name:{self.name},age:{self.age}"
10. class Animal(Life):
11.     def __init__(self, name, age, speed):
12.         super().__init__(name, age)
13.         self.speed = speed
15.     def __str__(self):
16.         return f"{super().__str__()},speed:{self.speed}"
18. class Flyable:
19.     def fly(self):
20.         return f"{self.name}\u6b63\u5728\u98de\u884c,\u901f\u5ea6\u4e3a{self.speed}"
22. class SwimAble:
23.     def swim(self):
24.         return f"{self.name}\u6b63\u5728\u6e38\u6cf3,\u901f\u5ea6\u4e3a{self.speed}"
26. class AttackAble:
27.     def attack(self):
28.         return f"{self.name}\u4f1a\u653b\u51fb,\u7834\u574f\u529b\u5f3a\u5927"
30. class Bird(Flyable, Animal, Life, AttackAble):
31.     def __init__(self, name, age, speed):
32.         super().__init__(name, age, speed)
34.     def speek(self):
35.         return f"{self.name}\u6b63\u5728\u5593\u5593\u5593"
37. class Dog(Animal, Life, SwimAble, AttackAble):
38.     def __init__(self, name, age, speed):
39.         super().__init__(name, age, speed)
41.     def speek(self):
42.         return f"{self.name}\u6b63\u5728\u6c6a\u6c6a\u6c6a"
44. class BigSwan(Animal, Life, SwimAble, Flyable, AttackAble):
45.     def __init__(self, name, age, speed):
46.         super().__init__(name, age, speed)
48.     def speek(self):
49.         return f"{self.name}\u53d1\u51fa\u989d\u989d\u9e45\u7684\u58f0\u97f3"

复制代码

测试多继承组合效果：

2. l0 = Life("\u5f20\u98de", 18)
3. print(l0)
5. a0 = Animal("\u9648\u519b", 18, 30)
6. print(a0)
8. b1 = Bird("\u5218\u632f\u9633", 18, 100)
9. print(b1, b1.speek(), b1.fly(), b1.attack())
11. d1 = Dog("\u9648\u519b", 18, 30)
12. print(d1, d1.speek(), d1.swim(), d1.attack())
14. bs = BigSwan("\u5f20\u6bc5\u98de", 20, 50)
15. print(bs, bs.speek(), bs.swim(), bs.fly(), bs.attack())

复制代码

这种设计让每个类只关注自己的特有能力，公共能力通过混合类复用。在真实的序列化/反序列化项目中，我们可以把 SerializableMixin、DeserializableMixin 也做成混合类，再配合类型注册表，让 JsonDecoder 能够更灵活地扩展。

五、总结

继承 JSONDecoder 并重写 decode() 方法，是实现自定义 JSON 反序列化的核心思路。需要记住几个关键点：

1. decode() 内部先调用 super().decode(s) 拿到标准解析结果；
2. 通过 __type__ 标记字段识别原始对象类型；
3. 递归处理 dict 和 list，保证嵌套对象也能被还原；
4. 多继承 + 混合类可以很好地复用序列化与业务能力。

如果只是简单转换，也可以考虑 object_hook 参数，它比重写 decode() 更轻量。但在需要深度控制解析流程、处理复杂嵌套以及定制类型还原时，重写 decode() 是一个清晰且可扩展的方案。希望这篇文章能帮你在 Python 自定义 JSON 编解码的路上少踩几个坑。