什么是 Mapping？链上余额表为什么不能直接遍历所有地址

区块浏览器能让你输入地址查询代币余额，却没有一个按钮直接把“所有持币地址”从合约里列出来。开发者明明写了 mapping(address => uint256) balances，为什么合约知道某个地址有多少，却不知道自己一共有多少个地址？

Mapping 可以理解为链上键值查找表：给定 Key，就能定位对应 Value。它非常适合余额、授权、权限和订单状态，但它没有内置长度、不会保存可遍历键列表，也无法区分“从未设置”和“被设置为默认值”。

Mapping 擅长回答“这个键对应什么”，不擅长回答“所有键有哪些”。

Mapping 的基本结构

mapping(address => uint256) 表示地址到无符号整数的映射。Key 可以是内置值类型、bytes、string、合约或枚举等允许类型；Value 可以更复杂，甚至是结构体、数组或另一个 mapping。

所有 Key 看起来都“已经存在”

官方文档把 mapping 描述为虚拟初始化：任何可能的 Key 都映射到该类型的默认值。查询一个从未写过的地址余额会得到 0，而不是“找不到”。布尔值默认 false，地址默认零地址。

零值为什么会产生歧义

返回 0 可能表示从未登记、余额已经清零或明确写入 0。若业务必须区分，可以增加 mapping(key => bool) exists、在结构体中保存标志，或维护状态枚举。不能仅凭值非零判断对象存在。

为什么 Mapping 没有 Length

mapping 不保存键本身的列表，查找时使用 Key 与存储槽信息计算位置。因此没有天然长度，也无法在合约里请求“下一个键”。这避免了为每次写入自动维护庞大列表，却把枚举责任交给应用设计。

Mapping 只能位于 Storage

mapping 只能使用 storage 数据位置，可作为状态变量、内部函数的 storage 引用或库函数参数。它不能像普通数组一样整体复制到 memory，也不能作为公开合约函数的普通参数或返回值。

Public Mapping 会生成 Getter

将状态 mapping 标为 public，编译器会生成按 Key 查询的 getter。例如 balances(address) 返回对应余额。Getter 仍不会返回全部键；嵌套 mapping 则需要依次提供多层 Key。

ERC-20 余额为何适合 Mapping

代币转账通常只需读写发送者和接收者的余额，不需要在每笔交易中遍历所有持有人。地址到余额的 mapping 能直接定位目标。总供应量通常单独记录，因为无法通过遍历余额表随时求和。

授权为什么常用嵌套 Mapping

mapping(address => mapping(address => uint256)) 可以先用资产所有者地址定位第一层，再用被授权者地址定位额度。查询需要 owner 与 spender 两个 Key，修改授权时也必须确认二者顺序。

怎样维护可遍历键列表

常见做法是 mapping 保存值，数组保存键，再用额外 mapping 记录键在数组中的位置。新增、更新和删除必须同时维护三者。若只删除 mapping 值却忘了索引，列表会出现幽灵项；若重复插入键，又会造成重复统计。

删除 Mapping 项会发生什么

delete balances[user] 会把该 Key 的 Value 重置为默认值。它不会自动从自建键数组移除，也不会证明历史上没有存在过。完整删除流程需要同步更新索引，并考虑顺序变化和事件。

为什么不能一键清空整个 Mapping

因为合约本身不知道所有键，不能遍历并删除。官方文档指出，缺少已写 Key 的额外信息时无法清空 mapping。若业务需要批量重置，可采用版本号、分代命名空间、维护键索引或部署新实例，但每种方案都有 Gas 与复杂度。

事件可以帮助链下建立列表

写入和删除时发事件，索引服务可以重放日志得到地址列表、历史变化和排行榜。这些是链下派生视图，不是 mapping 内置数据。索引器要处理起始区块、重组、重复消费和漏块，并用链上查询核对关键结果。

遍历大型数组为什么危险

为了弥补 mapping 不可遍历而维护数组后，不要在状态修改函数中无界循环所有键。列表增长会使 Gas 超出区块限制，导致清算、分配或管理功能最终无法执行。使用分页、批次或链下计算加链上验证。

存储位置如何计算

概念上，mapping 项的位置由 Key 与 mapping 所在存储槽经过哈希计算得到，嵌套 mapping 逐层计算。这让不同 Key 分散到确定位置。开发者通常无需手算，但代理升级、底层调试和存储证明会依赖准确布局。

代理升级要保持布局兼容

mapping 状态属于代理 storage，实现升级若改变变量顺序或错误占用原存储槽，旧余额可能被新代码错误解释。升级合约应遵守所用框架的存储布局规则，并做布局比较与迁移测试。

常见错误清单

• 把默认零值误当成对象不存在。
• 维护键数组但更新和删除不同步。
• 在链上无界遍历所有成员。
• 嵌套 mapping 的 Key 顺序写反。
• 只改余额却忘记总量或事件等关联状态。
• 升级时破坏 mapping 所在存储槽。

用户看到列表时要明白什么

持币地址数、排行榜和授权列表通常来自区块浏览器或索引服务，不是合约直接返回完整 mapping。页面短暂缺项可能是索引延迟，关键余额与授权应通过合约 getter 在指定区块核对。

开发者检查清单

1. 业务是否需要区分未设置与默认值？
2. 是否真的需要枚举全部 Key？
3. 索引数组与 mapping 能否原子地更新？
4. 批量操作是否有分页和上限？
5. 事件能否支持链下重建与审计？
6. 代理升级是否验证存储布局兼容？

官方资料

语法、默认值、数据位置、getter 与不可清空限制参考 Solidity：Mapping Types。开发与审计请结合项目实际编译器版本和代理框架文档。

Mapping 的高效来自明确取舍：它保留从 Key 到 Value 的关系，不替你维护所有 Key 的目录。设计前先问业务是否需要存在性、枚举、统计和删除，再决定要不要增加索引与事件。

本文为链上指南原创科普内容，不构成任何投资建议。余额、授权与列表展示可能依赖不同数据源，链上操作前请核对合约地址、Key 参数和当前状态。