Python 中的 json 模块

json 是 Python 标准库中用于处理 JSON 数据的模块。JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，广泛用于 Web API、配置文件等场景。

json 模块的核心功能是：在 Python 对象和 JSON 字符串之间互相转换。

一、序列化与反序列化

操作	说明	方法
序列化	Python 对象 → JSON 字符串	dumps() / dump()
反序列化	JSON 字符串 → Python 对象	loads() / load()

说明：

• 带 s 的 （dumps/loads）→ 操作字符串 （string）

• 不带 s 的 （dump/load）→ 操作文件 （file）

二、Python 与 JSON 的类型映射

Python 类型	JSON 类型
dict	object
list / tuple	array
str	string
int / float	number
True / False	true / false
None	null

注意：

• Python 的 tuple 会被序列化为 JSON 的 array，但反序列化时变回 list

• JSON 的 number 反序列化时，整数变 int，小数变 float

三、json.dumps()：Python 对象 → JSON 字符串

1. 基本用法

import json

data = {
    "name": "Alice",
    "age": 25,
    "is_active": True,
    "hobbies": ["reading", "swimming"],
    "address": None
}

json_str = json.dumps(data)
print(json_str)
# '{"name": "Alice", "age": 25, "is_active": true, "hobbies": ["reading", "swimming"], "address": null}'
print(type(json_str))   # <class 'str'>

2. 常用参数

参数	说明	示例
indent	缩进空格数，美化输出	indent=2
ensure_ascii	是否转义非 ASCII 字符	ensure_ascii=False（保留中文）
sort_keys	按键排序	sort_keys=True
separators	自定义分隔符	separators=(",", ":")
default	处理不可序列化对象	default=str

data = {"name": "张三", "age": 25}

# 美化输出 + 保留中文
print(json.dumps(data, indent=2, ensure_ascii=False))
# {
#   "name": "张三",
#   "age": 25
# }

# 按 key 排序
print(json.dumps(data, sort_keys=True))
# '{"age": 25, "name": "张三"}'

# 紧凑输出（默认分隔符是 ", " 和 ": "）
print(json.dumps(data, separators=(",", ":")))
# '{"name":"张三","age":25}'

3. 处理不可序列化对象

json.dumps() 默认只能序列化基本类型。遇到 datetime、自定义对象时会报错，需要用 default 指定转换函数。

from datetime import datetime

data = {"time": datetime.now()}

# 报错：Object of type datetime is not JSON serializable
# json.dumps(data)

# 用 default 指定转换函数
json_str = json.dumps(data, default=str)
print(json_str)   # '{"time": "2024-01-01 12:00:00"}'

# 自定义转换函数
def custom_converter(obj):
    if isinstance(obj, datetime):
        return obj.isoformat()
    raise TypeError(f"Object of type {type(obj)} is not JSON serializable")

json_str = json.dumps(data, default=custom_converter)

四、json.loads()：JSON 字符串 → Python 对象

import json

json_str = '{"name": "Alice", "age": 25, "hobbies": ["reading"]}'

data = json.loads(json_str)
print(data)           # {'name': 'Alice', 'age': 25, 'hobbies': ['reading']}
print(type(data))     # <class 'dict'>
print(data["name"])   # Alice

常用参数

参数	说明
object_hook	自定义字典的反序列化处理
parse_float	自定义浮点数解析
parse_int	自定义整数解析

# 自定义整数解析
data = json.loads('{"age": 25}', parse_int=lambda x: int(x) * 2)
print(data)   # {'age': 50}

五、json.dump()：写入文件

dump() 直接把 Python 对象写入文件，不用手动 write()。

import json

data = {
    "name": "Alice",
    "age": 25,
    "hobbies": ["reading", "swimming"]
}

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

参数说明：

参数	说明
fp	文件对象（必须支持 write()）
indent	缩进
ensure_ascii	是否保留中文
sort_keys	按键排序
default	不可序列化对象的处理

注意 ：dump() 的第一个参数是对象 ，第二个参数才是文件。

六、json.load()：从文件读取

import json

# 从文件读取
with open("data.json", "r", encoding="utf-8") as f:
    data = json.load(f)

print(data["name"])   # Alice
print(type(data))     # <class 'dict'>

注意 ：load() 只接受文件对象，不接受字符串。

# 正确：传文件对象
data = json.load(f)

# 错误：传字符串会报错
# data = json.load('{"name": "Alice"}')

# 字符串用 loads
data = json.loads('{"name": "Alice"}')

方法对比

方法	方向	数据源/目标	返回值
dumps()	Python → JSON	对象 → 字符串	str
loads()	JSON → Python	字符串 → 对象	dict / list
dump()	Python → JSON	对象 → 文件	None
load()	JSON → Python	文件 → 对象	dict / list