Python yield 压平嵌套字典：递归生成器实现与内存优化

简介：这是一份面向Python初学者与数据处理开发者的技术文档，聚焦如何用yield关键字优雅地压平嵌套字典，解决字典套字典结构难以直接遍历和取值的问题。资源以单个PDF文件交付，压缩包约174KB，内容围绕生成器与递归思路展开，从最内层键值对逐层向外拼接路径，最终得到形如b_e_f的扁平键名。文档给出了8行核心实现代码，并说明yield如何保持函数状态、按需生成结果，从而避免一次性加载全部数据，兼顾内存效率与代码可读性。读者可从中掌握生成器在复杂数据结构处理中的实际用法，理解递归与yield结合的组装逻辑，并可将该方法迁移到字典与列表混合嵌套等场景。目前已有769人学习，适合希望提升Python函数式编程与数据扁平化处理能力的读者参考。

1. 用 yield 压平嵌套字典：一个被低估的递归写法

上周帮同事排查一个数据清洗脚本的内存问题，发现他把三层嵌套的配置字典展开成扁平结构时，用了五层 for 循环加临时列表，结果处理一个 20MB 的 JSON 配置直接吃掉 1.2GB 内存。其实这种场景用 Python 的yield写递归生成器，代码量能砍掉三分之二，内存占用也降一个数量级。yield压平嵌套字典不是什么新技巧，但很多写了几年 Python 的人还是习惯用列表累加，原因无非是递归加生成器的组合看起来有点绕。这篇就把这个方法的原理、写法、参数边界和实际踩过的坑一次讲清楚，适合手头有嵌套配置、日志结构或 API 返回数据需要扁平化的后端和数据处理方向的人。

2. yield 压平嵌套字典的原理与最小实现

2.1 为什么用生成器而不是列表

先看一个典型的嵌套字典结构，这种格式在配置文件、前端表单数据、NoSQL 文档里非常常见：

nested = { "user": { "name": "A同学", "contact": { "email": "a@example.com", "phone": "13800000000" } }, "order": { "id": 1001, "items": { "book": {"price": 45, "qty": 2}, "pen": {"price": 3, "qty": 10} } } }

如果要把这棵树压成{"user.name": "A同学", "user.contact.email": "a@example.com", ...}这种扁平键值对，用列表累加的做法通常是写一个递归函数，每层把结果extend进一个列表。问题在于：列表必须一次性把所有结果装进内存，嵌套层级越深、叶子越多，峰值内存越高。而生成器是惰性的，调用方for循环取一个才产出一个，中间不保存完整结果集。

另一个容易被忽略的点是组合性。生成器可以被itertools.chain、islice、groupby直接接住，列表不行。比如你只想取前 100 个扁平键值对做抽样检查，生成器方案天然支持，列表方案得先全量展开再切片。

2.2 递归生成器的最小代码

核心实现其实不到 15 行：

def flatten_dict(d, parent_key="", sep="."): """ 递归压平嵌套字典，产出 (flat_key, value) 元组。 d: 待压平的字典 parent_key: 上层累积的键前缀，递归时传入 sep: 扁平键的连接符，默认点号 """ for key, value in d.items(): # 拼接当前层级的完整键名 new_key = f"{parent_key}{sep}{key}" if parent_key else key if isinstance(value, dict): # 遇到子字典就递归，用 yield from 把下层产出透传上来 yield from flatten_dict(value, new_key, sep=sep) else: # 叶子节点直接产出元组 yield new_key, value

调用方式：

for k, v in flatten_dict(nested): print(k, "=>", v)

输出：

user.name => A同学 user.contact.email => a@example.com user.contact.phone => 13800000000 order.id => 1001 order.items.book.price => 45 order.items.book.qty => 2 order.items.pen.price => 3 order.items.pen.qty => 10

这里的关键是yield from。Python 3.3 引入的yield from会把子生成器的产出逐个透传给外层调用者，不需要手动写for item in flatten_dict(...): yield item。少了这层手动循环，递归深度大时栈帧也少一层。

2.3 参数说明与返回值约定

parent_key默认空字符串，这是递归的起点标记。判断if parent_key而不是if parent_key is not None，是因为空字符串在布尔上下文里为假，逻辑上更简洁。但要注意：如果字典的键本身可能是空字符串，这个判断会出问题。实际项目里我一般改成if parent_key != ""或者干脆用一个哨兵对象，避免键名为空时的歧义。

sep参数控制连接符。默认点号适合大多数配置场景，但如果键名里本身含点号（比如"user.name"作为一个完整键），压平后会产生歧义。这种情况建议换成"/"或"__"，或者干脆返回元组形式的路径("user", "name")而不是拼接字符串。

返回值约定为(flat_key, value)元组而不是直接yield value，是因为压平后的键名才是调用方真正需要的索引。如果只关心值，调用方可以自己for _, v in flatten_dict(...)忽略键。

3. 处理列表嵌套与自定义分隔符的进阶写法

3.1 字典里嵌列表怎么办

真实数据里，字典和列表经常混在一起。比如订单的items可能是一个列表而不是字典：

nested_with_list = { "order": { "id": 1001, "items": [ {"name": "book", "price": 45}, {"name": "pen", "price": 3} ] } }

上面的最小实现遇到列表会直接当叶子节点产出，结果是order.items => [{'name': 'book', ...}]，没有真正压平。要处理列表，需要加一个分支，用索引作为键的一部分：

def flatten_dict_list(d, parent_key="", sep="."): """ 同时处理嵌套字典和列表的压平生成器。 列表元素用 [i] 形式拼进键名。 """ if isinstance(d, dict): for key, value in d.items(): new_key = f"{parent_key}{sep}{key}" if parent_key else key yield from flatten_dict_list(value, new_key, sep=sep) elif isinstance(d, list): for idx, item in enumerate(d): # 列表索引用方括号包裹，和字典键区分开 new_key = f"{parent_key}[{idx}]" yield from flatten_dict_list(item, new_key, sep=sep) else: # 叶子节点：此时 parent_key 就是完整路径 yield parent_key, d

调用后输出：

order.id => 1001 order.items[0].name => book order.items[0].price => 45 order.items[1].name => pen order.items[1].price => 3

注意这里把isinstance判断从「值是不是字典」改成了「当前对象是不是字典或列表」，递归入口也变了。这种写法的好处是统一了处理逻辑，字典和列表走同一套递归框架。代价是每次递归都要做类型判断，深层嵌套时性能略低于纯字典版本。实测在 10 万叶子节点规模下，差异在 15% 左右，一般场景可以忽略。

3.2 自定义分隔符与键名冲突处理

分隔符的选择有个血泪经验：如果扁平化后的键要作为数据库列名或 CSV 表头，点号在很多 SQL 方言里是保留字符，会引发语法错误。我一般会根据下游消费方来定：

如果键名本身可能包含分隔符，最稳妥的做法是压平后返回路径元组，让调用方自己决定怎么拼接：

def flatten_dict_tuple(d, parent_path=()): """产出 (path_tuple, value)，路径以元组形式返回，避免分隔符歧义。""" for key, value in d.items(): current_path = parent_path + (key,) if isinstance(value, dict): yield from flatten_dict_tuple(value, current_path) else: yield current_path, value

这样("user", "contact", "email")作为路径是明确的，调用方要拼成字符串时自己选分隔符，要查数据库时直接映射到多级索引。

3.3 与 json 模块配合的完整流程

实际工作中，嵌套字典往往来自 JSON 文件或 API 响应。一个完整的处理链路是：读 JSON → 压平 → 写入 CSV 或数据库。下面是一个可复现的脚本：

import json import csv def flatten_dict(d, parent_key="", sep="."): for key, value in d.items(): new_key = f"{parent_key}{sep}{key}" if parent_key else key if isinstance(value, dict): yield from flatten_dict(value, new_key, sep=sep) else: yield new_key, value # 模拟从文件读取嵌套 JSON with open("config.json", "r", encoding="utf-8") as f: data = json.load(f) # 流式写入 CSV，不需要先把所有扁平结果存进列表 with open("flat.csv", "w", newline="", encoding="utf-8") as f: writer = csv.writer(f) writer.writerow(["key", "value"]) for k, v in flatten_dict(data): writer.writerow([k, v])

这个脚本的关键在于：flatten_dict是生成器，for循环每取一个才写一行，内存里始终只有当前这一个键值对。处理几百 MB 的 JSON 时，内存占用基本等于json.load本身的开销，不会因为压平再翻倍。

提示：如果 JSON 文件大到json.load都吃不下，需要换成ijson之类的流式解析库，但那是另一个话题了。本文的生成器方案解决的是「字典已经在内存里，压平过程不要再复制一份」的问题。

4. 避坑与排查：yield 压平字典的五个翻车现场

4.1 递归深度超限：RecursionError

现象：处理一个层级特别深的嵌套字典时，抛出RecursionError: maximum recursion depth exceeded。

原因：Python 默认递归深度限制是 1000 层。虽然大多数业务数据的嵌套不会超过 10 层，但有些自动生成的配置或恶意构造的数据可能嵌套几百层。每层递归都会消耗一个栈帧，生成器递归也不例外。

解决：两种方案。一是用sys.setrecursionlimit调高限制，但这治标不治本，栈溢出风险仍在。二是改成显式栈的迭代版本：

def flatten_dict_iterative(d, sep="."): """用显式栈代替递归，避免 RecursionError。""" stack = [("", d)] while stack: parent_key, current = stack.pop() for key, value in current.items(): new_key = f"{parent_key}{sep}{key}" if parent_key else key if isinstance(value, dict): stack.append((new_key, value)) else: yield new_key, value

迭代版本用列表当栈，先入后出，产出顺序和递归版本略有不同（深度优先但兄弟节点顺序反转），如果对顺序有要求，把stack.pop()改成stack.pop(0)并配合append就是广度优先，但性能会差一些。

4.2 键名含分隔符导致路径歧义

现象：压平后出现两个不同的原始路径映射到同一个扁平键。

原因：原始字典里既有{"a": {"b": 1}}又有{"a.b": 2}，用点号作分隔符时，两者都产出"a.b"。

解决：压平前先扫描一遍所有键名，如果发现键名包含分隔符，要么换分隔符，要么在键名里对分隔符做转义。我一般会在函数入口加一个可选的escape参数，默认不转义，调用方明确知道数据干净时才用点号。

4.3 生成器只能消费一次

现象：对同一个生成器对象调用了两次for循环，第二次什么都没输出。

原因：生成器是惰性的、一次性的。第一次迭代耗尽后，生成器就空了，不会重置。

解决：如果需要多次遍历，要么每次重新调用flatten_dict(data)生成新的生成器，要么在调用方用list(flatten_dict(data))物化一次再复用。后者会失去内存优势，所以只在确实需要多次遍历且数据量不大时用。

4.4 修改原始字典导致意外结果

现象：压平过程中另一个线程修改了原始字典，产出结果不一致或抛RuntimeError: dictionary changed size during iteration。

原因：生成器是惰性的，迭代过程中原始字典被改动，d.items()视图会受影响。

解决：压平前对字典做一次浅拷贝，或者约定压平期间原始数据只读。多线程场景下更稳妥的做法是先json.loads(json.dumps(data))深拷贝一份再压平，代价是内存翻倍，但避免了并发修改的玄学问题。

4.5 空字典和 None 值的处理

现象：嵌套字典里某个值是空字典{}或None，压平后这个键直接消失了。

原因：空字典进入递归分支后for循环一次都不执行，自然没有产出。None值虽然走叶子分支，但如果调用方过滤了None也会丢。

解决：如果业务上需要保留空字典的路径，在递归前加一个判断：

if isinstance(value, dict): if not value: # 空字典也产出一个标记值，保留路径信息 yield new_key, {} else: yield from flatten_dict(value, new_key, sep=sep)

None值同理，取决于下游是否需要区分「键不存在」和「键存在但值为 None」。这个决策没有标准答案，取决于具体业务语义。

5. 性能验证与一个我常用的调试技巧

生成器方案到底比列表方案省多少内存，空口说没意义，直接测。用tracemalloc对比两种实现处理同一份嵌套数据的峰值内存：

import tracemalloc import sys # 构造一个三层嵌套、约 10 万叶子节点的字典 def build_nested(depth=3, breadth=10): if depth == 0: return {f"leaf_{i}": i for i in range(breadth)} return {f"level_{depth}_{i}": build_nested(depth - 1, breadth) for i in range(breadth)} data = build_nested(depth=3, breadth=10) # 列表方案 def flatten_list(d, parent_key="", sep="."): result = [] for key, value in d.items(): new_key = f"{parent_key}{sep}{key}" if parent_key else key if isinstance(value, dict): result.extend(flatten_list(value, new_key, sep=sep)) else: result.append((new_key, value)) return result tracemalloc.start() flat_list = flatten_list(data) current, peak_list = tracemalloc.get_traced_memory() tracemalloc.stop() print(f"列表方案峰值内存: {peak_list / 1024 / 1024:.2f} MB") # 生成器方案 tracemalloc.start() count = sum(1 for _ in flatten_dict(data)) current, peak_gen = tracemalloc.get_traced_memory() tracemalloc.stop() print(f"生成器方案峰值内存: {peak_gen / 1024 / 1024:.2f} MB")

实测数据因机器和 Python 版本而异，但趋势是明确的：列表方案的峰值内存约等于所有叶子节点键值对的总大小，生成器方案只等于单次产出的开销加上递归栈。在 10 万叶子节点规模下，差距通常在 20 到 50 倍之间。

调试生成器时有个小技巧：生成器对象不直接显示内容，print(flatten_dict(data))只会输出<generator object ...>。我习惯用itertools.islice取前几个值快速验证：

from itertools import islice # 只看前 5 个产出，确认键名拼接逻辑正确 for k, v in islice(flatten_dict(data), 5): print(k, "=>", v)

这样不用等全量展开就能判断递归逻辑对不对。从那以后我每次写完递归生成器，都先用islice抽前几个值确认路径拼接和叶子判断没问题，再跑全量。这个习惯帮我省了不少回头排查的时间。希望帮到你。

本文还有配套的精品资源，点击获取