Python3如何用json_normalize展开嵌套JSON数据

相比手工编写递归函数，使用 json_normalize 要可靠得多——它专为展平嵌套的 JSON 结构而设计，能够妥善处理各种边界情况，如 None 值、空列表、混合类型等。同时，通过 record_path 和 meta 参数，可以精准地提取记录数据和上下文信息。

为什么 json_normalize 比手写递归更可靠？

它的设计初衷是将树形嵌套结构“压平”为二维表格，而不仅仅是提取某个值或遍历所有节点。当你最终需要构建 pandas.DataFrame、导出 CSV 或进行聚合分析时，json_normalize 可以直接生成列对齐的规整结构，避免手动处理键冲突、空值对齐、列表长度不一致等潜在问题。

该函数内部自动处理了：None 值填充、重复键的层级前缀、嵌套列表的可选展开、多级路径映射等任务——这些正是手工编写递归函数时容易遗漏或出现逻辑错误的地方。

如何正确选择 json_normalize 的三个关键参数？

关键取决于原始 JSON 的顶层结构：

• 如果顶层是 list（例如 API 返回的多个订单），直接传入该列表，data=your_list
• 如果顶层是 dict，但你想展开其中某个嵌套字段（如 "orders"），使用 record_path="orders"，再配合 meta 提取外层字段（如 ["system_info.api_version"]）
• 遇到字段名包含点号（"user.name"）或需要自定义列名时，必须设置 sep="_"，否则默认的 . 符号会与路径分隔符冲突，导致列名解析失败

为什么展开嵌套列表时数据会缺失？

默认情况下，json_normalize 遇到字段值为 list 时，只取第一个元素（相当于 pd.json_normalize(..., max_level=0)）。要完整展开，必须显式指定：

• record_path 指向那个列表字段（如 ["products"]）
• meta 列出需要保留的父级字段（如 ["order_id", "customer.name"]）
• 若列表位于多层深处（如 data["response"]["items"][0]["details"]），不能使用字符串路径，而要用 record_path=["response", "items", "details"]

忽略 record_path 或将路径写成字符串（如 "response.items.details"），结果会得到空 DataFrame 或抛出 KeyError。

如何安全处理缺失字段与类型不一致的情况？

json_normalize 默认对缺失字段填充 NaN，但后续导入数据库或导出 Excel 时，NaN 可能引发问题。建议：

• 添加参数 errors="ignore" 防止某条记录字段缺失导致整个解析中断
• 使用 fill_value 统一替换空值（例如 fill_value="" 或 fill_value=None）
• 对于已知可能为 int/str 混合的字段（如 "amount"），解析后手动调用 df["amount"] = pd.to_numeric(df["amount"], errors="coerce")

最容易忽略的是：当原始 JSON 中同一字段在不同记录里类型不一致（比如有时是 str，有时是 dict），json_normalize 会静默丢弃该字段的全部值——必须先用 pd.json_normalize(..., max_level=1) 查看原始结构，再决定展开策略。