[!info] 关联笔记

• 所属 MOC：标准库 · 学习路线
• 前置：字典 · dataclass
• 相关：HTTP 客户端

Python JSON 与序列化

这个概念为什么出现

API、配置、日志事件普遍 JSON。类型映射与失败模式（非法 JSON、非 UTF-8、不可序列化对象）必须清楚。

[!abstract] 一句话理解 json.loads/dumps 在 str 与 Python 基础容器间转换；复杂对象先变成可 JSON 结构再编码。

最小可运行示例

场景：下单 API 编解码 body

# order_json_demo.py
# 业务意图：解析下单 JSON 并回编码响应。
# 教学点：loads/dumps；类型映射；错误。

import json


def parse_order(raw: str) -> dict:
    data = json.loads(raw)
    if "sku" not in data:
        raise ValueError("sku required")
    return data


def main() -> None:
    raw = '{"sku":"SKU-1","qty":2}'
    order = parse_order(raw)
    print(order)
    print(json.dumps({"ok": True, "order": order}, ensure_ascii=False))
    try:
        parse_order("{")
    except json.JSONDecodeError as exc:
        print("bad json:", type(exc).__name__)


if __name__ == "__main__":
    main()

建议运行：

python order_json_demo.py

期望输出：

{'sku': 'SKU-1', 'qty': 2}
{"ok": true, "order": {"sku": "SKU-1", "qty": 2}}
bad json: JSONDecodeError

结合场景再看三个关注点

1. 对象→dict/list/str/number/bool/null。
2. datetime/自定义类需转换。
3. ensure_ascii=False 便于中文日志。

核心概念与准确模型

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

• load/dump 针对文件
• default= / object_hook

边界情况与反直觉行为

1. 浮点精度
2. 键必须是 str（dumps 会转换非 str 键）
3. 大数字 与 JS 互操作

常见误区

[!warning] 常见误区：直接 dumps 任意对象 错误理解：魔法序列化一切。
正确模型：先 DTO/asdict。

工程实践

• 边界校验（pydantic 等）
• 版本化 schema
• 日志脱敏

本节总结

JSON 是跨服务契约。编解码简单，契约治理不易。

自测题

1. loads 失败抛什么？
2. dataclass 怎么 JSON？

参考答案

1. JSONDecodeError。
2. 先 asdict 或自定义编码器。

延伸阅读与资料来源

资料	类型	支撑内容
json	文档	标准库