智能合约与以太坊 / 系统课时

使用数组、结构体和映射存储

使用数组、结构体和映射存储

当合约需要同时保存多个账户及其业务记录时,单个状态变量已经不够用。本课通过一个可部署的会员积分合约,将数组、结构体和映射组合起来,实现账户注册、积分更新、按地址查询和按顺序访问,并验证数据如何持久化到链上。

学习目标

  • 区分数组、结构体和映射的用途,理解索引、默认值和数据组织方式。
  • 编写使用 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,写入完整代码:

solidity
// 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。

这里有三个值得注意的设计:

  1. members 使用账户地址作为键,避免为寻找会员而遍历整个数组。
  2. memberList.push(msg.sender) 只在首次注册时执行,防止相同地址重复出现在列表中。
  3. credit() 仅允许部署时的管理员调用,防止普通会员自行增加积分。

public 会为映射和数组分别生成外部读取函数。members(address) 返回结构体中可公开返回的字段,本例是 points 和 exists;memberList(uint256) 返回指定索引的地址。但数组的自动 getter 不会直接返回整个数组,因此额外提供 memberCount()。

会员数组、结构体与映射的链上存储关系

join() 对两个状态变量的修改发生在同一笔交易中。如果交易执行回退,之前的状态写入也会回滚,不会出现本次调用只成功写入其中一处的半成品状态。

在 Remix 中验证注册与更新

使用浏览器中的 Remix IDE 即可完成实验,不需要真实 ETH。

  1. 在文件资源管理器中创建 MemberRegistry.sol,粘贴上述源码。
  2. 打开 Solidity Compiler,选择 0.8.20 或兼容版本,点击 Compile MemberRegistry.sol。
  3. 打开 Deploy & Run Transactions,将 Environment 设为 Remix VM,选择测试账户 A,点击 Deploy。
  4. 在已部署合约中调用 members(A),确认当前记录是默认值;再调用 join() 注册账户 A。
  5. 保持账户 A 为当前调用者,执行 credit(A, 15),查询更新后的积分。
  6. 切换到另一个测试账户 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 引用的更新能够持久化,就已经掌握了这三种结构在合约中的基本协作方式。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用数组、结构体和映射存储

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通