如何让 json.dumps 序列化时保持 dict 插入顺序

Python 3.7+ 中 json.dumps 默认保持 dict 插入顺序,因 dict 本身有序;3.6 及更早需 OrderedDict;sort_keys=True 会强制字母序覆盖原序;第三方库如 ujson、orjson 行为各异,需实测验证。

Python 3.7+ 中 json.dumps 默认就保持 dict 插入顺序

只要用的是 Python 3.7 或更新版本(包括 3.8、3.9、3.10+),dict 本身就是有序的,json.dumps 会原样保留键的插入顺序,无需额外配置。这是语言层面的保证,不是 json 模块的特例。

验证方式很简单:

>>> import json
>>> d = {'c': 1, 'a': 2, 'b': 3}
>>> json.dumps(d)
'{"c": 1, "a": 2, "b": 3}'

输出中键顺序和插入顺序完全一致。

Python 3.6 及更早版本必须用 collections.OrderedDict

在 Python 3.6(仅限 CPython 实现,且属偶然行为)及之前,dict 无序,json.dumps 会按哈希顺序输出,结果不可预测。此时必须显式使用 OrderedDict

  • 导入:from collections import OrderedDict
  • 构造时严格按需插入:od = OrderedDict([('c', 1), ('a', 2), ('b', 3)]),不能从普通 dict 转换(OrderedDict(dict(...)) 会丢失顺序)
  • 直接传给 json.dumps(od) 即可

注意:json.loads(..., object_hook=OrderedDict) 可用于反序列化时也保持顺序,但仅当原始 JSON 本身键序有意义时才需要。

别被 sort_keys=True 干扰——它会强制重排

如果代码里写了 json.dumps(data, sort_keys=True),哪怕你

用的是 OrderedDict 或 Python 3.7+ 的 dict,最终输出也会按字母升序排列键名,完全覆盖原始插入顺序。

常见误操作场景:

  • 复制了带 sort_keys=True 的调试代码到生产逻辑中
  • 用了某些封装函数(如 Flask 的 jsonify 或旧版 Django JSON 序列化器),内部默认启用了排序
  • IDE 自动补全或代码模板悄悄加了这个参数

检查方法:打印 json.dumps(your_dict) 原始调用,确认不含 sort_keys 参数。

第三方库(如 ujsonorjson)的行为差异

高性能 JSON 库不一定遵循 CPython dict 的顺序语义:

  • ujson:在较老版本(如 1.x)中,即使输入是 OrderedDict,也可能打乱顺序;建议升级到 5.0+ 并测试
  • orjson:明确声明“preserve insertion order for dict”,但仅限 Python 3.7+;对 OrderedDict 同样支持
  • 如果你切换了底层 JSON 库,务必在目标 Python 版本下实测顺序输出,不要假设行为一致

最稳妥的做法:只依赖标准库 json,除非有明确性能瓶颈且已验证第三方库顺序行为符合预期。