pandas.json_normalize() 是首选，因为它专为嵌套JSON设计，能递归展平、处理数组、避免类型错误和结构丢失，而pd.DataFrame()直接构造会保留dict/list导致失效。
为什么 pandas.json_normalize() 是首选，而不是 pd.DataFrame() 直接构造
直接用 pd.DataFrame() 处理嵌套 JSON 会失败或丢失结构——它只展开顶层键，对 list 或 dict 类型字段原样保留，导致列里塞满对象。而 pandas.json_normalize() 是专为嵌套 JSON 设计的展平工具，能递归提取、拼接路径、处理数组嵌套，且支持自定义前缀和元数据列。
常见错误现象：ValueError: arrays must all be same length（因某字段是长度不一的嵌套列表）、TypeError: unhashable type: 'dict'（DataFrame 尝试把 dict 当索引）、列值显示为 {'id': 1, 'name': 'a'} 而非展开字段。
- 若 JSON 中有同名但不同层级的字段（如外层
id和内层user.id），json_normalize()默认用点号分隔路径，避免冲突 - 遇到数组字段（如
"tags": ["x", "y"]），默认会展开成多行（一行一元素），需用record_path显式指定“主记录路径”来控制主体结构 -
sep参数可改分隔符（如设为'__'避免字段名含点号时解析歧义）
如何用 record_path 和 meta 处理“一对多”嵌套结构
典型场景：一个订单（order）含多个商品（items），想让每行对应一个商品，同时保留订单级信息（如 order_id, date）。这时不能只传整个 JSON 列表给 json_normalize()，必须分离“重复主体”和“元数据”。
示例输入：{"order_id": 1001, "date": "2024-01-01", "items": [{"sku": "A", "qty": 2}, {"sku": "B", "qty": 1}]}
立即学习“Python免费学习笔记（深入）”；
-
record_path=['items']：告诉函数真正要展开的记录在items数组里 -
meta=['order_id', 'date']：将这两个字段作为每条 item 行的附加列带入 -
meta也支持嵌套路径，如['customer.name', 'customer.email']，自动按点号取值 - 若
meta字段在某些记录中缺失，对应行该列会是NaN，不会报错
遇到混合类型字段（如 null、str、dict）时如何避免 TypeError
json_normalize() 在展平时默认要求同一路径下所有值类型一致。若某字段有时是字符串、有时是对象（如 "profile": {"age": 30}，另一处是 "profile": null 或 "profile": "N/A"），会抛出 TypeError: unhashable type: 'dict' 或类型推断失败。
- 预处理：用
pd.json_normalize()前先统一字段类型，例如对疑似混合字段做lambda x: x if isinstance(x, dict) else {"raw": str(x)} - 启用
errors='ignore'（仅限meta字段）可跳过无法解析的meta路径，但不解决 record 层问题 - 更稳妥的做法是用
max_level限制展开深度，避开可疑嵌套层，再手动处理剩余字段 - Python 3.9+ 可配合
typing.Union注解做静态检查，但运行时不生效，仅辅助开发
性能提示：大文件别一次性 json_normalize()，先切片再合并
当 JSON 数据超过几万条且嵌套深（如日志、API 响应流），json_normalize() 内部递归解析开销明显，内存占用陡增，甚至 OOM。
- 拆解策略：用
json.load()分块读取（如每次 1000 条），逐批调用json_normalize()，再用pd.concat(..., ignore_index=True)合并 - 避免重复计算：若多次调用且参数不变，把
sep、max_level等固定参数提出来，减少函数内部判断 - 注意
record_path指向的数组若为空列表[]，该条记录会被完全丢弃——如果业务需要保留空记录，得先补默认值
嵌套越深、字段类型越杂、数组长度差异越大，json_normalize() 的行为就越依赖你对数据实际结构的理解，而不是函数文档里的理想情况。
