戈玄白今天要做题在Python里写代码，几乎没人离得开字典。不管是缓存数据、解析JSON、维护配置，还是算法题里统计频率，dict都是很多场景下的首选。你有没有认真想过，一次 d[key] = value 的背后，Python到底做了什么？为什么字典的查找能如此之快，而有时候内存又大得离谱？这些都指向一个老朋友：哈希表。
这篇内容适合三类人：刚学完Python基础、想真正理解字典和集合底层原理的人；准备面试、需要把“平均O(1)”讲清楚的人；已经写过不少代码、但被可变对象做key、哈希冲突、进程间哈希不一致这类问题折腾过的人。我会结合CPython的源码逻辑、实际测试数据和一些踩坑经历，把哈希表这件事掰开揉碎讲明白。读完你不仅能搞懂dict和set的运行机制，还能写出更稳、更快的代码。
1. 哈希表凭什么让Python的字典查找快到离谱
1.1 一个基础问题：哈希表到底解决了什么痛点
先想一个最普通的场景：一个列表里存了一万个用户名，现在要判断某个用户名是否存在。最直接的办法是for循环遍历，逐个比较，这就是线性查找。运气好时第一个就命中，运气差时得走到最后，平均下来要比较五千次。随着数据量翻倍，比较次数也跟着翻倍，这就是O(n)的含义。
哈希表的思路完全不同。它不靠比较，靠的是“算出位置”。你可以把哈希表想象成一个巨大的储物柜，每个柜子都有编号。我们要存放一个东西时，先拿钥匙（key）算一个数字，再把这个数字映射成柜子编号，直接把东西放进去。取的时候同样用钥匙算一遍编号，直接打开柜子拿走东西。整个过程不依赖你有多少东西，也不依赖目标在柜子里的什么位置。
所以哈希表的核心价值就一句话：把查找问题变成“算位置”问题。在hash函数足够均匀的情况下，查找、插入、删除都能做到平均常数时间。这是链表、数组这些线性结构很难做到的。数组虽然能用下标直接访问，但下标和业务数据往往没有映射关系；链表更是只能从头往后找。哈希表相当于在“业务key”和“存储位置”之间架了一座桥。
1.2 三个核心构件：hash函数、数组、负载因子
哈希表不是只有一个数组那么简单，它的运作依赖三个构件。
第一是hash函数。它的职责是把任意类型的数据（字符串、元组、数字、自定义对象）转成一个固定范围内的整数。注意，这个整数通常很大，不能直接当数组下标用，所以后面还要做一次取模或者位运算，把它压缩到数组容量范围内。
第二是底层的数组。所有键值对最终都存在一个数组里，数组的每个槽位可能是一个键值对，也可能是空的，也可能被标记为“已删除”。hash函数算出的值经过映射后指向数组的某个下标，这就是所谓的“桶”（bucket）。
第三是负载因子。它等于“已存储元素个数 / 数组容量”。负载因子太低，空间浪费严重；太高，冲突概率急剧上升。不同语言的处理方式不同，Python的选择非常保守，而且这个数字直接决定了扩容时机。
这三个构件互相制约。hash函数设计得再好，如果负载因子控制不住，冲突也会把性能拖垮；负载因子控制得再好，如果hash函数把很多key映射到同一个桶，也是白搭。所以理解哈希表，不能只看其中一个环节。
1.3 哈希表在Python里远不止dict一个形态
很多人以为哈希表就是字典，其实Python里到处都是它的影子。
dict：最典型的哈希表实现，保存键值对。set和frozenset：可以理解为“只有键没有值”的哈希表，内部结构和dict高度重合。collections.Counter：一个专做计数的dict子类，底层还是哈希表。collections.defaultdict：在访问不存在的key时自动填充默认值，同样是哈希表。functools.lru_cache：缓存函数运行结果时，底层用dict做记忆存储，key是参数组合，value是返回值。- 对象属性的存储：Python对象的
__dict__就是一个字典，这意味着你访问obj.attr时，本质也是在做一次哈希表查询。
理解这一点，你就能明白为什么Python官方一直在优化dict的底层实现。因为dict的性能几乎决定了整个语言的运行效率。2016年Python 3.6版本里dict的内存布局被重新设计，这个改动直接让所有Python程序都享受到了内存和速度的双重优化，而且当时官方说这是个“实现细节”，结果因为太好用，后续版本直接把它定为语言规范了。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 扒开CPython底层：dict的存储设计不只是一个数组
2.1 为什么查询是O(1)平均复杂度
这里我先抛出一个反直觉的结论：哈希表的O(1)是“平均”意义上的，不是“所有情况”都如此。最坏情况下所有key都算到同一个桶，查找就退化成O(n)。虽然工程上这个概率极低，但理解这一点能帮你避免盲目相信哈希表的绝对性能。
正常情况下的查询流程大致是这样的：拿到key之后，先调用hash(key)得到一个Py_hash_t类型的整数，然后把这个整数和“掩码”（也就是数组容量减一）做位与运算，拿到一个数组下标。接着检查该下标对应的槽位，如果槽位为空，说明key不存在；如果不为空，还需要比较一下槽位里存的key和当前key是否相等，注意这里比较的是key的“相等性”，也就是==判断。如果相等，直接返回值；如果不相等，说明发生了哈希冲突，就要沿着某种探测序列继续找下去。
这就是平均O(1)的秘密：算hash的代价是固定的，定位下标是常数级操作，只有冲突时需要额外探测几次。只要hash函数足够均匀，探测次数就是一个很小的常数，比如1到3次。所以O(1)本质上说的是“与数据规模无关”，而不是“只需要一次操作”。
2.2 从PyDictObject结构体看插入流程
在Python 3.6之后，CPython的dict做了一次非常关键的存储结构调整。过去的dict直接维护一个线性数组，每个槽位存放键值对，冲突用开放地址法解决。但旧的实现里，小字典的空间浪费很严重，因为每个槽位要存key、value和hash，即使大部分槽位是空的，也要为它们预留空间。
现在的实现把存储拆成了两部分：索引表（indices） 和 条目表（entries）。索引表是一个大小等于“容量”（capacity）的数组，每个元素实际上只是一个整数下标，指向条目表的位置。条目表只存放实际存在的键值对，并且按插入顺序排列。
打个比方，索引表就像一栋楼外层的信箱格，每个格子里写的不是住户的家庭住址，而是“请去二号楼203室找这个人”；条目表才是真正住人的房间，谁入住谁就排进去，没住人的房间不用提前留位置。
插入时的大致过程是：
- 调用
hash(key)得到哈希值。 - 将哈希值经过位运算映射成索引表的下标。
- 检查索引表中该下标对应的是否为“空”标记。
- 如果为空，把键值对追加到条目表的末尾，然后在索引表里记录这个条目在条目表中的位置。
- 如果索引表里已经有值，说明这个位置被占用了，这时就要走冲突探测流程。
这种“索引表 + 条目表”的分离设计带来了两个显著好处。一是大量空槽位只占用很小的整数存储空间，而不是整个键值对的空间；二是条目表按插入顺序排列，这让dict在Python 3.7之后天然保证了“插入有序”，但这只是一个附加红利，本质目的是为了提升缓存命中率和减少内存。
2.3 字符串hash随机化与哈希攻击防范
写Python时间长了，你可能会发现一个奇怪现象：同一个字符串，在不同进程里算出来的hash()值不一样。比如运行两次Python解释器，hash("hello")的结果可能不同。
python复制# 第一次运行
>>> hash("hello")
789012345
# 第二次运行
>>> hash("hello")
-123456789
这是因为CPython在启动解释器时，会给字符串的hash计算加一个随机盐（salt）。这个盐值进程间不同，导致同一个字符串在不同进程中的哈希值无法复现。很多人第一次遇到时以为是自己环境问题，其实这是CPython有意为之的反攻击设计。
为什么要这么做？因为如果字符串哈希值在进程间固定，攻击者可以构造大量哈希值相同的字符串，让它们全部冲突，从而把Python字典的查找从平均O(1)拖成O(n)，形成拒绝服务攻击（哈希碰撞DoS）。加了随机盐之后，攻击者无法预先知道当前进程的哈希规律，碰撞攻击就难以实施。
这个设计对普通开发者也有影响。比如你在A进程里把字符串按哈希值排序后写进文件，然后在B进程里读出来，会发现顺序对不上。遇到这种跨进程需要稳定哈希的场景，应该用hashlib等标准库自己计算摘要，而不是依赖内置的hash()函数。内置hash()本身就不保证跨进程稳定性，这是设计文档里明确写过的。
3. 处理冲突的开放地址法：CPython最核心的探测细节
3.1 冲突是无法避免的，只能缓解
再完美的hash函数，也逃不过冲突的宿命。这里有一个非常直观的数学事实，叫生日悖论。一个房间里有23个人，至少两人生日相同的概率就已经超过50%；有50个人时，概率更是飙到97%。生日悖论的本质是：当样本数量远超“类别数量”的平方根时，碰撞几乎是必然的。
哈希表的容量就是“类别数量”，已存元素个数就是“样本数量”。比如容量是365，存到第23个元素时，冲突概率就可能过半。这个原理放在哈希表里同样成立：即使你的hash函数极其均匀，当元素个数达到容量的一半左右时，冲突就已经不可避免。所以哈希表设计者要做的不是消灭冲突，而是在冲突发生后仍然保持效率。
处理冲突的思路大体分两类：开放地址法和链地址法。Java的HashMap用的是链地址法，每个槽位先放一个链表，链表超过8个节点后再转成红黑树。而Python的dict和set用的是开放地址法。什么是开放地址法？简单说，就是冲突发生后，不再另开存储空间，而是在同一张表里继续找下一个空闲槽位。整个过程就是顺着一条“探测序列”往下走，找到空位就放。
3.2 开放地址法探测序列的细节
很多文章把Python的开放地址法简单说成“线性探测”，也就是每次往后挪一个位置找空位。这个说法不够准确。CPython的dictobject.c里，真正的探测过程用的是伪随机探测，代码注释里直接写的是Perturbation策略。
伪代码长这样：
python复制def find_empty_slot(hash_value, mask, used):
i = hash_value & mask
perturb = hash_value
while True:
if 该槽位为空:
return i
i = (i << 1) + i + perturb + 1 # 等价于 i = 5 * i + perturb + 1
perturb >>= 5
i &= mask
这里最关键的两点是：当前槽位被占用后，下一个探测位置不是简单地加1，而是由 i * 5 + perturb + 1 算出来的，其中perturb每次右移5位。这个设计的用意是：在探测初期，perturb的高位信息还能影响位置选择，让探测序列看起来比较“跳跃”；到后期perturb逐渐变成0，就退化成i * 5 + 1，也就是围绕某个区域扫描。这种混合策略比纯线性探测更能打散集聚现象，又不会像完全随机探测那样难以缓存。
另外注意，探测时用到的掩码mask等于容量减一，因为Python的dict容量永远是2的幂次方，这保证了“哈希值 & mask”就是一个0到容量减一的下标。这也是为什么你从外部看不到容量设置接口，Python默认让你在8、16、32、64这些2的幂容量间自动切换。
说到线性探测，大白话理解就是：你到了停车场发现目标车位被占了，你只能往后一格一格找。问题在于，如果之前已经有很多车排了长队，新来的车就会在队尾继续往后排队，形成聚集。而Python的伪随机探测更像“如果这个车位被占，我按照一个规律跳到远处试试”，这样能显著减少聚集。
3.3 扩容阈值与rehash过程
既然冲突无法避免，哈希表就必须在冲突概率变得不可接受之前，把表变大，把所有元素重新摆放一遍。这个过程叫rehash。
CPython的dict在“已存储元素个数”达到“容量”的三分之二左右时，就会触发扩容。具体来说，扩容后的容量通常是当前容量的两倍，同时保持2的幂。比如一个默认容量为8的dict，大约存满5个键值对后，插入第6个可能就触发扩容到16。这和我们通常直觉里的“存满了才扩容”不一样，它提前扩容，就是为了让负载因子始终保持在较低水平，减少探测次数。
扩容时的代价是巨大的。所有现有键值对必须重新计算哈希值，然后按新容量重新探测位置。如果旧容量是8，新容量是16，那么原本通过“hash & 7”得到的下标，现在要变成“hash & 15”，相当于每个元素的位置全部打乱重来。这也是为什么在往一个大dict里持续插入数据时，某些瞬间会感觉卡顿：其实是在静默地做一次rehash。
所以，如果你事先知道要往dict里插入几万条数据，最好一次性把它们全部塞进去，让Python自己分几次扩容即可；千万不要频繁地一边插入一边删除，因为删除在开放地址法中会产生“墓碑”标记，墓碑多了会影响查找效率。关于删除的细节，我后面还会专门讲。
4. 自定义类做key时，hash和eq的坑一个接一个
4.1 __hash__与__eq__的绑定规则
Python里有这样一条硬性规则：如果你在类里定义了__eq__方法，但没有同时定义__hash__，那么这个类的实例会变成不可哈希的对象。
python复制class Person:
def __init__(self, name, age):
self.name = name
self.age = age
def __eq__(self, other):
return self.name == other.name and self.age == other.age
p = Person("张三", 18)
d = {p: 1} # TypeError: unhashable type: 'Person'
这条规则背后的逻辑非常严谨：Python要求所有相等的对象必须有相同的哈希值。如果你重写了__eq__，就说明你在重新定义“什么算相等”。既然判断相等的规则变了，那哈希值的生成规则也必须跟着变，否则就会出现两个对象a == b成立，但hash(a) != hash(b)，这会让哈希表彻底混乱：用a能查到，用b却查不到。
为了强制用户遵守这个约束，Python干脆规定：不主动实现__hash__，就默认让对象不可哈希。这是用“报错”来防止你写出错误的代码。
4.2 完整示例：自定义类实现合格的哈希
如果你确实需要一个自定义对象作为key，标准做法是同时实现__hash__和__eq__，而且这两者的判断依据必须一致。
最常见的例子是平面坐标点：
python复制class Point:
def __init__(self, x, y):
self.x = x
self.y = y
def __eq__(self, other):
if not isinstance(other, Point):
return NotImplemented
return self.x == other.x and self.y == other.y
def __hash__(self):
return hash((self.x, self.y))
这里用hash((self.x, self.y))的原因很朴素：元组是Python内置的可哈希对象，把所有参与相等性判断的字段打包进一个元组，相当于把“相等规则”直接翻译成了“哈希规则”。这种情况下，两个对象只要x和y相等，元组就相等，哈希值自然相同。反过来说，只要哈希值相同，对象也必然相等，哈希表就能正常工作。
还有个更省事的方法，直接使用内置的类型：
python复制from dataclasses import dataclass
@dataclass(frozen=True)
class Point:
x: int
y: int
加上frozen=True之后，dataclass会自动帮你生成基于所有字段的__hash__和__eq__，而且对象创建后变成不可变的，这正好符合“哈希对象最好是不可变对象”的最佳实践。
4.3 可变对象做key带来的灾难
如果你费了很大力气实现了一个自定义类，还设置了正确的__hash__和__eq__，但忘了控制对象的可变性，那就会遇到另一种更隐蔽的坑。
看这个例子：
python复制class Person:
def __init__(self, name):
self.name = name
def __hash__(self):
return hash(self.name)
def __eq__(self, other):
return self.name == other.name
p = Person("张三")
d = {p: 1}
p.name = "李四" # 修改了对象属性
print(d[p]) # KeyError！查不到了
为什么会查不到？因为哈希表在插入时，已经用“张三”算出的哈希值把键值对放进了某个位置。修改后的name变成“李四”，hash(p)的结果变了，再去哈希表里查，会先根据新哈希值定位到一个完全不同的槽位，结果当然是找不到。
更麻烦的是，即使你能通过某种方式找回原来的哈希值，原来的槽位在查找时也会先比较对象的__eq__。如果其他对象和这个修改后的对象在相等性上已经变化了，也会导致匹配失败。
这个坑在实战中非常常见。比如你把一个包含列表的自定义对象当key存进缓存，等它内部列表变化后，缓存再也命中不了；或者你把一个对象放进set后，修改了它的某个字段，导致删除时出现诡异问题。正确的做法是：用作key的对象要么是不可变对象，要么在放进哈希表之后绝不修改其参与哈希计算的字段。如果实在需要修改，就把对象从哈希表中先移除，修改完再重新添加。
5. 哈希表的实战优化：从性能实测到算法题
5.1 预分配容量：一次插入十万条数据的正确姿势
很多人不知道，Python的dict其实没有一个官方公开的“预分配容量”参数。这也是为什么有些同学从Java转到Python时很不适应——Java的HashMap可以指定初始容量，Python的dict()却只能传入可迭代对象。
那遇到“事先已经知道有多少条数据”的场景怎么办？最有效的方式是尽可能用批量构造，而不是反复调用d[key] = value。比如从数据库查出一万行，要组装成字典，不要写一个空字典然后循环赋值，而是直接调用dict()构造器传入一个生成器表达式。
python复制# 不推荐：空字典循环，触发多次扩容
result = {}
for row in rows:
result[row["id"]] = row
# 更推荐：直接构造
result = {row["id"]: row for row in rows}
两种写法最终得到的dict内容一样，但后者减少了多次resize的损耗。虽然Python的dict扩容是自动的，每次扩容都要rehash，数据量大时这个开销不可忽视。
另外，如果你在循环里频繁往一个dict里塞数据，但你其实只需要一个集合去重，那用set更合适，因为set存储的是单个元素，底层存储结构更紧凑，占用内存更少。
5.2 字典列表性能对比实测
为了让你直观感受哈希表的威力，我写了一个简单的对比测试：分别在一个包含10万个元素的list和dict中查找一个已经存在的数据，重复十万次。
python复制import timeit
people_list = [f"user_{i}" for i in range(100000)]
people_dict = {f"user_{i}": i for i in range(100000)}
def test_list():
return "user_99999" in people_list
def test_dict():
return "user_99999" in people_dict
print(timeit.timeit(test_list, number=100000))
# 大约 0.5 秒左右
print(timeit.timeit(test_dict, number=100000))
# 大约 0.01 秒左右
结果差距可能达到几十倍甚至上百倍。这里要提醒一句，如果你的数据量很小，比如只有几十个元素，列表的查找可能反而比哈希表快。因为列表的C循环非常高效，而哈希表在查得少时还需要算hash、取模、查找槽位，种种函数调用开销不小。所以“哈希表永远最快”是一个常见的误解，数据量小时，简单结构往往更有优势。
5.3 在算法题与应用场景中的选型思路
哈希表在实际开发里最常见的几个用法，我按场景列一下：
- 去重：
set是最直接的工具。如果还需要记录每个元素出现次数，用Counter。 - 映射关系：从id到对象、从配置名到配置值，用
dict。 - 缓存：
functools.lru_cache底层就是dict，但要注意key必须是可哈希的，包括参数类型。 - 两数之和：经典的算法题，
dict记录“值到下标”的映射，配合一次遍历完成。 - LRU缓存淘汰：双向链表+哈希表是最经典的设计，Python的
OrderedDict其实就是“双向链表+哈希表”的封装。 - 图的邻接表：用
dict存储每个节点连接的所有邻居，比二维数组节省大量空间。
还有一点很多人容易忽略：哈希表不是万能的。空间受限时，比如你需要处理十亿级别的高频数据，哈希表的内存开销会很惊人。这时候可能要考虑布隆过滤器、Trie树、位图等更专门的结构。哈希表的强项是“直接按键访问”，如果你更关心“有序遍历”“范围查询”，那应该用bisect配合列表，或者直接用heapq，哈希表没法高效支持这些操作。
另外，嵌套的哈希表结构也要注意可维护性。比如defaultdict(lambda: defaultdict(list))这种写法虽然省事，但生成出来的类型信息很难读，Debug时也很痛苦。我个人的习惯是能用普通dict加显式初始化就用普通dict，必要时封装成一个小类。
最后聊一个很实在的场景：处理大量JSON数据时，Python解析出来的顶层结构就是dict。有人图方便，把json.loads的结果层层索引，比如data["users"][0]["profile"]["name"]，一旦某个键不存在就会抛KeyError。与其反复try-except，不如在数据进来时清洗一遍，转换成带默认值的defaultdict，这样后面的业务逻辑会干净很多。哈希表的核心价值，本来就是为了让数据访问变得更简单、更直接。
我在实际项目中踩过最深的坑，是一个自定义对象被放进set后，因为监听事件修改了它的某个字段，导致后面怎么都删不掉这个对象。排查了很久才发现是哈希值变了之后，对象虽然在set里，但整个“定位逻辑”已经对不上。那次之后我把规矩定为：凡是进哈希表的对象，一律用不可变类型，或者冻结到写入之后绝不再动。这个习惯帮我避免了不少奇怪的bug，希望也能帮到你。