下面我将从基础用法、处理复杂数据类型、格式化输出以及错误处理等方面,为你详细讲解。

基础用法：json.dumps()

json 模块的核心函数是 dumps()，它的作用是 "dump string"（转储为字符串）。

语法： json.dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)

最常用的参数是 indent,用于格式化输出。

示例 1：简单的字典转换

import json
# 1. 准备一个 Python 字典
my_dict = {
    "name": "张三",
    "age": 30,
    "isStudent": False,
    "courses": ["数学", "物理", "化学"],
    "address": {
        "city": "北京",
        "district": "海淀区"
    }
}
# 2. 使用 json.dumps() 将字典转换为 JSON 字符串
# 默认情况下，输出是紧凑的（没有缩进）
json_string_compact = json.dumps(my_dict)
print("紧凑格式的 JSON 字符串:")
print(json_string_compact)
# 输出: {"name": "张三", "age": 30, "isStudent": false, "courses": ["数学", "物理", "化学"], "address": {"city": "北京", "district": "海淀区"}}
print("-" * 20)
# 3. 使用 indent 参数进行格式化，使 JSON 更易读
json_string_pretty = json.dumps(my_dict, indent=4, ensure_ascii=False)
print("格式化后的 JSON 字符串:")
print(json_string_pretty)

格式化后的输出：

{
    "name": "张三",
    "age": 30,
    "isStudent": false,
    "courses": [
        "数学",
        "物理",
        "化学"
    ],
    "address": {
        "city": "北京",
        "district": "海淀区"
    }
}

关键点解释：

• import json: 首先必须导入 json 模块。
• indent=4: 指定缩进为 4 个空格，使输出非常美观,适合调试或配置文件。
• ensure_ascii=False: 这是一个非常重要的参数！
  • 默认值 True 会将所有非 ASCII 字符（如中文）转义为 \uXXXX 的形式。
  • 设置为 False 可以保留原始的 Unicode 字符（如中文）,这在处理中文数据时非常常用。

处理 Python 特有的数据类型

JSON 标准只支持以下数据类型：

• dict (对象)
• list, tuple (数组)
• str (字符串)
• int, float (数字)
• True, False (布尔值)
• None

当你尝试转换包含 Python 特有类型（如 datetime, set）的字典时，json.dumps() 会抛出 TypeError。

示例 2：处理不支持的类型（会报错）

import json
import datetime
my_dict_with_error = {
    "name": "李四",
    "birthday": datetime.date(1990, 1, 1),
    "tags": {"python", "json"}
}
try:
    json.dumps(my_dict_with_error)
except TypeError as e:
    print(f"发生错误: {e}")
    # 输出: 发生错误: Object of type date is not JSON serializable

解决方案：使用 default 参数

json.dumps() 的 default 参数允许你指定一个函数，当遇到无法序列化的对象时,会调用这个函数来转换它。

示例 3：自定义序列化函数

import json
import datetime
# 自定义一个序列化函数
def custom_serializer(obj):
    # 如果对象是 date 或 datetime 类型，就将其转换为 ISO 格式的字符串
    if isinstance(obj, (datetime.date, datetime.datetime)):
        return obj.isoformat()
    # 如果对象是 set 类型，就将其转换为 list
    elif isinstance(obj, set):
        return list(obj)
    # 其他不支持的类型，抛出 TypeError
    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
my_dict = {
    "name": "李四",
    "birthday": datetime.date(1990, 1, 1),
    "login_time": datetime.datetime(2025, 10, 27, 10, 30, 0),
    "tags": {"python", "json", "developer"}
}
# 使用 default 参数传入我们的自定义函数
json_string = json.dumps(my_dict, indent=4, ensure_ascii=False, default=custom_serializer)
print("处理特殊类型后的 JSON:")
print(json_string)

输出：

{
    "name": "李四",
    "birthday": "1990-01-01",
    "login_time": "2025-10-27T10:30:00",
    "tags": [
        "python",
        "json",
        "developer"
    ]
}

这样，我们就成功地处理了 date, datetime 和 set 类型。

将 JSON 字符串写入文件

除了将字典转为字符串，更常见的场景是将结果保存到一个 .json 文件中，这时使用 json.dump() 会更方便（注意没有 s）。

json.dump() 直接将 Python 对象写入文件流,避免了先创建字符串再写入的步骤。

示例 4：将字典写入 JSON 文件

import json
import datetime
# 准备数据
data_to_save = {
    "status": "success",
    "timestamp": datetime.datetime.now(),
    "data": [1, 2, 3, {"key": "value"}]
}
# 自定义序列化函数
def default_serializer(obj):
    if isinstance(obj, datetime.datetime):
        return obj.isoformat()
    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")
# 定义文件名
file_name = "data.json"
# 使用 'with' 语句打开文件，确保文件会被正确关闭
# 使用 json.dump() 直接写入
with open(file_name, "w", encoding="utf-8") as f:
    json.dump(data_to_save, f, indent=4, ensure_ascii=False, default=default_serializer)
print(f"数据已成功写入到 {file_name}")
# 验证文件内容
with open(file_name, "r", encoding="utf-8") as f:
    content = f.read()
    print("\n文件内容:")
    print(content)

生成的 data.json 文件内容：

{
    "status": "success",
    "timestamp": "2025-10-27T15:45:12.123456",
    "data": [
        1,
        2,
        3,
        {
            "key": "value"
        }
    ]
}

总结与对比

最佳实践清单：

1. 导入模块: import json
2. 处理中文: 优先使用 ensure_ascii=False。
3. 美化输出: 调试用或给人看时，使用 indent=4。
4. 处理特殊类型: 定义一个 default 函数来处理 datetime, set 等。
5. 写入文件: 使用 with open(...) 和 json.dump(),确保文件安全关闭。

希望这份详细的解释能帮助你完全掌握 Python 字典到 JSON 的转换！