【AI Agent系列课程13-Python 基础13】JSON 读写:结构化数据交换基础

上一篇读配置文件的时候,咱们用了 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 校验"走向"声明式校验"的分水岭。 到时候见。

相关推荐
可夫小子32 分钟前
Inkling 2 Mini 实测解析:26.4B 模型把中间层循环跑 3 遍,20GB 内存塞进笔记本
ai编程·gemini
Highcharts.js5 小时前
Highcharts漏斗图表使用配置指南
java·开发语言·javascript·信息可视化·highcharts·漏斗图
wuyk55510 小时前
Python办公自动化-第01讲-环境搭建与自动化认知
python·自动化·pyqt
高洁0111 小时前
数字孪生与计算机视觉:让机器看懂现场
人工智能·python·机器学习·transformer·迁移学习
ComPDFKit11 小时前
RAG 回答只显示 PDF 文件名?用 Python 保留引用页码
开发语言·python·pdf·rag
FRing0311 小时前
vue3干货总结2(vue3生命周期、父子通信、模版引用、provide和inject)
开发语言·前端·vue.js·vue3
yz_aiks13 小时前
Termux 使用教程:把安卓手机变成随身 Linux(装 Python、SSH 远程、跑自动化脚本)
android·linux·python·智能手机·ssh·termux
琳少_14 小时前
java程序开发笔记
java·开发语言·数据库·笔记
七夜zippoe14 小时前
Agent 告警设计:分级告警、智能降噪与值班排班
开发语言·ai·agent·告警·智能降噪·值班排班