智能合约与以太坊 / 系统课时
使用数组、结构体和映射存储
使用数组、结构体和映射存储
当合约需要同时保存多个账户及其业务记录时,单个状态变量已经不够用。本课通过一个可部署的会员积分合约,将数组、结构体和映射组合起来,实现账户注册、积分更新、按地址查询和按顺序访问,并验证数据如何持久化到链上。
学习目标
- 区分数组、结构体和映射的用途,理解索引、默认值和数据组织方式。
- 编写使用
mapping、struct、动态数组和storage引用的 Solidity 合约。 - 验证注册与更新结果,识别映射不可遍历、数组越界及复合数据更新的常见问题。
三种数据结构分别解决什么问题
假设一个会员系统需要记录账户地址、积分和注册状态,同时允许按注册顺序查看会员。可以将数据拆成三部分:
| 数据结构 | Solidity 声明 | 解决的问题 |
|---|---|---|
| 动态数组 | address[] |
保存注册顺序,通过从 0 开始的索引访问地址 |
| 结构体 | struct Member |
将积分和注册状态组合为一条业务记录 |
| 映射 | mapping(address => Member) |
根据地址直接找到对应的会员记录 |
动态数组没有固定的编译期长度,可以使用 push() 追加元素、pop() 删除末尾元素,并通过 length 获取当前元素数量。访问 memberList[0] 表示第一个地址,访问超过范围的索引会导致执行回退。
结构体适合组织属于同一对象的字段。例如一个 Member 包含 uint256 points 和 bool exists,更新时可以只修改 points,不必重建整个业务概念。
映射使用键查找值。members[account] 能取得指定地址的记录,但映射本身没有 length、push() 或键遍历功能。即使从未写入某个地址,也能读取到字段的默认值。
因此,本例采用数组保存可枚举的地址顺序,采用映射保存按地址查询的结构体记录。二者都是合约的状态变量,数据会保留在合约存储中。
编写可持久化的会员积分合约
以下示例适用于 Solidity 0.8.20 及兼容的 0.8.x 编译器。创建 MemberRegistry.sol,写入完整代码:
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;
contract MemberRegistry {
struct Member {
uint256 points;
bool exists;
}
address public immutable admin;
mapping(address => Member) public members;
address[] public memberList;
constructor() {
admin = msg.sender;
}
function join() external {
require(!members[msg.sender].exists, "already joined");
// 注册成功时同时维护记录和可枚举的地址列表
members[msg.sender] = Member({points: 0, exists: true});
memberList.push(msg.sender);
}
function credit(address account, uint256 amount) external {
require(msg.sender == admin, "not admin");
// storage 引用直接定位并更新链上结构体
Member storage record = members[account];
require(record.exists, "not registered");
record.points += amount;
}
function memberCount() external view returns (uint256) {
return memberList.length;
}
}预期结果:合约可正常编译和部署。部署账户成为 admin;账户首次调用 join() 后,members(账户地址) 返回积分 0 和注册状态 true,memberCount() 返回 1。管理员执行 credit(账户地址, 15) 后,该账户的积分变为 15。
这里有三个值得注意的设计:
members使用账户地址作为键,避免为寻找会员而遍历整个数组。memberList.push(msg.sender)只在首次注册时执行,防止相同地址重复出现在列表中。credit()仅允许部署时的管理员调用,防止普通会员自行增加积分。
public 会为映射和数组分别生成外部读取函数。members(address) 返回结构体中可公开返回的字段,本例是 points 和 exists;memberList(uint256) 返回指定索引的地址。但数组的自动 getter 不会直接返回整个数组,因此额外提供 memberCount()。

join() 对两个状态变量的修改发生在同一笔交易中。如果交易执行回退,之前的状态写入也会回滚,不会出现本次调用只成功写入其中一处的半成品状态。
在 Remix 中验证注册与更新
使用浏览器中的 Remix IDE 即可完成实验,不需要真实 ETH。
- 在文件资源管理器中创建
MemberRegistry.sol,粘贴上述源码。 - 打开 Solidity Compiler,选择
0.8.20或兼容版本,点击 Compile MemberRegistry.sol。 - 打开 Deploy & Run Transactions,将 Environment 设为
Remix VM,选择测试账户 A,点击 Deploy。 - 在已部署合约中调用
members(A),确认当前记录是默认值;再调用join()注册账户 A。 - 保持账户 A 为当前调用者,执行
credit(A, 15),查询更新后的积分。 - 切换到另一个测试账户 B,调用
join(),再查询两个账户以及数组长度。
其中 A、B 表示 Remix 提供的实际测试地址,界面中需要填入完整地址。不同测试环境中的地址可能不同。
| 操作 | 预期结果 |
|---|---|
首次读取 members(A) |
points=0、exists=false |
A 调用 join() |
交易成功,members(A) 返回 0, true |
A 调用 credit(A, 15) |
交易成功,members(A) 返回 15, true |
B 调用 join() |
交易成功,memberCount() 返回 2 |
读取 memberList(0) |
返回账户 A 的地址 |
读取 memberList(1) |
返回账户 B 的地址 |
读取 members(B) |
返回 0, true |
B 调用 credit(B, 10) |
交易回退,提示 not admin |
如果 A 再次调用 join(),会触发 already joined,数组长度仍为 2。这验证了映射中的 exists 字段可以用于防止重复注册。
在 Remix 中,读取 view 函数通常可以通过本地调用完成,不需要发送链上状态变更交易;执行 join() 或 credit() 则需要状态写入,消耗执行 Gas。
storage、memory 与 calldata 怎样影响更新
Solidity 的数组和结构体属于引用类型。声明局部引用时,必须理解数据位置,否则代码即使可以编译,也可能没有修改预期中的链上数据。
| 数据位置 | 特征 | 本例中的用途 |
|---|---|---|
storage |
持久化合约状态,局部 storage 引用指向原数据 | 修改 members[account].points |
memory |
调用期间的临时内存,读取 storage 到 memory 会产生独立副本 | 临时计算或返回结构体数据 |
calldata |
调用输入中的只读数据区域 | 接收外部函数传入的数组等引用类型参数 |
在示例中,Member storage record = members[account]; 不会复制一份独立的会员状态,而是让 record 引用映射内对应的结构体。因此执行 record.points += amount,就能直接更新持久化数据。
如果把它改为 Member memory record = members[account];,则会复制一份结构体到临时内存。随后修改 record.points 只会改变副本,原映射不会随之更新。若确实需要先修改副本,应在完成计算后显式执行 members[account] = record,将结果写回状态变量。
同样,Member memory snapshot = members[account] 适合只读处理;如果需要频繁更新多个字段,使用 storage 引用通常可以避免不必要的完整结构体复制。
映射默认值、数组越界与删除风险
映射没有传统数据库意义上的“键是否存在”查询。对于从未注册的地址,members[account].points 默认是 0,members[account].exists 默认是 false。
因此,不能仅凭积分是否为零判断会员是否存在。合法会员刚注册时积分同样为零,本例用 exists 明确区分这两种情况。
数组的行为则不同。假设 memberCount() 返回 2,合法索引只有 0 和 1。访问 memberList(2) 会触发越界检查并回退,而不会像映射那样返回默认地址。
删除复合数据时还需要处理索引一致性:
- 对映射记录执行
delete members[account],会将该记录的字段恢复为默认值,但不会从memberList中删除对应地址。 - 对动态数组调用
pop(),只会删除最后一个元素,不会自动清理映射中的对应记录。 - 如果需要任意位置删除且不要求保持注册顺序,可以维护地址到数组索引的辅助映射,再使用末尾元素交换与
pop();若必须保持顺序,则需要额外的移动操作或改用逻辑删除。
本示例没有实现注销,避免读者误以为单独删除一份数据就能自动更新另一份。实际业务应先明确注销后是否允许再次注册,以及历史积分是否保留,再设计删除策略。
此外,枚举整个会员列表可能产生较高的 Gas 成本,不应让状态变更函数无上限地遍历大量地址。实际应用通常通过 memberCount() 与 memberList(index) 分页查询,或结合事件日志在链下建立索引。
完成实验后,可以再用第三个未注册账户 C 调用 members(C),确认结果为 0, false,并尝试访问越界索引。只要能解释为什么映射返回默认值、数组访问会回退,以及为什么 storage 引用的更新能够持久化,就已经掌握了这三种结构在合约中的基本协作方式。