上一篇读配置文件的时候,咱们用了 json.load,但只是把它当个工具随手一用,没展开。这一篇专门聊 JSON------因为它就是接口世界的"普通话"。
你想想,前端给你发数据,用 JSON;你给前端回数据,用 JSON;调第三方 API,请求体和响应体还是 JSON。数据库里存不下的嵌套结构,序列化成 JSON 塞进去。你写的 Python 代码和外部世界之间,隔着的几乎永远是一层 JSON。
所以这一篇不只是讲 json 模块的几个函数,而是讲**"Python 对象和 JSON 之间怎么来回翻译,以及翻译过程中哪些地方会翻车"**。
先把两对函数分清楚
json 模块里最常用的四个函数,名字长得像,但干的活不一样。先花两分钟把这张表刻进脑子里,能省掉后面无数次"我到底该用哪个"的犹豫。
| 函数 | 方向 | 操作对象 |
|---|---|---|
json.dumps() |
Python → JSON | 字符串 |
json.dump() |
Python → JSON | 文件 |
json.loads() |
JSON → Python | 字符串 |
json.load() |
JSON → Python | 文件 |
记忆口诀:带 s 的跟字符串打交道(s = string),不带 s 的跟文件打交道。
python
import json
# Python 对象 → JSON 字符串
text = json.dumps({"name": "xiaoming", "age": 22})
# '{"name": "xiaoming", "age": 22}'
# JSON 字符串 → Python 对象
data = json.loads('{"name": "xiaoming", "age": 22}')
# {'name': 'xiaoming', 'age': 22}
# Python 对象 → 写入文件
with open("user.json", "w", encoding="utf-8") as f:
json.dump({"name": "xiaoming"}, f, ensure_ascii=False, indent=2)
# 从文件读取 → Python 对象
with open("user.json", encoding="utf-8") as f:
data = json.load(f)
接口开发里,你用得最多的是 dumps 和 loads ,因为 HTTP 传过来传过去的都是字符串,不是文件。dump 和 load 主要用在读写配置文件、导出数据这些场景。
Python 类型和 JSON 类型的对应关系
JSON 只有六种数据类型,Python 的类型比它多得多。所以翻译的时候,是一对多、有损的。这张表你得心里有数:
| Python | JSON | 说明 |
|---|---|---|
dict |
object {} |
一一对应 |
list / tuple |
array [] |
元组会被转成数组,转回来是列表 |
str |
string | 一一对应 |
int / float |
number | 转回来时,整数是 int,带小数点是 float |
True / False |
true / false |
Python 大写,JSON 小写 |
None |
null |
名字都不一样 |
datetime |
❌ 不支持 | 得手动转成字符串 |
set |
❌ 不支持 | 得先转成列表 |
| 自定义对象 | ❌ 不支持 | 得先转成字典 |
看最后三行,这就是 JSON 序列化最常翻车的地方 。你从数据库查出来一个 datetime 对象,直接 json.dumps,立刻报错:
text
TypeError: Object of type datetime is not JSON serializable
这个报错,每个写接口的人都会遇到,而且不止一次。
第一个高频坑:中文变乱码
python
data = {"name": "小明", "city": "杭州"}
print(json.dumps(data))
# '{"name": "\u5c0f\u660e", "city": "\u676d\u5dde"}'
dumps 默认会把非 ASCII 字符转成 \uXXXX 的转义形式。这在程序之间传数据没问题,JSON 解析器能正确还原。但你要是把这段 JSON 存到文件里、或者直接给人看,就是一堆看不懂的乱码。
解法就一个参数:
python
json.dumps(data, ensure_ascii=False)
# '{"name": "小明", "city": "杭州"}'
ensure_ascii=False,建议你在所有 dumps 和 dump 里都加上,无脑加。 中文原样输出,文件可读,日志可读,调试的时候能省很多事。
第二个高频坑:输出的 JSON 是一坨,没法读
python
json.dumps({"a": 1, "b": {"c": 2, "d": [1, 2, 3]}})
# '{"a": 1, "b": {"c": 2, "d": [1, 2, 3]}}'
一行到底,嵌套深了根本没法看。加 indent:
python
json.dumps(data, ensure_ascii=False, indent=2)
输出就变成:
json
{
"a": 1,
"b": {
"c": 2,
"d": [
1,
2,
3
]
}
}
indent=2 是"给人看"的标配。 但你得知道:加了 indent 的 JSON,体积会变大 ,因为多了空格和换行。所以写文件、给人看、调试的时候加;走网络传输、追求体积的时候不加。 接口返回给前端的 JSON,通常不加 indent,前端自己会格式化。
第三个坑:datetime 序列化不了
这是接口开发里绕不过去 的一个问题。数据库里查出来的 created_at 是 datetime 对象,你想把它塞进 JSON 返回给前端,直接炸。
没有银弹,只能手动转。 常见的做法是转成 ISO 格式的字符串:
python
from datetime import datetime
data = {"created_at": datetime(2024, 1, 15, 10, 30)}
json.dumps(data) # TypeError
# 手动转
data["created_at"] = data["created_at"].isoformat()
json.dumps(data)
# '{"created_at": "2024-01-15T10:30:00"}'
isoformat() 出来的格式是 2024-01-15T10:30:00,前端各种日期库都能直接解析,算是事实标准。
如果数据结构嵌套很深,手动逐个转太累,可以用 default 参数给 dumps 一个"兜底转换函数":
python
def json_default(obj):
if isinstance(obj, datetime):
return obj.isoformat()
if isinstance(obj, set):
return list(obj)
raise TypeError(f"类型 {type(obj)} 不支持 JSON 序列化")
json.dumps(data, ensure_ascii=False, default=json_default)
这个 default 函数的意思是:遇到不知道怎么转的类型,就交给它处理。 它返回什么,dumps 就用什么代替。返回不了就抛 TypeError,让你知道还有没覆盖到的情况。
这个套路在接口开发里非常有用 ,因为你的数据里可能同时有 datetime、Decimal(金额)、set(标签),写一个统一的 json_default,一劳永逸。
反序列化:loads 也会翻车
dumps 是把 Python 转成 JSON,loads 是反过来。反过来的坑,主要在于输入的 JSON 可能不合法。
python
json.loads('{"name": "xiaoming",}') # 多余的逗号
json.loads("{'name': 'xiaoming'}") # 单引号,不是合法 JSON
json.loads('') # 空字符串
这三种,全都会抛 json.JSONDecodeError。接口开发里,这个异常必须接住,因为请求体是外部传进来的,你永远不知道对方发了什么。
python
try:
data = json.loads(request_body)
except json.JSONDecodeError as e:
logger.warning("请求体不是合法 JSON:%s", e)
return {"code": 400, "message": "请求格式错误"}
注意:json.loads 只认双引号。 单引号、Python 风格的 True/None、结尾多余的逗号,全都不认。这是 JSON 标准定的,不是 Python 的锅。你从别的地方复制来的"看起来像 JSON"的字符串,经常因为这些细节挂掉。
一个特别容易被忽略的点:loads 的结果类型
json.loads 返回的是什么类型,取决于你传进去的 JSON 是什么:
python
json.loads('{"a": 1}') # dict
json.loads('[1, 2, 3]') # list
json.loads('"hello"') # str
json.loads('123') # int
json.loads('true') # bool
json.loads('null') # None
JSON 顶层不一定是对象。 你可以直接传一个数组、一个数字、一个字符串。所以如果你写了一个函数,假设 loads 的结果一定是字典,然后直接 data["key"],碰到对方传了个数组过来,就是 TypeError: list indices must be integers。
接口开发里,请求体通常约定是对象(字典) ,但你最好在 loads 之后加一句类型检查:
python
data = json.loads(body)
if not isinstance(data, dict):
return {"code": 400, "message": "请求体必须是 JSON 对象"}
这行代码很短,但能挡住一类很烦的错误。
JSON 和接口:把这一篇落到实地
接口开发里,JSON 出现在两个地方:请求进来的时候,和响应出去的时候。
请求进来:反序列化 + 校验
python
def handle_request(body: str) -> dict:
try:
data = json.loads(body)
except json.JSONDecodeError:
return {"code": 400, "message": "请求体不是合法 JSON"}
if not isinstance(data, dict):
return {"code": 400, "message": "请求体必须是 JSON 对象"}
name = data.get("name")
if not name:
return {"code": 400, "message": "name 字段不能为空"}
return {"code": 200, "data": {"name": name}}
这就是接口处理请求的骨架:先解析,解析失败返回 400;再检查结构,结构不对返回 400;再检查字段,字段缺了返回 400;都过了,才进业务逻辑。
响应出去:组装 + 序列化
python
def build_response(data: dict) -> str:
return json.dumps(
{"code": 200, "data": data, "message": "success"},
ensure_ascii=False,
default=json_default
)
响应这边,通常统一包一层 {code, data, message} 的外壳,然后用 dumps 序列化。ensure_ascii=False 和 default 是标配,一个保中文,一个保日期。
你后面用 FastAPI 的时候,框架会帮你把这两步自动做掉。 但你现在得知道它背后在干什么,否则出了序列化错误,你连从哪儿查都不知道。
格式化输出:调试时的小帮手
调试的时候,手里有一段又长又扁的 JSON 字符串,看不清结构,用 indent 重新排一下:
python
print(json.dumps(json.loads(raw), ensure_ascii=False, indent=2))
一行代码,把"解析 → 重排 → 输出"串起来。这个命令我在排查接口问题时用了无数次,尤其是对方返回一大坨压缩过的 JSON,不排一下根本找不到字段在哪。
反过来,如果你想把手写的带缩进的 JSON 压成一行(比如塞进环境变量),用 separators:
python
json.dumps(data, ensure_ascii=False, separators=(",", ":"))
默认的分隔符是 ", " 和 ": ",带了空格。换成 (",", ":") 就没空格了,体积更小。这个参数知道就行,日常用得不多,但传输大 JSON 的时候能省一点带宽。
踩坑清单
| 坑 | 表现 | 正确姿势 |
|---|---|---|
| 中文被转义 | 文件里全是 \uXXXX |
ensure_ascii=False |
直接 dumps(datetime) |
TypeError: not JSON serializable |
.isoformat() 或 default 参数 |
| 单引号当 JSON 解析 | JSONDecodeError |
JSON 只认双引号 |
不接 JSONDecodeError |
请求体不合法时接口 500 | try/except,返回 400 |
假设 loads 返回字典 |
对方传数组,直接炸 | isinstance(data, dict) 检查 |
dump 到文件没加 indent |
文件是一行,没法读 | 写文件加 indent=2 |
网络传输加 indent |
体积无谓变大 | 传输不加,写文件才加 |
混淆 dumps 和 dump |
参数传错,报奇怪的错 | 带 s 的跟字符串,不带跟文件 |
这个阶段可以练什么: 写一个
safe_parse(body: str) -> tuple[dict | None, str | None],接收一个 JSON 字符串,返回(data, error)二元组。要求:解析失败返回(None, "格式错误");解析成功但不是字典返回(None, "必须是对象");成功返回(data, None)。再写一个safe_dump(data: dict) -> str,要求支持datetime自动转 ISO 字符串、支持set自动转列表、中文不转义。这两个函数,就是你将来接口里"请求解析"和"响应序列化"的原型,写完你会发现 FastAPI 帮你省了多少事。
说句实在话,JSON 这块,函数就四个,参数也就那么几个,语法层面真的一天就能学完。 但"什么时候会翻车""翻车了怎么兜",才是接口开发真正考验人的地方。你序列化一个带 datetime 的字典,第一次报错,查一下,解决了;第二次你加了 default,一劳永逸。这种"踩过一次就再也不用想"的坑,越早踩越好。
下一篇,咱们讲 Pydantic 入门 。你现在用 json.loads 解析出来的数据,本质上还是一个"裸字典"------你知道它"应该有"什么字段,但代码不知道。Pydantic 就是来给这个裸字典"上规矩"的:定义清楚它该有什么字段、什么类型、缺了怎么办。它是 FastAPI 自动校验的命根子,也是你从"手写 if 校验"走向"声明式校验"的分水岭。 到时候见。