Python 处理 JSON 实战指南：读取、写入、校验与转换

Python 内置的 json 模块足以完成大多数日常工作：读取接口样例、写入配置、转换导出数据和定位损坏内容。真正容易出问题的不是第一次调用 json.loads，而是编码、异常、数字精度和数据结构变化。

解析字符串并保留有效错误信息

内存中的 JSON 文本使用 json.loads。捕获 JSONDecodeError 后记录行号和列号，不要把包含隐私或密钥的完整正文写入日志。

import json

raw = '{"name": "Ada", "active": true}'

try:
    data = json.loads(raw)
except json.JSONDecodeError as exc:
    print(f"JSON 无效：第 {exc.lineno} 行，第 {exc.colno} 列：{exc.msg}")
    raise

不要在生产导入中悄悄修复输入后继续处理。排查阶段可以尝试修复，但应保留原始数据，并让每一步转换都可审计。

用 UTF-8 读写文件

始终显式指定编码。ensure_ascii=False 能保持中文可读，indent=2 便于审查。

import json
from pathlib import Path

source = Path("input.json")
target = Path("output.json")

with source.open("r", encoding="utf-8") as handle:
    data = json.load(handle)

with target.open("w", encoding="utf-8") as handle:
    json.dump(data, handle, ensure_ascii=False, indent=2)
    handle.write("\n")

写配置文件时，可以先写入临时文件，序列化成功后再替换正式文件，避免程序中断留下半个 JSON。

在需要时保留十进制精度

JSON 数字没有业务语义。Python 默认把小数解析成 float，不适合需要精确结果的金额计算。可以使用 Decimal：

import json
from decimal import Decimal

payload = json.loads('{"amount": 19.99}', parse_float=Decimal)
print(payload["amount"] * 3)

Decimal 默认不能直接序列化为 JSON。应先明确外部契约采用十进制字符串，还是采用最小货币单位整数，再显式转换。

转换前先校验结构

能解析不等于结构正确。遍历前先确认根节点类型和必填字段。

def normalize_users(value):
    if not isinstance(value, list):
        raise ValueError("根节点必须是数组")

    result = []
    for index, item in enumerate(value):
        if not isinstance(item, dict):
            raise ValueError(f"第 {index} 项必须是对象")
        if "id" not in item or "email" not in item:
            raise ValueError(f"第 {index} 项缺少 id 或 email")
        result.append({
            "id": str(item["id"]),
            "email": str(item["email"]).strip().lower(),
        })
    return result

结构较复杂时，可使用 JSON Schema 和维护良好的校验库，并把 Schema 放入版本控制。语法校验和契约校验解决的是不同问题。

转换时不要默默丢失信息

把嵌套 JSON 转为 CSV 或数据库行时，要提前规定数组、缺失字段、null 和嵌套对象如何表达。

def order_row(order):
    customer = order.get("customer") or {}
    return {
        "order_id": order.get("id"),
        "customer_email": customer.get("email"),
        "item_count": len(order.get("items") or []),
        "status": order.get("status", "unknown"),
    }

为输入和输出保留测试样例。它们能记录代码中不容易看出的业务决定。

用命令行快速检查

Python 自带格式化和语法检查工具：

python -m json.tool input.json
python -m json.tool --sort-keys input.json

需要快速查看结构时，也可以使用 JSON 美化器或 JSON 树形查看器。即使工具在浏览器本地处理数据，也应先移除密钥和不必要的个人信息。

上线前清单

• • 明确文件和 HTTP 字符编码。

• • 在入口限制正文大小和嵌套深度。

• • 日志记录错误位置和请求 ID，不记录完整敏感正文。

• • 区分字段缺失和显式 null。

• • 精度敏感数据使用 Decimal、字符串或最小单位整数。

• • 转换之前校验结构。

• • 测试空数组、Unicode、大整数、无效 JSON 和不完整记录。

Python 官方 json 模块文档列出了编码器和解码器的全部选项。优先使用标准库，在数据契约需要时增加 Schema 校验，并让每一步转换都足够明确、可以审计。