用 ijson 流式校验大 JSON 的踩坑记录
作者尝试用 ijson 逐项读取数 MB 以上的 JSON,再以 Pydantic 做类型校验,以降低整文件加载带来的内存开销。复盘指出解析前缀理解有误,且添加了一层多余的序列化。
AI 深度解读
处理数 MB 以上的 JSON,作者想用 ijson 逐条读取,再交给 Pydantic v2 校验,把内存开销控制在与记录总数无关的水平。验证过程中,最隐蔽的问题是前缀写错后,程序可能顺利跑完,却一条数据都没处理。
这份记录适合拿来检查自己的导入流程。它讲清了三件容易漏掉的事:解析路径要对准输入结构,校验可以直接接收解析结果,坏记录和坏文件需要分别处理。作者没有给出内存或吞吐的对照数据,最终实现也没有满足全部要求。
为什么程序跑完了,却一条数据都没读到
json.load() 会先把整份 JSON 解析成 Python 对象。ijson.items() 可以边读输入边产出匹配路径上的对象,让下游拿到一条就处理一条。这里的前缀描述的是数据在 JSON 里的位置。
根数组 [...] 的每个元素位于 item,所以用 ijson.items(file_handle, 'item')。如果输入改成 {"item": [...]},第一个 item 是对象的字段名,第二个 item 才代表数组元素,逐条读取的前缀就该用 item.item。原文还提到空字符串前缀,它选中的是根值。根值是数组时,整个数组会作为一个结果返回。
前缀与输入结构对不上,迭代器可能直接结束。对导入任务来说,合法空数组和路径写错都可能表现为零条记录。只盯着退出状态或异常日志,很容易漏掉后者。
Pydantic v2 可以直接校验解析结果
作者最初把 ijson 产出的 Python 对象交给 orjson.dumps(),再用 orjson.loads() 转回 Python 对象。Pydantic v2 的 model_validate() 可以直接接收原生字典,这一来一回增加了编解码工作,也会产生临时数据。
下面这段代码从根数组逐条取对象,校验整数 id、非空字符串 name 和浮点数 value,并跳过校验失败的记录。
import ijson
from pydantic import BaseModel, Field, ValidationError
from typing import Any, Generator
class DataItem(BaseModel):
id: int
name: str = Field(..., min_length=1)
value: float
def stream_process_json(file_handle: Any) -> Generator[DataItem, None, None]:
# Specify the prefix to process the root array
parser = ijson.items(file_handle, 'item')
for record in parser:
try:
# Eliminate the round-trip and validate directly
yield DataItem.model_validate(record)
except ValidationError as e:
# Catch only validation errors and continue streaming
continue
注意 for record in parser: 这一行。解析器在这里取下一条记录,发生的解析错误会传播出去。try 里的 ValidationError 则对应已经成功解析、但字段校验失败的单条记录,跳过后还能继续处理。示例里的 continue 会让坏记录静默消失,实际导入时应至少统计被跳过的条数。
流式读取能省多少内存,还看下游怎么消费
作者把 O(1) 设为目标。按记录数衡量,这个目标成立需要两个条件:单条记录的大小有上界,下游处理完就释放记录。如果调用方用 list() 收集所有 DataItem,内存仍会随记录数增长。即使下游不累积,单条记录特别大,也会推高峰值,因为 ijson.items() 仍要组装这条记录再产出。
吞吐还取决于解析后端。作者指出,ijson 会按运行环境选择后端,可能使用基于 yajl 的 C 后端,也可能在精简容器里回退到纯 Python。原文没有给出实际选中的后端、测试环境和耗时,无法判断这次回退究竟慢了多少。
我的判断
我会优先采纳直接校验和区分两类错误。前者少走两步,后者决定了失败怎么处理:字段缺失时,跳过一条可能符合导入规则;JSON 截断时,前面的记录却可能已经写入目标系统。流式处理能提前产出结果,也让失败时的部分写入成为需要明确处理的问题。
至于内存和性能,这篇文章给的是工程经验,没有峰值内存、吞吐和输入分布的对照数据。与 json.load() 相比,流式方案更适合体积大、能逐条消费的数据。文件体积有明确上限、任务又需要跨记录检查时,一次加载往往更容易实现。选哪种方案,取决于部署环境的内存预算和下游处理方式。
能拿来做什么
- 给导入接口准备根数组、嵌套数组和合法空数组三种样例,断言实际产出的记录条数。遇到业务上应当有数据的输入,把零产出视为需要排查的信号。
- 让 AI 帮你写或审查 Python 导入脚本时,检查
ijson产出的字典是否直接送进model_validate(),并分别用字段缺失和文件截断验证跳过与中止两条路径。 - 在实际部署的容器里确认
ijson选中的后端,用有代表性的文件测峰值内存和吞吐。测量时保留真实的下游写入逻辑,才能看到批量写入或结果累积带来的开销。