在日常的数据处理工作中，你是否曾经面对过层级极深、结构复杂的 JSON 数据，感到一头雾水？特别是在 2026 年，随着大模型（LLM）应用的爆发，我们经常需要将非结构化的 JSON 输入转化为向量数据库能够理解的扁平化键值对。当我们只需要某些特定字段用于分析或存储时，这种嵌套结构往往会增加处理的复杂度。在这篇文章中，我们将深入探讨一种非常实用的技术——JSON 扁平化。
我们将一起探索什么是 JSON 扁平化，为什么它在数据处理流程中至关重要，以及最重要的——我们如何用不同的方法在 Python 中实现这一过程。无论你是喜欢使用原生代码构建工具，还是倾向于利用强大的第三方库，本文都将为你提供详尽的指南和实战技巧。此外，我们还将结合 2026 年的最新技术栈，探讨 AI 辅助编程下的最佳实践。
什么是 JSON 扁平化？
首先，让我们快速回顾一下基础。JSON（JavaScript Object Notation）是一种轻量级的数据交换格式。在 Python 中，JSON 对象通常表现为字典或列表的嵌套组合，或者是嵌套了列表的字典。
所谓的“扁平化”，简单来说，就是把这种复杂的嵌套结构“压平”。 我们的目标是将一个多层的嵌套对象转换为一个单层的键值对集合。在这个过程中，原本嵌套的键路径会被合并成一个单一的键，通常使用下划线（INLINECODE12d6f46e或点INLINECODEd9a2957b）作为连接符。
让我们来看一个直观的例子：
假设我们有一个包含用户信息的嵌套 JSON 对象，如下所示：
# 未扁平化的 JSON (嵌套结构)
nested_json = {
‘user‘: {
‘Rachel‘: {
‘UserID‘: 1717171717,
‘Email‘: ‘[email protected]‘,
‘friends‘: [‘John‘, ‘Jeremy‘, ‘Emily‘]
}
}
}
如果不进行扁平化，要获取 INLINECODEa4f93534，我们需要编写 INLINECODE6f86c74c。虽然这在 Python 中很简单，但在数据分析或特定存储场景下可能不够方便。
当我们对其进行扁平化处理后，它将变成这样：
# 扁平化后的 JSON
flattened_json = {
‘user_Rachel_UserID‘: 1717171717,
‘user_Rachel_Email‘: ‘[email protected]‘,
‘user_Rachel_friends_0‘: ‘John‘,
‘user_Rachel_friends_1‘: ‘Jeremy‘,
‘user_Rachel_friends_2‘: ‘Emily‘
}
看到区别了吗？所有的层级关系都体现在了键名上，数据结构变得更加线性，更容易进行遍历和查询。
为什么我们需要扁平化 JSON？
你可能会问，为什么要改变原有的数据结构？实际上，扁平化在以下几个场景中非常有用：
- 数据分析的福音：如果你使用过 Pandas 或 Excel，你会发现它们非常适合处理二维表格数据。扁平化的 JSON 可以直接转换为 DataFrame，每一列代表一个属性（如
user_Rachel_Email），每一行代表一条记录。 - 提高可读性：对于非开发人员或者刚刚接触代码的人来说，看到一个只有一层深度的字典比看到好几层缩进要容易理解得多。
- 特定存储格式与 AI 预处理：某些 NoSQL 数据库或搜索引擎（如 Elasticsearch）在索引数据时，扁平化的结构往往能提供更灵活的查询能力。更重要的是，在 2026 年，为了构建 RAG（检索增强生成）系统，我们通常需要将复杂的 JSON 文档扁平化后，通过 Embedding 模型转换为向量，以实现更精准的语义检索。
—
方法 1：使用递归函数手动实现
作为一名开发者，理解底层逻辑总是好的。我们先不依赖任何外部库，用 Python 原生的递归方法来实现一个扁平化函数。这种方法虽然代码量稍多，但它能让我们完全掌控数据的转换逻辑，并且不需要安装任何额外的包。
#### 代码实现与原理解析
让我们编写一个名为 flatten_json 的函数。这个函数的核心思想是遍历原始字典，检查每个值是字典还是列表，然后递归地处理它们，直到找到最基本的值类型（如字符串、数字）。
# 定义我们的扁平化函数
def flatten_json(nested_dict, parent_key=‘‘, sep=‘_‘):
"""
将嵌套的字典扁平化为单层字典。
这是一个纯 Python 实现，无需第三方库，便于调试和定制。
参数:
nested_dict: 要扁平化的嵌套字典。
parent_key: 父级的键名，用于递归时拼接。
sep: 连接键名的分隔符，默认为下划线。
返回:
一个扁平化的字典。
"""
items = [] # 用于存储最终结果的元组列表
for k, v in nested_dict.items():
# 构造新的键名：父级键名 + 分隔符 + 当前键名
new_key = f"{parent_key}{sep}{k}" if parent_key else k
# 如果当前值是字典，我们需要递归处理
if isinstance(v, dict):
items.extend(flatten_json(v, new_key, sep=sep).items())
# 如果当前值是列表，我们需要遍历列表元素
# 并给每个元素加上索引作为键名的一部分
elif isinstance(v, list):
for i, item in enumerate(v):
# 为列表项创建带索引的键名
list_key = f"{new_key}{sep}{i}"
# 如果列表项本身还是字典或列表，继续递归
if isinstance(item, (dict, list)):
items.extend(flatten_json(item, list_key, sep=sep).items())
else:
items.append((list_key, item))
else:
# 如果是基础类型，直接添加到结果中
items.append((new_key, v))
return dict(items)
# 让我们测试一下这个函数
# 我们准备了一个稍微复杂一点的嵌套数据
unflat_json = {
‘user‘: {
‘Rachel‘: {
‘UserID‘: 1717171717,
‘Email‘: ‘[email protected]‘,
‘friends‘: [‘John‘, ‘Jeremy‘, ‘Emily‘]
}
},
‘status‘: ‘active‘
}
print("--- 原始嵌套 JSON ---")
print(unflat_json)
# 调用函数进行扁平化
flat_result = flatten_json(unflat_json)
print("
--- 扁平化后的结果 ---")
print(flat_result)
#### 代码深度解析
在上述代码中，你可能注意到了几个关键点：
- INLINECODE396d4c6d 参数：这是递归的核心。当我们深入到嵌套层级时，我们需要记住“我们从哪里来”。例如，处理 INLINECODE305ec331 时，INLINECODEce739098 可能是 INLINECODE2efd672b，最后拼接成
user_Rachel_Email。 - 列表的处理：这是扁平化中最棘手的部分。JSON 中的列表通常代表数据集合。在扁平化时，我们无法直接把列表 INLINECODE5d237f0a 存为一个键。因此，我们使用了索引 INLINECODE8e86babf 将其拆分。比如 INLINECODE9e06d87e 列表变成了 INLINECODEecb8200f,
friends_1等。这确保了每一个数据点都有唯一的键名。 - 灵活性：我们添加了 INLINECODE8e4df54c 参数，这样你就可以自由决定使用下划线（INLINECODE396876f9）还是点（
.）或者其他字符来连接键。
输出结果：
{‘user_Rachel_UserID‘: 1717171717, ‘user_Rachel_Email‘: ‘[email protected]‘, ‘user_Rachel_friends_0‘: ‘John‘, ‘user_Rachel_friends_1‘: ‘Jeremy‘, ‘user_Rachel_friends_2‘: ‘Emily‘, ‘status‘: ‘active‘}
这个方法的优点是零依赖，完全可控。缺点是如果你需要处理极其庞大的 JSON 文件，Python 的递归深度可能会受到限制（默认通常限制在 1000 层），尽管在一般的数据处理中很少遇到这么深的结构。
方法 2：使用 flatten_json 库
虽然手写代码能锻炼我们的编程能力，但在实际的生产环境中，复用经过验证的轮子通常是更好的选择。flatten_json 是一个专门为此目的设计的 Python 库，它封装了上述所有的逻辑，使用起来更加简洁，并且处理各种边界情况（比如特殊字符转义）也更加稳健。
#### 安装
首先，我们需要通过 pip 安装这个库。打开你的终端或命令行，运行以下命令：
pip install flatten_json
#### 实战示例
安装完成后，我们就可以直接导入并使用了。让我们看看它有多简单。
from flatten_json import flatten
# 我们定义一个稍微更复杂的数据，包含更多层级的嵌套
data = {
‘user‘: {
‘Rachel‘: {
‘UserID‘: 1717171717,
‘Email‘: ‘[email protected]‘,
‘address‘: {
‘city‘: ‘New York‘,
‘zip‘: ‘10001‘
},
‘friends‘: [‘John‘, ‘Jeremy‘, ‘Emily‘]
}
},
‘app_settings‘: {
‘theme‘: ‘dark‘,
‘notifications‘: True
}
}
# 使用库提供的 flatten 函数
# 可以自定义分隔符，这里我们尝试用 ‘.‘
flat_dictionary = flatten(data, sep=‘.‘)
print("--- 使用库扁平化后的结果 (以点为分隔符) ---")
for key, value in flat_dictionary.items():
print(f"{key}: {value}")
为什么推荐使用库？
- 简洁性：正如上面的例子所示，一行代码即可完成工作，减少了出错的可能性。
- 高级功能：
flatten_json库还提供了反扁平化的功能，这在需要数据还原的场景下非常有用。
2026年进阶视角：Pandas 与大数据处理
既然我们已经掌握了基础，让我们进入 2026 年开发者的实战思维。在现代数据栈中，我们很少仅仅为了“扁平化”而扁平化，通常是为了后续的分析或机器学习做准备。
#### 为什么 Pandas 依然不可或缺？
你可能会问，现在不是都在用 Polars 或 DuckDB 吗？没错，但 Pandas 依然是数据科学领域的通用语言。更重要的是，Pandas 提供的 json_normalize 是处理半结构化数据的神器，它比简单的扁平化更智能。
让我们思考一下这个场景： 你有一个包含用户元数据的列表，你需要将其分析出每个用户的地理位置分布。
import pandas as pd
# 模拟 API 返回的复杂嵌套数据
api_response = [
{
‘id‘: 101,
‘name‘: ‘Product A‘,
‘details‘: {
‘price‘: 99.99,
‘stock‘: 20,
‘meta‘: {‘rating‘: 4.5, ‘reviews‘: 120}
}
},
{
‘id‘: 102,
‘name‘: ‘Product B‘,
‘details‘: {
‘price‘: 49.50,
‘stock‘: 150,
‘meta‘: {‘rating‘: 4.8, ‘reviews‘: 340}
}
}
]
# 使用 Pandas 的 json_normalize 进行高级扁平化
# 它可以自动处理列表和深层嵌套字典
df = pd.json_normalize(api_response)
print("--- 使用 Pandas json_normalize 转换后的 DataFrame ---")
print(df)
# 现在我们可以直接操作列，例如筛选评分高于 4.5 的产品
high_rating = df[df[‘details.meta.rating‘] > 4.5]
print("
--- 高评分产品 ---")
print(high_rating[[‘name‘, ‘details.meta.rating‘]])
我们的经验建议： 在 2026 年，如果你的数据量超过 1GB，请考虑直接使用 Polars。Polars 在处理 JSON 数据时拥有更好的内存管理和懒惰求债特性，且 API 风格在现代 IDE 中具有更好的类型提示支持。
现代开发工作流：AI 辅助与性能优化
在我们的团队中，处理 JSON 数据通常不是孤立的任务，而是整个数据管道的一部分。我们最近在一个项目中遇到了一个挑战：需要处理高达 5GB 的单行 JSON 日志文件。使用传统的递归方法直接导致了内存溢出（OOM）。
#### 1. AI 辅助编程
如果你正在使用 Cursor 或 GitHub Copilot，你可以这样输入你的需求：
> "Create a Python generator to flatten a deeply nested JSON object without loading the entire file into memory, using the ijson library for streaming."
AI 会不仅生成代码，还会解释如何使用 ijson.items 来流式解析文件。这就是我们所说的 Vibe Coding（氛围编程）——你负责架构和逻辑，AI 负责实现细节。
#### 2. 流式处理：解决内存瓶颈
当你面对 2026 年常见的海量日志数据时，不要使用 INLINECODEdc88e8d5。你需要改用 流式解析。这是一个基于 INLINECODE0aef1d23 的生产级代码片段，我们用它来处理无法完全放入内存的文件：
import ijson
import sys
# 注意：这是一个简化的示例，展示流式处理的核心思想
# 假设我们有一个巨大的 JSON 文件 ‘huge_data.json‘
# 为了演示，我们假设文件结构为 {"users": [{...}, {...}, ...]}
def stream_flatten_json(filename):
"""
使用流式解析器逐项处理 JSON，避免内存溢出。
这是处理 TB 级日志文件的标准做法。
"""
with open(filename, ‘rb‘) as f:
# 这里的 ‘users.item‘ 指的是顶层 ‘users‘ 数组中的每一项
# ijson 会逐块解析，不会一次性加载整个文件
for user in ijson.items(f, ‘users.item‘):
# 在这里你可以调用之前的 flatten_json 函数
# 或者直接提取需要的字段
yield flatten_json(user)
# 模拟使用场景
# for flat_user in stream_flatten_json(‘huge_data.json‘):
# # 将数据写入数据库或进行实时分析
# process_record(flat_user)
常见陷阱与最佳实践
在我们多年的开发经验中，我们总结了一些容易踩的坑，特别是在生产环境中：
- 键名冲突：如果你有两个不同的路径，在扁平化后生成了相同的键名（例如 INLINECODEa51bbddc 和 INLINECODEa5654eae 都变成了
email），后者的值会覆盖前者。
解决办法*：确保你的递归逻辑正确拼接了父级键名，不要在递归深处丢失上下文。
- 性能陷阱：不要在循环中重复进行扁平化操作。如果可能，尽量使用向量化操作（如 Pandas）或 C 扩展库（如 Orjson）。
总结与后续步骤
在这篇文章中，我们深入探讨了扁平化 JSON 对象的多种方法：从手写递归算法到利用成熟的库，再到 2026 年流行的 Pandas 高级用法和流式处理。
回顾一下关键点：
- 扁平化将嵌套的键路径合并，并给列表元素加上索引，从而生成单层键值对。
- 它是数据分析、日志处理和数据清洗中的关键步骤。
- Python 提供了灵活的工具来处理这一过程，既可以是原生的递归函数，也可以是成熟的库。
- 面对大数据，请采用
ijson等流式处理方案，结合 AI 辅助工具提高开发效率。
你可以尝试的下一步：
- 实战演练：找一段你项目中的真实 JSON 数据（比如 Twitter API 或 GitHub API 的返回值），尝试用上面的代码将其扁平化。
- 探索 Polars：既然我们已经提到了 Pandas，为什么不试试
pl.read_json()？看看在处理大规模数据集时，它是否能给你带来惊喜。
希望这篇文章能帮助你更好地处理 Python 中的 JSON 数据！如果你在实践中有任何心得或疑问，欢迎继续探讨。