本文介绍一种通用、递归的 JSON 扁平化方法，可自动处理对象（dict）、数组（list）及深层嵌套结构，将嵌套路径转换为 parent_child_grandchild 形式的扁平键，并兼容单元素与多元素列表场景。
本文介绍一种通用、递归的 json 扁平化方法，可自动处理对象（dict）、数组（list）及深层嵌套结构，将嵌套路径转换为 `parent_child_grandchild` 形式的扁平键，并兼容单元素与多元素列表场景。
在实际数据处理中，尤其是对接 API 响应或日志 JSON 时，常遇到深度嵌套、混合包含字典与列表的结构。pandas.json_normalize() 虽强大，但默认仅展开一级嵌套，且对列表内多个字典的索引支持有限。要获得如 data_1_timestamp、device_model 这类语义清晰、全路径扁平化的字段名，需自定义递归扁平化逻辑。
以下是一个健壮、可扩展的 flatten_dict() 函数，支持三层核心类型：
- ✅ 标量值（str/int/float/bool/None）：直接映射为 prefix_key 键名；
- ✅ 嵌套字典（dict）：递归调用，前缀追加 key_；
- ✅ 列表（list）：对每个元素编号（1-indexed），若元素为字典则递归展开；若为标量则直接命名（如 tags_1, scores_2）。
def flatten_dict(d: dict, prefix: str = '') -> dict:
"""
递归扁平化嵌套字典（支持 list 和 dict 混合结构）
使用下划线连接路径，列表元素以 1-based 编号（如 'data_1_label'）
"""
result = {}
for key, value in d.items():
new_prefix = f"{prefix}{key}_" if prefix else f"{key}_"
if isinstance(value, dict) and value: # 非空字典 → 递归
result.update(flatten_dict(value, new_prefix))
elif isinstance(value, list):
for idx, item in enumerate(value, start=1):
if isinstance(item, dict) and item:
result.update(flatten_dict(item, f"{new_prefix}{idx}_"))
else: # 列表中的标量（如 ["a", "b"] 或 [42]）
result[f"{new_prefix}{idx}"] = item
else: # 标量值（str, int, float, bool, None）
result[f"{prefix}{key}"] = value
return result
使用示例（复现原始需求）：
import json
import pandas as pd
json_data = '''
{
"appVersion": "0.0.3",
"device": {
"model": "Lenovo"
},
"bef": {
"catalog": "Manual"
},
"data": [
{
"timestamp": "2024-04-24 12:08:02.415077",
"label": "zuf",
"category": "50"
}
]
}
'''
parsed = json.loads(json_data)
flattened = flatten_dict(parsed)
df = pd.DataFrame([flattened])
print(df)
输出：
appVersion device_model bef_catalog data_1_timestamp data_1_label data_1_category 0 0.0.3 Lenovo Manual 2024-04-24 12:08:02.415077 zuf 50
✅ 关键优势说明：
- 真正任意嵌套：函数无深度限制，可处理 a.b.c.d.e 多层嵌套；
- 列表友好：自动编号（_1, _2…），避免键名冲突；若确定列表恒为单元素，可简化为 item = value[0] if value else None 后直接递归；
- 生产就绪：显式处理空字典/空列表/None 值，避免 KeyError 或意外跳过；
- 无缝集成 Pandas：输出为标准 dict，一行 pd.DataFrame([flattened]) 即得目标 DataFrame。
⚠️ 注意事项：
- 若原始 JSON 中存在同名键（如不同层级均有 "id"），扁平后将被覆盖（后出现者胜）——这是扁平化的固有特性，必要时可在 new_prefix 中加入类型标识（如 f"{prefix}{key}_dict_"）；
- 对超大 JSON，递归深度可能触发 RecursionError，此时可改用栈式迭代实现（本文聚焦简洁性，未展开）；
- 时间戳等字符串若需后续解析，建议保留原格式，扁平化阶段不做类型转换。
总结：掌握 flatten_dict 这一模式，你将不再受限于 json_normalize 的预设规则，而是拥有了按需定制 JSON 展开逻辑的能力——无论数据来自 IoT 设备、微服务响应，还是复杂配置文件，都能一键转为分析友好的平面结构。
