一、问题的由来:JSON 的类型集合比 Python 小得多
JSON 规范里只有 6 种数据类型:object、array、string、number、true/false、null。而 Python 侧的常用类型远不止这些,int、float、str、list、dict、bool、None 之外,还有 datetime、Decimal、set、tuple、bytes、Path 等。当 Python 对象交给 json.dumps 时,能否映射、映射成什么、反序列化后能否回到原类型,是编写健壮 JSON 处理代码时必须先搞清楚的事情。
先把双向映射关系理清(写在注释里便于对照):
- import json
- # JSON -> Python(loads / load)
- # object -> dict
- # array -> list
- # string -> str
- # number -> int / float
- # true/false -> True / False
- # null -> None
- # Python -> JSON(dumps / dump)
- # dict -> object
- # list/tuple -> array
- # str -> string
- # int/float -> number
- # True/False -> true/false
- # None -> null
复制代码
这张表里最容易被忽略的是 tuple:序列化时被当作 array 输出,反序列化回来只能得到 list,原来的元组语义无法自动恢复。凡是依赖类型本身承载业务含义的场景,都要提前设计标记或转换逻辑。
二、可以直接序列化的类型及其隐性转换
标准容器与标量类型可以直接交给 json.dumps,包括嵌套结构:
- import json
- data = {
- "str_val": "hello",
- "int_val": 42,
- "float_val": 3.14,
- "bool_val": True,
- "none_val": None,
- "list_val": [1, 2, 3],
- "tuple_val": (1, 2, 3), # 元组会变成 JSON 数组
- "dict_val": {"a": 1},
- "nested": [{"x": 1}, {"y": 2}],
- }
- json_str = json.dumps(data, ensure_ascii=False, indent=2)
- print(json_str)
- # 注意:tuple 序列化后是 array,反序列化回来是 list,不再是 tuple
复制代码
ensure_ascii=False 保证中文不被转义为 \uXXXX,indent 控制缩进,这两个参数在日志输出、接口调试和配置文件生成里最常用。
三、不能直接序列化的类型与 default 参数
datetime、date、Decimal、set、bytes、Path 这些对象直接放进 dumps 会抛出 TypeError。json 模块为此提供了 default 回调:遇到无法识别的对象时调用它,返回值被当作可序列化结果继续处理。
- import json
- from datetime import datetime, date
- from decimal import Decimal
- from pathlib import Path
- problem_data = {
- "datetime": datetime.now(), # TypeError
- "date": date.today(), # TypeError
- "decimal": Decimal("3.14"), # TypeError
- "set_data": {1, 2, 3}, # TypeError
- "bytes_data": b"hello", # TypeError
- "path": Path("/tmp"), # TypeError
- }
复制代码
逐类处理的写法:
- import base64
- import json
- from datetime import datetime, date
- from decimal import Decimal
- from pathlib import Path
- # 1. datetime / date -> isoformat 字符串
- def serialize_datetime(obj):
- if isinstance(obj, (datetime, date)):
- return obj.isoformat()
- raise TypeError(f"Type {type(obj)} not serializable")
- json_str = json.dumps({"time": datetime.now()}, default=serialize_datetime)
- # 2. Decimal -> float 或 str
- def serialize_decimal(obj):
- if isinstance(obj, Decimal):
- return float(obj) # 需要保留精度时改为 str(obj)
- raise TypeError
- # 3. set -> list
- data = {"tags": list({"python", "json"})}
- json.dumps(data) # {"tags": ["python", "json"]}
- # 4. bytes -> base64 或 hex
- b64 = base64.b64encode(b"hello").decode()
- json.dumps({"data": b64})
- # 5. Path -> str
- json.dumps({"path": str(Path("/tmp"))})
复制代码
这里有个选择需要留意:Decimal 转 float 会引入二进制浮点误差,涉及金额、计费、统计口径的字段应当转成字符串,反序列化时再用 Decimal(str) 还原。bytes 转 base64 是文本安全编码,转 hex 体积会翻倍,二者按对端解析能力取舍。
四、用统一 Encoder 收敛所有特殊类型
当项目里到处散落 default 回调时,维护成本会明显上升。更常见的做法是继承 json.JSONEncoder,把所有非标准类型集中在一个类里判断:
- import base64
- import json
- from datetime import datetime, date
- from decimal import Decimal
- from pathlib import Path
- class UniversalEncoder(json.JSONEncoder):
- def default(self, obj):
- if isinstance(obj, (datetime, date)):
- return obj.isoformat()
- if isinstance(obj, Decimal):
- return float(obj)
- if isinstance(obj, set):
- return list(obj)
- if isinstance(obj, bytes):
- return base64.b64encode(obj).decode()
- if isinstance(obj, Path):
- return str(obj)
- if hasattr(obj, "to_dict"):
- return obj.to_dict()
- return super().default(obj)
复制代码
这种写法的好处是:判断顺序显式可控,遇到未覆盖类型时通过 super().default(obj) 抛出原本的 TypeError,不会静默吞掉未知对象;对带有 to_dict 方法的业务对象留了一个统一出口,便于把 ORM 实体或 DTO 直接序列化。
五、大整数精度与 NaN / Infinity
Python 的 int 没有位数上限,而 JSON 的 number 在多数语言里按 IEEE 754 双精度浮点解析。Python 自身 dump 再 loads 大整数不会丢精度:
- import json
- big_number = 999999999999999999999999999999999
- json_str = json.dumps({"big": big_number})
- print(json_str) # {"big": 999999999999999999999999999999999}
复制代码
但这份 JSON 一旦被 Java、JavaScript 等语言的解析器读取,超过 2^53 的整数就可能被截断或变成浮点数。跨语言传输雪花 ID、订单号、长整型主键时,常规做法是序列化成字符串而不是 number。
NaN 与 Infinity 不属于 JSON 标准。Python 的 dumps 默认 allow_nan=True,会输出 NaN、Infinity 这类非标准字面量,其他语言的严格解析器可能直接报错;若显式传入 allow_nan=False,遇到这类值会抛出 ValueError。所以生产环境里要么在数据入口就把 NaN/Inf 清洗掉,要么接受非标准 JSON 并确认对端能解析。
- import json
- json_str = json.dumps({"val": float("nan")}, allow_nan=True)
- print(json_str) # {"val": NaN} 非标准 JSON
- # json.dumps({"val": float("nan")}, allow_nan=False) # ValueError
复制代码
六、反序列化时的类型恢复
loads 返回的基本类型由 JSON 字面量决定,整数与浮点靠小数点区分:
- import json
- json_str = '''
- {
- "name": "张三",
- "age": 25,
- "score": 92.5,
- "is_active": true,
- "tags": ["python", "developer"],
- "meta": null
- }
- '''
- data = json.loads(json_str)
- print(type(data["name"])) # <class 'str'>
- print(type(data["age"])) # <class 'int'>
- print(type(data["score"])) # <class 'float'>
- print(type(data["is_active"])) # <class 'bool'>
- print(type(data["tags"])) # <class 'list'>
- print(type(data["meta"])) # <class 'NoneType'>
复制代码
如果字段在业务上必须是时间对象,可以借助 object_hook:每解析完一个 JSON 对象(dict)就回调一次,在这里把形如 ISO 8601 的字符串转回 datetime。
- import json
- from datetime import datetime
- json_str = '''
- {
- "user": "张三",
- "created_at": "2024-06-15T14:30:00",
- "updated_at": "2024-06-16T09:00:00",
- "login_times": ["2024-06-01T10:00:00", "2024-06-02T11:00:00"]
- }
- '''
- def datetime_hook(dct):
- """把符合 isoformat 的字符串自动转为 datetime"""
- result = {}
- for key, value in dct.items():
- if isinstance(value, str):
- try:
- result[key] = datetime.fromisoformat(value)
- continue
- except (ValueError, TypeError):
- pass
- elif isinstance(value, list):
- result[key] = [
- datetime.fromisoformat(v) if isinstance(v, str) and "T" in v else v
- for v in value
- ]
- continue
- result[key] = value
- return result
- data = json.loads(json_str, object_hook=datetime_hook)
- print(type(data["created_at"])) # <class 'datetime.datetime'>
- print(type(data["login_times"][0])) # <class 'datetime.datetime'>
复制代码
使用 object_hook 有两点限制需要注意:它只对 dict 生效,顶层是数组时不会触发;回调是全局的,对每个嵌套对象都会执行,条件判断写得太宽松会把本是普通字符串的字段误转成时间,因此通常用固定键名白名单或格式校验来收紧。
七、实战:带类型标记的双向序列化
需要严格还原 set、datetime 这类无法从 JSON 字面量推断的类型时,可以在序列化阶段写入类型标记,反序列化阶段按标记还原。下面这个 TypedJSON 用 __type__ 和 __value__ 两个保留键承载类型信息:
- import json
- from datetime import datetime
- class TypedJSON:
- """支持类型标记的 JSON 序列化 / 反序列化"""
- TYPE_MARKER = "__type__"
- VALUE_MARKER = "__value__"
- TYPE_MAP = {
- "datetime": datetime.fromisoformat,
- "date": lambda s: datetime.fromisoformat(s).date(),
- "set": set,
- }
- @classmethod
- def serialize(cls, obj):
- if isinstance(obj, datetime):
- return {cls.TYPE_MARKER: "datetime", cls.VALUE_MARKER: obj.isoformat()}
- elif isinstance(obj, set):
- return {cls.TYPE_MARKER: "set", cls.VALUE_MARKER: list(obj)}
- elif isinstance(obj, dict):
- return {k: cls.serialize(v) for k, v in obj.items()}
- elif isinstance(obj, list):
- return [cls.serialize(item) for item in obj]
- return obj
- @classmethod
- def deserialize(cls, obj):
- if isinstance(obj, dict):
- if cls.TYPE_MARKER in obj:
- type_name = obj[cls.TYPE_MARKER]
- value = obj[cls.VALUE_MARKER]
- if type_name in cls.TYPE_MAP:
- return cls.TYPE_MAP[type_name](value)
- return {k: cls.deserialize(v) for k, v in obj.items()}
- elif isinstance(obj, list):
- return [cls.deserialize(item) for item in obj]
- return obj
- data = {
- "user": "张三",
- "created_at": datetime.now(),
- "tags": {"python", "developer"},
- "scores": [85, 92, 78],
- }
- json_str = json.dumps(TypedJSON.serialize(data), ensure_ascii=False, indent=2)
- print(json_str)
- restored = TypedJSON.deserialize(json.loads(json_str))
- print(type(restored["created_at"])) # <class 'datetime.datetime'>
- print(type(restored["tags"])) # <class 'set'>
复制代码
这个方案的代价是 JSON 结构被包装了一层,可读性和与第三方系统的兼容性会下降,适合内部服务之间传输、或需要完整往返(round-trip)语义的缓存场景;对外公开的接口更适合用扁平结构加约定字段名,而不引入标记对象。
八、排查与落地清单
遇到 TypeError: Object of type X is not JSON serializable,按下面顺序定位:确认出错对象的具体类型(是 datetime 还是它的子类、是 set 还是 frozenset);检查是否已有 default 或自定义 Encoder 但分支顺序被前面的 isinstance 截走;确认 to_dict 之类的钩子方法是否真的存在且返回可序列化对象;最后再考虑是否需要在数据出口处先做一次规范化转换。
日常编码可以固化为几条规则:时间类型统一走 isoformat() 输出、fromisoformat() 输入;Decimal 涉及精度时用字符串而非浮点;set 和 bytes 先显式转换再入 JSON;tuple 不要指望反序列化后仍为元组;大整数与 NaN/Infinity 在跨语言边界处提前规避。把这些点收敛到一个 Encoder 和一个解码钩子里,比在每个调用点零散处理更容易维护。 |