相比手工编写递归函数，使用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) 查看原始结构，再决定展开策略。
