Python字典和列表怎么转换为JSON字符串

在 Python 中将字典（dict）或列表（list）转换为 JSON 格式的字符串，核心方法是使用内置的标准库 json 中的 json.dumps() 函数。Python 字典在转换后对应 JSON 的“对象”（以大括号包裹的键值对），列表则对应 JSON 的“数组”（以方括号包裹的有序序列）。整个过程无需安装任何第三方库，只需导入模块并传入目标对象即可完成序列化。

一、基础转换：使用 json.dumps()

json.dumps() 中的 s 代表 string，意思是将内存中的 Python 对象“转储”（dump）为一个普通的字符串。无论是字典还是列表，调用方式都完全统一。

1. 字典转换为 JSON 字符串

字典包含键值映射关系。在序列化时，Python 字典的键会自动转为带双引号的 JSON 键，常见的基础数据类型也会同步转为对应格式：

import json

# 定义一个普通的 Python 字典
user_info = {
    "name": "Alex",
    "age": 28,
    "is_active": True,
    "skills": ["Python", "SQL"],
    "profile": None
}

# 转换为 JSON 字符串
json_str = json.dumps(user_info)

print(type(json_str))
print(json_str)

示例输出：

<class 'str'>
{"name": "Alex", "age": 28, "is_active": true, "skills": ["Python", "SQL"], "profile": null}

2. 列表转换为 JSON 字符串

列表是有序序列。既可以转换纯数值或字符串构成的单一列表，也可以转换在 Web API 开发中最常见的“字典列表”（对象数组）：

import json

# 包含字典元素的列表
product_list = [
    {"id": 101, "name": "Keyboard", "price": 199.5},
    {"id": 102, "name": "Mouse", "price": 89.0}
]

# 执行转换
json_array_str = json.dumps(product_list)

print(json_array_str)

示例输出：

[{"id": 101, "name": "Keyboard", "price": 199.5}, {"id": 102, "name": "Mouse", "price": 89.0}]

二、核心参数控制：格式美化与中文保留

直接调用 json.dumps(data) 时，默认设置偏向于生成紧凑型 ASCII 字符串。在中文环境或需要人工排查日志时，需要配置以下关键参数。

1. 正确输出中文：ensure_ascii=False

默认情况下，ensure_ascii=True 会将所有非 ASCII 字符（包括中文字符）转义为 Unicode 编码转义序列（形如 \u4e2d\u6587）。这虽然符合规范，但严重影响人类阅读。

import json

user_data = {"城市": "北京", "职位": "工程师"}

# 默认行为（转义中文）
default_json = json.dumps(user_data)
print("默认转义:", default_json)

# 保留中文字符
chinese_json = json.dumps(user_data, ensure_ascii=False)
print("保留中文:", chinese_json)

示例输出：

默认转义: {"\u57ce\u5e02": "\u5317\u4eac", "\u804c\u4f4d": "\u5de5\u7a0b\u5e08"}
保留中文: {"城市": "北京", "职位": "工程师"}

2. 格式化缩进排版：indent

默认输出的 JSON 字符串是没有换行和空格的紧凑文本。通过传入 indent 参数（通常指定整数 2 或 4），可以输出带缩进换行的高可读性结构，便于在控制台或文件中查看：

data = {
    "project": "Report",
    "tags": ["python", "json"],
    "version": 1.0
}

pretty_json = json.dumps(data, indent=4, ensure_ascii=False)
print(pretty_json)

示例输出：

{
    "project": "Report",
    "tags": [
        "python",
        "json"
    ],
    "version": 1.0
}

3. 键名排序：sort_keys=True

在接口签名验证、数据比对或单元测试中，确保字典输出的键名按字母顺序排序非常有用：

raw_dict = {"z": 10, "a": 5, "m": 8}
sorted_json = json.dumps(raw_dict, sort_keys=True)
print(sorted_json)  # 输出: {"a": 5, "m": 8, "z": 10}

三、常见错误排查与重要注意事项

1. TypeError: Object of type ... is not JSON serializable

JSON 官方标准只定义了极少的基础类型（数字、字符串、布尔、数组、对象、null）。如果字典或列表中包含了 Python 的其他对象，如 set（集合）、datetime 对象或自定义 Class 实例，执行 json.dumps() 会直接抛出序列化异常。

import json
from datetime import datetime

# 错误示例：包含不可直接序列化的集合和日期
bad_data = {
    "tags": {"python", "coding"},  # set 集合不支持
    "created_at": datetime.now()     # datetime 对象不支持
}

# 解决方案：预先转换类型，或指定 default 参数处理器
def custom_encoder(obj):
    if isinstance(obj, set):
        return list(obj)
    if isinstance(obj, datetime):
        return obj.strftime("%Y-%m-%d %H:%M:%S")
    raise TypeError(f"无法序列化类型: {type(obj)}")

safe_json = json.dumps(bad_data, default=custom_encoder, ensure_ascii=False)
print(safe_json)

2. 明确区分 dumps() 与 dump()

很多初学者容易将 dumps 与 dump 混淆。两者的区别非常直观：

• json.dumps(obj)：带 s，接收对象并返回一个 Python 字符串（str），留在内存中处理。
• json.dump(obj, fp)：不带 s，接收对象和一个文件对象（如通过 open 打开的文件），直接将 JSON 数据写入磁盘文件。

import json

data = {"item": "notebook", "qty": 5}

# 场景 1：获取字符串（本文主题）
json_text = json.dumps(data)

# 场景 2：直接写入本地文件
with open("data.json", "w", encoding="utf-8") as f:
    json.dump(data, f, ensure_ascii=False, indent=2)

3. Python 单引号与 JSON 双引号规范

在 Python 语法中，字符串用单引号 'key' 或双引号 "key" 均可；但 JSON 规范强制规定键名和字符串值必须使用双引号 "。永远不要试图使用字符串的 replace("'", '"') 去手工拼凑 JSON，这种做法在遇到文本内部本身带有单引号、双引号或转义字符时极易损坏数据结构，始终应由 json.dumps() 自动转义生成。

四、方法总结表

掌握以上 json.dumps() 的调用方式和参数组合，即可在 Python 开发中稳定、高效地完成字典与列表到标准 JSON 字符串的转换处理。