Python JSON 序列化与反序列化:从入门到精通

告别 TypeError 异常，一文搞定 Python 中所有类型的 JSON 转换

前言

在 Python 开发中，我们经常遇到这样的错误：

TypeError: Object of type BlockConfig is not JSON serializableTypeError: Object of type set is not JSON serializable

这是因为 JSON 格式只支持有限的数据类型。今天我们就来彻底搞懂：如何把 Python 中的各种类型（list、set、dict、自定义类等）正确地转换成 JSON，以及如何还原。

一、JSON 序列化基础

什么是 JSON 序列化？

• • 序列化：Python 对象 → JSON 字符串（或文件）
• • 反序列化：JSON 字符串（或文件）→ Python 对象

JSON 支持的数据类型（有限）

JSON 不支持的 Python 类型：tuple、set、datetime、自定义类、枚举等。

两个核心函数

import json# 序列化：Python对象 → JSON字符串json_str = json.dumps(obj, ensure_ascii=False, indent=2)# 序列化到文件with open('data.json', 'w') as f:    json.dump(obj, f, ensure_ascii=False, indent=2)# 反序列化：JSON字符串 → Python对象obj = json.loads(json_str)# 从文件反序列化with open('data.json', 'r') as f:    obj = json.load(f)

二、常见数据类型的序列化实战

1. List 列表（原生支持）

import json# 简单列表simple_list = [1, 2, 3, "hello", True, None]json_str = json.dumps(simple_list)print(json_str)  # [1, 2, 3, "hello", true, null]# 反序列化restored = json.loads(json_str)print(restored)  # [1, 2, 3, 'hello', True, None]# 嵌套列表nested = [[1, 2], [3, 4], ["a", "b"]]print(json.dumps(nested))  # [[1, 2], [3, 4], ["a", "b"]]

2. Dict 字典（原生支持）

# 标准字典user = {    "name": "张三",    "age": 28,    "is_vip": True,    "scores": [90, 85, 92]}json_str = json.dumps(user, ensure_ascii=False, indent=2)print(json_str)# {#   "name": "张三",#   "age": 28,#   "is_vip": true,#   "scores": [90, 85, 92]# }# 反序列化restored = json.loads(json_str)

3. Tuple 元组（特殊处理）

# 问题：JSON 不支持元组coordinates = (10, 20)# json.dumps(coordinates)  # TypeError: tuple is not JSON serializable# 解决方案1：转换为列表json_str = json.dumps(list(coordinates))restored = tuple(json.loads(json_str))print(restored)  # (10, 20)# 解决方案2：自定义编码器（见后文）

4. Set 集合（需要转换）

# 问题：JSON 不支持集合tags = {"python", "json", "serialization"}# 解决方案1：转为列表json_str = json.dumps(list(tags))restored = set(json.loads(json_str))print(restored)  # {'python', 'json', 'serialization'}# 解决方案2：使用自定义编码器（见后文）

5. Datetime 日期时间（常用）

from datetime import datetime, datenow = datetime.now()today = date.today()# 问题：datetime 不可序列化# json.dumps(now)  # TypeError# 解决方案：转成字符串def datetime_handler(obj):    if isinstance(obj, datetime):        return obj.strftime('%Y-%m-%d %H:%M:%S')    elif isinstance(obj, date):        return obj.strftime('%Y-%m-%d')    raise TypeError(f"Type {type(obj)} not serializable")data = {    "created_at": now,    "published_date": today,    "name": "test"}json_str = json.dumps(data, default=datetime_handler, ensure_ascii=False)print(json_str)# {"created_at": "2024-01-15 14:30:00", "published_date": "2024-01-15", "name": "test"}# 反序列化时还原restored = json.loads(json_str)restored['created_at'] = datetime.strptime(restored['created_at'], '%Y-%m-%d %H:%M:%S')

6. 自定义类（最核心）

from dataclasses import dataclass, asdictfrom typing import List, Optional@dataclassclass BlockConfig:    """区域配置类"""    id: int    name: str    total_questions: int    questions_per_row: int = 4    options_per_question: int = 5    tags: List[str] = None    scores: List[int] = None    def __post_init__(self):        if self.tags is None:            self.tags = []        if self.scores is None:            self.scores = []# 创建实例block = BlockConfig(    id=1,     name="区域A",     total_questions=140,    tags=["基础", "进阶"],    scores=[85, 92, 78])# 方法1：使用 dataclasses.asdict()（推荐）json_str = json.dumps(asdict(block), ensure_ascii=False, indent=2)print(json_str)# 反序列化data = json.loads(json_str)restored_block = BlockConfig(**data)print(restored_block)# 方法2：手动实现 to_dict() 和 from_dict()@dataclassclass ExamTemplate:    name: str    blocks: List[BlockConfig]    def to_dict(self) -> dict:        return {            'name': self.name,            'blocks': [asdict(block) for block in self.blocks]        }    @classmethod    def from_dict(cls, data: dict) -> 'ExamTemplate':        blocks = [BlockConfig(**block_data) for block_data in data['blocks']]        return cls(name=data['name'], blocks=blocks)# 使用示例template = ExamTemplate(    name="期末考试",    blocks=[block])json_str = json.dumps(template.to_dict(), ensure_ascii=False, indent=2)restored = ExamTemplate.from_dict(json.loads(json_str))# 結果等同json_str = json.dumps(asdict(template), ensure_ascii=False, indent=2)restored = ExamTemplate(**json.loads(json_str))

7. 枚举 Enum

from enum import Enumclass OrderType(Enum):    ROW_MAJOR = "row_major"    COLUMN_MAJOR = "column_major"    RANDOM = "random"# 问题：枚举不可序列化order = OrderType.ROW_MAJOR# json.dumps(order)  # TypeError# 解决方案：保存值和名称data = {    "order": order.value,  # 保存值    "order_name": order.name  # 保存名称}json_str = json.dumps(data)# 反序列化restored = json.loads(json_str)order_value = OrderType(restored['order'])  # 从值恢复order_name = OrderType[restored['order_name']]  # 从名称恢复

三、高级技巧：自定义 JSONEncoder

当需要序列化多种特殊类型时，最佳实践是继承 JSONEncoder：

from json import JSONEncoderfrom datetime import datetime, datefrom decimal import Decimalclass AdvancedEncoder(JSONEncoder):    """支持多种类型的自定义编码器"""    def default(self, obj):        # 处理 set        if isinstance(obj, set):            return list(obj)        # 处理 tuple        if isinstance(obj, tuple):            return list(obj)        # 处理 datetime        if isinstance(obj, datetime):            return obj.strftime('%Y-%m-%d %H:%M:%S')        if isinstance(obj, date):            return obj.strftime('%Y-%m-%d')        # 处理 Decimal        if isinstance(obj, Decimal):            return float(obj)        # 处理自定义类（有 __dict__ 的）        if hasattr(obj, '__dict__'):            return obj.__dict__        # 处理 dataclass        try:            from dataclasses import asdict            return asdict(obj)        except:            pass        return super().default(obj)# 使用示例data = {    "name": "test",    "tags": {"python", "json"},  # set    "position": (10, 20),  # tuple    "created_at": datetime.now(),  # datetime    "price": Decimal("19.99"),  # Decimal    "block": BlockConfig(id=1, name="A", total_questions=50)  # dataclass}json_str = json.dumps(data, cls=AdvancedEncoder, ensure_ascii=False, indent=2)print(json_str)# 输出结果包含所有正确转换的类型

四、反序列化的类型还原

序列化后，类型信息会丢失。我们需要在反序列化时手动还原：

def complex_decoder(dct):    """自定义解码器，还原特定字段的类型"""    # 还原 datetime    if 'created_at' in dct and isinstance(dct['created_at'], str):        dct['created_at'] = datetime.strptime(dct['created_at'], '%Y-%m-%d %H:%M:%S')    # 还原 set（通过特殊标记）    if '__set__' in dct:        return set(dct['__set__'])    # 还原 tuple    if '__tuple__' in dct:        return tuple(dct['__tuple__'])    return dct# 序列化时标记特殊类型def enhanced_encoder(obj):    if isinstance(obj, set):        return {'__set__': list(obj)}    if isinstance(obj, tuple):        return {'__tuple__': list(obj)}    raise TypeError(f"Type {type(obj)} not serializable")data = {"tags": {"py", "js"}, "pos": (10, 20)}json_str = json.dumps(data, default=enhanced_encoder)print(json_str)  # {"tags": {"__set__": ["py", "js"]}, "pos": {"__tuple__": [10, 20]}}# 反序列化时还原restored = json.loads(json_str, object_hook=complex_decoder)print(restored)  # {'tags': {'py', 'js'}, 'pos': (10, 20)}

五、常见问题与最佳实践

问题1：含有 None 值的字段

data = {"name": "test", "value": None}json_str = json.dumps(data)print(json_str)  # {"name": "test", "value": null}  # 自动处理

问题2：循环引用

# JSON 不支持循环引用a = {"name": "A"}b = {"name": "B"}a["friend"] = bb["friend"] = a# json.dumps(a)  # 报错：circular reference

最佳实践总结

1. 1. 优先使用 dataclass：配合 asdict() 最方便
2. 2. 实现 to_dict() 和 from_dict()：明确控制序列化逻辑
3. 3. 自定义 JSONEncoder：当项目中频繁处理多种特殊类型时
4. 4. 保留版本号：在序列化数据中加入 version 字段，便于兼容升级
5. 5. 不要序列化函数/类：JSON 不支持，考虑换用 pickle
6. 6. 大文件用流式处理：使用 json.dump() 和 json.load()，避免内存溢出

# 版本控制的示例def save_with_version(data, filepath, version=1):    wrapper = {        "version": version,        "data": data    }    with open(filepath, 'w') as f:        json.dump(wrapper, f)def load_with_version(filepath):    with open(filepath, 'r') as f:        wrapper = json.load(f)    version = wrapper.get("version", 1)    data = wrapper.get("data")    return version, data

六、总结速查表

一句话总结：JSON 只认识基础类型，复杂对象要自己动手转换成字典再序列化，反序列化时再还原回来。

掌握了这些技巧，再也不怕 TypeError: not JSON serializable 了！