查看: 55|回复: 3

Python JSON序列化类型映射与非标准类型处理

[复制链接]
发表于 22 分钟前 | 显示全部楼层 |阅读模式
一、问题的由来: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 处理代码时必须先搞清楚的事情。

先把双向映射关系理清(写在注释里便于对照):
  1. import json
  2. # JSON -> Python(loads / load)
  3. # object  -> dict
  4. # array   -> list
  5. # string  -> str
  6. # number  -> int / float
  7. # true/false -> True / False
  8. # null    -> None
  9. # Python -> JSON(dumps / dump)
  10. # dict      -> object
  11. # list/tuple -> array
  12. # str       -> string
  13. # int/float -> number
  14. # True/False -> true/false
  15. # None      -> null
复制代码

这张表里最容易被忽略的是 tuple:序列化时被当作 array 输出,反序列化回来只能得到 list,原来的元组语义无法自动恢复。凡是依赖类型本身承载业务含义的场景,都要提前设计标记或转换逻辑。

二、可以直接序列化的类型及其隐性转换

标准容器与标量类型可以直接交给 json.dumps,包括嵌套结构:
  1. import json
  2. data = {
  3.     "str_val": "hello",
  4.     "int_val": 42,
  5.     "float_val": 3.14,
  6.     "bool_val": True,
  7.     "none_val": None,
  8.     "list_val": [1, 2, 3],
  9.     "tuple_val": (1, 2, 3),   # 元组会变成 JSON 数组
  10.     "dict_val": {"a": 1},
  11.     "nested": [{"x": 1}, {"y": 2}],
  12. }
  13. json_str = json.dumps(data, ensure_ascii=False, indent=2)
  14. print(json_str)
  15. # 注意:tuple 序列化后是 array,反序列化回来是 list,不再是 tuple
复制代码

ensure_ascii=False 保证中文不被转义为 \uXXXX,indent 控制缩进,这两个参数在日志输出、接口调试和配置文件生成里最常用。

三、不能直接序列化的类型与 default 参数

datetime、date、Decimal、set、bytes、Path 这些对象直接放进 dumps 会抛出 TypeError。json 模块为此提供了 default 回调:遇到无法识别的对象时调用它,返回值被当作可序列化结果继续处理。
  1. import json
  2. from datetime import datetime, date
  3. from decimal import Decimal
  4. from pathlib import Path
  5. problem_data = {
  6.     "datetime": datetime.now(),   # TypeError
  7.     "date": date.today(),         # TypeError
  8.     "decimal": Decimal("3.14"),   # TypeError
  9.     "set_data": {1, 2, 3},        # TypeError
  10.     "bytes_data": b"hello",       # TypeError
  11.     "path": Path("/tmp"),         # TypeError
  12. }
复制代码

逐类处理的写法:
  1. import base64
  2. import json
  3. from datetime import datetime, date
  4. from decimal import Decimal
  5. from pathlib import Path
  6. # 1. datetime / date -> isoformat 字符串
  7. def serialize_datetime(obj):
  8.     if isinstance(obj, (datetime, date)):
  9.         return obj.isoformat()
  10.     raise TypeError(f"Type {type(obj)} not serializable")
  11. json_str = json.dumps({"time": datetime.now()}, default=serialize_datetime)
  12. # 2. Decimal -> float 或 str
  13. def serialize_decimal(obj):
  14.     if isinstance(obj, Decimal):
  15.         return float(obj)   # 需要保留精度时改为 str(obj)
  16.     raise TypeError
  17. # 3. set -> list
  18. data = {"tags": list({"python", "json"})}
  19. json.dumps(data)  # {"tags": ["python", "json"]}
  20. # 4. bytes -> base64 或 hex
  21. b64 = base64.b64encode(b"hello").decode()
  22. json.dumps({"data": b64})
  23. # 5. Path -> str
  24. json.dumps({"path": str(Path("/tmp"))})
复制代码

这里有个选择需要留意:Decimal 转 float 会引入二进制浮点误差,涉及金额、计费、统计口径的字段应当转成字符串,反序列化时再用 Decimal(str) 还原。bytes 转 base64 是文本安全编码,转 hex 体积会翻倍,二者按对端解析能力取舍。

四、用统一 Encoder 收敛所有特殊类型

当项目里到处散落 default 回调时,维护成本会明显上升。更常见的做法是继承 json.JSONEncoder,把所有非标准类型集中在一个类里判断:
  1. import base64
  2. import json
  3. from datetime import datetime, date
  4. from decimal import Decimal
  5. from pathlib import Path
  6. class UniversalEncoder(json.JSONEncoder):
  7.     def default(self, obj):
  8.         if isinstance(obj, (datetime, date)):
  9.             return obj.isoformat()
  10.         if isinstance(obj, Decimal):
  11.             return float(obj)
  12.         if isinstance(obj, set):
  13.             return list(obj)
  14.         if isinstance(obj, bytes):
  15.             return base64.b64encode(obj).decode()
  16.         if isinstance(obj, Path):
  17.             return str(obj)
  18.         if hasattr(obj, "to_dict"):
  19.             return obj.to_dict()
  20.         return super().default(obj)
复制代码

这种写法的好处是:判断顺序显式可控,遇到未覆盖类型时通过 super().default(obj) 抛出原本的 TypeError,不会静默吞掉未知对象;对带有 to_dict 方法的业务对象留了一个统一出口,便于把 ORM 实体或 DTO 直接序列化。

五、大整数精度与 NaN / Infinity

Python 的 int 没有位数上限,而 JSON 的 number 在多数语言里按 IEEE 754 双精度浮点解析。Python 自身 dump 再 loads 大整数不会丢精度:
  1. import json
  2. big_number = 999999999999999999999999999999999
  3. json_str = json.dumps({"big": big_number})
  4. 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 并确认对端能解析。
  1. import json
  2. json_str = json.dumps({"val": float("nan")}, allow_nan=True)
  3. print(json_str)  # {"val": NaN}  非标准 JSON
  4. # json.dumps({"val": float("nan")}, allow_nan=False)  # ValueError
复制代码

六、反序列化时的类型恢复

loads 返回的基本类型由 JSON 字面量决定,整数与浮点靠小数点区分:
  1. import json
  2. json_str = '''
  3. {
  4.   "name": "张三",
  5.   "age": 25,
  6.   "score": 92.5,
  7.   "is_active": true,
  8.   "tags": ["python", "developer"],
  9.   "meta": null
  10. }
  11. '''
  12. data = json.loads(json_str)
  13. print(type(data["name"]))       # <class 'str'>
  14. print(type(data["age"]))        # <class 'int'>
  15. print(type(data["score"]))      # <class 'float'>
  16. print(type(data["is_active"]))  # <class 'bool'>
  17. print(type(data["tags"]))       # <class 'list'>
  18. print(type(data["meta"]))       # <class 'NoneType'>
复制代码

如果字段在业务上必须是时间对象,可以借助 object_hook:每解析完一个 JSON 对象(dict)就回调一次,在这里把形如 ISO 8601 的字符串转回 datetime。
  1. import json
  2. from datetime import datetime
  3. json_str = '''
  4. {
  5.   "user": "张三",
  6.   "created_at": "2024-06-15T14:30:00",
  7.   "updated_at": "2024-06-16T09:00:00",
  8.   "login_times": ["2024-06-01T10:00:00", "2024-06-02T11:00:00"]
  9. }
  10. '''
  11. def datetime_hook(dct):
  12.     """把符合 isoformat 的字符串自动转为 datetime"""
  13.     result = {}
  14.     for key, value in dct.items():
  15.         if isinstance(value, str):
  16.             try:
  17.                 result[key] = datetime.fromisoformat(value)
  18.                 continue
  19.             except (ValueError, TypeError):
  20.                 pass
  21.         elif isinstance(value, list):
  22.             result[key] = [
  23.                 datetime.fromisoformat(v) if isinstance(v, str) and "T" in v else v
  24.                 for v in value
  25.             ]
  26.             continue
  27.         result[key] = value
  28.     return result
  29. data = json.loads(json_str, object_hook=datetime_hook)
  30. print(type(data["created_at"]))      # <class 'datetime.datetime'>
  31. print(type(data["login_times"][0])) # <class 'datetime.datetime'>
复制代码

使用 object_hook 有两点限制需要注意:它只对 dict 生效,顶层是数组时不会触发;回调是全局的,对每个嵌套对象都会执行,条件判断写得太宽松会把本是普通字符串的字段误转成时间,因此通常用固定键名白名单或格式校验来收紧。

七、实战:带类型标记的双向序列化

需要严格还原 set、datetime 这类无法从 JSON 字面量推断的类型时,可以在序列化阶段写入类型标记,反序列化阶段按标记还原。下面这个 TypedJSON 用 __type__ 和 __value__ 两个保留键承载类型信息:
  1. import json
  2. from datetime import datetime
  3. class TypedJSON:
  4.     """支持类型标记的 JSON 序列化 / 反序列化"""
  5.     TYPE_MARKER = "__type__"
  6.     VALUE_MARKER = "__value__"
  7.     TYPE_MAP = {
  8.         "datetime": datetime.fromisoformat,
  9.         "date": lambda s: datetime.fromisoformat(s).date(),
  10.         "set": set,
  11.     }
  12.     @classmethod
  13.     def serialize(cls, obj):
  14.         if isinstance(obj, datetime):
  15.             return {cls.TYPE_MARKER: "datetime", cls.VALUE_MARKER: obj.isoformat()}
  16.         elif isinstance(obj, set):
  17.             return {cls.TYPE_MARKER: "set", cls.VALUE_MARKER: list(obj)}
  18.         elif isinstance(obj, dict):
  19.             return {k: cls.serialize(v) for k, v in obj.items()}
  20.         elif isinstance(obj, list):
  21.             return [cls.serialize(item) for item in obj]
  22.         return obj
  23.     @classmethod
  24.     def deserialize(cls, obj):
  25.         if isinstance(obj, dict):
  26.             if cls.TYPE_MARKER in obj:
  27.                 type_name = obj[cls.TYPE_MARKER]
  28.                 value = obj[cls.VALUE_MARKER]
  29.                 if type_name in cls.TYPE_MAP:
  30.                     return cls.TYPE_MAP[type_name](value)
  31.             return {k: cls.deserialize(v) for k, v in obj.items()}
  32.         elif isinstance(obj, list):
  33.             return [cls.deserialize(item) for item in obj]
  34.         return obj
  35. data = {
  36.     "user": "张三",
  37.     "created_at": datetime.now(),
  38.     "tags": {"python", "developer"},
  39.     "scores": [85, 92, 78],
  40. }
  41. json_str = json.dumps(TypedJSON.serialize(data), ensure_ascii=False, indent=2)
  42. print(json_str)
  43. restored = TypedJSON.deserialize(json.loads(json_str))
  44. print(type(restored["created_at"]))  # <class 'datetime.datetime'>
  45. 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 和一个解码钩子里,比在每个调用点零散处理更容易维护。
回复

使用道具 举报

发表于 17 分钟前 | 显示全部楼层

Re: Python JSON序列化类型映射与非标准类型处理

楼主整理得很系统,尤其是把双向类型映射和 tuple 的隐性转换单独点出来,这个确实是实际写代码时最容易踩的坑。default 回调那段也很实用,datetime、Decimal、set、bytes、Path 这些非标准类型统一走一个分支处理,比在每个业务对象里手动转换干净很多。 补充几个我平时会注意的点:反序列化时 datetime 不会自动变回对象,需要自己按约定字段做 fromisoformat;Decimal 如果业务上要求精度,最好序列化成字符串并带类型标记,别直接转 float;set 转 list 后顺序不保证,如果对输出稳定性有要求可以先排序;bytes 用 base64 或 hex 时最好同时记录编码方式,否则解码端容易猜错。另外帖子最后 bytes 那段好像没显示完整,期待楼主后续补上这块的处理示例。
回复 支持 反对

使用道具 举报

发表于 17 分钟前 | 显示全部楼层

Re: Python JSON序列化类型映射与非标准类型处理

这篇整理得很清楚,尤其是把双向映射表、tuple 序列化后变 list 的隐性转换,以及用 default 处理非标准类型放在一起讲,实际写代码时很容易踩这些坑。补充几个实践里值得注意的点:default 只负责“序列化出去”,反序列化回来 datetime、Decimal、set、bytes、Path 都不会自动恢复,需要提前约定格式,必要时用 object_hook 或自定义解析;Decimal 转 float 可能丢精度,要求精度时建议转字符串;set 转 list 顺序不稳定,有需要可以先排序;bytes 用 base64 后记得 decode 成字符串;Path 一般转 str 更通用。另外 dict 的键如果不是字符串,dumps 时会被转成字符串,NaN 和 Infinity 默认虽能输出但不算严格 JSON,接口场景可以加 allow_nan=False 更稳妥。整体思路很实用,继续往下写反序列化还原和循环引用处理会更完整。
回复 支持 反对

使用道具 举报

发表于 17 分钟前 | 显示全部楼层

Re: Python JSON序列化类型映射与非标准类型处理

整理得很系统,那张双向映射表一目了然。tuple 序列化成数组、反序列化回来变成 list 这个点,确实是日常最容易踩的坑,之前做配置回写时就因为没注意,原样读回来类型全变了。default 回调按类型分支处理的写法很清楚,Decimal 那里特别提醒需要保留精度就转 str,这点很实用。 不过帖子好像发到 bytes 转 base64 那里就截断了,后面的内容没贴出来,有点可惜。另外想请教一下反序列化这一侧:像 isoformat 的字符串想还原成 datetime,一般是在 object_hook 里按字段名判断,还是约定一个带类型标记的字段更稳妥?期待楼主把后面补全,尤其是 bytes、Path 以及 set 反序列化还原的思路。
回复 支持 反对

使用道具 举报

您需要登录后才可以回帖 登录 | 注册

本版积分规则

指导单位

江苏省公安厅

江苏省通信管理局

浙江省台州刑侦支队

DEFCON GROUP 86025

Hacking Group 021A

旗下站点

态势感知中心

应急响应中心

红盟安全

联系我们

官方QQ群:112851260

官方邮箱:security#ihonker.org(#改成@)

官方核心成员

关注微信公众号

Archiver|手机版|小黑屋| ( 沪ICP备2021026908号 )

GMT+8, 2026-11-23 05:22 , Processed in 0.025051 second(s), 18 queries , Gzip On, Redis On.

Powered by ihonker.com

Copyright © 2015-现在.

  • 返回顶部