Python将嵌套字典或JSON数据展平后导入CSV文件

林见深
林见深
发布时间:2026-11-18 | 5人浏览过
原创

详细讲解如何使用Python内置模块与pandas将多层嵌套的字典或JSON数据展平成扁平结构,并规范导出为CSV文件的具体步骤与避坑指南。

将多层嵌套的字典或 JSON 数据导出为二维 CSV 文件,核心任务是确定“键名拼接规则”与“记录拆分维度”,将纵向延伸的树状层级压缩为横向扩展的列。本文通过纯 Python 原生递归与 pandas.json_normalize 两种方案,讲解单条与列表嵌套数据的展平逻辑、处理边界,并最终生成格式合规的 CSV 文件。

1. 树状层级与二维表格的结构冲突

假设你从某个第三方接口调用用户详情,返回了如下包含地址信息与多级配置的典型嵌套结构:

{
  "user_id": 1001,
  "profile": {
    "name": "张伟",
    "contact": {
      "email": "zhangwei@example.com",
      "phone": "13800000000"
    }
  },
  "roles": ["developer", "admin"]
}

CSV 本质上是由固定的行和列构成的二维文本格式,每个单元格仅能承载原子化的标量数据(如字符串、数字)。一旦遇到内嵌的子字典,表格无法在同一个单元格中直接表现从属结构;而遇到数组列表时,又面临“是将多个元素拼成一个字段,还是分裂成多行展示”的决策抉择。如果直接强行把子字典写入 CSV,通常只能得到类似 "{'name': '张伟'}" 这样的无序字符串,丢失了结构化查询与统计价值。

Python将嵌套字典或JSON数据展平后导入CSV文件
图 1:嵌套键名通过分隔符合并为单层列名的数据流向

2. 方法一:使用 Python 原生内置模块进行递归展平

如果项目环境受到限制,不能安装第三方科学计算库,使用标准库中的 csv 配合自定义递归函数是兼顾轻量与灵活的解决方案。处理的思路是:遍历字典的所有键值对,若值依然是字典,则带上前缀继续向下递归,直到抵达基本数据类型。

2.1 递归函数实现

下面的 flatten_dict 函数能够以点号 . 作为连接符,将任意深度的嵌套字典压缩为一维结构:

def flatten_dict(nested_dict, parent_key='', sep='.'):
    """
    将多层嵌套字典递归转换为一维平铺字典。
    :param nested_dict: 待展平的字典对象
    :param parent_key: 上一层级的键前缀
    :param sep: 键名层级之间的连接符
    :return: 扁平化后的一维字典
    """
    items = []
    for k, v in nested_dict.items():
        new_key = f"{parent_key}{sep}{k}" if parent_key else str(k)
        if isinstance(v, dict):
            # 遇到字典类型,继续向下递归展平
            items.extend(flatten_dict(v, new_key, sep=sep).items())
        elif isinstance(v, list):
            # 遇到简单列表类型,转为以逗号分隔的字符串以保留单行结构
            # 若列表内部包含子字典,需配合拆行逻辑处理(参见第 4 节)
            items.append((new_key, ", ".join(map(str, v))))
        else:
            # 基础标量值直接保留
            items.append((new_key, v))
    return dict(items)

2.2 收集字段名并批量写入 CSV

在实际业务中,由于不同记录所拥有的属性可能存在差异(部分嵌套字段在某些数据项中缺失),直接写入会导致列名错位。必须先汇总所有记录展开后的完整键集合,再使用 csv.DictWriter 统一写入:

import csv

records = [
    {
        "id": 1,
        "name": "李强",
        "info": {"age": 28, "city": "北京"}
    },
    {
        "id": 2,
        "name": "王芳",
        "info": {"age": 32, "city": "上海", "education": "硕士"}
    }
]

# 1. 展平全部数据
flattened_records = [flatten_dict(item) for item in records]

# 2. 收集所有出现过的字段名作为表头
headers = set()
for r in flattened_records:
    headers.update(r.keys())
fieldnames = sorted(list(headers))

# 3. 写入 CSV 文件
with open('output_native.csv', mode='w', encoding='utf-8-sig', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=fieldnames)
    writer.writeheader()
    for row in flattened_records:
        writer.writerow(row)
参数提示:在 Windows 平台使用 Excel 打开 CSV 文件时,若包含中文,推荐指定 encoding='utf-8-sig',这样 Python 会在文件开头写入 BOM 头,防止 Excel 自动按 ANSI 编码解析导致中文乱码。同时必须指定 newline='',避免在 Windows 环境下出现空行。

3. 方法二:使用 pandas 库快速完成解析与导出

在安装了数据分析生态的环境中,pandas.json_normalize 是处理嵌套结构的标准工具。该函数内部深度优化了路径解析机制,能够一行代码将复杂 JSON 数组转换为 DataFrame,再通过 to_csv() 完成输出。

Python将嵌套字典或JSON数据展平后导入CSV文件
图 2:使用 pandas 处理从 JSON 文件到 CSV 文件的流水线步骤

3.1 标准操作代码

import json
import pandas as pd

# 模拟从文件加载复杂 JSON 数据
raw_json = '''
[
  {
    "order_id": "ORD-2026-001",
    "customer": {
      "name": "陈敏",
      "address": {
        "province": "浙江",
        "city": "杭州"
      }
    },
    "payment": {
      "status": "PAID",
      "amount": 299.5
    }
  },
  {
    "order_id": "ORD-2026-002",
    "customer": {
      "name": "刘洋",
      "address": {
        "province": "广东",
        "city": "深圳"
      }
    },
    "payment": {
      "status": "UNPAID",
      "amount": 128.0
    }
  }
]
'''

data = json.loads(raw_json)

# 使用 json_normalize 展平,并通过 sep 指定列名连接符
df = pd.json_normalize(data, sep='_')

# 导出为 CSV 文件
df.to_csv('orders_flattened.csv', index=False, encoding='utf-8-sig')

# 输出清洗后的结果查看
print(df.columns.tolist())
# 输出示例: ['order_id', 'customer_name', 'customer_address_province', 'customer_address_city', 'payment_status', 'payment_amount']

在执行上述代码后,生成的 orders_flattened.csv 内容呈现标准规则矩阵,嵌套对象的所有叶子节点均升维成为第一层列,可以直接供数据库入库工具或电子表格调用。

4. 进阶场景:当嵌套结构中包含列表(一对多)

最棘手的嵌套情况并非字典套字典,而是对象中包含了数组列表,例如“一位客户拥有多张信用卡”或“一个订单包含多个商品明细”。在关系型建模中,这属于一对多(1:N)关联。

Python将嵌套字典或JSON数据展平后导入CSV文件
图 3:包含嵌套列表时,聚合模式与纵向拆分模式的结构差异

如果业务场景需要将列表拆解成多行呈现,可以利用 json_normalize 的 record_path 和 meta 参数:

order_payload = [
    {
        "order_id": "ORD-001",
        "store": "旗舰店",
        "items": [
            {"sku": "SKU-A", "qty": 2, "price": 50},
            {"sku": "SKU-B", "qty": 1, "price": 100}
        ]
    }
]

# record_path 指定需要拆开为行的列表键名
# meta 指定在每一行中需要继承保留的顶层公共字段
df_exploded = pd.json_normalize(
    order_payload,
    record_path=['items'],
    meta=['order_id', 'store'],
    meta_prefix='meta_'
)

df_exploded.to_csv('items_exploded.csv', index=False, encoding='utf-8-sig')

导出生成的 CSV 数据结构如下所示:

sku qty price meta_order_id meta_store
SKU-A 2 50 ORD-001 旗舰店
SKU-B 1 100 ORD-001 旗舰店

5. 两种方案选型与技术总结

在面对不同体量与复杂度的数据时,应根据部署依赖、内存表现和结构复杂度选择合适的实现方案:

Python将嵌套字典或JSON数据展平后导入CSV文件
图 4:原生实现与 pandas 工具箱的核心属性与决策边界对比

6. 常见问题排查与注意事项

  • 特殊字符与逗号截断:如果展平后的字段值中包含换行符(\n)或半角英文逗号(,),会导致某些简陋解析器串行。Python 内置的 csv.writer 与 pandas 会默认在包含特殊字符的字符串两侧包裹双引号。在读取导出的 CSV 时,务必通过标准的 CSV 引擎加载,避免使用纯文本按逗号切分(split(','))。
  • 层级过深时的栈溢出风险:默认情况下 Python 的最大递归深度为 1000。如果 JSON 嵌套异常深(例如极深递归生成树),可使用基于显式栈循环的迭代法替换函数递归,或适度调整 sys.setrecursionlimit()。
  • 分隔符冲突:如果原始字段名本身就包含点号(如 "v1.0": {"status": "ok"}),使用默认的 sep='.' 会导致还原与解析时的歧义。此时建议改用双下划线 sep='__' 作为路径连接符。
相关专题:

本站声明

本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。

Python 相关产品和应用

全部下载

专题列表