json.dumps怎么格式化输出_json美化与格式化方法

使用json.dumps并设置indent参数可格式化JSON输出，提升可读性；通过indent指定缩进空格数，sort_keys=True确保键有序，separators压缩体积，ensure_ascii=False支持中文显示。

Python里要格式化输出JSON，让它看起来更规整、易读，核心就是用json.dumps函数，并且巧妙地利用它的indent参数。这个参数能帮你把原本挤成一团的JSON字符串，像搭积木一样，一层层地缩进排开，瞬间清晰很多。

解决方案

当我们处理JSON数据时，尤其是从API获取或者需要手动检查时，原始的JSON字符串往往是紧凑的，所有键值对都挤在一行，阅读起来简直是噩梦。json.dumps就是Python标准库json模块里一个非常实用的函数，它能把Python对象序列化成JSON格式的字符串。而要实现格式化输出，关键在于给indent参数传递一个整数值，这个值就代表了每一级缩进要使用的空格数量。

比如，我们有一个字典：

data = {
    "name": "张三",
    "age": 30,
    "isStudent": False,
    "courses": [
        {"title": "Python编程", "credits": 3},
        {"title": "数据结构", "credits": 4}
    ],
    "address": {
        "street": "科技路123号",
        "city": "北京",
        "zipCode": "100000"
    }
}

如果直接json.dumps(data)，输出会是这样： {"name": "张三", "age": 30, "isStudent": false, "courses": [{"title": "Python编程", "credits": 3}, {"title": "数据结构", "credits": 4}], "address": {"street": "科技路123号", "city": "北京", "zipCode": "100000"}} 这阅读体验确实不太好。

现在，我们加入indent参数，通常我会选择2或4个空格，因为这在代码界是个比较通用的习惯：

import json

data = {
    "name": "张三",
    "age": 30,
    "isStudent": False,
    "courses": [
        {"title": "Python编程", "credits": 3},
        {"title": "数据结构", "credits": 4}
    ],
    "address": {
        "street": "科技路123号",
        "city": "北京",
        "zipCode": "100000"
    }
}

# 使用indent=4进行格式化输出
formatted_json_output = json.dumps(data, indent=4, ensure_ascii=False)
print(formatted_json_output)

输出就会变得清晰明了：

{
    "name": "张三",
    "age": 30,
    "isStudent": false,
    "courses": [
        {
            "title": "Python编程",
            "credits": 3
        },
        {
            "title": "数据结构",
            "credits": 4
        }
    ],
    "address": {
        "street": "科技路123号",
        "city": "北京",
        "zipCode": "100000"
    }
}

你看，是不是一下子就舒服多了？indent参数传入的整数值，就是告诉json.dumps，每个层级需要增加多少个空格作为缩进。这个小小的改动，在调试、日志记录或者生成配置文件时，都能极大提升效率和心情。

如何精细控制JSON输出的缩进层级？

控制json.dumps的缩进层级，其实就是玩转indent参数。它不只是一个开关，更像是一个刻度盘，让你能根据具体需求来调整JSON的“胖瘦”。最常用的，无非就是indent=2或indent=4，这两个值在大多数编程社区里，都是被广泛接受的缩进标准，代码看起来会很和谐。

当你设置indent=2时，每一级嵌套会比上一级多两个空格：

import json

data = {"a": 1, "b": {"c": 2, "d": [3, 4]}}
print(json.dumps(data, indent=2))

输出：

{
  "a": 1,
  "b": {
    "c": 2,
    "d": [
      3,
      4
    ]
  }
}

而indent=4则会多四个空格，让结构看起来更“宽松”：

print(json.dumps(data, indent=4))

输出：

{
    "a": 1,
    "b": {
        "c": 2,
        "d": [
            3,
            4
        ]
    }
}

除了整数，indent其实还可以接受字符串，比如indent='\t'就可以用制表符（tab）来缩进。不过，我个人更推荐使用空格，因为制表符在不同的编辑器或显示环境下，宽度可能不一致，容易造成视觉上的混乱。而空格，就是实实在在的空格，在哪儿都一样。

当然，如果你不设置indent参数，或者将其设置为None，json.dumps就会输出最紧凑的JSON字符串，没有任何缩进和换行。这在需要节省存储空间或网络传输带宽时很有用，但在人工阅读时就显得非常吃力了。所以，选择哪个值，完全取决于你的使用场景：是给人看，还是给机器处理？

为什么JSON键的顺序会变？如何让它始终一致？

JSON规范本身并没有规定对象（也就是Python里的字典）中键的顺序。这意味着，当你把一个Python字典转换为JSON字符串时，不同的Python版本、甚至在某些特定情况下，字典内部键的迭代顺序都可能影响到json.dumps的输出顺序。这在调试、版本控制（比如Git diff）或者自动化测试中，可能会带来一些不必要的麻烦，因为即使内容完全相同，仅仅因为键的顺序不同，也会被认为是两个不同的字符串。

为了解决这个问题，json.dumps提供了一个非常贴心的参数：sort_keys。当sort_keys设置为True时，json.dumps在序列化之前会先对字典的键进行排序（默认是按字母顺序升序排列），然后再生成JSON字符串。这样，无论你原始字典里的键是啥顺序，最终输出的JSON都会有一个统一、可预测的顺序。

举个例子：

import json

data_unordered = {
    "beta": 2,
    "alpha": 1,
    "gamma": 3
}

# 不排序的输出（可能与原始顺序相同，也可能不同，取决于Python版本和字典实现）
print("不排序：", json.dumps(data_unordered, indent=2))

# 排序后的输出
print("排序后：", json.dumps(data_unordered, indent=2, sort_keys=True))

输出可能会是这样：

不排序： {
  "beta": 2,
  "alpha": 1,
  "gamma": 3
}
排序后： {
  "alpha": 1,
  "beta": 2,
  "gamma": 3
}

你看，通过sort_keys=True，键的顺序就固定了，alpha总是在beta前面，beta总是在gamma前面。这对于确保输出的稳定性至关重要，尤其是在进行比较操作时，它能帮你排除掉因键顺序不同而产生的“假性差异”。我个人在写测试用例或者生成需要人工比对的日志时，几乎都会加上sort_keys=True，省去了很多不必要的困扰。

除了美化，json.dumps还能怎么优化输出？比如压缩或处理中文？

除了美化输出（indent）和保证键序（sort_keys），json.dumps还有几个参数能帮你进一步优化JSON的输出，无论是为了压缩体积，还是为了更好地处理非ASCII字符，它都考虑到了。

1. 极致压缩输出：separators参数

如果你需要生成最紧凑的JSON字符串，例如为了网络传输效率或者存储空间，indent和sort_keys就显得有些“奢侈”了。这时，你可以利用separators参数来去除所有不必要的空白字符。separators接受一个元组(item_separator, key_separator)，分别用于分隔列表项和字典键值对。默认情况下，它们是(', ', ': ')，带有空格。要实现最紧凑的输出，我们可以把它们设置成(',', ':')：

import json

data = {"name": "张三", "age": 30, "city": "北京"}

# 默认输出 (带空格)
print("默认：", json.dumps(data))

# 紧凑输出 (无空格)
print("紧凑：", json.dumps(data, separators=(',', ':')))

输出：

默认： {"name": "张三", "age": 30, "city": "北京"}
紧凑： {"name":"张三","age":30,"city":"北京"}

这样，原本在逗号和冒号后面的空格都被移除了，字符串长度会进一步缩短。这在处理大量JSON数据时，哪怕只是微小的优化，累积起来也能节省不少资源。

2. 优雅处理非ASCII字符：ensure_ascii参数

默认情况下，json.dumps会将所有非ASCII字符（比如中文、日文、俄文等）转义成\uXXXX的形式。这是为了确保生成的JSON字符串在任何严格遵循ASCII编码的环境中都能正确解析，具有很好的兼容性。

import json

data_chinese = {"message": "你好，世界！"}

# 默认输出 (中文被转义)
print("默认 (转义)：", json.dumps(data_chinese))

输出： 默认 (转义)： {"message": "\u4f60\u597d\uff0c\u4e16\u754c\uff01"}

但很多时候，我们希望JSON字符串能直接显示这些非ASCII字符，尤其是在日志、调试输出或者明确知道接收方能正确处理UTF-8编码时。这时，可以将ensure_ascii参数设置为False：

# 不转义输出 (中文直接显示)
print("不转义：", json.dumps(data_chinese, ensure_ascii=False, indent=2))

输出：

不转义： {
  "message": "你好，世界！"
}

这样，中文就能直接在JSON字符串中显示了，阅读起来更加直观。不过，使用ensure_ascii=False时，你需要确保你的输出环境（比如终端、文件编辑器）以及接收这个JSON字符串的系统或程序，都能够正确处理UTF-8编码，否则可能会出现乱码。这是一个权衡，在本地开发调试时我经常用ensure_ascii=False，但在生产环境需要考虑兼容性时，可能还是会倾向于默认的转义行为。