导读 — 本书结构与阅读方式

本页说明本书适合谁、如何阅读，并逐章交代各篇内容与依赖关系；具体语法与 API 以正文为准。

本书适合的读者

• 已有至少一门编程语言经验、希望在 Sui 上编写 Move 2024 合约的开发者。
• 若你来自 Solidity / 其他链，建议先读第一章与第九章 · 对象模型，理解对象所有权与账户模型的差异，再进入实战章。
• 零基础编程的读者本书并非最佳选择，建议先掌握变量、函数与控制流再读第二章之后的内容。

如何使用本书

默认顺序：建议从第一章依次往后读。后文会默认你已读过前文中的术语（如 Abilities、对象所有权、PTB（Programmable Transaction Block，可编程交易块） 等）。

可以跳读吗：可以。若你已有 Move 基础，可从第九章 · 对象模型或第十二章 · 高级可编程性切入；遇到不熟悉的概念再回到对应章节。跳读时若产生困惑，回到更早的「概念章」补全通常比硬啃更快。

概念章与综合章：本书大致可分为：

阅读编译器与验证器报错：Move 与 Sui 验证器会在编译或发布阶段拒绝不少「在别的语言里能写」的代码。本书部分示例会故意展示错误写法与报错信息，文中会写明「以下不能通过验证」；请勿对随机片段直接复制到项目中期望能编译通过。

命令与版本：书中命令以当前稳定 Sui CLI 为准；Move.toml 的 edition 与依赖 rev 若与本地不一致，请先对齐第二章（环境）与第六章 §6.11（Edition 与 Framework 约定），或仓库根说明。

各章导读

以下按章概述，便于你把目录当作「路线图」使用（章号与本书页首目录一致）。仓库路径：src/ 下主文件夹与章号对应——例如宏函数为 11_move_macros/（书中第十一章）、12_programmability/（第十二章）、15_tokens/（第十五章 代币）；第 1–6 章为 01_…06_。正文标题与下表以「第 × 章」为准。

入门篇（第 1–3 章） — 认识 Sui 与 Move、搭建环境、完成第一个包的编写、测试、部署与链上交互。

语言篇（第 4–6、8 章） — 包与清单、账户与交易；Move 语法基础与进阶（宏函数仅 §6.8 导读）；泛型、类型反射、编译模式等。**第 6 章末（§6.11）**集中整理 Move 2024 Edition 与 Move.toml 约定；第 8 章收尾高级语言特性，为对象篇做准备。

对象篇（第 9–10 章） — Sui 对象模型、所有权细分、拥有/共享与排序；第 10 章讲解 key / store、存储 API、内部约束、转移限制与 Transfer to Object。

Move 宏函数篇（第 11 章） — 宏函数详解，目录上在第十章之后、第十二章（Framework）之前，单独成篇。第六章 §6.8 为导读。

进阶篇（第 12–14 章） — Framework、事件、动态字段、集合与 Coin、密码学与随机数；设计模式；测试（场景、系统对象、覆盖率、Gas 分析等）。

应用篇（第 15–18 章） — 代币经济、NFT 与 Kiosk、TypeScript 客户端与 PTB、全栈 DApp 实战。

工程篇（第 19–23 章） — 第 19 章包升级与迁移；第 20 章安全实践、漏洞模式、错误处理与协议限制（与升级章互补）。随后为基础设施、前沿特性与 PAS（第二十三章）。

附录 — 术语、保留地址、Transfer API、CLI、规范与检查清单；另见延伸阅读。

源代码

本书正文与示例对应本仓库根目录；章节中的代码路径以各章说明为准。

没有「唯一正确」的阅读方式

你可以按项目需要翻到任意一章；若出现概念断层，再回到上文对应概念章即可。以你能坚持学下去的方式为准。

第一章 · 走进 Sui 与 Move

本章将带你了解 Sui 区块链的核心理念和技术架构，认识 Move 语言的独特优势。开发工具链（Sui CLI、Suiup）的安装与版本管理已移至 第二章 §2.1，避免在概念章重复环境步骤。

本章内容

学习目标

读完本章后，你将能够：

• 理解 Sui 区块链相对于其他链的核心差异
• 说出 Move 语言在安全性和资产建模上的优势
• （环境）在第二章完成 Sui CLI 的安装与验证

本章实战练习

每章 1～3 个动手任务见 hands-on.md（目录中亦列为「本章实战练习」）。

区块链与智能合约

区块链是一种去中心化的分布式账本技术，它通过密码学和共识机制保证数据的不可篡改性与一致性。智能合约则是运行在区块链上的程序，它们能够在无需信任第三方的情况下自动执行预定义的逻辑。理解这两个基础概念，是踏入 Sui 与 Move 开发世界的第一步。

什么是区块链

分布式账本

区块链的本质是一个由众多节点共同维护的分布式账本。与传统的中心化数据库不同，区块链没有单一的管理者——每个参与节点都持有完整（或部分）的账本副本。当一笔新的交易发生时，它会被广播到整个网络，经过验证后被永久记录。

这种架构带来了几个关键特性：

• 去中心化：没有单点故障，任何单一节点的宕机不会影响整个网络
• 透明性：所有交易记录公开可查，任何人都可以验证
• 不可篡改：一旦数据被记录到区块链上，修改它的代价在计算上是不可行的

区块与交易

区块链由一系列按时间顺序链接的**区块（Block）**组成。每个区块包含：

• 区块头：包含时间戳、前一个区块的哈希值、Merkle 根等元数据
• 交易列表：该区块中包含的所有交易
• 区块哈希：对区块头的加密哈希值，作为该区块的唯一标识

**交易（Transaction）**是区块链上状态变更的最小单位。一笔交易通常包含：

• 发送者地址与签名
• 接收者地址或目标合约
• 调用的函数与参数
• Gas 费用（执行成本）

区块 N-1          区块 N           区块 N+1
┌──────────┐    ┌──────────┐    ┌──────────┐
│ Hash N-2 │◄───│ Hash N-1 │◄───│ Hash N   │
│ 时间戳    │    │ 时间戳    │    │ 时间戳    │
│ 交易列表  │    │ 交易列表  │    │ 交易列表  │
│ Merkle根  │    │ Merkle根  │    │ Merkle根  │
└──────────┘    └──────────┘    └──────────┘

共识机制

共识机制是区块链网络中各节点就账本状态达成一致的规则。不同的区块链采用不同的共识算法，各有优劣：

工作量证明（Proof of Work, PoW）

PoW 是比特币采用的共识机制。矿工需要通过大量计算找到满足特定条件的哈希值（即“挖矿“），第一个找到的矿工获得记账权和区块奖励。

• 优势：经过十多年验证，安全性极高
• 劣势：能源消耗巨大，交易确认速度慢（比特币约 10 分钟一个区块）

权益证明（Proof of Stake, PoS）

PoS 中，验证者通过质押（Staking）代币来获得参与共识的权利。被选中的验证者负责提议和验证新区块。以太坊在 2022 年从 PoW 迁移到了 PoS。

• 优势：能效大幅提升，交易速度更快
• 劣势：可能出现“富者越富“的中心化趋势

拜占庭容错变体（BFT Variants）

BFT 类共识机制能够在部分节点存在恶意行为的情况下仍然达成一致。许多公链的验证者集合会采用 BFT 思路实现最终性；具体实现与命名因地而异。

• 优势：常见设计下可较快到达最终性
• 劣势：通常对验证者集合与网络假设有特定要求

Sui 以对象为中心组织状态：共享对象等多方争用场景需要网络对访问顺序达成一致；仅涉及单方拥有对象时交互面通常更简单。见第九章 §9.4；本书不展开具体共识算法名。

什么是智能合约

定义与核心思想

智能合约（Smart Contract）是部署在区块链上、由网络中的节点自动执行的程序代码。它们一旦部署，便按照预定义的规则运行，无法被单方面修改或停止——“代码即法律”（Code is Law）。

更准确地说，智能合约是一组存储在链上的函数和状态，任何人都可以通过发送交易来调用这些函数，触发状态变更。

与传统编程的区别

智能合约编程与传统的后端开发有着根本性的区别：

Gas 模型

区块链上的每一步计算都需要消耗Gas——这是防止网络滥用的经济机制。Gas 的作用包括：

1. 防止无限循环：每笔交易都有 Gas 上限，超出则交易失败
2. 资源定价：计算越复杂、存储越多，费用越高
3. 激励验证者：Gas 费用支付给验证者作为处理交易的报酬

在 Sui 上，Gas 以 SUI 代币（最小单位为 MIST，1 SUI = 10^9 MIST）支付。Sui 的 Gas 定价机制相对稳定，且支持 Gas 赞助（Sponsored Transactions），允许应用为用户代付 Gas 费。

一个智能合约的概念示例

以下伪代码展示了一个简单的数字资产合约应该具备的基本结构：

Contract DigitalAsset:

    // 定义资产结构
    struct Asset:
        id: UniqueID
        owner: Address
        name: String
        value: u64

    // 创建新资产
    function create_asset(name: String, value: u64) -> Asset:
        return Asset {
            id: generate_unique_id(),
            owner: caller_address(),
            name: name,
            value: value
        }

    // 转移资产
    function transfer_asset(asset: Asset, recipient: Address):
        require(asset.owner == caller_address(), "Not the owner")
        asset.owner = recipient

    // 查询资产
    function get_value(asset: Asset) -> u64:
        return asset.value

在 Move 语言中，这个概念可以被优雅地表达。Move 的所有权系统使得资产转移变得更加安全——你不需要手动检查调用者是否是所有者，类型系统会在编译期帮你保证：

module examples::digital_asset;

use std::string::String;

/// 一个简单的数字资产
public struct Asset has key, store {
    id: UID,
    name: String,
    value: u64,
}

/// 创建新资产
public fun create(
    name: String,
    value: u64,
    ctx: &mut TxContext,
): Asset {
    Asset {
        id: object::new(ctx),
        name,
        value,
    }
}

/// 获取资产价值
public fun value(asset: &Asset): u64 {
    asset.value
}

/// 创建并转移给接收者
entry fun mint_and_transfer(
    name: String,
    value: u64,
    recipient: address,
    ctx: &mut TxContext,
) {
    let asset = create(name, value, ctx);
    transfer::public_transfer(asset, recipient);
}

注意在 Move 中，我们不需要 require(asset.owner == caller_address()) 这样的检查——所有权由运行时自动管理。当函数接收一个 Asset 类型参数时，Sui 运行时已经验证了调用者确实拥有该对象。

智能合约的应用场景

去中心化金融（DeFi）

DeFi 是智能合约最成功的应用领域。通过智能合约，用户可以在无需银行等中介的情况下完成借贷、交易、保险等金融操作：

• 去中心化交易所（DEX）：如 Uniswap、Cetus，允许用户直接进行代币交换
• 借贷协议：如 Aave、Scallop，用户可以质押资产并借入其他代币
• 稳定币：如 DAI，通过超额抵押机制维持与美元的锚定
• 流动性质押：如 Lido、Volo，将质押资产代币化以释放流动性

非同质化代币（NFT）

NFT 是代表唯一数字资产所有权的代币。智能合约定义了 NFT 的铸造、转移和销毁规则：

• 数字艺术：艺术家可以直接向全球收藏者出售作品
• 游戏资产：游戏道具以 NFT 形式存在，玩家真正拥有自己的游戏资产
• 身份凭证：学位证书、会员资格等可以以 NFT 形式颁发

去中心化自治组织（DAO）

DAO 通过智能合约实现组织治理的自动化：

• 提案与投票：成员可以提交提案并投票表决
• 资金管理：国库资金按照投票结果自动分配
• 权限控制：不同角色拥有不同的操作权限

链上游戏（GameFi）

区块链游戏将游戏逻辑和资产管理放到链上，确保公平性和资产所有权：

• 链上随机数：确保游戏结果的公平性
• 可组合资产：不同游戏之间的资产可以互操作
• Play-to-Earn：玩家通过游戏获得真正有价值的代币奖励

为什么选择 Sui

在众多区块链平台中，Sui 具有以下独特优势：

1. 并行执行：Sui 可以同时处理不相关的交易，吞吐量远超传统区块链
2. 亚秒级终局：对于所有权明确的交易，Sui 可以在不到一秒内完成确认
3. 对象中心模型：资产是一等公民，天然适合表达数字资产的所有权
4. Move 语言的安全性：编译期消除了重入攻击、整数溢出等常见漏洞
5. 低且可预测的 Gas 费：Sui 的 Gas 定价机制更加稳定

小结

本节介绍了区块链和智能合约的基础概念。我们了解了区块链作为分布式账本的核心特性、主流共识机制的工作原理，以及智能合约与传统编程的根本区别。我们还通过一个数字资产的示例，初步体会了 Move 语言在表达资产逻辑时的优雅与安全。在下一节中，我们将深入了解 Sui 独特的技术架构，理解为什么它在性能和安全性上能够超越前代区块链。

Sui 的技术架构

Sui 是一条高性能的 Layer 1 区块链，由 Mysten Labs 开发。它从底层重新设计了区块链的执行模型——以对象（Object）而非账户为核心，通过对象级别的并行执行与验证者网络对共享状态的一致性处理，实现高吞吐与可扩展性。本节从产品级视角介绍架构要点；共识与排序的具体算法以当前主网及官方文档为准，本书不展开算法名称与演进细节。

对象中心模型 vs 账户模型

以太坊的账户模型

在以太坊中，所有状态都存储在账户下。每个账户有一个余额和一个存储空间（Storage），智能合约的数据以键值对的形式存放在合约账户的 Storage 中。

以太坊账户模型:

账户 0xAlice
├── 余额: 10 ETH
└── Nonce: 5

合约账户 0xERC20
├── 余额: 0 ETH
├── 代码: ERC20 逻辑
└── Storage:
    ├── balances[Alice] = 1000
    ├── balances[Bob] = 500
    └── totalSupply = 1500

这个模型的问题在于：Alice 和 Bob 的代币余额都存储在同一个合约的 Storage 中。当 Alice 和 Bob 同时发起转账时，即使他们的交易完全无关，由于都需要修改同一个 Storage，这两笔交易也必须顺序执行。

Sui 的对象模型

Sui 采用了完全不同的方式——数据以对象的形式存在，每个对象有唯一的 ID 和明确的所有者：

Sui 对象模型:

对象 0x1a2b (Coin<SUI>)
├── 所有者: Alice
└── 余额: 10 SUI

对象 0x3c4d (Coin<USDC>)
├── 所有者: Alice
└── 余额: 1000 USDC

对象 0x5e6f (Coin<USDC>)
├── 所有者: Bob
└── 余额: 500 USDC

在这个模型中，Alice 的 USDC（对象 0x3c4d）和 Bob 的 USDC（对象 0x5e6f）是独立的对象。当 Alice 转账给 Carol 时，她操作的是对象 0x3c4d；Bob 转账给 Dave 时，操作的是对象 0x5e6f。这两笔交易涉及不同的对象，可以被完全并行地执行。

对象模型的优势

并行交易执行

Sui 的并行执行能力是其高性能的核心来源。传统区块链（如以太坊）按顺序逐一执行交易，而 Sui 可以同时处理大量不相关的交易。

依赖关系分析

Sui 在执行交易前，会分析每笔交易涉及的对象集合。如果两笔交易操作的对象集合没有交集，它们就可以并行执行：

交易 A: Alice 转 SUI 给 Bob    → 涉及对象: {0x1a2b}
交易 B: Carol 铸造 NFT          → 涉及对象: {新对象}
交易 C: Dave 转 USDC 给 Eve    → 涉及对象: {0x7g8h}
交易 D: Alice 转 USDC 给 Frank → 涉及对象: {0x3c4d}

依赖分析:
- A, B, C, D 涉及的对象完全不同
- 四笔交易可以完全并行执行！

对比以太坊:
- 所有交易都必须排队顺序执行
- 即使交易之间完全无关

水平可扩展性

由于交易可以并行执行，Sui 的吞吐量可以随着硬件资源的增加而线性提升。增加更多的 CPU 核心和验证者节点，就能处理更多的并发交易。这种水平可扩展性是传统区块链所不具备的。

验证者与全局排序（概要）

Sui 由一组验证者共同维护账本。凡是多方可能争用同一链上可变状态的情形，网络都需要在验证者之间形成一致的排序与提交结果——具体协议名称、模块划分与性能数字会随版本迭代，本书不展开算法课；对象级并行与「共享对象为何更敏感」见第九章 §9.4。

已拥有对象 vs 共享对象

Sui 中的对象根据所有权模型分为不同类型，这直接影响你可用的并行度与交互模式（而非背诵某种「路径」名称）。

已拥有对象（Owned Objects）

已拥有对象是归属于某个特定地址的对象。只有所有者才能在交易中使用它们。

module examples::owned_demo;

/// 只有所有者能使用的资产
public struct MyAsset has key, store {
    id: UID,
    value: u64,
}

/// 创建一个已拥有对象——转移给发送者
public fun create(value: u64, ctx: &mut TxContext) {
    let asset = MyAsset {
        id: object::new(ctx),
        value,
    };
    transfer::transfer(asset, ctx.sender());
}

/// 只有所有者能调用此函数修改值
public fun update_value(asset: &mut MyAsset, new_value: u64) {
    asset.value = new_value;
}

共享对象（Shared Objects）

共享对象可以被任何人在交易中访问。由于多个用户可能同时操作共享对象，涉及共享对象的交易必须经过完整的共识排序。

module examples::shared_demo;

/// 一个共享的计数器，任何人都可以递增
public struct Counter has key {
    id: UID,
    count: u64,
}

/// 创建共享对象
fun init(ctx: &mut TxContext) {
    let counter = Counter {
        id: object::new(ctx),
        count: 0,
    };
    transfer::share_object(counter);
}

/// 任何人都可以调用此函数
public fun increment(counter: &mut Counter) {
    counter.count = counter.count + 1;
}

/// 读取计数值
public fun value(counter: &Counter): u64 {
    counter.count
}

设计选择的影响

理解已拥有对象和共享对象的区别，对于 Sui 开发者来说至关重要。它直接影响了你的合约设计：

module examples::design_choice;

/// 方案 A：共享池（多方写同一状态，需全局协调）
public struct SharedPool has key {
    id: UID,
    total_liquidity: u64,
}

/// 方案 B：个人金库（仅所有者操作，无多方争用同一可变共享状态）
public struct PersonalVault has key {
    id: UID,
    balance: u64,
}

/// 在设计合约时，需要权衡：
/// - 共享对象：适合 DEX、借贷池等必须多方协作的场景
/// - 已拥有对象：适合钱包资产、NFT 等单方主控场景

Sui 的独特特性

终局与体验（定性对比）

不同链的「确认快慢」与共识模型、区块时间有关；Sui 以对象并行与验证者网络为特点，具体数字随版本与负载变化，以官方文档与实测为准。传统对比（数量级仅作直觉）：

水平可扩展性

传统区块链的吞吐量受限于单条链的处理能力。Sui 通过对象级别的并行执行，实现了真正的水平可扩展性——增加更多的计算资源，就能获得更高的吞吐量，而不需要分片或二层扩展方案。

对象级粒度

Sui 的状态管理精确到单个对象级别，这带来了以下好处：

• 精确的 Gas 计量：按实际使用的对象存储和计算量收费
• 存储费退还：当对象被删除时，用户可以拿回预付的存储费
• 细粒度权限控制：每个对象可以有不同的所有权和访问模式

可编程交易块（PTB）

可编程交易块允许在单笔交易中组合多个操作，实现复杂的原子操作：

PTB 示例：单笔交易完成三个步骤

Transaction {
    // 步骤 1：从 DEX 购买代币
    let coin = dex::swap(sui_coin, usdc_type);

    // 步骤 2：用代币添加流动性
    let lp = pool::add_liquidity(coin);

    // 步骤 3：将 LP 代币质押
    staking::stake(lp);
}

PTB 的优势：

• 原子性：要么全部成功，要么全部回滚
• 可组合性：一个步骤的输出可以直接作为下一个步骤的输入
• Gas 效率：多个操作合并在一笔交易中，节省 Gas
• 无需合约串联：不需要编写专门的聚合合约

Sui 架构全景图

┌─────────────────────────────────────────────────────┐
│                    客户端层                           │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐         │
│   │ 钱包应用  │  │  DApp    │  │ SDK/CLI  │         │
│   └────┬─────┘  └────┬─────┘  └────┬─────┘         │
│        └──────────────┼──────────────┘               │
└───────────────────────┼─────────────────────────────┘
                        │ JSON-RPC / GraphQL
┌───────────────────────┼─────────────────────────────┐
│                    全节点层                           │
│              ┌────────▼────────┐                     │
│              │    Full Node    │                     │
│              │  ┌────────────┐ │                     │
│              │  │ 交易路由    │ │                     │
│              │  │ 状态查询    │ │                     │
│              │  │ 事件索引    │ │                     │
│              │  └────────────┘ │                     │
│              └────────┬────────┘                     │
└───────────────────────┼─────────────────────────────┘
                        │
┌───────────────────────┼─────────────────────────────┐
│                   验证者层                            │
│     ┌─────────────────▼─────────────────────┐       │
│     │            交易处理与一致性层              │       │
│     │  （对象调度、共享状态排序等，实现随版本演进）  │       │
│     └───────────────────────────────────────┘       │
│     ┌───────────────────────────────────────┐       │
│     │           Move 虚拟机 (MoveVM)          │       │
│     └───────────────────────────────────────┘       │
│     ┌───────────────────────────────────────┐       │
│     │          对象存储 (Object Store)        │       │
│     └───────────────────────────────────────┘       │
└─────────────────────────────────────────────────────┘

小结

本节从架构视角介绍了 Sui：对象模型带来并行与清晰的资产边界；验证者网络对共享状态提供一致性；具体共识与执行管线以官方文档为准。在下一节中，我们将纵览 Sui 的生态系统，了解在这个基础设施之上构建的各类应用和协议。

Sui 生态全景

本节概述 Sui 网络上的钱包、浏览器、开发者工具与主流应用方向。更细的索引与链接可在后续版本补充。

开发者入口

• 官方文档：https://docs.sui.io/
• 主网 / 测试网浏览器与网络信息见第二章 · 创建钱包与获取测试币与本书后续部署相关章节。

Move 语言的演进

Move 语言诞生于 2018 年 Facebook（现 Meta）的 Libra（后更名为 Diem）区块链项目，并于 2019 年随 Libra 白皮书首次公开亮相。它是第一种专为数字资产设计的智能合约语言，从一开始就将安全性、资源导向和形式化验证作为核心设计目标。如今，Move 已经从 Diem 的账户模型演化到 Sui 的对象模型，在保持语言内核安全特性的同时，获得了前所未有的表达力和性能。

Move 的诞生：Diem 时代

背景与设计动机

2018 年，Facebook 启动了雄心勃勃的 Libra 项目，目标是创建一个全球性的数字货币和金融基础设施。项目团队意识到，现有的智能合约语言（尤其是 Solidity）在安全性方面存在根本性的缺陷——重入攻击、整数溢出、权限管理混乱等问题导致了数十亿美元的资产损失。

为此，他们决定从零开始设计一门新语言，核心设计原则包括：

• 资源安全：数字资产不能被复制或意外销毁，就像现实世界中的物理资产
• 类型安全：通过强类型系统在编译期捕获尽可能多的错误
• 模块封装：资源类型只能由定义它的模块创建和销毁
• 形式化可验证：语言设计支持数学层面的安全性证明

线性类型与资源模型

Move 最核心的创新是引入了线性类型系统。在传统编程语言中，一个值可以被随意复制和丢弃。但在 Move 中，某些类型（资源类型）必须被恰好使用一次——不能复制，不能丢弃，只能移动（Move）。

module examples::linear_type_demo;

/// 一个不能被复制或丢弃的代币
/// 没有 copy 和 drop 能力
public struct PreciousToken has key, store {
    id: UID,
    value: u64,
}

/// 创建代币
public fun mint(value: u64, ctx: &mut TxContext): PreciousToken {
    PreciousToken {
        id: object::new(ctx),
        value,
    }
}

/// 销毁代币并取回值
public fun burn(token: PreciousToken): u64 {
    let PreciousToken { id, value } = token;
    id.delete();
    value
}

/// 以下代码将无法编译——Move 编译器阻止了不安全行为：
///
/// fun unsafe_copy(token: &PreciousToken): PreciousToken {
///     *token  // 错误! PreciousToken 没有 copy 能力
/// }
///
/// fun unsafe_drop(token: PreciousToken) {
///     // 什么都不做就返回
///     // 错误! PreciousToken 没有 drop 能力，必须被显式处理
/// }

这种设计从语言层面保证了数字资产的安全性——你的代币不可能因为编程错误而被凭空复制或消失。

Ability 系统

Move 使用**四种 Ability（能力）**来精确控制类型的行为：

module examples::abilities_demo;

/// 普通数据——可以自由复制和丢弃
public struct Point has copy, drop {
    x: u64,
    y: u64,
}

/// 链上对象——可以存储和转移，但不能复制
public struct Sword has key, store {
    id: UID,
    damage: u64,
    level: u8,
}

/// 权限凭证——只能转移，不能复制或存储到其他对象中
public struct AdminCap has key {
    id: UID,
}

从 Diem Move 到 Sui Move

账户模型 vs 对象模型

Diem/Aptos Move 和 Sui Move 最大的区别在于存储模型。

在 Diem Move 中，资源存储在账户之下。如果 Alice 想把一个 Token 转给 Bob，Bob 的账户下必须先有一个接收该类型 Token 的“容器“：

Diem Move（账户模型）:

Alice 的账户 (0xAlice)
└── Token { value: 100 }

转移前提: Bob 的账户必须先执行 "accept<Token>()" 创建空容器
Bob 的账户 (0xBob)
└── Token { value: 0 }  ← 必须预先存在！

转移过程:
1. 从 Alice 账户取出 Token
2. 检查 Bob 账户是否有 Token 容器
3. 合并到 Bob 的 Token 中

Sui Move 彻底改变了这个模型。在 Sui 中，对象是一等公民，拥有全局唯一 ID 和独立的所有权。Alice 可以直接将对象转给 Bob，无需 Bob 做任何准备：

Sui Move（对象模型）:

对象 0xAABB (Token)
├── id: 0xAABB
├── owner: Alice
└── value: 100

转移过程:
1. 更改对象 0xAABB 的 owner 为 Bob
就这么简单！Bob 不需要做任何操作。

代码对比

以下代码展示了同样的“转移代币“操作在两种模型中的差异：

// ===== Sui Move 风格 =====
module examples::sui_token;

public struct Token has key, store {
    id: UID,
    value: u64,
}

/// 铸造并直接转给接收者
/// Bob 不需要任何前置操作！
public fun mint_and_send(
    value: u64,
    recipient: address,
    ctx: &mut TxContext,
) {
    let token = Token {
        id: object::new(ctx),
        value,
    };
    transfer::public_transfer(token, recipient);
}

在 Diem/Aptos Move 中，类似操作需要更多的样板代码——接收者需要先“注册“才能接收资源。Sui 的对象模型消除了这种摩擦，让数字资产的转移像发送电子邮件一样简单。

关键差异总结

Move vs Solidity

对于从以太坊转来的开发者，理解 Move 和 Solidity 的区别尤为重要。

类型安全

Solidity 中的代币本质上是一个映射表中的数字，没有类型安全保障：

// Solidity — 代币只是一个数字
mapping(address => uint256) public balances;

function transfer(address to, uint256 amount) public {
    require(balances[msg.sender] >= amount);
    balances[msg.sender] -= amount;
    balances[to] += amount;
}

Move 中的代币是一个真正的类型对象，编译器保证它不能被凭空创造或复制：

module examples::move_token;

/// 代币是一个有 Ability 约束的结构体
/// 只能通过 mint 创建，通过 burn 销毁
public struct Token has key, store {
    id: UID,
    value: u64,
}

/// 唯一的创建途径
public fun mint(treasury: &mut Treasury, value: u64, ctx: &mut TxContext): Token {
    treasury.total_supply = treasury.total_supply + value;
    Token { id: object::new(ctx), value }
}

/// 唯一的销毁途径
public fun burn(treasury: &mut Treasury, token: Token) {
    let Token { id, value } = token;
    treasury.total_supply = treasury.total_supply - value;
    id.delete();
}

public struct Treasury has key {
    id: UID,
    total_supply: u64,
}

重入攻击

重入攻击是 Solidity 中最臭名昭著的安全漏洞，2016 年的 The DAO 事件导致了 6000 万美元的损失。

// Solidity — 存在重入风险
function withdraw(uint256 amount) public {
    require(balances[msg.sender] >= amount);
    // 危险！先转账，再更新余额
    (bool success,) = msg.sender.call{value: amount}("");
    require(success);
    balances[msg.sender] -= amount;  // 攻击者可以在这之前重复调用 withdraw
}

Move 从语言设计上完全消除了重入攻击的可能性：

1. 没有动态调度：Move 的函数调用在编译时完全确定，不存在 Solidity 中的 call 机制
2. 线性类型：资源在同一时刻只能有一个所有者，不可能在持有资源的同时将其传递给外部代码
3. 借用检查：Move 的引用系统保证不会出现可变引用和不可变引用同时存在的情况

module examples::safe_withdraw;

use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::balance::Balance;

const EInsufficientBalance: u64 = 0;

/// Move 中的提款——天然安全，无需特殊防护
public fun withdraw(vault: &mut Vault, amount: u64, ctx: &mut TxContext): Coin<SUI> {
    assert!(vault.balance >= amount, EInsufficientBalance);
    vault.balance = vault.balance - amount;
    // 返回 Coin 对象，调用者获得所有权
    // 不存在回调机制，不可能触发重入
    coin::take(&mut vault.coin_balance, amount, ctx)
}

public struct Vault has key {
    id: UID,
    balance: u64,
    coin_balance: Balance<SUI>,
}

全面对比

Move 的核心价值观

Move 语言的设计哲学可以概括为三个核心价值：

1. 默认安全（Secure by Default）

安全不是事后添加的特性，而是融入语言 DNA 的设计原则。Move 编译器会在你的代码运行之前就捕获绝大多数安全漏洞：

module examples::secure_by_default;

/// 编译器保证:
/// 1. NFT 不能被复制（没有 copy ability）
/// 2. NFT 不能被意外丢弃（没有 drop ability）
/// 3. 只有该模块能创建和销毁 NFT
public struct NFT has key, store {
    id: UID,
    name: vector<u8>,
}

/// 这是创建 NFT 的唯一入口
public fun mint(name: vector<u8>, ctx: &mut TxContext): NFT {
    NFT { id: object::new(ctx), name }
}

/// 这是销毁 NFT 的唯一入口
public fun burn(nft: NFT) {
    let NFT { id, name: _ } = nft;
    id.delete();
}

/// 模块外的代码无法绕过这些函数来创建或销毁 NFT
/// 这是由 Move 的模块封装机制在语言层面保证的

2. 天然表达力（Expressive by Nature）

Move 提供了丰富的原语来表达复杂的数字资产逻辑。可编程对象、动态字段、可编程交易块等特性让开发者能够构建高度灵活的应用：

module examples::expressive;

use sui::dynamic_field;

/// 一个可以动态扩展属性的角色
public struct Character has key {
    id: UID,
    name: vector<u8>,
    level: u64,
}

/// 装备武器——使用动态字段
public fun equip_weapon(character: &mut Character, weapon: Weapon) {
    dynamic_field::add(&mut character.id, b"weapon", weapon);
}

/// 武器本身也是一个结构体
public struct Weapon has store {
    name: vector<u8>,
    damage: u64,
}

/// 在 PTB 中，这些操作可以组合在一笔交易中:
/// 1. 铸造角色
/// 2. 铸造武器
/// 3. 装备武器
/// 4. 将角色转给玩家
/// 全部在一笔交易中原子性完成！

3. 对所有人直觉化（Intuitive for All）

Move 2024 Edition 引入了大量语法改进，让代码更加简洁和直观：

module examples::intuitive;

use std::string::String;

public struct Profile has key {
    id: UID,
    name: String,
    bio: String,
    score: u64,
}

public fun create_profile(
    name: String,
    bio: String,
    ctx: &mut TxContext,
): Profile {
    Profile {
        id: object::new(ctx),
        name,
        bio,
        score: 0,
    }
}

/// Move 2024 方法语法——像调用对象方法一样
public fun update_score(profile: &mut Profile, delta: u64) {
    profile.score = profile.score + delta;
}

/// 使用示例（在测试或 PTB 中）:
/// let profile = create_profile(name, bio, ctx);
/// profile.update_score(10);  // 方法语法：直观！

Move 语言时间线

2018 年
├── Facebook 启动 Libra 项目
└── Move 语言开始设计和开发

2019 年
├── 6 月: Libra 白皮书发布，Move 首次公开亮相
└── Move 技术论文发表

2020 年
├── Libra 更名为 Diem
├── 第一个 Move 网络启动
└── Move Prover（形式化验证工具）发布

2021 年
├── Mysten Labs 成立（由前 Meta/Novi 核心成员创建）
└── Sui 项目启动，开始设计对象模型

2022 年
├── Meta 宣布关闭 Diem 项目
├── Sui 测试网上线
├── Move 社区分化：Aptos Move（账户模型）vs Sui Move（对象模型）
└── Sui 获得大规模融资

2023 年
├── 5 月: Sui 主网正式上线
├── Move 2024 Edition 预览
└── zkLogin、DeepBook 等创新功能发布

2024 年
├── Move 2024 Edition 正式发布
├── 枚举类型、方法语法等新特性落地
├── Walrus 去中心化存储发布
└── Sui 生态快速扩张

2025–2026 年
├── Move 语言持续演进
├── Sui 性能进一步优化
└── 生态项目全面开花

Move 的核心技术要素

可编程对象（Programmable Objects）

每个 Sui 对象都有唯一 ID、明确的所有权和类型化的数据。对象是 Move 在 Sui 上最核心的抽象单元。

Ability 系统（线性类型）

四种 Ability（key、store、copy、drop）精确控制值的生命周期行为，从编译期保证资源安全。

模块系统与强封装

Move 的模块是类型和函数的命名空间。关键安全属性：只有定义类型的模块才能创建、销毁和访问该类型的内部字段。这种封装是不可绕过的。

动态字段（Dynamic Fields）

允许在运行时向对象添加任意类型的键值对，实现灵活的数据模型扩展，而不需要预先定义所有字段。

可编程交易块（PTBs）

允许在单笔交易中组合多个 Move 调用，前一个调用的返回值可以直接作为后一个调用的参数。这是 Sui 独有的强大特性，实现了无合约级别的可组合性。

小结

Move 语言从 2018 年 Facebook Libra 项目中诞生，经历了从 Diem 到 Sui 的重大演化。它的核心设计——线性类型、Ability 系统、模块封装——在 Sui 的对象模型中得到了最充分的发挥。与 Solidity 相比，Move 在类型安全、资产安全和重入防护方面具有本质性的优势。Move 2024 Edition 进一步提升了语言的表达力和开发者体验，使其成为当前最先进的智能合约语言之一。从下一章开始，我们将搭建开发环境，亲手编写第一个 Move 程序，开始真正的 Move on Sui 之旅。

第一章 · 实战练习

实战一：确认本机工具链

1. 安装或更新 Sui CLI（若使用 suiup，按第二章 §2.1切换版本）。
2. 执行 sui --version，记下主版本号，与官方发布说明对照。
3. 验收：终端能输出 sui 版本，无报错。

实战二：在浏览器里读一笔真实交易

1. 打开 Sui Explorer（或测试网 Explorer），任选最近一笔成功交易。
2. 在页面上找到：发送者、Gas、至少一个 Input、Effects 中的变更摘要。
3. 验收：用自己的话写 3～5 句话，说明「这笔交易在链上改变了什么状态」。

实战三：对象模型 vs 账户模型（小短文）

1. 回顾本章 1.2 中关于 Sui 以对象为中心的表述。
2. 对比你熟悉的「全局账户 nonce」模型，列出 2 条 Sui 设计带来的直接后果（例如并行性、费用支付对象等）。
3. 验收：写成一段不超过 200 字的笔记即可。

第二章 · 开发环境搭建

本章将指导你从零搭建完整的 Sui Move 开发环境，包括 CLI 工具、IDE 配置、钱包创建和网络连接。Move 2024 Edition 的完整语法对照与 Move.toml 约定集中在第六章 §6.11，避免入门阶段信息过载；前三章只需跟示例能 sui move build 即可。

本章内容

学习目标

读完本章后，你将能够：

• 安装 Suiup 与 Sui CLI，在本地运行 sui / suiup 并查看版本（必要时切换 testnet/devnet 构建）
• 在 VS Code 中获得 Move 代码的语法高亮和错误提示
• 拥有一个 devnet/testnet 钱包并持有测试 SUI

本章实战练习

每章 1～3 个动手任务见 hands-on.md（目录中亦列为「本章实战练习」）。

安装 Sui CLI 与 Suiup

Sui CLI 是开发 Move 合约、编译测试、部署并与链交互的核心工具。Suiup 是 Mysten Labs 提供的 Sui 生态工具链安装与版本管理器（类似其他语言的版本管理工具）：一键安装预编译 sui，并可在 testnet / devnet / mainnet 等版本间切换，通常 无需 自行从源码编译。

本节将 先介绍推荐路径（安装 suiup → 再安装 sui），再列出 Homebrew、预编译包、源码等 备选方式，最后说明 版本管理、诊断与常见问题。

为何需要 Sui CLI

Sui CLI 集成了项目创建、sui move build / test、部署、客户端与环境切换等能力，是后续各章的默认命令行入口。

推荐：先安装 Suiup，再安装 Sui

为何优先用 Suiup

在广泛使用 suiup 之前，安装 sui 往往需要本地 Rust 工具链并从源码编译（耗时长）。Suiup 提供：

安装 Suiup

macOS / Linux（常用）：在终端执行：

curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh

脚本会检测系统与架构，并将 suiup 安装到 ~/.local/bin/（若使用自定义路径，见下文）。安装后 重启终端，或执行：

source ~/.bashrc   # bash
source ~/.zshrc    # zsh（macOS 常见）

验证：

suiup --version

自定义安装目录：

SUIUP_INSTALL_DIR=/opt/suiup curl -sSfL https://raw.githubusercontent.com/MystenLabs/suiup/main/install.sh | sh

已安装 Rust 时 也可用 Cargo：

cargo install --git https://github.com/MystenLabs/suiup.git --locked

Windows：从 suiup Releases 下载 suiup-Windows-msvc-x86_64.zip，解压后将 suiup.exe 加入 PATH。

用 Suiup 安装 Sui CLI

# 安装最新 testnet 构建（默认常用）
suiup install sui

# 按网络安装
suiup install sui@testnet
suiup install sui@devnet
suiup install sui@mainnet

# 指定版本号（示例）
suiup install sui@testnet-1.40.1
suiup install sui@1.44.2

# CI 等非交互场景可跳过确认
suiup install sui -y

安装完成后验证：

sui --version
sui client --version

测试覆盖率（sui move test --coverage）需要 debug 构建时：

suiup install sui --debug

需要跟踪最新开发分支（需本地 Rust）时：

suiup install sui --nightly
# 或指定分支，例如：
# suiup install sui --nightly releases/sui-v1.45.0-release

提示：官方也提供一键安装脚本的短链入口（若文档有更新，以 docs.sui.io 当前说明为准）。本书示例以 suiup 命令 为主。

其他安装方式（备选）

若你暂时不想使用 Suiup，可选用下列方式之一安装 sui；版本管理仍建议后续改用 Suiup，以免多网络切换时手工换二进制。

Homebrew（macOS）

brew install sui

Chocolatey（Windows）

choco install sui

预编译二进制

1. 打开 Sui Releases
2. 选择版本，下载对应平台的压缩包
3. 解压后将 sui 放到 PATH 中的目录

# macOS / Linux 示例
tar -xzf sui-<version>-<platform>.tgz
sudo mv sui /usr/local/bin/

从源码编译（Cargo）

需要较长时间与足够磁盘/内存：

cargo install --git https://github.com/MystenLabs/sui.git sui --branch testnet
# 或 --branch mainnet 等

使用 Suiup 管理版本与默认 CLI

同时安装多版本时，常用命令：

suiup show                    # 已安装版本与默认项
suiup switch sui@testnet      # 快速切换
suiup default set sui@devnet    # 设置默认
suiup default get
suiup which                   # 当前默认二进制路径

升级与自检：

suiup update sui
suiup update sui@testnet
suiup self update             # 升级 suiup 自身
suiup doctor                  # 环境诊断（PATH、二进制完整性等）

缓存与卸载：

suiup cleanup                 # 清理下载缓存（可加 --days、--all、--dry-run）
suiup remove sui              # 卸载某工具（具体行为以当前 CLI 为准）
suiup self uninstall          # 卸载 suiup

CI 提示：可向环境注入 GITHUB_TOKEN 以降低 GitHub API 限流概率；示例见 suiup 文档或本书仓库历史中的 GitHub Actions 片段。

生态工具（可选，与 IDE 联动）

除 sui 外，开发时常一并安装：

suiup list
suiup install move-analyzer
suiup install mvr

与 §2.2 · IDE 配置 中的 Move Analyzer 一致：推荐用 suiup 安装 move-analyzer，便于与 sui 版本统一管理。

常见问题

找不到 sui 或 suiup

• 确认 ~/.local/bin（或你的安装目录）已在 PATH 中。
• 执行 suiup which 查看期望路径；必要时在 ~/.zshrc / ~/.bashrc 中追加 export PATH="$HOME/.local/bin:$PATH"。

与目标网络协议版本不匹配

部署或调用前，用 suiup install sui@<对应网络> 与 suiup switch 对齐；并用 sui client envs 查看当前客户端环境。

源码编译失败

安装 Xcode 命令行工具（macOS）或 build-essential、libssl-dev 等（Linux）；预留足够磁盘与内存。

权限问题

确保二进制有执行权限；安装到系统目录时可能需要 sudo。

小结

• 推荐路径：安装 Suiup → suiup install sui（可按网络/版本细化）→ sui --version 验收。
• 备选：Homebrew、Chocolatey、预编译包、Cargo 源码编译。
• 长期维护：用 suiup show / switch / update / doctor 管理版本与排障；需要 IDE 时再装 move-analyzer（见下一节）。

下一节配置 IDE 与 Move Analyzer，便于编写与调试 Move 代码。

IDE 开发环境配置

一个良好的 IDE 配置可以显著提升 Move 开发效率。通过语言服务器的支持，你可以获得代码补全、实时错误检查、跳转定义等功能，避免许多低级错误。本节将详细介绍如何配置主流编辑器来支持 Move 开发。

Visual Studio Code（推荐）

VSCode 是目前 Move 开发体验最好的编辑器，拥有最完善的插件生态。

安装 Move 扩展

Move（Mysten Labs 官方扩展）

这是 Sui Move 开发的核心扩展，由 Mysten Labs 官方维护，提供：

• Move Analyzer 语言服务器：实时语法和类型检查
• 代码补全：智能提示函数、类型、模块名等
• 跳转定义：Cmd/Ctrl + 点击 跳转到符号定义
• 悬停文档：鼠标悬停显示类型信息和文档
• 错误诊断：编译错误实时显示在编辑器中

安装步骤：

1. 打开 VSCode
2. 按 Cmd+Shift+X（macOS）或 Ctrl+Shift+X（Windows/Linux）打开扩展面板
3. 搜索 “Move” 并安装由 Mysten Labs 发布的扩展

注意：市场上有多个名为 “Move” 的扩展，请确认发布者是 Mysten Labs，而非其他第三方。

Move Formatter

基于 prettier-plugin-move 的代码格式化扩展，帮助你保持代码风格一致：

1. 在扩展面板搜索 “Move Formatter” 并安装
2. 在 VSCode 设置中将 Move 文件的默认格式化工具设为此扩展

在 VSCode 的 settings.json 中添加：

{
    "[move]": {
        "editor.defaultFormatter": "mysten.prettier-move",
        "editor.formatOnSave": true
    }
}

Move Syntax

提供增强的 Move 语法高亮支持，让代码更易阅读。在扩展面板搜索 “Move Syntax” 并安装即可。

VSCode 推荐配置

以下是一份针对 Move 开发优化的 VSCode 配置：

{
    "editor.tabSize": 4,
    "editor.insertSpaces": true,
    "editor.rulers": [100],
    "editor.wordWrap": "off",
    "[move]": {
        "editor.defaultFormatter": "mysten.prettier-move",
        "editor.formatOnSave": true,
        "editor.tabSize": 4
    },
    "files.associations": {
        "Move.toml": "toml"
    }
}

工作区设置

对于多包项目，建议创建 .vscode/settings.json 进行工作区级别配置：

{
    "move.sui.path": "/usr/local/bin/sui",
    "move.server.path": "/path/to/move-analyzer",
    "move.lint": true
}

其中 move.server.path 仅在扩展找不到 move-analyzer 时需要填写；move.sui.path 仅在 sui 不在默认 PATH 上时需要填写。

其他编辑器

IntelliJ IDEA

JetBrains 系列 IDE 用户可以使用 Move Language Plugin：

1. 打开 Settings/Preferences → Plugins → Marketplace
2. 搜索 “Move Language”，安装由 MoveFuns 发布的插件
3. 重启 IDE

该插件提供：

• Move 语法高亮
• 基本代码补全
• 项目结构识别
• Move.toml 文件支持

提示：IntelliJ 的 Move 插件功能不如 VSCode 扩展完善，但对于习惯 JetBrains 生态的开发者来说仍是不错的选择。

Emacs

Emacs 用户可以使用 move-mode：

# 通过 MELPA 安装
M-x package-install RET move-mode RET

或在 Emacs 配置文件中添加：

(use-package move-mode
  :ensure t
  :mode "\\.move\\'"
  :hook (move-mode . (lambda ()
                       (setq tab-width 4)
                       (setq indent-tabs-mode nil))))

Zed

Zed 编辑器通过其扩展系统提供 Move 支持：

1. 打开 Zed
2. 通过命令面板 Cmd+Shift+P 搜索 “Extensions”
3. 搜索并安装 Move 语言扩展

GitHub Codespaces

如果你不想配置本地环境，GitHub Codespaces 是一个很好的选择：

1. 在 Sui 相关仓库中点击 “Code → Codespaces → New codespace”
2. Codespaces 会自动配置开发环境
3. 在线上 VSCode 中安装上述推荐的 Move 扩展

配置 Move Analyzer

move-analyzer 是独立的语言服务器程序：在系统里表现为单独的 move-analyzer 可执行文件，由 Mysten 的 Move VSCode 扩展通过 LSP 调用。它不是 sui CLI 的子命令——没有 sui move analyzer 这类用法；构建与测试仍由 sui move build / sui move test 完成，与语言服务器是两回事。

安装（推荐：suiup）

与第二章 §2.1 · 安装 Sui CLI 与 Suiup一致，推荐用 suiup 安装 move-analyzer，便于与 sui、mvr 等统一版本管理：

suiup install move-analyzer

安装完成后（若 shell 已按 suiup 说明加载 PATH），可在终端验证：

which move-analyzer
move-analyzer --version

若找不到命令，执行 suiup which 查看各工具的安装路径，把对应 bin 目录加入 PATH，或直接在 VSCode 里为扩展指定二进制路径（见下）。

VSCode 中的两项路径（勿混淆）

扩展里常见两个设置，含义不同：

默认情况下，扩展会在 ~/.sui/bin（Windows 为 C:\Users\<用户>\.sui\bin）查找 move-analyzer。通过 suiup 安装时若二进制不在该目录，请将 move.server.path 设为 which move-analyzer 输出的完整路径，并重启 VSCode。

which sui
which move-analyzer

备选：也可依赖扩展安装时下载的平台 move-analyzer，或按 Sui 文档 · Move IDE 使用 cargo install … sui-move-lsp 等方式；无论何种来源，扩展都是通过 move.server.path（或默认目录）定位 move-analyzer，与 sui 的路径无关。

开发工作流

一个高效的 Move 开发工作流通常包括以下步骤：

编辑 - 检查 - 构建 - 测试循环

# 1. 编辑代码（在 IDE 中进行，实时错误检查）

# 2. 构建项目
sui move build

# 3. 运行测试
sui move test

# 4. 运行特定测试
sui move test test_function_name

# 5. 查看测试覆盖
sui move test --coverage

集成终端

建议在 VSCode 中使用集成终端（Ctrl + ~），这样你可以在同一个窗口中编辑代码和运行命令。你可以设置常用命令的快捷方式：

// .vscode/tasks.json
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Move Build",
            "type": "shell",
            "command": "sui move build",
            "group": "build",
            "problemMatcher": []
        },
        {
            "label": "Move Test",
            "type": "shell",
            "command": "sui move test",
            "group": "test",
            "problemMatcher": []
        }
    ]
}

配置完成后，你可以通过 Cmd+Shift+B（macOS）或 Ctrl+Shift+B（Windows/Linux）快速运行构建任务。

小结

本节介绍了多种编辑器的 Move 开发环境配置，其中 VSCode + Mysten Labs 官方 Move 扩展是目前最推荐的方案。关键要确保以下三个功能正常工作：实时错误检查（通过独立可执行文件 move-analyzer，推荐 suiup install move-analyzer）、代码格式化（通过 Move Formatter）和语法高亮（通过 Move Syntax）；并分清 move.server.path（move-analyzer） 与 move.sui.path（sui CLI）。配合集成终端和自动化任务，你将拥有一个流畅的 Move 开发体验。下一节我们将配置钱包并获取测试币，为部署合约做准备。

钱包与测试币

在 Sui 上部署和调用智能合约需要消耗 SUI 代币作为 Gas 费用。在开发阶段，我们可以通过 Sui CLI 创建钱包并从水龙头（Faucet）获取免费测试币。本节将介绍钱包的创建、网络环境切换以及测试币的获取方法。

创建钱包

首次初始化

第一次运行 sui client 时，CLI 会引导你完成钱包初始化：

sui client

系统会依次提示你配置以下内容：

Config file ["/Users/<username>/.sui/sui_config/client.yaml"] doesn't exist, do you want to connect to a Sui Full node server [y/N]?

输入 y 后选择连接的网络：

Sui Full node server URL (Defaults to Sui Devnet if not specified) :

可选的网络地址：

接下来选择密钥方案：

Select key scheme to generate keypair (0 for ed25519, 1 for secp256k1, 2 for secp256r1):

三种密钥方案的区别：

• ed25519（推荐）：最常用的方案，性能好，安全性高
• secp256k1：与比特币和以太坊使用相同的曲线，适合跨链场景
• secp256r1：也称为 P-256，广泛用于 Web 标准和硬件安全模块

建议：如果没有特殊需求，选择 0（ed25519）即可。

初始化完成后，系统会生成一个新的密钥对并显示你的地址：

Generated new keypair and alias for address with scheme "ed25519" [trusting-sapphire: 0x...]

导入已有密钥

如果你已有私钥或助记词，可以导入：

# 通过助记词导入
sui keytool import "<your-mnemonic-phrase>" ed25519

# 通过私钥导入
sui keytool import <private-key-base64> ed25519

地址管理

查看当前活跃地址

sui client active-address

输出示例：

0x7d20dcdb2bca4f508ea9613994683eb4e76e9c4ed371169571c0156a9e38437e

查看所有地址

sui client addresses

生成新地址

sui keytool generate ed25519

切换活跃地址

sui client switch --address <地址或别名>

网络环境管理

查看当前环境

sui client envs

输出示例：

╭──────────┬─────────────────────────────────────────┬────────╮
│ alias    │ url                                     │ active │
├──────────┼─────────────────────────────────────────┼────────┤
│ devnet   │ https://fullnode.devnet.sui.io:443      │ *      │
│ testnet  │ https://fullnode.testnet.sui.io:443     │        │
╰──────────┴─────────────────────────────────────────┴────────╯

添加新环境

# 添加 devnet
sui client new-env --alias devnet --rpc https://fullnode.devnet.sui.io:443

# 添加 testnet
sui client new-env --alias testnet --rpc https://fullnode.testnet.sui.io:443

# 添加 mainnet
sui client new-env --alias mainnet --rpc https://fullnode.mainnet.sui.io:443

# 添加本地网络
sui client new-env --alias local --rpc http://127.0.0.1:9000

切换网络

sui client switch --env devnet

注意：切换网络后，你的地址不变，但链上状态（余额、对象等）是网络独立的。也就是说，你在 devnet 上的余额和 testnet 上的余额是完全独立的。

获取测试币

通过 CLI 获取

在 devnet 或 testnet 上，你可以通过内置的水龙头命令获取免费测试币：

# 确保已切换到 devnet 或 testnet
sui client switch --env devnet

# 请求测试币
sui client faucet

成功后会看到类似输出：

Request successful. It can take up to 1 minute to get the coin.

提示：水龙头有请求频率限制，如果收到速率限制错误，请等待一段时间后重试。

通过 Web 水龙头获取

你也可以通过浏览器访问水龙头页面：

• Devnet：https://faucet.devnet.sui.io/
• Testnet：https://faucet.testnet.sui.io/

输入你的地址即可获取测试币。

通过 cURL 获取

curl --location --request POST 'https://faucet.devnet.sui.io/v2/gas' \
--header 'Content-Type: application/json' \
--data-raw "{
    \"FixedAmountRequest\": {
        \"recipient\": \"$(sui client active-address)\"
    }
}"

查看余额和对象

查看余额

sui client balance

输出示例：

╭─────────────────────────────────────────╮
│ Balance of coins owned by this address  │
├─────────────────────────────────────────┤
│ ╭─────────────────┬────────────────╮    │
│ │ coin            │ balance (MIST) │    │
│ ├─────────────────┼────────────────┤    │
│ │ 0x2::sui::SUI   │ 1000000000     │    │
│ ╰─────────────────┴────────────────╯    │
╰─────────────────────────────────────────╯

换算关系：1 SUI = 10^9 MIST。上面的 1000000000 MIST 就是 1 SUI。

查看拥有的对象

sui client objects

输出会列出你地址下所有的对象，包括 SUI 代币（Coin 对象）和其他资产。

查看特定对象详情

sui client object <object-id>

# 以 JSON 格式查看
sui client object <object-id> --json

安全提醒

• 永远不要在公开场合分享你的私钥或助记词
• 密钥文件默认存储在 ~/.sui/sui_config/sui.keystore
• 开发时使用 devnet/testnet，不要用主网私钥进行测试
• 建议为开发和生产使用不同的密钥对

小结

本节介绍了如何通过 Sui CLI 创建钱包、管理地址、切换网络环境以及获取测试币。核心命令包括：sui client（初始化）、sui client active-address（查看地址）、sui client switch --env（切换网络）、sui client faucet（获取测试币）和 sui client balance（查看余额）。这些是后续开发和部署合约的基础操作。下一节我们将了解 Move 2024 版本的新特性。

第二章 · 实战练习

实战一：环境自检脚本

1. 在仓库中执行：src/02_getting_started/code/check-env.sh（需已安装 sui）。
2. 若失败，按本章 2.1 节重装或修正 PATH。
3. 验收：脚本打印 sui 版本号。

实战二：测试网钱包与水龙头

1. 按 2.3 节创建地址：sui client new-address ed25519（或你使用的方案）。
2. 配置 sui client 指向 testnet，从水龙头领取测试 SUI。
3. 验收：sui client balance（或等价命令）显示非零余额。

实战三：确认示例包可构建

1. 克隆或进入仓库后，打开 src/03_first_move/code/hello_world/。
2. 执行 sui move build（无需先理解 Move.toml 中每一项含义）。
3. 验收：构建成功。若对 edition / rev 有疑问，读完第五～六章后再看第六章 §6.11。

第三章 · 第一个 Move 程序

本章将带你动手编写、编译、测试和部署第一个 Move 智能合约，完成从代码到链上的全流程。本章属于偏实战的入门综合章：在尚未讲完语言细节的前提下，先让你跑通工具链与发布流程，后续第四至七章再系统补全语法与语义。

本章内容

学习目标

读完本章后，你将能够：

• 独立创建一个 Move 项目并编写简单模块
• 将合约部署到 Sui devnet
• 通过 CLI 调用链上合约并查看结果

本章实战练习

每章 1～3 个动手任务见 hands-on.md（目录中亦列为「本章实战练习」）。

Hello, World!

与侧边栏目录对应：3.1 Hello World — 编写、编译与测试

每位开发者学习新语言的第一步，几乎都是编写一个 “Hello, World!” 程序。在 Move 中，我们将创建一个完整的 Move 包，编写模块和测试，并通过 Sui CLI 完成构建与测试。本节将带你体验从零开始创建 Move 项目的完整流程。

创建 Move 包

使用 sui move new 命令创建一个新的 Move 项目：

sui move new hello_world

该命令会生成以下目录结构：

hello_world/
├── Move.toml
├── sources/
│   └── hello_world.move
└── tests/
    └── hello_world_tests.move

各文件和目录的作用：

理解 Move.toml

打开生成的 Move.toml 文件：

[package]
name = "hello_world"
edition = "2024"

[addresses]
hello_world = "0x0"

依赖：Sui 1.45 起 Framework 为隐式依赖，Move.toml 中无需再写 Sui = { git = ... }。若你使用较旧工具链，可按第六章 §6.11补全 [dependencies]。

rev 说明：与第六章 §6.11 · Move 2024 Edition中的约定一致，默认使用 framework/mainnet。若你仅用 testnet/devnet 且希望与 CLI 模板习惯一致，可改为 framework/testnet，并与当前 sui client 环境匹配。

各字段含义：

[package]

• name：包名称，在依赖引用时使用
• edition：Move 语言版本。建议设为 "2024" 以使用最新语法

[dependencies]

新版本工具链下 Sui Framework 为隐式依赖；若显式声明，则与清单文件一致，指向 Mysten 仓库的 framework/mainnet 等分支。Framework 提供 object::UID、TxContext、transfer 等。

[addresses]

定义地址别名。hello_world = "0x0" 表示本包在本地开发时使用 0x0 作为地址占位符，发布到链上后会被替换为实际的包地址。

编写模块

打开 sources/hello_world.move，将内容替换为：

/// 与本书 3.1「Hello World」对应：创建一个可上链的 `Hello` 对象并转移给交易发送者。
module hello_world::hello_world;

use std::string::String;

/// 链上可拥有的问候对象；发布后调用 `mint_hello` 可在钱包或区块浏览器里看到。
public struct Hello has key, store {
    id: object::UID,
    greeting: String,
}

public fun greeting(hello: &Hello): &String {
    &hello.greeting
}

/// 构造 `Hello`（供测试或其它模块组合使用）。
public fun new_hello(ctx: &mut TxContext): Hello {
    Hello {
        id: object::new(ctx),
        greeting: b"Hello, World!".to_string(),
    }
}

/// 铸造 `Hello` 并转移给当前交易发送者（链上会产生新对象 ID）。
entry fun mint_hello(ctx: &mut TxContext) {
    let hello = new_hello(ctx);
    transfer::public_transfer(hello, ctx.sender());
}

模块声明与导入

module hello_world::hello_world;

use std::string::String;

• hello_world（地址别名）与 hello_world（模块名）与 Move.toml 中 [addresses] 对应；分号结尾为 Move 2024 文件级模块语法。
• 仅显式导入 String；object、transfer、TxContext 等由 Sui 预导入，可直接写 object::new、TxContext 等。

对象类型 Hello

public struct Hello has key, store {
    id: object::UID,
    greeting: String,
}

• has key：表示这是 Sui 对象，首字段必须是 id: UID。
• has store：对象可被转移，也可作为字段嵌入其它类型（后续章节会深入）。
• greeting：本例在链上可读的一段 UTF-8 文本，便于在浏览器里看出「这是 Hello 示例」。

构造函数与 entry

public fun new_hello(ctx: &mut TxContext): Hello { /* ... */ }

entry fun mint_hello(ctx: &mut TxContext) {
    let hello = new_hello(ctx);
    transfer::public_transfer(hello, ctx.sender());
}

• new_hello：用 object::new(ctx) 分配唯一 id，在内存 / 测试中也可单独调用。
• entry fun mint_hello：入口函数，可从钱包或 CLI 作为一笔交易的唯一调用直接执行（无需被其它 Move 模块再包装）。内部把新建的 Hello public_transfer 给 ctx.sender()，即当前交易的发送地址，因此发布后你用自己的地址调用，就会在自己的名下出现一个新的 Hello 对象。
• 这样不再只是「返回一个字符串」的纯函数，而是在链上创建可查询的对象，与真实 DApp 的「铸造 NFT / 道具」是同一类模式的最小版。

注意：Move 函数中最后一个表达式会自动作为返回值；无返回值的函数体以分号或控制流结束。

编写测试

打开 tests/hello_world_tests.move，将内容替换为：

#[test_only]
module hello_world::hello_world_tests;

use hello_world::hello_world::{Self, Hello};
use std::unit_test::destroy;

#[test]
fun test_greeting() {
    let ctx = &mut tx_context::dummy();
    let hello: Hello = hello_world::new_hello(ctx);
    assert!(hello_world::greeting(&hello) == b"Hello, World!".to_string());
    destroy(hello);
}

测试模块属性

#[test_only]
module hello_world::hello_world_tests;

#[test_only] 标注表示这个模块仅在测试时编译，不会包含在发布的包中。

测试函数

• #[test]：标记该函数为测试函数。
• 使用 tx_context::dummy() 模拟交易上下文，调用 new_hello 得到带 key 的对象；测试结束用 std::unit_test::destroy 回收对象（仅测试环境可用）。
• 测试函数不需要 public 修饰符。

构建项目

在项目根目录下运行：

cd hello_world
sui move build

成功构建的输出：

UPDATING GIT DEPENDENCY https://github.com/MystenLabs/sui.git
INCLUDING DEPENDENCY Sui
INCLUDING DEPENDENCY MoveStdlib
BUILDING hello_world

如果代码有错误，编译器会给出详细的错误信息和位置提示：

error[E01002]: unexpected token
   ┌─ sources/hello_world.move:5:1
   │
 5 │ public fun hello_world() String {
   │                          ^^^^^^
   │                          Expected ':'

提示：第一次构建会下载 Sui Framework 依赖，可能需要一些时间。后续构建会使用缓存，速度会快很多。

运行测试

sui move test

成功输出：

INCLUDING DEPENDENCY Sui
INCLUDING DEPENDENCY MoveStdlib
BUILDING hello_world
Running Move unit tests
[ PASS    ] hello_world::hello_world_tests::test_greeting
Test result: OK. Total tests: 1; passed: 1; failed: 0

运行特定测试

如果项目中有多个测试，可以通过名称过滤：

# 只运行名称包含 "hello" 的测试
sui move test hello

查看详细输出

# 显示测试过程中的调试信息
sui move test --verbose

测试覆盖率

sui move test --coverage

# 查看覆盖率报告
sui move coverage summary

链上铸一枚 Hello（可选）

本地 sui move test 通过后，若已按钱包与测试币配置好 sui client，可将本包发布到 devnet/testnet，再调用入口函数 mint_hello，这样浏览器与 CLI 里都会出现真实对象 ID（而非仅控制台打印字符串）：

# 在 hello_world 包根目录，发布（详见 §3.2）
sui client publish

# 将输出中的 Package ID 设为环境变量后，一笔交易只调 mint_hello：
sui client ptb --move-call $PACKAGE_ID::hello_world::mint_hello

成功后在交易回执的 Created Objects 中可看到类型为 ...::hello_world::Hello 的新对象；用 sui client object <对象ID> 可查看其中的 greeting 字段。PTB 与更多调用方式见 §3.3。

项目结构最佳实践

随着项目增长，建议采用以下结构：

my_project/
├── Move.toml
├── sources/
│   ├── module_a.move
│   ├── module_b.move
│   └── utils.move
└── tests/
    ├── module_a_tests.move
    └── module_b_tests.move

约定：

• 每个 .move 文件包含一个模块
• 文件名与模块名一致
• 测试文件名以 _tests 后缀命名
• 将相关功能组织在同一个包中

小结

本节我们完成了第一个 Move 程序的完整开发流程：使用 sui move new 创建项目，理解 Move.toml，编写带 Hello 对象与 entry fun mint_hello 的模块（转移给自己对应 ctx.sender()），编写测试，再通过 sui move build / sui move test 验证。这样你既练习了纯函数式的单元测试路径，又具备了链上可查询输出（对象 ID 与字段）的最小闭环；下一节将以另一示例深入发布交易的细节，§3.3 则系统讲解 PTB 调用。

若你希望先了解全书章节如何递进、哪些章可以跳读，可穿插阅读导读 — 本书结构与阅读方式。

部署合约到 Sui 网络

与侧边栏目录对应：3.2 Hello Sui — 部署到链上

编写和测试 Move 代码只是第一步，真正激动人心的是将合约部署到 Sui 网络上并让它运行起来。本节将通过一个 TodoList 合约示例，完整演示从编写到发布的全过程，并深入解读发布交易的每一个细节。

准备工作

在部署之前，确保你已完成以下准备（详见钱包与测试币章节）：

# 1. 确认当前网络为 devnet 或 testnet
sui client envs

# 2. 切换到 devnet（如果需要）
sui client switch --env devnet

# 3. 确认有足够的测试币
sui client balance

# 4. 如果余额不足，获取测试币
sui client faucet

编写 TodoList 合约

创建一个新项目：

sui move new todo_list
cd todo_list

编辑 sources/todo_list.move：

module todo_list::todo_list;

use std::string::String;

/// 一个简单的待办事项列表
public struct TodoList has key, store {
    id: UID,
    items: vector<String>,
}

/// 创建一个新的待办事项列表
public fun new(ctx: &mut TxContext): TodoList {
    TodoList {
        id: object::new(ctx),
        items: vector[],
    }
}

/// 添加一个待办事项
public fun add(list: &mut TodoList, item: String) {
    list.items.push_back(item);
}

/// 删除指定位置的待办事项，返回被删除的内容
public fun remove(list: &mut TodoList, index: u64): String {
    list.items.remove(index)
}

/// 获取待办事项数量
public fun length(list: &TodoList): u64 {
    list.items.length()
}

让我们解析这个合约的关键要素：

结构体定义

public struct TodoList has key, store {
    id: UID,
    items: vector<String>,
}

• has key：表示该结构体是一个 Sui 对象，拥有全局唯一的 id
• has store：表示该对象可以被存储在其他对象中，也可以被转移
• id: UID：每个 Sui 对象必须有的唯一标识符字段
• items: vector<String>：使用向量存储待办事项列表

对象创建

public fun new(ctx: &mut TxContext): TodoList {
    TodoList {
        id: object::new(ctx),
        items: vector[],
    }
}

• ctx: &mut TxContext：交易上下文，用于生成唯一 ID
• object::new(ctx)：创建新的 UID
• vector[]：Move 2024 的空向量字面量语法

构建项目

sui move build

确保编译通过没有错误。

发布合约

使用以下命令将合约发布到链上：

sui client publish

CLI 会自动估算 Gas，一般无需指定 --gas-budget；仅在需要覆盖默认值时再添加该参数。

解读发布交易输出

发布成功后，CLI 会输出大量信息。让我们逐部分解读。

Transaction Digest

Transaction Digest: 5JxQpNBk4r5F2UaGRe4Vb9DF7hLZqijU3aTvN8H7kQ2W

交易摘要（Digest）是交易的唯一标识符，可以在区块浏览器中查看交易详情。

Transaction Data

╭──────────────────────────────────────────────────────────╮
│ Transaction Data                                         │
├──────────────────────────────────────────────────────────┤
│ Sender: 0x7d20dcdb...                                    │
│ Gas Budget: 100000000 MIST                               │
│ Commands:                                                │
│   Publish:                                               │
│     - Package: todo_list                                 │
│   TransferObjects:                                       │
│     - UpgradeCap → Sender                                │
╰──────────────────────────────────────────────────────────╯

• Sender：发布者的地址
• Commands：交易包含两个命令
  • Publish：发布 todo_list 包
  • TransferObjects：将 UpgradeCap（升级能力）转移给发布者

Transaction Effects

╭──────────────────────────────────────────────────────────╮
│ Transaction Effects                                      │
├──────────────────────────────────────────────────────────┤
│ Status: Success                                          │
│ Created Objects:                                         │
│   - Package:    0xabc123...                              │
│   - UpgradeCap: 0xdef456...                              │
│ Gas Cost Summary:                                        │
│   Storage Cost:  8976000 MIST                            │
│   Computation Cost: 1000000 MIST                         │
│   Total Gas Cost: 9976000 MIST                           │
│   Storage Rebate: 978120 MIST                            │
╰──────────────────────────────────────────────────────────╯

• Status: Success：交易执行成功
• Created Objects：创建了两个对象
  • Package：发布的包，包含你的 Move 模块
  • UpgradeCap：升级能力对象，后续升级包时需要用到
• Gas Cost：Gas 费用明细

Object Changes

╭──────────────────────────────────────────────────────────╮
│ Object Changes                                           │
├──────────────────────────────────────────────────────────┤
│ Published Objects:                                       │
│   PackageID: 0xabc123def456...                           │
│   Modules: todo_list                                     │
╰──────────────────────────────────────────────────────────╯

PackageID 是你的合约在链上的唯一标识，后续调用合约函数时需要用到它。

重要：请记录下你的 PackageID，后续章节将需要使用它。

使用 JSON 格式输出

添加 --json 标志可以获取 JSON 格式的输出，方便程序化解析：

sui client publish --json

JSON 输出更适合脚本自动化处理，你可以用 jq 提取关键信息：

# 发布并提取 PackageID
sui client publish --json | jq -r '.objectChanges[] | select(.type == "published") | .packageId'

理解 UpgradeCap

UpgradeCap（升级能力）是 Sui 包管理的核心机制：

• 每次发布包时自动生成并转移给发布者
• 持有 UpgradeCap 的人可以升级对应的包
• 如果你销毁或转移 UpgradeCap，就放弃了升级权限
• 这是 Sui 上实现不可变性保证的一种方式

# 查看 UpgradeCap 对象
sui client object <upgrade-cap-id>

安全提示：如果你想让包变成不可变的（无法升级），可以在发布后销毁 UpgradeCap。但请谨慎操作，一旦销毁便无法撤回。

在区块浏览器上查看

你可以在 Sui 区块浏览器上查看已发布的包：

• Devnet：https://suiscan.xyz/devnet/object/<PackageID>
• Testnet：https://suiscan.xyz/testnet/object/<PackageID>

在浏览器中你可以看到：

• 包的所有模块
• 每个模块的公开函数
• 结构体定义
• 历史交易

完整发布流程总结

# 1. 创建项目
sui move new todo_list && cd todo_list

# 2. 编写合约代码（编辑 sources/todo_list.move）

# 3. 构建
sui move build

# 4. 测试
sui move test

# 5. 确保有测试币
sui client faucet

# 6. 发布
sui client publish

# 7. 记录 PackageID
export PACKAGE_ID=0x<your-package-id>

小结

本节我们完成了一个 TodoList 合约的编写和链上发布。关键步骤包括：使用 sui client publish 发布包、理解交易输出中的 Digest、Effects、Created Objects 等信息。发布后我们获得了两个重要的对象——Package（包含合约代码）和 UpgradeCap（升级能力）。记录好 PackageID，下一节我们将学习如何通过 CLI 与已发布的合约进行交互。

与合约交互

合约发布到链上后，我们需要通过交易来调用它的函数。Sui CLI 提供了强大的可编程交易块（Programmable Transaction Blocks，PTB）功能，可以在一笔交易中组合多个操作。本节将通过与上一节发布的 TodoList 合约交互，深入学习 PTB 的使用方法。

准备环境变量

首先，设置我们需要用到的环境变量：

# 替换为你上一节发布时获得的 PackageID
export PACKAGE_ID=0x<your-package-id>

# 获取当前活跃地址
export MY_ADDRESS=$(sui client active-address)

# 验证设置
echo "Package ID: $PACKAGE_ID"
echo "My Address: $MY_ADDRESS"

理解可编程交易块（PTB）

PTB 是 Sui 交易系统的核心概念。与传统区块链每次交易只能调用一个函数不同，Sui 的 PTB 允许你在一笔交易中执行多个命令，每个命令可以使用前面命令的结果。

PTB 的关键特性：

• 原子性：所有命令要么全部成功，要么全部回滚
• 可组合性：后续命令可以使用前面命令的返回值
• 高效性：多个操作合并为一笔交易，减少 Gas 消耗
• 灵活性：支持调用函数、转移对象、分割/合并 Coin 等

创建 TodoList 对象

让我们创建一个新的 TodoList 对象：

sui client ptb \
    --assign sender @$MY_ADDRESS \
    --move-call $PACKAGE_ID::todo_list::new \
    --assign list \
    --transfer-objects "[list]" sender

让我们逐行解析这个命令：

注意：new 函数虽然需要 &mut TxContext 参数，但 CLI 会自动传入，无需手动指定。

交易成功后，输出中会包含创建的对象 ID。记录下这个 ID：

# 从输出中找到 Created Objects 的 ID
export LIST_ID=0x<created-object-id>

查看对象

基本查看

sui client object $LIST_ID

输出示例：

╭───────────────┬──────────────────────────────────────────────╮
│ objectId      │ 0x1234...                                    │
│ version       │ 1                                            │
│ digest        │ abc123...                                    │
│ objType       │ 0x<pkg>::todo_list::TodoList                 │
│ owner         │ AddressOwner(0x7d20...)                      │
│ content       │ { id: 0x1234..., items: [] }                 │
╰───────────────┴──────────────────────────────────────────────╯

可以看到 items 字段为空数组，这是我们刚创建的空 TodoList。

JSON 格式查看

sui client object $LIST_ID --json

JSON 格式更适合程序解析，包含更详细的类型信息和字段值。

添加待办事项

使用 add 函数向列表中添加项目：

sui client ptb \
    --move-call $PACKAGE_ID::todo_list::add \
        @$LIST_ID \
        "'学习 Move 语言'"

这里直接传入了两个参数：

• @$LIST_ID：TodoList 对象的引用（@ 前缀表示对象 ID）
• "'学习 Move 语言'"：要添加的字符串内容

提示：字符串参数需要用单引号包裹，外层再用双引号，即 "'内容'"。

再添加几个事项：

sui client ptb \
    --move-call $PACKAGE_ID::todo_list::add \
        @$LIST_ID \
        "'编写智能合约'"

sui client ptb \
    --move-call $PACKAGE_ID::todo_list::add \
        @$LIST_ID \
        "'部署到主网'"

在一笔交易中执行多个操作

PTB 的强大之处在于可以在一笔交易中组合多个命令。让我们在一次交易中添加多个待办事项：

sui client ptb \
    --move-call $PACKAGE_ID::todo_list::add \
        @$LIST_ID \
        "'阅读 Sui 文档'" \
    --move-call $PACKAGE_ID::todo_list::add \
        @$LIST_ID \
        "'参与社区讨论'"

这样做不仅更高效（只需一笔 Gas 费），而且保证了原子性：要么两个事项都添加成功，要么都不添加。

创建对象并立即使用

下面展示一个更复杂的 PTB 示例——创建 TodoList 并立即添加事项：

sui client ptb \
    --assign sender @$MY_ADDRESS \
    --move-call $PACKAGE_ID::todo_list::new \
    --assign new_list \
    --move-call $PACKAGE_ID::todo_list::add new_list "'第一个任务'" \
    --move-call $PACKAGE_ID::todo_list::add new_list "'第二个任务'" \
    --transfer-objects "[new_list]" sender

这个交易包含了四个命令：

1. 调用 new 创建 TodoList
2. 调用 add 添加第一个事项（使用步骤 1 的返回值）
3. 调用 add 添加第二个事项
4. 将 TodoList 转移给自己

删除待办事项

# 删除索引为 0 的事项（第一个）
sui client ptb \
    --move-call $PACKAGE_ID::todo_list::remove \
        @$LIST_ID \
        0

查询拥有的对象

查看当前地址下的所有对象：

sui client objects

输出会列出你拥有的所有对象，包括 SUI Coin、TodoList、UpgradeCap 等：

╭───────────────────────────────────────────────────────────────╮
│ ╭────────────┬──────────────────────────────────────────────╮ │
│ │ objectId   │ 0x1234...                                   │ │
│ │ version    │ 5                                           │ │
│ │ digest     │ abc...                                      │ │
│ │ objectType │ 0x<pkg>::todo_list::TodoList                │ │
│ ╰────────────┴──────────────────────────────────────────────╯ │
│ ╭────────────┬──────────────────────────────────────────────╮ │
│ │ objectId   │ 0x5678...                                   │ │
│ │ version    │ 1                                           │ │
│ │ digest     │ def...                                      │ │
│ │ objectType │ 0x2::coin::Coin<0x2::sui::SUI>             │ │
│ ╰────────────┴──────────────────────────────────────────────╯ │
╰───────────────────────────────────────────────────────────────╯

查看交易历史

你可以通过区块浏览器查看某个地址或对象的所有交易历史：

# 查看特定交易详情
sui client transaction-block <transaction-digest> --json

PTB 命令速查

以下是 sui client ptb 支持的常用操作：

交互流程总结

# 完整的交互流程

# 1. 设置环境变量
export PACKAGE_ID=0x...
export MY_ADDRESS=$(sui client active-address)

# 2. 创建对象
sui client ptb \
    --assign sender @$MY_ADDRESS \
    --move-call $PACKAGE_ID::todo_list::new \
    --assign list \
    --transfer-objects "[list]" sender

# 3. 记录对象 ID
export LIST_ID=0x...

# 4. 调用函数修改对象
sui client ptb \
    --move-call $PACKAGE_ID::todo_list::add @$LIST_ID "'新任务'"

# 5. 查看对象状态
sui client object $LIST_ID

# 6. 查看所有对象
sui client objects

小结

本节我们学习了如何通过 Sui CLI 的 PTB 命令与链上合约交互。核心要点包括：使用 sui client ptb --move-call 调用合约函数、使用 --assign 捕获返回值、使用 --transfer-objects 转移对象。PTB 最强大的特性是可组合性——你可以在一笔交易中串联多个命令，后续命令可以使用前面命令的结果，而整个过程是原子的。这种设计让 Sui 上的交易既灵活又高效。至此，你已经掌握了 Move 开发的完整流程：编写 → 测试 → 发布 → 交互。接下来我们将深入学习 Move 语言的核心概念。

第三章 · 实战练习

实战一：本地编译 Hello World

1. 进入 src/03_first_move/code/hello_world/。
2. 执行 sui move build，再执行 sui move test（若有测试模块）。
3. 验收：build/ 生成且无编译错误。

实战二：发布到测试网

1. 使用第二章配置好的测试网账户，在本包目录执行 sui client publish --gas-budget <预算>（具体参数以当前 CLI 帮助为准）。
2. 记录输出的 Package ID。
3. 验收：在 Explorer 中能根据 Package ID 查到已发布模块。

实战三：链上读一次对象

1. 在已发布本包的前提下，执行 sui client ptb --move-call <PACKAGE_ID>::hello_world::mint_hello（或按 §3.3 组合 PTB），在交易结果里找到 Created Objects 中的 Hello。
2. 用 sui client object <HELLO_OBJECT_ID> 查看 greeting 字段与 owner（应为你的活跃地址）。
3. 验收：记录 Hello 的对象 ID，并确认 owner 为 AddressOwner(你的地址)。

第四章 · 核心概念

本章介绍 Sui Move 开发中的基础概念，理解这些概念是编写合约的前提。

本章内容

学习目标

读完本章后，你将能够：

• 理解 Move 包的组织方式和依赖管理
• 正确配置 Move.toml 文件
• 解释 Sui 上地址、账户和交易的关系

本章实战练习

每章 1～3 个动手任务见 hands-on.md（目录中亦列为「本章实战练习」）。

包（Package）

在 Move 语言中，包（Package）是代码组织的基本单位。每个包在发布到 Sui 区块链后，都会被分配一个唯一的链上地址作为标识。理解包的结构和工作机制，是编写和部署 Move 智能合约的第一步。

包的目录结构

使用 Sui CLI 创建一个新包：

sui move new my_package

生成的标准目录结构如下：

my_package/
├── Move.toml
├── sources/
│   └── my_module.move
└── tests/
    └── my_module_tests.move

各目录和文件的作用：

包与模块的关系

一个包可以包含多个模块（Module），每个模块又包含函数、类型（结构体）和常量。它们的层次关系可以这样理解：

package 0x...
    module a
        struct A1
        fun hello_world()
    module b
        struct B1
        fun hello_package()

在代码层面，每个 .move 文件通常定义一个模块：

// sources/cafe.move
module my_package::cafe;

public struct Coffee has drop {
    strength: u8,
}

public fun brew(strength: u8): Coffee {
    Coffee { strength }
}

// sources/bakery.move
module my_package::bakery;

public struct Bread has drop {
    flavor: vector<u8>,
}

public fun bake(flavor: vector<u8>): Bread {
    Bread { flavor }
}

上面的两个模块 cafe 和 bakery 同属于 my_package 这一个包。发布后，它们共享同一个链上地址。

包的发布与不可变性

使用以下命令将包发布到 Sui 网络：

sui client publish

发布后，包具有以下特性：

• 唯一地址：每个已发布的包都有一个唯一的链上地址（如 0xabc123...），后续所有对该包中模块和函数的调用都通过此地址进行。
• 不可变性：已发布的包是不可变对象（Immutable Object），任何人（包括发布者）都无法修改或删除它。这保证了链上合约代码的透明性和可审计性。

在代码中引用已发布的包

其他包可以通过地址引用已发布的模块：

module other_package::user;

use 0xabc123::cafe;

public fun drink() {
    let _coffee = cafe::brew(10);
}

包的升级与 UpgradeCap

虽然已发布的包不可变，但 Sui 提供了包升级机制，允许开发者发布一个新版本的包来替代旧版。

UpgradeCap

当一个包首次发布时，发布者会收到一个 UpgradeCap 对象。持有此对象即拥有升级该包的权限：

sui client upgrade

升级时需注意以下兼容性规则：

放弃升级权限

如果希望让包彻底不可变（无法再升级），可以销毁 UpgradeCap：

module my_package::config;

use sui::package;

public fun make_immutable(cap: package::UpgradeCap) {
    package::make_immutable(cap);
}

调用此函数后，包将永远无法再被升级。

包的命名规范

• 包名使用 snake_case，如 my_defi_app
• 模块名同样使用 snake_case，如 liquidity_pool
• 包名在 Move.toml 的 [package] 段中声明，同时作为 [addresses] 中的命名地址使用

[package]
name = "my_defi_app"

[addresses]
my_defi_app = "0x0"

小结

包是 Move 项目的顶层组织单位。一个包由 Move.toml 清单文件和 sources/ 目录中的模块组成。发布到链上后，包获得唯一地址并变为不可变。通过 UpgradeCap 机制，开发者可以在保持兼容性的前提下发布新版本。理解包的结构和生命周期，是构建 Sui 应用的基础。

Move.toml 清单文件详解

Move.toml 是每个 Move 包的清单文件（Manifest），位于包的根目录下。它定义了包的基本信息、依赖关系和地址别名等配置。可以说，Move.toml 之于 Move 包，就像 package.json 之于 Node.js 项目、或清单文件之于其他语言的包管理器。

全书约定：正文默认可复制片段使用 rev = "framework/mainnet"；下文出现 framework/testnet 时多用于对照（如 [dev-dependencies]）或与测试网环境匹配——详见第六章 §6.11 · Sui Framework 依赖中的表格说明。

完整示例

先看一个典型的 Move.toml 文件全貌，后续逐段讲解：

[package]
name = "my_project"
version = "0.0.0"
edition = "2024"

[dependencies]
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/mainnet" }

[addresses]
my_project = "0x0"

[dev-addresses]
my_project = "0x0"

[dev-dependencies]
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/testnet" }

[package] — 包的基本信息

[package]
name = "my_project"
version = "0.0.0"
edition = "2024"

edition 字段决定了编译器可用的语言特性。2024 版本相较于旧版引入了枚举类型（enum）、方法语法（method syntax）、位置域（positional fields）等重要特性。

[dependencies] — 依赖管理

Move 包通过 [dependencies] 段声明对其他包的依赖。

Git 依赖

最常见的依赖方式，从 Git 仓库拉取：

[dependencies]
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/mainnet" }

也可以使用多行格式使其更易读：

[dependencies.Sui]
git = "https://github.com/MystenLabs/sui.git"
subdir = "crates/sui-framework/packages/sui-framework"
rev = "framework/mainnet"

本地依赖

在开发或调试时，可以引用本地路径的包：

[dependencies]
MyLibrary = { local = "../my_library" }

自动依赖（Sui CLI v1.45+）

从 Sui CLI v1.45 版本开始，系统包（如 Sui、MoveStdlib）会自动根据当前网络环境解析，无需手动指定。你可以简化为：

[dependencies]

留空即可，编译器会自动添加必要的系统框架依赖。

解决版本冲突

当多个依赖引用了同一个包的不同版本时，可以使用 override = true 来强制指定版本：

[dependencies]
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/mainnet", override = true }

override = true 会让当前包中声明的这个版本覆盖所有传递依赖中的同名包版本。

[addresses] — 命名地址

[addresses]
my_project = "0x0"
std = "0x1"
sui = "0x2"

命名地址为链上地址提供了人类可读的别名。在代码中可以直接使用这些名称：

module my_project::hello;

// my_project 在本地编译时指向 "0x0"
// 发布后会被替换为实际的链上地址

其中 "0x0" 是一个特殊的占位地址，表示“尚未发布“。在执行 sui client publish 时，编译器会自动将其替换为实际分配的链上地址。

常见的保留地址：

[dev-addresses] — 开发/测试环境地址

[dev-addresses]
my_project = "0x0"

[dev-addresses] 中的配置仅在 test 和 dev 模式下生效，会覆盖 [addresses] 中的同名地址。这对于测试场景中需要使用不同地址的情况非常有用。

[dev-dependencies] — 开发/测试依赖

[dev-dependencies]
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/testnet" }

与 [dev-addresses] 类似，[dev-dependencies] 中声明的依赖仅在 test 和 dev 模式下使用，会覆盖 [dependencies] 中的同名依赖。典型用途是在测试时使用 testnet 版本的框架。

实战：一个 DeFi 项目的 Move.toml

[package]
name = "defi_swap"
version = "1.0.0"
edition = "2024"

[dependencies]
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/mainnet" }
MoveStdlib = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/move-stdlib", rev = "framework/mainnet" }

[addresses]
defi_swap = "0x0"

[dev-dependencies]
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/testnet", override = true }

[dev-addresses]
defi_swap = "0x0"

小结

Move.toml 是 Move 包的核心配置文件，由五个主要段落组成：[package] 声明包的基本信息，[dependencies] 管理外部依赖，[addresses] 定义命名地址别名，[dev-dependencies] 和 [dev-addresses] 则为测试环境提供覆盖配置。熟练掌握 Move.toml 的各项配置，有助于高效管理项目结构和依赖关系。

地址（Address）

地址（Address）是 Sui 区块链上的唯一标识符，长度为 32 字节（256 位），以十六进制字符串表示。在 Sui 中，地址被广泛用于标识包、账户和对象，是连接链上各种实体的核心概念。

地址的格式

地址由 64 个十六进制字符组成，前缀为 0x：

0x06b36e07f3d5a3d76e66fc1b14735e7f4b0045c3ebca6f3b1c3bfb9d3bcda2a7

格式规则

短地址补零

为了书写方便，地址可以使用简写形式。不足 64 个字符的地址会自动在左侧补零：

0x1
= 0x0000000000000000000000000000000000000000000000000000000000000001

0x2
= 0x0000000000000000000000000000000000000000000000000000000000000002

0xdead
= 0x000000000000000000000000000000000000000000000000000000000000dead

在代码中使用短地址和完整地址效果相同：

module example::demo;

use std::debug;

#[test]
fun address() {
    let addr1 = @0x1;
    let addr2 = @0x0000000000000000000000000000000000000000000000000000000000000001;
    assert_eq!(addr1, addr2);
}

保留地址

Sui 网络中有一些特殊的保留地址，用于系统级别的包和对象：

在代码中引用这些地址：

module my_project::example;

use std::string;          // 来自 0x1
use sui::clock::Clock;    // 来自 0x2
use sui::coin::Coin;      // 来自 0x2

地址的用途

在 Sui 中，地址有三个主要用途：

1. 标识账户

每个用户账户由一个地址标识。这个地址从用户的公钥派生而来：

私钥 → 公钥 → 地址

用户通过其地址接收对象、发送交易。

2. 标识包

每个已发布的 Move 包都有一个唯一的地址。调用包中的函数时需要指定包的地址：

module 0xabc123::marketplace;

// 该模块属于地址为 0xabc123 的包

3. 标识对象

Sui 上的每个对象也有一个唯一的地址（即对象 ID）。对象 ID 在创建时由系统分配。

Move 中的 address 类型

在 Move 语言中，address 是一个内置的原始类型：

module my_project::address_demo;

public fun show_address(): address {
    @0x1
}

public fun compare_addresses(a: address, b: address): bool {
    a == b
}

#[test]
fun address_type() {
    let system_addr = @0x1;
    let framework_addr = @0x2;
    assert!(system_addr != framework_addr);
}

地址与字符串转换

利用标准库可以在地址与字符串之间进行转换：

module my_project::addr_utils;

use std::string::String;
use sui::address;

public fun addr_to_string(addr: address): String {
    address::to_string(addr)
}

public fun addr_length(): u64 {
    address::length()  // 返回 32
}

地址字面量的使用

在 Move 代码中，地址字面量以 @ 符号开头：

module my_project::literals;

const ADMIN: address = @0xA11CE;
const STD: address = @std;   // 使用命名地址，等价于 @0x1

fun check_admin(sender: address): bool {
    sender == ADMIN
}

命名地址（如 @std、@sui）在 Move.toml 的 [addresses] 段中定义，编译时会被替换为实际值。

小结

地址是 Sui 区块链上标识各种实体的核心概念。它是一个 32 字节的十六进制值，用于标识账户、包和对象。Move 语言中提供了 address 原始类型来操作地址，并通过 @ 前缀表示地址字面量。Sui 网络中保留了若干特殊地址（如 0x1、0x2、0x6）用于系统组件。理解地址的格式和用途，是与 Sui 链上实体交互的基础。

账户模型

在 Sui 中，账户（Account）代表区块链上的一个用户身份。账户由私钥生成，通过对应的地址来标识。每个账户可以拥有对象、发送交易，是用户与 Sui 网络交互的入口。

账户的生成

账户的生成遵循一条从私钥到地址的推导链：

私钥（Private Key）
    ↓ 数学推导
公钥（Public Key）
    ↓ 哈希运算
地址（Address）

密钥对

密钥对（Key Pair）由公钥和私钥组成：

• 私钥：必须严格保密，用于对交易进行数字签名。持有私钥即拥有账户的完全控制权。
• 公钥：可以公开分享，用于验证签名的合法性。
• 地址：从公钥通过哈希运算派生，是账户在链上的唯一标识。

使用 Sui CLI 生成新的密钥对：

sui client new-address ed25519

输出示例：

╭─────────────────────────────────────────────────────────╮
│ Created new keypair and saved it to keystore.           │
├────────────────┬────────────────────────────────────────┤
│ alias          │ tender-garnet                          │
│ address        │ 0xa11c...                             │
│ keyScheme      │ ed25519                                │
╰────────────────┴────────────────────────────────────────╯

支持的密码学方案

Sui 支持多种密码学签名方案，这种特性被称为密码学敏捷性（Cryptographic Agility）：

密码学敏捷性

Sui 的密码学敏捷性意味着不同的签名方案可以共存于同一网络中。用户可以根据需求选择最合适的方案：

# 使用 Ed25519（默认）
sui client new-address ed25519

# 使用 Secp256k1（兼容比特币/以太坊）
sui client new-address secp256k1

# 使用 Secp256r1（兼容 Passkey/硬件安全模块）
sui client new-address secp256r1

所有方案生成的地址格式完全相同，都是 32 字节的地址，在链上可以无差别地使用。

zkLogin — 社交登录上链

zkLogin 是 Sui 独有的创新特性，允许用户通过社交账号（如 Google、Facebook、Apple、Twitch 等）直接生成区块链账户，无需管理私钥或助记词。

工作原理

用户使用 Google 登录
    ↓
获取 OAuth JWT Token
    ↓
生成零知识证明（ZKP）
    ↓
将证明映射为 Sui 地址
    ↓
用户获得链上账户

zkLogin 的核心价值在于：

• 降低门槛：用户无需理解密钥管理、助记词等区块链概念
• 隐私保护：零知识证明确保社交账号信息不会泄露到链上
• 安全性：即使 OAuth 提供商被攻破，攻击者也无法获取用户的私钥

账户与对象的关系

账户是对象的“所有者“。在 Sui 的面向对象模型中，账户可以：

• 拥有对象：对象可以归属于某个地址（账户）
• 发送交易：修改自己拥有的对象、调用智能合约函数
• 接收转移：接受其他账户转移过来的对象

module my_project::wallet;

use sui::coin::{Self, Coin};
use sui::sui::SUI;

public fun send_coin(
    coin: Coin<SUI>,
    recipient: address,
) {
    transfer::public_transfer(coin, recipient);
}

在上面的例子中，recipient 就是接收方的账户地址。

交易与签名

每一笔提交到 Sui 网络的交易都必须由发送者的私钥签名。签名过程确保：

1. 身份认证：证明交易确实由该地址的所有者发起
2. 完整性：交易内容在传输过程中未被篡改
3. 不可否认：发送者无法否认曾发送过该交易

交易构建（Transaction）
    ↓
私钥签名（Sign）
    ↓
提交到网络（Submit）
    ↓
验证者验证签名（Verify）
    ↓
执行交易（Execute）

使用 CLI 发送交易

# 查看当前活跃地址
sui client active-address

# 转账 SUI
sui client transfer-sui --to 0xRECIPIENT --sui-coin-object-id 0xCOIN_ID --amount 1000

CLI 在执行交易时会自动使用当前活跃地址对应的私钥进行签名。

多地址管理

一个用户可以同时管理多个地址（账户），Sui CLI 提供了相应的管理工具：

# 查看所有地址
sui client addresses

# 切换活跃地址
sui client switch --address 0xYOUR_ADDRESS

小结

Sui 的账户模型基于公钥密码学，通过“私钥 → 公钥 → 地址“的推导链生成用户身份。Sui 支持 Ed25519、Secp256k1、Secp256r1 三种密码学方案，并通过 zkLogin 实现社交账号登录上链，大幅降低了用户使用门槛。账户通过地址标识，可以拥有对象、发送交易，是用户与 Sui 链上世界交互的桥梁。

交易（Transaction）

交易（Transaction）是改变 Sui 区块链状态的唯一方式。无论是转移对象、调用智能合约函数，还是发布新的 Move 包，都必须通过交易来完成。理解交易的结构和生命周期，是掌握 Sui 开发的关键。

交易的结构

一笔 Sui 交易由以下几个核心部分组成：

Transaction {
    sender:    发送者地址（签名者）
    commands:  操作命令列表
    inputs:    输入参数（纯值参数 + 对象参数）
    gas:       Gas 支付信息（Gas 对象、价格、预算）
}

发送者（Sender）

每笔交易都有一个发送者，即签署并提交交易的账户地址。发送者必须用对应的私钥对交易进行签名。

命令（Commands）

交易可以包含一个或多个命令，按顺序执行。Sui 支持的命令类型：

输入（Inputs）

交易的输入分为两类：

纯值参数（Pure Arguments）

可以直接传入交易的基础值类型：

对象参数（Object Arguments）

链上对象需要根据其所有权类型以不同方式传入：

交易命令详解

MoveCall — 调用 Move 函数

最常用的命令，用于调用链上已发布包中的函数：

module marketplace::shop;

use sui::coin::Coin;
use sui::sui::SUI;

public struct Item has key, store {
    id: UID,
    name: vector<u8>,
}

public fun purchase(
    payment: Coin<SUI>,
    ctx: &mut TxContext,
): Item {
    // 验证支付金额、处理业务逻辑...
    let item = Item {
        id: object::new(ctx),
        name: b"Rare Sword",
    };
    transfer::public_transfer(payment, @0xSHOP_OWNER);
    item
}

SplitCoins — 拆分代币

从一个 Coin 对象中拆分出指定金额。Gas 是一个特殊的关键字，表示交易的 Gas 支付 Coin：

SplitCoins(Gas, [1000])
// 从 Gas Coin 中拆分出 1000 MIST

MergeCoins — 合并代币

将多个同类型 Coin 合并为一个：

MergeCoins(dest_coin, [coin_a, coin_b])
// 将 coin_a 和 coin_b 合并到 dest_coin 中

TransferObjects — 转移对象

将对象转移给指定地址：

TransferObjects([object_a, object_b], recipient)
// 将 object_a 和 object_b 转移给 recipient

交易示例

以下是一个在市场中购买物品的完整交易伪代码：

Inputs:
  - sender = 0xa11ce

Commands:
  - payment = SplitCoins(Gas, [1000])
  - item = MoveCall(0xAAA::market::purchase, [payment])
  - TransferObjects([item], sender)

这笔交易执行了三步操作：

1. 从 Gas Coin 中拆分出 1000 MIST 作为支付
2. 调用市场合约的 purchase 函数，传入支付 Coin，获取物品
3. 将获得的物品转移给自己（发送者）

使用 Sui TypeScript SDK 构建同样的交易：

const tx = new Transaction();

const [payment] = tx.splitCoins(tx.gas, [1000]);
const [item] = tx.moveCall({
    target: '0xAAA::market::purchase',
    arguments: [payment],
});
tx.transferObjects([item], tx.pure.address('0xa11ce'));

交易的生命周期

一笔交易从构建到最终确认，经历以下阶段：

构建（Construct）
    ↓
签名（Sign）
    ↓
提交（Submit）
    ↓
执行（Execute）
    ↓
产生效果（Effects）

1. 构建

开发者使用 SDK 或 CLI 构建交易，指定命令、输入和 Gas 参数。

2. 签名

发送者使用私钥对交易进行数字签名。

3. 提交

将签名后的交易提交给 Sui 验证者节点。

4. 执行

验证者验证签名和交易合法性后，执行交易中的命令序列。

5. 产生效果

交易执行完成后产生 交易效果（Transaction Effects），记录交易的所有结果。

交易效果（Transaction Effects）

每笔交易执行后都会产生一组效果，详细记录了交易的执行结果：

使用 CLI 查看交易效果：

sui client tx-block <TRANSACTION_DIGEST>

Gas 机制

Gas 是执行交易所需的费用，以 Sui 的最小单位 MIST 计价：

1 SUI = 1,000,000,000 MIST（10^9 MIST）

Gas 的组成

每笔交易需要指定三个 Gas 相关参数：

Gas 费用明细

交易执行后的 Gas 费用包含以下几部分：

实际扣除的 Gas 费用计算公式：

实际费用 = 计算费用 + 存储费用 - 存储退款

Gas 预算

如果交易执行的实际费用超过了设定的 Gas 预算，交易将失败并回滚所有操作，但 Gas 费用仍会被扣除。因此建议设置合理的 Gas 预算：

# CLI 会自动估算 Gas，一般无需写 --gas-budget
sui client call --package 0xPKG --module shop --function purchase \
    --args 0xCOIN_ID

可编程交易块（PTB）

Sui 的一大特色是可编程交易块（Programmable Transaction Block, PTB）。一笔交易可以包含多个命令，这些命令按顺序执行，前一个命令的输出可以作为后一个命令的输入：

Commands:
  1. coin = SplitCoins(Gas, [5000])
  2. nft = MoveCall(0xBBB::nft::mint, ["My NFT"])
  3. MoveCall(0xCCC::auction::bid, [nft, coin])

PTB 的优势：

• 原子性：所有命令要么全部成功，要么全部失败
• 组合性：可以在一笔交易中调用多个不同包的函数
• 高效性：减少了多次交易的网络往返开销
• 数据流转：前一个命令的返回值可以直接传给后续命令

小结

交易是 Sui 区块链上改变状态的唯一方式。一笔交易包含发送者、命令列表、输入参数和 Gas 支付信息。Sui 提供了 MoveCall、TransferObjects、SplitCoins 等多种命令类型，并通过可编程交易块（PTB）实现了多命令的原子组合。交易执行后会产生包含状态变更、Gas 费用、事件等信息的交易效果。Gas 以 MIST 为单位计价（1 SUI = 10^9 MIST），由计算费用、存储费用和存储退款三部分组成。

第四章 · 实战练习

实战一：从 Move.toml 追到链上地址

1. 打开 src/04_concepts/code/concepts_demo/Move.toml，查看 [addresses] 与 [package]。
2. 将该包 sui move build 通过后，若已发布，用 Explorer 查看命名地址与链上 Package ID 的对应关系。
3. 验收：能口头解释「清单里的 named address」与「发布后的 0x… package」不是同一概念、但如何关联。

实战二：读一个 Coin 对象的字段

1. 在测试网任选自己钱包中的 SUI coin 对象 ID（0x2::sui::SUI）。
2. 使用 sui client object <ID> --json（或 Explorer）查看 digest、version、owner。
3. 验收：写出该对象作为交易输入时，为什么需要 object ref（id + version + digest）。

实战三：干跑一笔简单 PTB（概念）

1. 阅读本章「交易」一节，列出 PTB 中三个你能在文档里找到的元素（例如：命令列表、gas、发送者）。
2. 不必须上链：写出你打算用 PTB 完成的一件小事（如：转 NFT、调 entry）。
3. 验收：3～5 条 bullet，说明你的 PTB 里会有哪些命令类型（MoveCall、TransferObjects 等）。

第五章 · Move 语法基础

本章讲解 Move 的基础语法：模块与组织、类型与表达式、结构体与能力、控制流与函数，为后续进阶与 Sui 开发打下扎实基础。进阶语法见第六章、第八章；宏函数系统讲解为 第十一章（排在第十章之后）。

编者注：Move 语法正文只维护本页及侧边栏各节（拆条结构），不另存与正文并行的「合并长稿」，避免同一知识点两套修订。

本章内容

学习目标

读完本章后，你将能够：

• 阅读并编写包含模块、类型、结构体与能力的 Move 代码
• 使用控制流、断言与函数实现简单业务逻辑
• 理解 Move 的能力系统（copy / drop 等）及其对类型与值的影响

本章实战练习

每章 1～3 个动手任务见 hands-on.md（目录中亦列为「本章实战练习」）。

模块（Module）

模块（Module）是 Move 语言中代码组织的基本单元，用于将相关的类型定义、函数和常量组织在一起。模块为代码提供了命名空间隔离，所有成员默认是私有的，只有显式标记为 public 的成员才能被外部访问。理解模块的声明方式和组织规范是学习 Move 语言的第一步。

模块声明语法

每个 Move 源文件通常包含一个模块声明。模块声明的基本语法如下：

module package_address::module_name;

其中 package_address 是包地址（可以是字面地址或命名地址），module_name 是模块名称。

2024 标签语法与传统语法

在 Move 2024 版本中，推荐使用上面的标签语法（label syntax），以分号结尾，模块体中的代码直接写在文件中，无需大括号包裹。

传统语法（pre-2024）使用大括号包裹模块体：

module book::my_module {
    // 模块内容全部在大括号内
    public fun hello(): u64 { 42 }
}

本书统一使用 2024 标签语法。

命名规范

Move 模块遵循 snake_case（蛇形命名法）规范，即全部小写字母，单词之间以下划线分隔：

• my_module ✅
• token_swap ✅
• MyModule ❌
• tokenSwap ❌

通常建议 一个文件只包含一个模块，文件名与模块名保持一致。例如模块 my_module 对应文件 my_module.move。

模块成员

一个模块可以包含以下成员：

• 结构体（Struct）：自定义数据类型
• 函数（Function）：可执行的逻辑单元
• 常量（Constant）：编译时确定的不可变值
• 导入（Use）：引用其他模块的成员

module book::my_module;

use std::string::String;

const MAX_SIZE: u64 = 100;

public struct Item has key, store {
    id: UID,
    name: String,
}

public fun create_item(name: String, ctx: &mut TxContext): Item {
    Item {
        id: object::new(ctx),
        name,
    }
}

上面的示例展示了一个完整的模块，包含了导入、常量、结构体和函数。

地址与命名地址

模块必须属于一个地址。地址可以是字面地址或命名地址。

字面地址

字面地址是一个十六进制值，例如 0x0、0x1、0x2：

module 0x1::math;

命名地址

命名地址是在 Move.toml 配置文件中定义的别名，更加可读且便于管理：

# Move.toml
[addresses]
book = "0x0"
std = "0x1"
sui = "0x2"

使用命名地址声明模块：

module book::my_module;

编译时，book 会被替换为 Move.toml 中定义的实际地址 0x0。命名地址的好处是在发布合约后只需修改 Move.toml 中的地址，而不需要修改源代码。

访问控制

模块中的所有成员默认是 私有的，即只能在定义它们的模块内部访问：

module book::access_control;

// 私有函数，只能在本模块内调用
fun internal_logic(): u64 {
    42
}

// 公开函数，可以被其他模块调用
public fun value(): u64 {
    internal_logic()
}

// 仅供 package 内其他模块调用
public(package) fun package_only(): u64 {
    100
}

Move 提供了三种可见性级别：

小结

模块是 Move 语言的代码组织基石。本节的核心要点包括：

• 模块使用 module address::name; 语法声明，推荐使用 2024 标签语法
• 模块名遵循 snake_case 命名规范，一个文件对应一个模块
• 模块可以包含结构体、函数、常量和导入
• 地址可以是字面地址或 Move.toml 中定义的命名地址
• 所有模块成员默认私有，需要显式标记 public 或 public(package) 来暴露

注释

注释是代码中用于解释和说明的文本，不会被编译器执行。Move 语言支持三种注释方式：行注释、块注释和文档注释。合理使用注释可以大幅提升代码的可读性和可维护性，特别是文档注释能够用于自动生成 API 文档。

行注释

行注释以 // 开头，从 // 到该行末尾的所有内容都会被编译器忽略：

module book::line_comments;

// 这是一个行注释
public fun add(a: u64, b: u64): u64 {
    a + b // 也可以放在代码后面
}

行注释适用于简短的说明，是最常用的注释形式。

块注释

块注释以 /* 开头，以 */ 结尾，可以跨越多行：

module book::block_comments;

/* 这是一个块注释
   可以跨越多行
   适合用于较长的说明 */
public fun multiply(a: u64, b: u64): u64 {
    a * b
}

public fun complex_logic(x: u64): u64 {
    /* 临时禁用某段逻辑时也可以用块注释
    let temp = x * 2;
    temp + 1
    */
    x + 1
}

块注释支持嵌套，即你可以在块注释内部再嵌套一个块注释，这在临时注释掉一段已经包含块注释的代码时非常有用。

文档注释

文档注释以 /// 开头，用于为模块、结构体、函数等生成文档。文档注释必须放在被注释项的 正上方：

module book::comments_example;

/// This is a doc comment for the module

/// A simple counter struct
public struct Counter has key {
    id: UID,
    /// The current count value
    count: u64,
}

// This is a line comment
/* This is a block comment
   spanning multiple lines */

/// Increment the counter by 1
public fun increment(counter: &mut Counter) {
    counter.count = counter.count + 1;
}

文档注释的最佳实践

文档注释应该描述 为什么 和 做什么，而不是 怎么做（代码本身已经说明了怎么做）：

module book::doc_best_practices;

/// 用户积分记录，用于奖励系统的积分追踪。
/// 积分不可转让，只能由系统增减。
public struct Points has key {
    id: UID,
    /// 当前积分余额
    balance: u64,
    /// 历史累计获得积分（不会因消费减少）
    total_earned: u64,
}

/// 为用户增加积分。
/// 同时更新当前余额和历史累计。
///
/// 参数：
/// - `points`: 积分记录的可变引用
/// - `amount`: 要增加的积分数量
public fun earn(points: &mut Points, amount: u64) {
    points.balance = points.balance + amount;
    points.total_earned = points.total_earned + amount;
}

空白字符

在 Move 中，空白字符（空格、制表符、换行符）对程序的语义没有影响，仅影响代码的可读性。以下两段代码在编译器看来完全等价：

module book::whitespace_example;

public fun add(a: u64, b: u64): u64 { a + b }

public fun add_formatted(
    a: u64,
    b: u64,
): u64 {
    a + b
}

虽然空白不影响语义，但建议遵循社区代码风格约定，保持一致的缩进（4 个空格）和合理的换行，以提升代码可读性。

小结

注释是代码可读性的重要组成部分。本节核心要点：

• 行注释 //：最常用，适合简短说明
• 块注释 /* */：可跨行，支持嵌套，适合较长说明或临时禁用代码
• 文档注释 ///：放在定义之前，用于生成 API 文档
• 空白字符不影响程序语义，但应遵循统一的代码风格
• 好的注释应解释 “为什么”，而非重复代码已经表达的 “怎么做”

模块导入

Move 的模块系统通过 use 语句实现代码复用和依赖管理。导入机制让你可以引用标准库、Sui Framework 以及外部包中定义的类型和函数，而无需在每次使用时写出完整的模块路径。掌握模块导入的各种方式是编写整洁、可维护的 Move 代码的关键。

基本导入语法

导入整个模块

使用 use package::module; 可以导入一个模块，之后通过 module::member 的方式访问其成员：

module book::import_module;

use sui::coin;
use sui::sui::SUI;

public fun value(c: &coin::Coin<SUI>): u64 {
    coin::value(c)
}

导入具体成员

使用 use package::module::MemberName; 直接导入模块中的某个类型或函数，之后可以直接使用名称，无需模块前缀：

module book::import_member;

use std::string::String;

public struct Profile has drop {
    name: String,
}

分组导入

当需要从同一个模块导入多个成员时，可以使用花括号进行分组：

module book::grouped_import;

use sui::coin::{Self, Coin};
use sui::sui::SUI;

public fun coin_value(c: &Coin<SUI>): u64 {
    coin::value(c)
}

上例中 {Self, Coin} 同时导入了模块本身（Self 等价于 coin）和 Coin 类型。这样既可以使用 Coin 类型，也可以通过 coin::value 调用模块函数。

Self 关键字

Self 在导入中代表模块本身。使用 Self 可以在分组导入中同时引入模块和其成员：

module book::self_import;

use std::string::{Self, String};

public fun create_greeting(): String {
    let bytes = b"Hello, Sui!";
    string::utf8(bytes)
}

别名导入

使用 as 关键字可以为导入的模块或类型指定别名，解决命名冲突或提升可读性：

module book::alias_import;

use std::string::String as UTF8String;
use std::ascii::String as ASCIIString;

public struct Names has drop {
    utf8_name: UTF8String,
    ascii_name: ASCIIString,
}

当两个不同模块导出了同名的类型时，别名是避免冲突的唯一方式。

从 Sui Framework 导入

Sui Framework 是构建 Sui 智能合约最常用的依赖库。它提供了对象模型、代币系统、事件等核心功能。以下是一些常见的导入：

module book::sui_imports;

use sui::coin::{Self, Coin};
use sui::sui::SUI;
use sui::event;
use sui::object;
use sui::transfer;
use sui::tx_context::TxContext;
use std::string::String;

常用的 Framework 模块

自动导入

Move 编译器会自动导入一些常用的模块和类型，无需手动编写 use 语句：

• std::vector — 向量模块
• std::option — Option 模块
• std::option::Option — Option 类型

这意味着你可以直接使用 vector[]、option::some()、Option<T> 等，而无需显式导入。

module book::auto_import;

public struct Container has drop {
    items: vector<u64>,
    label: Option<u64>,
}

#[test]
fun auto_import() {
    let items = vector[1u64, 2, 3];
    let label = option::some(42u64);

    let c = Container { items, label };
    assert_eq!(c.items.length(), 3);
    assert!(c.label.is_some());
}

外部依赖

外部包的依赖通过 Move.toml 配置文件进行管理。

Move.toml 中的依赖配置

[package]
name = "my_project"
edition = "2024"

[dependencies]
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/mainnet" }

[addresses]
book = "0x0"

与第六章 §6.11 · Move 2024 Edition一致，本书示例统一使用 edition = "2024" 与 rev = "framework/mainnet"。若在 testnet 上开发，可将 rev 改为 framework/testnet。若本地 CLI 仍生成 2024.beta，可改为 "2024"（与迁移期别名等价，见 §6.11 说明）。

定义好依赖后，就可以在代码中导入该依赖包提供的模块。

CLI v1.45+ 的简化

从 Sui CLI v1.45 版本开始，系统包（std、sui）会被 自动包含 为依赖，无需在 Move.toml 中手动添加。这大大简化了新项目的配置。

导入位置

use 语句通常放在模块声明之后、其他代码之前。虽然 Move 允许在函数内部使用 use，但推荐在模块顶部统一管理导入：

module book::import_placement;

// 推荐：在模块顶部统一导入
use std::string::String;
use sui::coin::{Self, Coin};
use sui::sui::SUI;

public struct Token has drop {
    name: String,
}

public fun coin_value(c: &Coin<SUI>): u64 {
    // 也可以在函数内部导入（不推荐）
    // use sui::coin;
    coin::value(c)
}

完整示例

下面的例子综合展示了各种导入方式的实际用法：

module book::import_example;

use std::string::String;
use sui::coin::{Self, Coin};
use sui::sui::SUI;

public struct MyToken has key {
    id: UID,
    name: String,
}

public fun coin_value(c: &Coin<SUI>): u64 {
    coin::value(c)
}

public fun create_token(name: String, ctx: &mut TxContext): MyToken {
    MyToken {
        id: object::new(ctx),
        name,
    }
}

小结

模块导入是 Move 代码组织的核心机制。本节核心要点：

• 模块导入：use package::module; 导入模块，通过 module::member 访问成员
• 成员导入：use package::module::Member; 直接导入类型或函数
• 分组导入：use package::module::{Self, Type1, Type2}; 一次导入多个成员
• 别名：use package::module::Type as Alias; 解决命名冲突
• Self 关键字：在分组导入中代表模块本身
• 预导入（Prelude）：object、transfer、TxContext 及常用 vector / option 等往往无需再 use，详见 §5.4 默认导入的包与预置名称
• 外部依赖：通过 Move.toml 配置，CLI v1.45+ 自动包含系统包

默认导入的包与预置名称

上一节学习了显式 use。在 Sui Move 中，编译器还会注入一层 Prelude（预导入）：部分模块与类型无需写 use 即可使用。若再手动 use 同名模块，会触发 duplicate alias 类警告。本节说明预导入里有什么、哪些仍须手写 use，并区分「编译期预导入」与「链上固定地址上的包 / 对象」。

为什么需要 Prelude

合约里几乎总会用到 object::new、transfer::public_transfer、TxContext 等。若每个文件都重复：

use sui::object;
use sui::transfer;
use sui::tx_context::TxContext;

既冗长又易与编译器内建别名冲突。因此 Sui 工具链为 Move 2024 Edition 提供了预导入集合（具体列表以当前 sui move build 为准，随版本可能微调）。

常见预导入模块与类型

下表为日常编写中最常遇到的、往往可直接写 object::、transfer::、tx_context:: 的原因（不必再为模块名单独 use）：

提示：若你显式写了 use sui::object; 而编译器提示 Unnecessary alias / duplicate alias，说明该项已在 Prelude 中，可删去多余的 use 以消除警告。

仍须显式 use 的常见项

下列在多数模块中不会预导入，需按上一节方式自行 use：

• std::string::String、std::ascii::String 等字符串类型
• sui::coin、sui::sui::SUI、sui::balance 等与代币相关的模块
• sui::event、sui::clock::Clock、sui::table::Table 等按业务再引入

编写时以 sui move build 报错为准：若提示 未解析的名称，补一条 use 即可。

「链上的包地址」≠ Prelude

• Prelude 是编译器在源码里帮你展开的命名空间，解决的是「少写 use」。
• 链上 0x1、0x2 等是已发布包的地址（Move 标准库、Sui Framework 等），与「是否预导入」是不同层面的事；详见第四章 · 地址与附录 B · 保留地址。

系统对象（共享对象）简表

部分能力需要在函数参数中传入系统共享对象的引用，例如：

调用这些函数时，通常通过 sui::clock::Clock 等类型与 entry / public 函数参数由运行时注入，不是 Prelude 替你导入「整个对象」，而是类型定义仍来自 sui::clock 等模块——多数情况需要 use sui::clock::Clock。

与 Move.toml 隐式依赖的关系

Sui CLI 1.45+ 对 Framework 的隐式 [dependencies] 与 Prelude 是互补关系：前者让 sui::... / std::... 包能链接到链上对应字节码；后者让你在源码里少写 use。Edition 与依赖写法见第六章 §6.11 · Move 2024 Edition。

小结

• Prelude：编译器预导入的一批模块（如 object、transfer、tx_context，以及常用的 vector / option 等），可直接使用其路径或类型。
• 重复 use：易触发 duplicate alias 警告，删除多余导入即可。
• 多数业务模块（string、coin、event 等）仍需显式 use。
• 0x1 / 0x2 / 系统共享对象 ID 描述的是链上部署与运行时对象，与 Prelude 概念不同；系统对象详见后文章节与附录 B。

整数类型

Move 提供六种无符号整数类型，没有有符号整数。所有整数类型都具有 copy、drop 和 store 能力，是构建数值逻辑的基础。

整数类型一览

整数字面量

整数字面量可以使用后缀指定类型，也可以使用下划线分隔提高可读性：

module book::int_literals;

#[test]
fun literals() {
    let a: u8 = 255;
    let b = 1_000_000u64;       // 下划线分隔
    let c = 0xFF_u8;            // 十六进制
    let d: u128 = 1_000_000_000_000;
    let e: u256 = 0;

    assert_eq!(a, 255);
    assert_eq!(b, 1000000);
}

算术运算符

位运算符

比较运算符

综合示例

module book::primitive_examples;

#[test]
fun primitives() {
    let a: u8 = 255;
    let b: u64 = 1_000_000;
    let c: u128 = 1_000_000_000_000;
    let d: u256 = 0;

    let sum = 10u64 + 20;
    let diff = 30u64 - 10;
    let product = 5u64 * 6;
    let quotient = 100u64 / 3;
    let remainder = 100u64 % 3;
}

溢出保护

Move 的整数运算在运行时具有 溢出保护。当运算结果超出类型范围时，程序会产生运行时错误（abort），而不是静默地回绕（wrapping）：

module book::overflow;

#[test]
#[expected_failure(abort_code = /* arithmetic error */)]
fun overflow() {
    let max: u8 = 255;
    let _result = max + 1; // 运行时 abort，不会回绕为 0
}

这一设计确保了链上资产运算的安全性，避免因溢出导致的漏洞。

类型推断与显式标注

Move 编译器通常可以根据上下文推断变量类型，但在某些情况下需要显式标注：

module book::type_inference;

#[test]
fun inference() {
    let a = 42;             // 编译器从使用场景推断类型
    let b: u64 = 42;        // 显式标注为 u64
    let c = 42u8;           // 通过后缀指定为 u8
    let d = (42 as u128);   // 通过 as 指定为 u128

    assert_eq!(b, (a as u64));
}

当编译器无法推断类型时（例如变量未被使用，或者存在多种可能的类型），你需要显式标注类型。

小结

• 整数类型：u8、u16、u32、u64、u128、u256，全部为无符号
• 字面量：后缀指定类型、下划线分隔、十六进制
• 运算符：算术（+、-、*、/、%）、位运算（&、|、^、<<、>>）、比较（==、!=、<、>、<=、>=）
• 溢出保护：运行时检测溢出并 abort，而非静默回绕

布尔与类型转换

布尔类型与类型转换是 Move 基础类型的重要组成部分。布尔用于条件与逻辑判断；as 用于在不同整数类型之间进行显式转换。

布尔类型

布尔类型 bool 只有两个值：true 和 false。

逻辑运算符

module book::bool_example;

#[test]
fun bool_ops() {
    let a = true;
    let b = false;

    assert!(a && !b);     // true && true = true
    assert!(a || b);      // true || false = true
    assert!(!(a && b));   // !(true && false) = true
}

逻辑与 && 和逻辑或 || 支持 短路求值：如果左操作数已经能确定结果，右操作数不会被求值。

类型转换

Move 使用 as 关键字在不同整数类型之间进行显式转换：

module book::casting;

#[test]
fun casting() {
    let x: u8 = 42;
    let y: u64 = (x as u64);
    let z: u128 = (y as u128);
    let w: u256 = (z as u256);

    // 也可以从大类型转到小类型（会截断）
    let big: u64 = 300;
    let small: u8 = (big as u8); // 300 % 256 = 44
    assert_eq!(small, 44);
}

注意：从大类型向小类型转换时会发生截断，高位被丢弃。

小结

• 布尔类型：true/false，支持 &&、||、!，短路求值
• 类型转换：使用 as 关键字进行显式转换，大转小会截断

地址类型（address）

地址类型 address 是 Move 语言中的一种特殊类型，占用 32 字节（256 位），用于表示区块链上的位置标识。在 Sui 中，地址既用于标识账户（用户钱包），也用于标识对象（Object）。掌握地址类型及其转换方法，是与链上资源交互的基础。

地址字面量

地址字面量以 @ 符号开头，可以使用十六进制值或命名地址：

module book::address_literal;

#[test]
fun address_literal() {
    // 十六进制字面地址
    let addr1 = @0x0;
    let addr2 = @0x1;
    let addr3 = @0x2;

    // 命名地址（在 Move.toml 中定义）
    let std_addr = @std;   // 等价于 @0x1
    let sui_addr = @sui;   // 等价于 @0x2
}

常见的预定义地址：

地址与 u256 之间的转换

地址本质上是一个 256 位的数值，因此可以与 u256 类型互相转换：

module book::address_u256;

#[test]
fun address_u256() {
    let addr = @0x1;

    // address -> u256
    let addr_as_u256: u256 = addr.to_u256();
    assert_eq!(addr_as_u256, 1u256);

    // u256 -> address
    let addr_from_u256 = address::from_u256(addr_as_u256);
    assert_eq!(addr, addr_from_u256);
}

地址与字节数组之间的转换

地址可以转换为 32 字节的 vector<u8>，也可以从字节数组还原：

module book::address_bytes;

#[test]
fun address_bytes() {
    let addr = @0x1;

    // address -> vector<u8>（32字节）
    let bytes: vector<u8> = addr.to_bytes();
    assert_eq!(bytes.length(), 32);

    // vector<u8> -> address
    let addr_from_bytes = address::from_bytes(bytes);
    assert_eq!(addr, addr_from_bytes);
}

注意：address::from_bytes 要求传入的 vector<u8> 长度恰好为 32 字节，否则会产生运行时错误。

地址与字符串之间的转换

地址可以转换为十六进制字符串表示：

module book::address_examples;

use std::string::String;

#[test]
fun address() {
    let addr = @0x1;
    let named_addr = @std;

    // Convert to u256
    let addr_as_u256: u256 = addr.to_u256();
    let addr_from_u256 = address::from_u256(addr_as_u256);
    assert_eq!(addr, addr_from_u256);

    // Convert to bytes
    let bytes: vector<u8> = addr.to_bytes();
    let addr_from_bytes = address::from_bytes(bytes);
    assert_eq!(addr, addr_from_bytes);

    // Convert to string
    let addr_str: String = addr.to_string();
}

地址与对象 ID 的关系

在 Sui 中，每个对象（Object）都有一个唯一的 ID，类型为 sui::object::ID。对象 ID 本质上也是一个地址值，两者之间存在密切关系：

module book::address_and_id;

use sui::object;

public fun id_to_address(id: &object::ID): address {
    object::id_to_address(id)
}

public fun address_to_id(addr: address): object::ID {
    object::id_from_address(addr)
}

理解地址的双重角色

在 Sui 网络中，地址扮演着双重角色：

1. 账户地址：每个用户钱包对应一个地址，用于发送交易和持有对象
2. 对象地址：每个链上对象都有一个唯一的地址（即对象 ID）

两者在格式上完全相同，都是 32 字节的十六进制值。区别在于语义：账户地址是由公钥派生的，而对象地址是在对象创建时由系统生成的。

转换方法汇总

小结

地址类型是 Move 与区块链交互的核心类型。本节核心要点：

• 地址是 32 字节（256 位）的特殊类型，用 @ 前缀表示
• 支持十六进制字面量（@0x1）和命名地址（@std）
• 提供与 u256、vector<u8>、String 之间的双向转换方法
• 在 Sui 中，地址既标识账户也标识对象，对象 ID 本质上就是一个地址

元组与 Unit

Move 支持元组形式的表达式，用于多返回值和解构；同时提供 unit 类型 ()，表示“无有意义值”。元组在字节码层并不存在独立表示，因此不能绑定到局部变量、不能存入结构体、也不能作为泛型类型参数实例化，只能在表达式（尤其是返回值）中使用。

Unit 类型 ()

Unit 是“空元组”，类型为 ()，常用于无返回值的函数：

module book::unit_example;

public fun do_nothing(): () {
    ()
}

public fun do_nothing_implicit() {
    // 无返回类型时默认为 ()
}

空块或块尾带分号时，块的值也是 ()。

元组字面量

元组由括号内逗号分隔的表达式构成，类型为 (T1, T2, ...)。注意单元素 (e) 只是括号，类型仍是 e 的类型，不是单元素元组：

module book::tuples;

public fun returns_unit(): () {
    ()
}

public fun returns_pair(): (u64, bool) {
    (0, false)
}

public fun returns_three(): (u64, u8, address) {
    (1, 2, @0x42)
}

元组解构

在 let 或赋值中可对元组解构，按位置绑定到多个局部变量：

#[test]
fun destructure() {
    let () = ();
    let (x, y): (u64, u64) = (0, 1);
    let (a, b, c) = (@0x0, 0u8, true);

    (x, y) = (2, 3);
    assert_eq!(x, 2);
    assert_eq!(y, 3);
}

元组长度必须与模式一致，否则会报错。

多返回值

函数返回多个值时，在类型和 return 处使用元组语法；调用方用解构接收：

public fun swap(a: u64, b: u64): (u64, u64) {
    (b, a)
}

#[test]
fun use_swap() {
    let (x, y) = swap(1, 2);
    assert_eq!(x, 2);
    assert_eq!(y, 1);
}

Move 不允许在结构体中存储引用，因此多返回值（尤其是包含引用时）依赖元组语法实现。

小结

• () 是 unit 类型，表示“无值”；无返回类型的函数即返回 ()。
• 元组 (e1, e2, ...) 用于多返回值和解构，不能存到变量或结构体。
• 通过 let (a, b, ...) = ... 或赋值解构元组，长度需匹配。

表达式

在 Move 中，几乎所有的语法构造都是表达式（Expression），即它们会产生一个值。唯一的例外是 let 语句——它是语句（Statement），不产生值。这种“一切皆表达式“的设计让 Move 的代码风格更加简洁和富有表达力。

字面量表达式

字面量是最基本的表达式，直接表示一个值：

module book::literals;

#[test]
fun literals() {
    // 布尔字面量
    let _b1 = true;
    let _b2 = false;

    // 整数字面量
    let _i1 = 42u64;
    let _i2 = 0xFF;        // 十六进制

    // 字节向量字面量
    let _bytes1 = b"hello"; // UTF-8 字符串转字节向量
    let _bytes2 = x"0A1B";  // 十六进制字节向量

    // 地址字面量
    let _addr = @0x1;
}

字节向量的两种写法

• b"hello"：将 UTF-8 字符串编码为 vector<u8>
• x"0A1B"：将十六进制值直接解析为 vector<u8>

运算符表达式

所有运算符都会产生一个值，因此它们也是表达式：

module book::operator_expr;

#[test]
fun operators() {
    // 算术运算产生整数值
    let sum = 10 + 20;         // 30
    let product = 5 * 6;       // 30

    // 比较运算产生布尔值
    let is_equal = sum == product;  // true

    // 逻辑运算产生布尔值
    let is_positive = sum > 0;
    let combined = is_equal && is_positive; // true

    assert!(combined);
}

块表达式

用花括号 { } 包裹的代码块本身也是一个表达式。块中最后一个表达式的值（不带分号）就是整个块的返回值：

module book::block_expr;

#[test]
fun block_returns_value() {
    let x = {
        let a = 10;
        let b = 20;
        a + b  // 没有分号 = 返回值
    };
    assert_eq!(x, 30);

    // 嵌套块表达式
    let y = {
        let inner = {
            let c = 5;
            c * 2
        };
        inner + 10
    };
    assert_eq!(y, 20);
}

空块

空块 {} 返回单元值 ()（unit type）：

module book::empty_block;

#[test]
fun empty_block() {
    let _unit: () = {};
}

分号的作用

分号 ; 用于终止一个表达式。被分号终止的表达式的值会被丢弃。如果分号后面没有其他表达式，编译器会自动插入单元值 ()：

module book::semicolons;

#[test]
fun semicolons() {
    // 带分号：值被丢弃，块返回 ()
    let _a: () = {
        10 + 20; // 值 30 被丢弃
    };

    // 不带分号：值被返回
    let b: u64 = {
        10 + 20 // 值 30 被返回
    };
    assert_eq!(b, 30);
}

常见错误：函数末尾不小心加了分号，导致返回 () 而非预期值。这是新手最容易犯的错误之一。

函数调用作为表达式

函数调用也是表达式，其值为函数的返回值：

module book::func_expr;

fun double(x: u64): u64 {
    x * 2
}

fun add(a: u64, b: u64): u64 {
    a + b
}

#[test]
fun func_as_expr() {
    // 函数调用的结果可以直接参与运算
    let result = add(double(5), double(3));
    assert_eq!(result, 16); // (5*2) + (3*2) = 16
}

控制流表达式

if/else 在 Move 中也是表达式，会产生一个值：

module book::expression_examples;

#[test]
fun expressions_mixed() {
    // Literals
    let _bool_val = true;
    let _int_val = 42u64;
    let _hex_val = 0xFF;
    let _bytes = b"hello";

    // Block expression returns a value
    let x = {
        let a = 10;
        let b = 20;
        a + b  // no semicolon = return value
    };
    assert_eq!(x, 30);

    // if as expression
    let y = if (x > 20) { 1 } else { 0 };
    assert_eq!(y, 1);

    // Operators
    let sum = 10 + 20;
    let is_positive = sum > 0;
    assert!(is_positive);
}

当 if/else 作为表达式使用时，两个分支的返回类型必须一致：

module book::if_expr;

#[test]
fun if_expr_grade() {
    let score = 85u64;

    let grade = if (score >= 90) {
        b"A"
    } else if (score >= 80) {
        b"B"
    } else if (score >= 70) {
        b"C"
    } else {
        b"D"
    };

    assert_eq!(grade, b"B");
}

表达式序列

多个表达式可以通过分号连接形成序列，最后一个表达式的值是整个序列的值：

module book::expr_sequence;

fun compute(input: u64): u64 {
    let doubled = input * 2;
    let offset = doubled + 10;
    let result = offset / 3;
    result // 最后一个表达式的值作为函数返回值
}

#[test]
fun sequence() {
    assert_eq!(compute(10), 10); // (10*2 + 10) / 3 = 10
}

小结

表达式是 Move 语言的核心语法概念。本节核心要点：

• Move 中几乎一切都是表达式，唯一的例外是 let 语句
• 字面量：布尔、整数、十六进制、字节向量（b"..."、x"..."）、地址都是表达式
• 块表达式：{ } 中最后一个不带分号的表达式是块的返回值
• 分号：终止表达式并丢弃其值，末尾加分号会导致返回 ()
• 控制流：if/else 也是表达式，两个分支返回类型必须一致
• 函数调用：函数调用的结果可以直接作为表达式参与运算

局部变量与作用域

Move 中的局部变量采用词法（静态）作用域，通过 let 引入。使用 mut 标记的变量可以重新赋值或被可变借用。本节系统介绍变量声明、类型标注、解构、作用域、遮蔽（shadowing）以及 move 与 copy 的语义。

let 绑定

使用 let 将名字绑定到值：

module book::variables;

#[test]
fun let_bindings() {
    let x = 1;
    let y = x + x;
    assert_eq!(y, 2);
}

可以先声明后赋值（便于在分支或循环中赋初值）：

#[test]
fun let_then_assign() {
    let x;
    if (true) {
        x = 1
    } else {
        x = 0
    };
    assert_eq!(x, 1);
}

变量在赋值前不能使用，且在所有控制流路径上都必须被赋值，否则类型检查会报错（例如 let x; if (cond) x = 0; x + 1 在 else 分支未赋 x 会报错；while 循环后的 x 也视为可能未赋值）。

mut 可变变量

需要重新赋值或需要被 &mut 借用时，必须用 let mut 声明：

#[test]
fun mut_var() {
    let mut x = 0;
    x = x + 1;
    assert_eq!(x, 1);
}

函数参数若需可变借用，也应使用 mut，例如 fun f(mut v: vector<u64>)。

变量命名规则

变量名可包含字母、数字和下划线，且必须以小写字母或下划线开头，不能以大写字母开头（大写用于类型或常量）：

let x = 1;      // 合法
let _x = 1;     // 合法，下划线常用于“有意忽略”
let x0 = 1;     // 合法
// let X = 1;   // 非法

类型标注

多数情况下类型可推断，需要时可显式标注：

let x: u64 = 0;
let v: vector<u8> = vector[];
let a: address = @0x0;

在以下情况类型标注是必须的：（1）泛型无法推断，例如空向量 vector[]；（2）发散表达式（如 return、abort、无 break 的 loop）的绑定，编译器无法从后续代码推断类型。类型标注写在模式右侧、等号左侧，例如 let (x, y): (u64, u64) = (0, 1);，而不是 let (x: u64, y: u64) = ...。

let empty: vector<u64> = vector[];  // 必须标注元素类型

用元组一次绑定多个变量

let 可以用元组同时引入多个变量：

#[test]
fun tuple_destructure() {
    let () = ();
    let (x, y) = (0u64, 1u64);
    let (a, b, c) = (true, 10u8, @0x1);
    assert_eq!(x + y, 1);
}

元组长度必须与模式匹配，且同一 let 中不能重复同名变量。

用结构体解构绑定

可以从结构体中解构出字段并绑定到局部变量：

public struct Point has copy, drop {
    x: u64,
    y: u64,
}

#[test]
fun struct_destructure() {
    let Point { x, y } = Point { x: 1, y: 2 };
    assert_eq!(x + y, 3);
}

#[test]
fun struct_destructure_rename() {
    let Point { x: a, y: b } = Point { x: 10, y: 20 };
    assert_eq!(a, 10);
    assert_eq!(b, 20);
}

对引用解构会得到引用类型的绑定（&t / &mut t），不会消费原值。

忽略值：下划线

不需要绑定的值可用 _ 忽略，避免“未使用变量”警告：

let (x, _, z) = (1, 2, 3);  // 第二个值被忽略

块与作用域

用花括号 { } 构成块；块内 let 只在该块内有效。块最后一个表达式（无分号）的值即为块的值：

#[test]
fun block_scope() {
    let x = 0;
    let y = {
        let inner = 1;
        x + inner
    };
    assert_eq!(y, 1);
    // inner 在此不可见
}

内层块可以访问外层变量；外层不能访问内层声明的变量。

遮蔽（Shadowing）

同一作用域内再次用 let 声明同名变量会遮蔽之前的绑定，之后无法访问旧值：

#[test]
fun shadowing() {
    let x = 0;
    assert_eq!(x, 0);
    let x = 1;  // 遮蔽
    assert_eq!(x, 1);
}

被遮蔽的变量若类型无 drop 能力，其值仍须在函数结束前被转移或销毁，不能“藏起来”就不管。

赋值

mut 变量可通过赋值 x = e 修改。赋值本身是表达式，类型为 ()：

let mut x = 0;
x = 1;
if (cond) x = 2 else x = 3;

move 与 copy

• copy：复制值，原变量仍可使用；仅对具有 copy 能力的类型可用。
• move：将值移出变量，移出后该变量不可再使用。

未显式写 copy 或 move 时，编译器按以下规则推断：
（1）有 copy 能力的类型默认 copy；
（2）引用（&T、&mut T）默认 copy（特殊情况下在不再使用时可能按 move 处理以得到更清晰的借用错误）；
（3）其他类型（无 copy 或资源类型）默认 move。

let x = 1;
let y = copy x;  // 显式复制，x 仍可用
let z = move x;  // 移出后 x 不可再用

小结

• 用 let 引入局部变量，需要修改或可变借用时用 let mut。
• 变量名以小写或下划线开头；可选用类型标注。
• 可用元组或结构体解构一次绑定多个变量，用 _ 忽略不需要的值。
• 块 { } 限定作用域；块尾无分号的表达式为块的值。
• 同名 let 会遮蔽；赋值仅针对 mut 变量。
• 值的使用方式由 move/copy 语义决定，编译器会做推断。

相等比较

Move 提供两种相等运算：==（相等）和 !=（不相等）。两者都要求两个操作数类型相同，且比较会消费参与比较的值，因此只有具有 drop 能力的类型可以直接用 == / != 比较；否则应先借用再比较。

基本用法

module book::equality;

#[test]
fun equality_basic() {
    assert!(0 == 0);
    assert!(1u128 != 2u128);
    assert!(b"hello" != b"world");
}

类型要求

两边类型必须一致；可用于所有类型（包括自定义结构体，只要该类型有 drop 能力）：

public struct S has copy, drop {
    f: u64,
}

#[test]
fun struct_equality() {
    let s1 = S { f: 1 };
    let s2 = S { f: 1 };
    assert!(s1 == s2);
    assert!(s1 != S { f: 2 });
}

引用比较

比较引用时，比较的是所指的值，与引用是 & 还是 &mut 无关；&T 与 &mut T 可以互相比较（底层类型须相同）。语义上等价于在需要不可变引用的地方对 &mut 做一次 freeze 再比较：

#[test]
fun ref_equality() {
    let x = 0;
    let mut y = 1;
    let r = &x;
    let m = &mut y;
    assert!(r != m);  // 0 != 1
    assert!(r == r);
    assert!(m == m);
    // 等价于：r == freeze(m)、freeze(m) == r 等
}

两边的底层类型必须相同，例如 &u64 与 &vector<u8> 不能比较。

无 drop 类型：先借用再比较

没有 drop 能力的值不能直接被 == / != 消费，否则会报错。应使用引用比较：

public struct Coin has store {
    value: u64,
}

public fun coins_equal(c1: &Coin, c2: &Coin): bool {
    c1 == c2  // 比较引用指向的值
}

Move 2024：自动借用

Move 2024 中，若一边是引用、另一边是值，会自动对值做不可变借用再比较，因此无需手写 &：

let r = &0;
r == 0;   // true，0 被自动借用为 &0
0 == r;   // true
r != 1;   // false

自动借用始终是不可变借用。

避免不必要的 copy

对大型值或向量，用引用比较可避免复制：

assert!(&v1 == &v2);   // 推荐
assert!(copy v1 == copy v2);  // 可能产生大拷贝

小结

• ==、!= 要求两操作数类型相同，可用于有 drop 的类型及引用。
• 无 drop 的类型需通过引用比较（&a == &b）。
• 大值或向量建议用引用比较以减少 copy。

结构体（Struct）

结构体（Struct）是 Move 语言中定义自定义类型的核心机制，也是类型系统的基本构建块。通过结构体，开发者可以将多个不同类型的数据组合成一个有意义的整体。在 Sui 中，链上对象本质上就是带有 key 能力的结构体。

定义结构体

结构体使用 struct 关键字定义，可以附带能力声明和字段列表：

module book::struct_definition;

use std::string::String;

public struct Profile has key, store {
    id: UID,
    name: String,
    age: u8,
    is_active: bool,
}

语法结构

[public] struct 名称 [has 能力列表] {
    字段名1: 类型1,
    字段名2: 类型2,
    ...
}

• public 修饰符使类型对外可见（字段仍然是私有的）
• has 后面跟能力列表，详见能力系统章节
• 字段类型可以是任何合法的 Move 类型，包括其他结构体

命名规范

• 结构体名使用 PascalCase（大驼峰）：MyStruct、TokenBalance
• 字段名使用 snake_case（蛇形）：total_supply、is_active

嵌套结构体

结构体的字段可以包含其他结构体类型，但 不允许递归引用自身：

module book::struct_examples;

use std::string::String;
use std::option::Option;

public struct Artist has copy, drop {
    name: String,
}

public struct Record has copy, drop {
    title: String,
    artist: Artist,
    year: u16,
    is_debut: bool,
    edition: Option<u16>,
}

创建实例

通过结构体名称和字段赋值来创建实例。所有字段都必须赋值：

module book::struct_create;

use std::string::String;

public struct Point has copy, drop {
    x: u64,
    y: u64,
}

public struct NamedPoint has copy, drop {
    name: String,
    point: Point,
}

#[test]
fun create() {
    let origin = Point { x: 0, y: 0 };
    let p = Point { x: 10, y: 20 };

    let named = NamedPoint {
        name: b"Center".to_string(),
        point: origin,
    };
}

当变量名与字段名相同时，可以使用简写语法：

module book::struct_shorthand;

public struct Pair has copy, drop {
    first: u64,
    second: u64,
}

#[test]
fun shorthand() {
    let first = 10u64;
    let second = 20u64;
    let pair = Pair { first, second }; // 等价于 Pair { first: first, second: second }
    assert_eq!(pair.first, 10);
}

字段访问

使用 . 运算符访问结构体字段。字段访问仅限于定义该结构体的模块内部：

module book::struct_access;

use std::string::String;
use std::option::Option;

public struct Artist has copy, drop {
    name: String,
}

public struct Record has copy, drop {
    title: String,
    artist: Artist,
    year: u16,
    is_debut: bool,
    edition: Option<u16>,
}

public fun new_artist(name: String): Artist {
    Artist { name }
}

public fun new_record(
    title: String,
    artist: Artist,
    year: u16,
    is_debut: bool,
    edition: Option<u16>,
): Record {
    Record { title, artist, year, is_debut, edition }
}

public fun artist_name(artist: &Artist): &String {
    &artist.name
}

public fun record_year(record: &Record): u16 {
    record.year
}

解构（Unpacking）

解构可以将结构体的字段值提取到独立变量中。这是访问结构体内部数据的另一种方式：

module book::struct_unpack;

use std::string::String;
use std::option::Option;

public struct Artist has copy, drop {
    name: String,
}

public struct Record has copy, drop {
    title: String,
    artist: Artist,
    year: u16,
    is_debut: bool,
    edition: Option<u16>,
}

#[test]
fun struct_unpack() {
    let artist = Artist { name: b"The Beatles".to_string() };
    let record = Record {
        title: b"Abbey Road".to_string(),
        artist,
        year: 1969,
        is_debut: false,
        edition: option::none(),
    };

    assert_eq!(record.year, 1969);
    assert_eq!(record.is_debut, false);

    // Unpacking
    let Record { title: _, artist: _, year, is_debut: _, edition: _ } = record;
    assert_eq!(year, 1969);
}

忽略不需要的字段

解构时，对于不需要的字段，使用 _ 前缀或直接用 _ 来忽略：

module book::struct_ignore;

public struct Config has copy, drop {
    width: u64,
    height: u64,
    depth: u64,
    color: u8,
}

#[test]
fun ignore_fields() {
    let config = Config { width: 100, height: 200, depth: 50, color: 3 };

    // 只关心 width 和 height
    let Config { width, height, depth: _, color: _ } = config;
    assert_eq!(width, 100);
    assert_eq!(height, 200);
}

无能力结构体的约束

没有任何能力的结构体不能被丢弃，必须显式处理（解构）。这是 Move 资源安全性的重要保障：

module book::struct_no_ability;

public struct Receipt {
    amount: u64,
    paid: bool,
}

public fun create_receipt(amount: u64): Receipt {
    Receipt { amount, paid: false }
}

public fun consume_receipt(receipt: Receipt) {
    let Receipt { amount: _, paid: _ } = receipt; // 必须解构
}

如果尝试忽略没有 drop 能力的结构体实例，编译器会报错。这一特性常用于实现 Hot Potato 模式，确保某些操作必须被完成。

可变字段

对于可变引用的结构体，可以直接修改其字段值：

module book::struct_mut;

public struct Balance has copy, drop {
    value: u64,
}

public fun increase(balance: &mut Balance, amount: u64) {
    balance.value = balance.value + amount;
}

public fun decrease(balance: &mut Balance, amount: u64) {
    assert!(balance.value >= amount);
    balance.value = balance.value - amount;
}

#[test]
fun mut_fields() {
    let mut bal = Balance { value: 100 };
    increase(&mut bal, 50);
    assert_eq!(bal.value, 150);
    decrease(&mut bal, 30);
    assert_eq!(bal.value, 120);
}

小结

结构体是 Move 类型系统的核心。本节核心要点：

• 使用 struct 关键字定义自定义类型，字段可以是任何合法类型（不支持递归）
• 结构体类型默认私有，public struct 使类型可见，但 字段始终私有
• 创建实例需要提供所有字段值，支持变量名与字段名相同时的简写语法
• 字段访问（.运算符）仅限于定义该结构体的模块内部
• 解构（unpacking）可以提取字段值，不需要的字段用 _ 忽略
• 没有能力的结构体不能被丢弃，必须显式解构——这是 Move 资源安全性的基石

能力系统概览（Abilities）

能力系统（Abilities）是 Move 语言最独特的类型系统特性之一，它通过四种能力——copy、drop、key、store——来精确控制类型的行为。不同于大多数编程语言中类型可以被随意复制和丢弃，Move 要求开发者显式声明类型的行为权限，从而在编译期保障链上资源的安全性。

能力声明

能力通过 has 关键字声明在结构体定义中：

module book::ability_syntax;

// 同时拥有多个能力，用逗号分隔
public struct Token has key, store {
    id: UID,
    value: u64,
}

// 没有任何能力的结构体
public struct Unique {
    value: u64,
}

四种能力详解

copy —— 可复制

拥有 copy 能力的类型，其值可以被隐式复制。没有 copy 的值在赋值或传参时会被 移动（move），原变量将不可再使用：

module book::ability_copy;

public struct Copyable has copy, drop {
    value: u64,
}

public struct NonCopyable has drop {
    value: u64,
}

#[test]
fun copy_vs_move() {
    let a = Copyable { value: 42 };
    let b = a;  // 复制，a 仍然可用
    assert_eq!(a.value, 42);
    assert_eq!(b.value, 42);

    let c = NonCopyable { value: 100 };
    let d = c;  // 移动，c 不再可用
    // assert!(c.value == 100); // 编译错误！c 已被移动
    assert_eq!(d.value, 100);
}

drop —— 可丢弃

拥有 drop 能力的类型，其值可以在离开作用域时被自动丢弃。没有 drop 的值必须被显式消费（解构或转移）：

module book::ability_drop;

public struct Droppable has drop {
    value: u64,
}

public struct MustUse {
    value: u64,
}

public fun consume(item: MustUse) {
    let MustUse { value: _ } = item; // 必须显式解构
}

key —— 可作为存储键

拥有 key 能力的类型可以作为链上对象存在。在 Sui 中，key 结构体的第一个字段必须是 id: UID：

module book::ability_key;

public struct MyObject has key {
    id: UID,
    data: u64,
}

key 是将结构体变为 Sui 对象的必要条件。拥有 key 的对象可以被转移、共享或冻结。

store —— 可存储

拥有 store 能力的类型可以被存储在其他拥有 key 的对象内部。store 也是对象能被公开转移（public_transfer）的必要条件：

module book::ability_store;

use std::string::String;

public struct Metadata has store, copy, drop {
    name: String,
    version: u64,
}

public struct Container has key, store {
    id: UID,
    metadata: Metadata,  // Metadata 有 store，可以存在对象中
}

能力组合总览

内置类型的能力

所有原始类型天然拥有 copy、drop 和 store：

完整示例

module book::abilities_example;

// Has all four abilities - can be copied, dropped, stored as object
public struct FullAbility has key, store, copy, drop {
    id: UID,
    value: u64,
}

// Can be copied and dropped but not stored
public struct Copyable has copy, drop {
    value: u64,
}

// No abilities - Hot Potato! Must be explicitly consumed
public struct HotPotato {
    value: u64,
}

// Only drop - Witness pattern
public struct Witness has drop {}

能力约束与泛型

在泛型函数或泛型结构体中，可以对类型参数施加能力约束：

module book::ability_constraints;

public struct Box<T: store> has key, store {
    id: UID,
    content: T,
}

public fun unbox<T: store>(box: Box<T>): T {
    let Box { id, content } = box;
    object::delete(id);
    content
}

T: store 意味着只有拥有 store 能力的类型才能放入 Box 中。这种约束在编译期就能捕获类型错误。

常见设计模式

Hot Potato 模式

没有任何能力的结构体不能被复制、丢弃或存储，必须在创建它的交易中被显式消费。这个模式常用于强制执行某些操作序列：

module book::hot_potato;

public struct FlashLoan {
    amount: u64,
}

public fun borrow(amount: u64): (u64, FlashLoan) {
    (amount, FlashLoan { amount })
}

public fun repay(loan: FlashLoan, payment: u64) {
    let FlashLoan { amount } = loan;
    assert!(payment >= amount);
}

Witness 模式

只有 drop 能力的结构体，通常用于一次性类型证明（One-Time Witness）：

module book::witness;

public struct WITNESS has drop {}

小结

能力系统是 Move 语言安全性的核心保障。本节核心要点：

• 四种能力：copy（可复制）、drop（可丢弃）、key（可作为对象）、store（可存储）
• 能力通过 has 关键字在结构体定义中声明
• 所有原始类型拥有 copy、drop、store
• 没有能力的结构体（Hot Potato）必须被显式消费，确保操作不可跳过
• 只有 drop 的结构体（Witness）用于一次性类型证明
• 泛型中可以通过能力约束限制类型参数
• 能力系统在编译期强制执行资源安全规则，防止资产被意外复制或丢弃

Drop 能力详解

drop 能力决定了结构体实例是否可以被自动丢弃（忽略）。当一个值离开作用域或被赋值覆盖时，如果该类型拥有 drop 能力，值会被自动清理；否则编译器会要求开发者显式处理该值。这一机制是 Move 保障数字资产安全的重要组成部分。

默认行为：不可丢弃

在 Move 中，结构体默认 没有 drop 能力。这意味着编译器会跟踪每一个实例的生命周期，确保它不会被静默地丢弃：

module book::no_drop;

public struct NoDrop {
    value: u64,
}

public fun create(): NoDrop {
    NoDrop { value: 42 }
}

// 如果函数中创建了 NoDrop 实例但没有处理，编译器会报错
// fun bad_example() {
//     let item = NoDrop { value: 42 };
//     // 编译错误：item 没有 drop 能力，不能被忽略
// }

public fun consume(item: NoDrop) {
    let NoDrop { value: _ } = item; // 必须显式解构
}

添加 drop 能力

通过 has drop 让结构体可以被自动丢弃：

module book::with_drop;

public struct Droppable has drop {
    value: u64,
}

#[test]
fun auto_drop() {
    let _item = Droppable { value: 42 };
    // 函数结束时，_item 自动被丢弃，无需任何处理
}

#[test]
fun reassign_drops_old() {
    let mut x = Droppable { value: 1 };
    x = Droppable { value: 2 }; // 旧值自动被丢弃
    assert_eq!(x.value, 2);
}

完整示例

module book::drop_example;

// Without drop - compilation error if ignored
public struct NoDrop {
    value: u64,
}

// With drop - can be safely ignored
public struct Droppable has drop {
    value: u64,
}

#[test]
fun drop_vs_no_drop() {
    // This works - Droppable is automatically dropped
    let _ = Droppable { value: 42 };

    // To use NoDrop, we must explicitly unpack it
    let no_drop = NoDrop { value: 100 };
    let NoDrop { value: _ } = no_drop; // must unpack
}

安全性价值

drop 的设计初衷是保护数字资产。考虑以下场景：

module book::asset_safety;

public struct Coin {
    value: u64,
}

public fun mint(value: u64): Coin {
    Coin { value }
}

public fun burn(coin: Coin): u64 {
    let Coin { value } = coin;
    value
}

因为 Coin 没有 drop 能力，它不能被“凭空消失“。如果函数接收了一个 Coin 却没有处理它，编译器会立即报错。这确保了代币不会在转账或交易过程中意外丢失。

原生类型的 drop 能力

所有原生类型都拥有 drop 能力：

标准库中拥有 drop 的类型

以下常用标准库类型拥有 drop 能力：

Witness 模式

Witness（见证者）模式是 drop 能力最经典的应用之一。Witness 是一个 只有 drop 能力 的结构体，通常没有字段（或只有空字段），用于在类型层面进行身份证明：

module book::witness_pattern;

public struct MY_TOKEN has drop {}

public fun create_currency(witness: MY_TOKEN) {
    let MY_TOKEN {} = witness;
    // 使用 witness 证明调用者有权创建此类型的货币
    // witness 被解构后自动丢弃
}

One-Time Witness（OTW）

在 Sui 中，One-Time Witness 是一种特殊的 Witness，它只在模块初始化函数 init 中被创建一次，保证了某些操作（如代币发行）全局唯一：

module book::otw_example;

public struct OTW_EXAMPLE has drop {}

fun init(witness: OTW_EXAMPLE) {
    // witness 由系统自动创建并传入，全局只有一次
    // 用于初始化代币、NFT 集合等需要唯一性保证的操作
    let OTW_EXAMPLE {} = witness;
}

OTW 的命名规则：类型名必须与模块名相同（全大写），且结构体只有 drop 能力、没有字段。

条件 drop

对于包含泛型字段的结构体，drop 能力取决于所有字段类型是否都拥有 drop：

module book::conditional_drop;

public struct Wrapper<T: drop> has drop {
    inner: T,
}

public struct Container<T> {
    content: T,
}

// Wrapper<u64> 有 drop，因为 u64 有 drop
// Container<u64> 没有 drop，因为 Container 本身没有声明 drop

小结

drop 能力是 Move 资源安全模型的关键组成部分。本节核心要点：

• 默认不可丢弃：结构体默认没有 drop，必须显式处理每一个实例
• 添加 drop：通过 has drop 允许实例在离开作用域时自动清理
• 安全保障：不可丢弃的类型确保数字资产不会意外消失
• 原生类型：所有内置类型（bool、整数、address）天然拥有 drop
• 标准库：Option<T>、String 等常用类型也拥有 drop（可能依赖于泛型参数）
• Witness 模式：只有 drop 能力的空结构体，用于类型级别的身份证明
• OTW 模式：Sui 特有的一次性见证者，保证操作的全局唯一性

Copy 能力详解

copy 能力允许值被复制（Duplicate），是 Move 四大能力之一。没有 copy 能力的类型遵循 移动语义（Move Semantics），即值在赋值或传参后原变量将失效。理解 copy 能力对于掌握 Move 的所有权模型至关重要，它决定了值能否被安全地重复使用。

什么是 Copy

在 Move 中，默认情况下自定义结构体没有 copy 能力。当一个值被赋给另一个变量、传递给函数时，原始值会被 移动（move），此后不再可用。copy 能力改变了这一行为——拥有 copy 能力的类型在赋值和传参时会自动复制，原始值保持有效。

移动语义 vs 复制语义

没有 copy 的类型使用移动语义：

module book::move_semantics;

public struct NoCopy { value: u64 }

#[test]
#[expected_failure]
fun move_invalid_use_after() {
    let a = NoCopy { value: 42 };
    let _b = a;     // a 被移动到 _b
    // let _c = a;  // 编译错误：a 已被移动，不再可用
}

拥有 copy 的类型使用复制语义：

module book::copy_semantics;

public struct Copyable has copy, drop {
    value: u64,
}

#[test]
fun copy_both_valid() {
    let a = Copyable { value: 42 };
    let b = a;     // 隐式复制，a 仍然可用
    let c = a;     // 再次复制，a 依然可用
    assert_eq!(a.value, 42);
    assert_eq!(b.value, 42);
    assert_eq!(c.value, 42);
}

隐式复制与显式复制

隐式复制

当拥有 copy 能力的值被赋给新变量或传递给函数时，编译器会自动进行隐式复制：

module book::implicit_copy;

public struct Point has copy, drop {
    x: u64,
    y: u64,
}

fun consume_point(_p: Point) {}

#[test]
fun implicit_copy() {
    let p = Point { x: 10, y: 20 };

    let q = p;           // 隐式复制
    consume_point(p);    // 隐式复制后传入函数

    assert_eq!(q.x, 10);  // q 是 p 的副本
}

显式复制

使用解引用运算符 *& 可以进行显式复制，这种写法更加清晰地表达了开发者的意图：

module book::explicit_copy;

public struct Data has copy, drop {
    value: u64,
}

#[test]
fun explicit_copy() {
    let a = Data { value: 100 };
    let b = *&a;         // 显式复制：先取引用 &a，再解引用 *

    assert_eq!(a.value, 100);
    assert_eq!(b.value, 100);
}

*& 的语义是：先获取值的引用（&a），再通过解引用（*）创建一个副本。对于拥有 copy 能力的类型，这与隐式复制效果相同，但在代码审查中更容易识别复制操作。

Copy 与 Drop 的关系

在实践中，拥有 copy 能力的类型几乎总是同时拥有 drop 能力。原因在于：如果一个值可以被复制但不能被丢弃，那么每次复制都会产生一个新值，而所有这些值都必须被显式消耗，这会导致代码极其繁琐且容易出错。

module book::copy_drop;

public struct CopyDrop has copy, drop {
    value: u64,
}

#[test]
fun copy_drop_both_dropped() {
    let a = CopyDrop { value: 1 };
    let _b = a;     // 复制
    let _c = a;     // 再次复制
    // 函数结束时，a、_b、_c 都会自动 drop，无需手动处理
}

规则：如果一个类型拥有 copy，通常也应该赋予 drop。Move 编译器不会强制要求这一点，但这是社区的最佳实践。

原始类型的 Copy 能力

Move 中所有原始类型天然拥有 copy（以及 drop 和 store）能力：

module book::primitive_copy;

#[test]
fun primitive_copy() {
    let x: u64 = 42;
    let y = x;          // 隐式复制
    let z = *&x;        // 显式复制
    assert_eq!(x, 42);
    assert_eq!(y, 42);
    assert_eq!(z, 42);

    let v1 = vector[1u64, 2, 3];
    let v2 = v1;         // vector<u64> 有 copy，因为 u64 有 copy
    assert_eq!(v1.length(), 3);
    assert_eq!(v2.length(), 3);
}

标准库中拥有 Copy 的类型

除了原始类型，标准库中也有一些常用类型拥有 copy 能力：

module book::stdlib_copy;

use std::string::String;

#[test]
fun stdlib_copy() {
    let name: String = b"Sui".to_string();
    let name_copy = name;           // String 有 copy，可以复制
    assert!(name == name_copy);

    let maybe: Option<u64> = option::some(42);
    let maybe_copy = maybe;         // Option<u64> 有 copy
    assert!(maybe.is_some());
    assert!(maybe_copy.is_some());
}

结构体字段的约束

当一个结构体声明为 has copy 时，它的 所有字段 的类型都必须拥有 copy 能力。如果任何字段的类型不支持 copy，编译器会报错：

module book::copy_fields;

public struct Inner has copy, drop {
    value: u64,
}

public struct Outer has copy, drop {
    inner: Inner,       // Inner 有 copy，合法
    count: u64,         // u64 有 copy，合法
}

// 以下代码无法编译：
// public struct Bad has copy, drop {
//     id: UID,          // UID 没有 copy，编译错误
// }

这一规则确保了 copy 操作可以递归地复制结构体的每一个字段。

完整示例

下面的例子综合展示了 copy 能力在实际开发中的使用场景：

module book::copy_example;

use std::string::String;

public struct Config has copy, drop, store {
    name: String,
    max_retries: u64,
    enabled: bool,
}

public fun default_config(): Config {
    Config {
        name: b"default".to_string(),
        max_retries: 3,
        enabled: true,
    }
}

public fun with_name(config: &Config, name: String): Config {
    let mut new_config = *config;    // 显式复制配置
    new_config.name = name;
    new_config
}

#[test]
fun config_copy() {
    let base = default_config();
    let custom = with_name(&base, b"custom".to_string());

    // base 未被移动，仍然可用
    assert_eq!(base.name, b"default".to_string());
    assert_eq!(custom.name, b"custom".to_string());
    assert_eq!(base.max_retries, custom.max_retries);
}

小结

copy 能力控制了值是否可以被复制。本节核心要点：

• 移动 vs 复制：没有 copy 的类型遵循移动语义，赋值后原变量失效；有 copy 则自动复制
• 隐式复制：赋值和传参时自动发生
• 显式复制：使用 *&value 语法，意图更清晰
• Copy + Drop：拥有 copy 的类型通常也应该拥有 drop
• 原始类型：bool、所有整数类型、address 天然拥有 copy
• 字段约束：结构体声明 copy 时，所有字段类型必须也拥有 copy
• 标准库：String、Option<T>、TypeName 等常用类型拥有 copy

常量

常量（Constants）是使用 const 关键字定义的模块级不可变值。常量在编译时确定，存储在字节码中，每次使用时会被复制到使用位置。它们用于定义配置值、限制条件、错误码等在整个模块中共用的固定值。合理使用常量可以避免代码中出现难以理解的“魔术数字“，提升代码的可读性和可维护性。

基本语法

常量声明

常量使用 const 关键字声明，必须指定类型和初始值：

module book::const_basic;

const MAX_SUPPLY: u64 = 1_000_000;
const DEFAULT_PRICE: u64 = 100;
const IS_TESTNET: bool = true;
const ADMIN_ADDRESS: address = @0x1;
const APP_NAME: vector<u8> = b"MyApp";

名称约束

常量名称 必须以大写字母开头，这是编译器强制要求的规则。

社区约定使用两种命名风格：

• ALL_CAPS_WITH_UNDERSCORES — 用于普通常量值
• EPascalCase — 用于错误码常量（E 前缀 + 大驼峰）

module book::const_naming;

// 普通常量：全大写 + 下划线分隔
const MAX_RETRIES: u64 = 3;
const DEFAULT_TIMEOUT: u64 = 5000;
const BASE_URL: vector<u8> = b"https://api.sui.io";

// 错误码常量：E 前缀 + 驼峰命名
const ENotAuthorized: u64 = 0;
const EInsufficientBalance: u64 = 1;
const EItemNotFound: u64 = 2;
const EExceedsMaxSupply: u64 = 3;

支持的类型

常量只能使用以下类型：

注意：常量不支持自定义结构体类型、String、Option 等复杂类型。如需使用这些类型的常量值，应通过函数封装。

module book::const_types;

const BOOL_CONST: bool = false;
const U8_CONST: u8 = 255;
const U64_CONST: u64 = 1_000_000;
const U128_CONST: u128 = 1_000_000_000_000;
const U256_CONST: u256 = 0;
const ADDR_CONST: address = @0xCAFE;
const BYTES_CONST: vector<u8> = b"Hello, Move!";

常量是模块私有的

常量只能在定义它们的模块内部使用，无法被其他模块直接访问。这是 Move 的设计决策——如果需要将常量值暴露给外部模块，应通过公开函数（getter）来实现。

配置模式

module book::const_config;

const MAX_SUPPLY: u64 = 1_000_000;
const DEFAULT_PRICE: u64 = 100;
const MIN_STAKE: u64 = 1_000;

// 通过公开函数暴露常量值
public fun max_supply(): u64 { MAX_SUPPLY }
public fun default_price(): u64 { DEFAULT_PRICE }
public fun min_stake(): u64 { MIN_STAKE }

#[test]
fun config_getters() {
    assert_eq!(max_supply(), 1_000_000);
    assert_eq!(default_price(), 100);
    assert_eq!(min_stake(), 1_000);
}

这种模式在智能合约开发中非常常见，它将常量值的访问控制权保留在定义模块中，同时允许外部读取。

错误码常量

在 Move 中，assert! 宏的第二个参数是一个错误码。使用常量定义错误码比直接使用数字更具可读性：

module book::const_errors;

const ENotOwner: u64 = 0;
const EInsufficientFunds: u64 = 1;
const EAlreadyInitialized: u64 = 2;
const EInvalidAmount: u64 = 3;

public struct Wallet has drop {
    owner: address,
    balance: u64,
}

public fun withdraw(wallet: &mut Wallet, amount: u64, caller: address): u64 {
    assert!(caller == wallet.owner, ENotOwner);
    assert!(amount > 0, EInvalidAmount);
    assert!(wallet.balance >= amount, EInsufficientFunds);

    wallet.balance = wallet.balance - amount;
    amount
}

#[test]
fun withdraw_ok() {
    let mut wallet = Wallet { owner: @0x1, balance: 1000 };
    let amount = withdraw(&mut wallet, 100, @0x1);
    assert_eq!(amount, 100);
    assert_eq!(wallet.balance, 900);
}

#[test]
#[expected_failure(abort_code = ENotOwner)]
fun not_owner() {
    let mut wallet = Wallet { owner: @0x1, balance: 1000 };
    withdraw(&mut wallet, 100, @0x2); // 非 owner 调用，触发 abort
}

错误码命名建议

常量的存储方式

常量存储在编译后的字节码中，每次使用时会被 复制 到使用位置。这意味着：

• 常量不占用链上存储空间（不是对象）
• 每次引用常量都是一次值复制
• 对于大型 vector<u8> 常量，频繁使用可能增加字节码大小

module book::const_storage;

const LARGE_BYTES: vector<u8> = b"This is a relatively long constant string value";

#[test]
fun constant_copy() {
    let a = LARGE_BYTES;
    let b = LARGE_BYTES;   // 独立的副本

    assert!(a == b);
    assert_eq!(a.length(), b.length());
}

不可变性

常量是真正不可变的——一旦定义，无法在运行时修改。任何试图对常量赋值的操作都会导致编译错误：

module book::const_immutable;

const VALUE: u64 = 42;

public fun value(): u64 {
    // VALUE = 100;  // 编译错误：无法对常量赋值
    VALUE
}

如果需要可修改的全局状态，应使用链上对象（Object）来存储。

完整示例

module book::constants_example;

const MAX_SUPPLY: u64 = 1_000_000;
const DEFAULT_PRICE: u64 = 100;
const ADMIN_ADDRESS: address = @0x1;
const APP_NAME: vector<u8> = b"MyApp";

const ENotAuthorized: u64 = 0;
const EInsufficientBalance: u64 = 1;

public fun max_supply(): u64 { MAX_SUPPLY }
public fun default_price(): u64 { DEFAULT_PRICE }

public fun check_authorized(addr: address) {
    assert!(addr == ADMIN_ADDRESS, ENotAuthorized);
}

#[test]
fun constants_example() {
    assert_eq!(max_supply(), 1_000_000);
    assert_eq!(default_price(), 100);
    check_authorized(@0x1);
}

#[test]
#[expected_failure(abort_code = ENotAuthorized)]
fun unauthorized() {
    check_authorized(@0x99);
}

小结

常量是 Move 模块中不可变的固定值。本节核心要点：

• 声明语法：const NAME: Type = value;，名称必须大写字母开头
• 命名规范：普通常量用 ALL_CAPS，错误码用 EPascalCase
• 支持的类型：bool、整数类型、address、vector<u8>
• 模块私有：常量只在定义模块内可见，通过公开函数暴露给外部
• 配置模式：使用 public fun xxx(): Type { CONSTANT } 暴露常量值
• 错误码：使用 E 前缀命名，配合 assert! 进行条件检查
• 存储方式：编译时嵌入字节码，每次使用时复制
• 不可变性：定义后无法修改，需要可变状态请使用链上对象

条件分支（if / else）

Move 使用 if/else 实现条件分支。与许多语言不同，Move 中的 if/else 是 表达式，可以返回值，两个分支的返回类型必须一致。

基本语法

if 表达式根据布尔条件选择执行路径：

module book::if_basic;

public fun is_positive(n: u64): bool {
    if (n > 0) {
        true
    } else {
        false
    }
}

#[test]
fun if_positive() {
    assert!(is_positive(10));
    assert!(!is_positive(0));
}

作为表达式使用

if/else 可以返回值，此时两个分支的返回类型必须一致：

module book::if_expression;

public fun abs_diff(a: u64, b: u64): u64 {
    if (a > b) { a - b } else { b - a }
}

public fun max(a: u64, b: u64): u64 {
    if (a >= b) { a } else { b }
}

public fun describe(n: u64): vector<u8> {
    if (n == 0) {
        b"zero"
    } else if (n < 10) {
        b"small"
    } else if (n < 100) {
        b"medium"
    } else {
        b"large"
    }
}

#[test]
fun expression_if() {
    assert_eq!(abs_diff(10, 3), 7);
    assert_eq!(max(5, 8), 8);
    assert_eq!(describe(0), b"zero");
    assert_eq!(describe(5), b"small");
    assert_eq!(describe(50), b"medium");
    assert_eq!(describe(200), b"large");
}

无 else 分支

当 if 不作为表达式使用时（即不返回值），可以省略 else 分支：

module book::if_no_else;

#[test]
fun no_else() {
    let mut result = 0u64;
    let condition = true;

    if (condition) {
        result = 42;
    };

    assert_eq!(result, 42);
}

小结

• if/else：条件分支，可作为表达式返回值
• 分支类型：作为表达式时，两个分支的返回类型必须一致
• 无 else：不返回值时可以省略 else

循环与带标签控制流

Move 支持 while 条件循环、loop 无限循环，以及 break、continue、return 等流程控制。在嵌套循环或块中，可以使用 标签 精确指定跳转目标。

while 循环

while 在条件为 true 时重复执行循环体：

module book::while_loop;

public fun sum_to_n(n: u64): u64 {
    let mut i = 0u64;
    let mut sum = 0u64;
    while (i <= n) {
        sum = sum + i;
        i = i + 1;
    };
    sum
}

#[test]
fun while_sum() {
    assert_eq!(sum_to_n(10), 55);
}

注意：while 循环的尾部需要加分号 ;，因为循环本身是一条语句。

loop 无限循环

loop 创建一个无限循环，必须通过 break 或 return 退出。配合 break 可以返回值，作为表达式使用：

module book::loop_example;

public fun find_first_divisible(v: &vector<u64>, divisor: u64): Option<u64> {
    let mut i = 0;
    loop {
        if (i >= v.length()) {
            break option::none()
        };
        if (v[i] % divisor == 0) {
            break option::some(v[i])
        };
        i = i + 1;
    }
}

break 和 continue

break 提前退出循环，可携带返回值；continue 跳过当前迭代的剩余部分：

module book::break_continue;

#[test]
fun break_early() {
    let mut sum = 0u64;
    let mut i = 0;
    while (i < 100) {
        if (sum > 50) break;
        sum = sum + i;
        i = i + 1;
    };
}

#[test]
fun continue_even_sum() {
    let mut sum = 0u64;
    let mut i = 0;
    while (i < 10) {
        i = i + 1;
        if (i % 2 != 0) continue;
        sum = sum + i;
    };
    assert_eq!(sum, 30); // 2 + 4 + 6 + 8 + 10
}

return — 提前返回

return 可以在函数中任意位置提前返回值：

module book::return_example;

public fun find_first_even(v: &vector<u64>): Option<u64> {
    let mut i = 0;
    while (i < v.length()) {
        if (v[i] % 2 == 0) {
            return option::some(v[i])
        };
        i = i + 1;
    };
    option::none()
}

Gas 消耗与无限循环

在区块链环境中，每条指令都会消耗 Gas。循环必须有明确的退出条件，避免无限循环导致 Gas 耗尽。

带标签的控制流

在嵌套循环或块中，可以用 标签 精确指定 break、continue 或 return 的目标，格式为 'label:。

循环标签

给 loop 或 while 加上标签后，break 'label value 会直接跳出到该标签对应的循环并携带返回值；continue 'label 会跳到该循环的下一次迭代：

module book::labeled_loop;

public fun sum_until_threshold(input: &vector<vector<u64>>, threshold: u64): u64 {
    let mut sum = 0u64;
    let mut i = 0u64;
    let len = input.length();

    'outer: loop {
        if (i >= len) break sum;
        let vec = &input[i];
        let mut j = 0u64;
        while (j < vec.length()) {
            let v_entry = vec[j];
            if (sum + v_entry < threshold) {
                sum = sum + v_entry;
            } else {
                break 'outer sum
            };
            j = j + 1;
        };
        i = i + 1;
    }
}

块标签与 return

给块加标签后，可以在块内使用 return 'label value 从该块“返回”一个值，作为整个块表达式的值。return 只能用于块标签；break/continue 只能用于循环标签。

小结

• while：条件循环，尾部需加分号
• loop：无限循环，必须通过 break 或 return 退出；break 可携带返回值
• break / continue / return：控制流程
• 标签：'label: 用于循环或块，精确指定跳转目标
• Gas 安全：循环必须有明确退出条件

断言与中止

Move 语言中的错误处理机制与大多数编程语言截然不同：它没有 try/catch 异常捕获机制。当出现错误时，交易要么完全成功，要么通过中止（abort）回滚所有状态变更。abort 用于立即中止执行，assert! 宏则提供了一种便捷的条件检查方式——当条件不满足时自动中止。

abort 关键字

基本用法

abort 是 Move 的关键字，用于立即停止当前交易的执行。它必须传入一个错误常量。历史上常用 u64 数值；当前 Sui 推荐使用带 #[error] 的常量（通常为 vector<u8> 可读消息，即 Clever Errors，见下文「Move 2024 #[error] 属性」），工具链会自动解码展示。

module book::abort_basic;

const ENotAllowed: u64 = 0;

public fun only_positive(value: u64): u64 {
    if (value == 0) {
        abort ENotAllowed
    };
    value
}

#[test, expected_failure(abort_code = ENotAllowed)]
fun abort_on_zero() {
    only_positive(0);
}

当 abort 被触发时，当前交易的所有状态变更都会被撤销，链上不会留下任何修改痕迹，但消耗的 gas 费不会退还。

abort 的语法形式

abort 可以作为表达式使用。由于它永远不会返回值，可以用在任何需要表达式的地方：

module book::abort_expr;

const EInvalidChoice: u64 = 0;

public fun describe(choice: u8): vector<u8> {
    if (choice == 1) {
        b"Option A"
    } else if (choice == 2) {
        b"Option B"
    } else {
        abort EInvalidChoice
    }
}

#[test]
fun describe_ok() {
    assert_eq!(describe(1), b"Option A");
    assert_eq!(describe(2), b"Option B");
}

assert! 宏

基本用法

assert! 是一个内置宏，它检查一个布尔条件，如果条件为 false，则以给定的错误码中止执行：

module book::assert_basic;

const ENotAuthorized: u64 = 0;
const EInvalidAmount: u64 = 1;

public fun transfer_tokens(
    sender: address,
    admin: address,
    amount: u64,
) {
    assert!(sender == admin, ENotAuthorized);
    assert!(amount > 0, EInvalidAmount);
    // 主要逻辑在这里...
}

#[test]
fun valid_transfer() {
    transfer_tokens(@0x1, @0x1, 100);
}

#[test, expected_failure(abort_code = ENotAuthorized)]
fun not_authorized() {
    transfer_tokens(@0x1, @0x2, 100);
}

#[test, expected_failure(abort_code = EInvalidAmount)]
fun invalid_amount() {
    transfer_tokens(@0x1, @0x1, 0);
}

assert! 本质上是 if (!condition) abort code 的语法糖，让代码更加简洁易读。

单参数 assert!

在测试中，assert! 可以只传一个参数，省略错误码。此时如果条件为 false，将以默认错误码中止：

module book::assert_single;

#[test]
fun assert_single_arg() {
    let x = 42;
    assert!(x == 42);       // 仅检查条件，无自定义错误码
    assert!(x > 0);
    assert!(x != 100);
}

错误常量约定

命名规范

错误常量使用 E 前缀 + EPascalCase。新代码请优先使用 #[error] + vector<u8>（见下一节）。以下为早期仅使用 u64 编号的约定，存量代码中仍常见：

module book::error_conventions;

const ENotOwner: u64 = 0;
const EInsufficientBalance: u64 = 1;
const EItemNotFound: u64 = 2;
const EAlreadyExists: u64 = 3;
const EExpired: u64 = 4;

public fun check_owner(caller: address, owner: address) {
    assert!(caller == owner, ENotOwner);
}

public fun check_balance(balance: u64, required: u64) {
    assert!(balance >= required, EInsufficientBalance);
}

每个模块内的错误码通常从 0 开始递增，确保每个错误码在模块内是唯一的。

Move 2024 #[error] 属性

Move 2024 引入了 #[error] 属性，允许错误常量使用 vector<u8> 类型来提供人类可读的错误信息：

module book::error_attribute;

#[error]
const ECustomNotFound: vector<u8> = b"The requested item was not found";

#[error]
const EInvalidInput: vector<u8> = b"Input validation failed: value out of range";

public fun find_item(id: u64): u64 {
    if (id == 0) {
        abort ECustomNotFound
    };
    id
}

public fun validate(value: u64) {
    assert!(value <= 1000, EInvalidInput);
}

#[test, expected_failure]
fun not_found() {
    find_item(0);
}

使用 #[error] 后，Sui CLI 与 GraphQL 会将 abort 解码为可读信息。单元测试中断言「会失败」时，优先写 #[test, expected_failure]（不填 abort_code），避免 Clever Error 的数值随源码行号变化导致测试脆弱。不写第二参数的 assert!(cond) 也会从行号派生 clever 信息；具名 #[error] 常量用于需要在链上/客户端展示稳定语义的场景。

Clever Errors 的编码与解码

带 #[error] 的常量在运行时会被编码为一个 u64 的 clever 码，其高位包含：标记位（表示是 clever 码）、中止发生的行号、常量名在模块标识表中的索引、常量值在模块常量表中的索引。例如某次中止得到的十六进制码可能形如 0x8000_0007_0001_0000，解码后可得到行号、常量名（如 EIsThree）和常量值（如 b"The value is three"），工具会渲染为类似：

Error from '0x...::module::fun' (line 7), abort 'EIsThree': "The value is three"

未提供错误码的 assert!(cond) 或 abort 也会生成 clever 码，其中“常量名索引”和“常量值索引”用哨兵值 0xffff 填充，仅行号有效，便于在源码中定位。
宏中的 assert!/abort 的行号取宏调用处，而不是宏定义内部，这样错误信息会指向调用方代码。

如需从 u64 手工解码 clever 码，可参考 Sui 文档或 CLI/GraphQL 的解码流程；日常开发中直接依赖 Sui CLI 与 GraphQL 的自动解码即可。

错误处理的最佳实践

前置断言模式

最佳实践是将所有的断言检查放在函数主逻辑之前，这样可以在执行任何状态变更前就发现问题，即“先验证，后执行“：

module book::abort_example;

const ENotAuthorized: u64 = 0;
const EInvalidAmount: u64 = 1;
const EInsufficientBalance: u64 = 2;

#[error]
const ECustomError: vector<u8> = b"This is a custom error message";

public fun transfer_tokens(
    sender: address,
    admin: address,
    amount: u64,
) {
    // 所有断言在前
    assert!(sender == admin, ENotAuthorized);
    assert!(amount > 0, EInvalidAmount);
    // 主要逻辑在后...
}

public fun must_be_positive(value: u64): u64 {
    if (value == 0) {
        abort EInvalidAmount
    };
    value
}

#[test]
fun assert_ok() {
    let result = must_be_positive(42);
    assert_eq!(result, 42);
}

#[test, expected_failure(abort_code = EInvalidAmount)]
fun abort_zero() {
    must_be_positive(0);
}

交易的原子性

由于 Move 没有 try/catch 机制，整个交易是原子性的：

• 全部成功：所有操作都执行完毕，状态变更生效
• 全部回滚：只要有一个 abort 被触发，所有状态变更都被撤销

这种设计简化了安全模型——开发者不需要担心部分执行导致的不一致状态：

module book::atomic_example;

const EStepOneFailed: u64 = 0;
const EStepTwoFailed: u64 = 1;

public fun multi_step_operation(a: u64, b: u64) {
    // 步骤一
    assert!(a > 0, EStepOneFailed);

    // 步骤二
    assert!(b > a, EStepTwoFailed);

    // 如果执行到这里，说明所有检查都通过了
    // 实际操作逻辑...
}

#[test]
fun success() {
    multi_step_operation(5, 10);
}

#[test, expected_failure(abort_code = EStepTwoFailed)]
fun step_two_fails() {
    // 即使步骤一通过了，步骤二失败也会回滚所有变更
    multi_step_operation(5, 3);
}

小结

Move 的错误处理机制简洁而强大。abort 立即中止执行并回滚所有状态变更，assert! 宏提供了简洁的条件检查语法。错误常量使用 E 前缀的驼峰命名，Move 2024 还引入了 #[error] 属性支持可读的错误信息。由于没有 try/catch 机制，交易具有完全的原子性——要么全部成功，要么全部回滚。最佳实践是将断言检查放在函数主逻辑之前，确保“先验证，后执行“。

函数定义与调用

函数是 Move 程序的基本构建单元，使用 fun 关键字声明。函数体最后一个不带分号的表达式即为返回值；支持通过元组返回多值并用解构接收。

基本语法

函数遵循蛇形命名法（snake_case）。每个参数都必须显式标注类型：

module book::function_basic;

fun add(a: u64, b: u64): u64 {
    a + b  // 最后一个表达式作为返回值，不加分号
}

#[test]
fun add_returns_sum() {
    assert_eq!(add(2, 3), 5);
}

无返回值与 Unit

如果函数不需要返回值，返回类型可以省略，默认返回空元组 ()（unit 类型）：

module book::function_unit;

public fun do_nothing() {
    // 隐式返回 ()
}

public fun explicit_unit(): () {
    ()
}

参数与类型标注

Move 是强类型语言，函数签名中的参数类型必须显式标注，不能依赖推导：

module book::function_params;

use std::string::String;

public fun greet(name: String, times: u64): String {
    let _ = times;
    name
}

单一返回值与 return

函数体中最后一个不带分号的表达式就是返回值；也可以使用 return 提前返回：

module book::function_return;

public fun max(a: u64, b: u64): u64 {
    if (a > b) {
        return a
    };
    b
}

多返回值（元组）

Move 支持通过元组返回多个值，调用方使用解构接收：

module book::function_tuple;

public fun swap(a: u64, b: u64): (u64, u64) {
    (b, a)
}

public fun min_max(a: u64, b: u64): (u64, u64) {
    if (a < b) { (a, b) } else { (b, a) }
}

#[test]
fun swap_returns_reversed() {
    let (x, y) = swap(1, 2);
    assert_eq!(x, 2);
    assert_eq!(y, 1);
}

忽略返回值

使用 _ 可以忽略不需要的返回值：

#[test]
fun ignore_return() {
    let (value, _) = get_pair();
    let (_, flag) = get_pair();
}

小结

• 声明：fun 关键字，蛇形命名，参数必须显式类型
• 返回值：最后表达式或 return；支持元组多返回值与解构
• Unit：无返回值时隐式返回 ()

entry 与 public 函数

Move 函数有多种可见性级别，控制可被谁调用。入口函数（entry） 是 Sui 交易的直接入口，可从客户端发起；公共函数（public） 可被任意模块调用。

四种可见性

module book::function_example;

// 私有函数 — 仅模块内部
fun add(a: u64, b: u64): u64 {
    a + b
}

// 公共函数 — 任何模块都可调用
public fun multiply(a: u64, b: u64): u64 {
    a * b
}

// 包内可见
public(package) fun internal_multiply(a: u64, b: u64): u64 {
    a * b
}

entry 函数

entry 函数是 Sui 交易的入口点，可以直接从客户端发起的交易中被调用，但不能从其他 Move 模块中调用。参数类型通常限于基础类型、对象和 &mut TxContext：

module book::entry_example;

public struct Counter has key {
    id: UID,
    value: u64,
}

entry fun create_counter(ctx: &mut TxContext) {
    let counter = Counter {
        id: object::new(ctx),
        value: 0,
    };
    transfer::transfer(counter, ctx.sender());
}

entry fun increment(counter: &mut Counter) {
    counter.value = counter.value + 1;
}

调用其他模块的函数

通过 模块名::函数名() 调用其他模块的公共函数，需先用 use 导入：

module book::caller_example;

use book::function_example;

fun call_public() {
    let result = function_example::multiply(3, 4);
    assert!(result == 12);
}

小结

• 可见性：私有、public、public(package)、entry
• entry：交易入口，仅可从交易调用，不能从其他模块调用
• 调用方式：模块名::函数名()，需先 use 导入

可见性修饰符

可见性修饰符控制模块成员（函数、结构体等）的访问范围，是 Move 模块化设计的核心机制。Move 提供四种可见性级别：私有（private）、公共（public）、包内可见（public(package)）和入口（entry），每种级别对应不同的访问权限和使用场景。合理使用可见性可以实现良好的封装，保护模块的内部实现细节。

私有可见性（private）

默认访问级别

不添加任何修饰符的函数默认是私有的，只能在定义它的模块内部调用：

module book::private_example;

// 私有函数 —— 只有本模块内部可以调用
fun internal_helper(): u64 {
    42
}

fun another_helper(): u64 {
    // 同一模块内，可以调用私有函数
    internal_helper() + 8
}

#[test]
fun private_only_in_module() {
    assert_eq!(internal_helper(), 42);
    assert_eq!(another_helper(), 50);
}

私有函数是模块封装的基础。将实现细节隐藏在私有函数中，只暴露必要的公共接口，是良好 API 设计的关键。

公共可见性（public）

对外开放的接口

使用 public 修饰的函数可以被任何模块调用，是模块对外暴露的 API：

module book::public_example;

const EInvalid: u64 = 0;

// 公共函数 —— 任何模块都可以调用
public fun calculate(a: u64, b: u64): u64 {
    validate(a, b);
    a + b
}

// 内部验证逻辑保持私有
fun validate(a: u64, b: u64) {
    assert!(a > 0 && b > 0, EInvalid);
}

#[test]
fun public_calculate() {
    assert_eq!(calculate(3, 7), 10);
}

需要注意：一旦函数被标记为 public，它就成为模块的公共 API。在包升级时，不能删除或更改已有的 public 函数签名，否则会破坏依赖它的外部模块。

包内可见性（public(package)）

包级别的共享

public(package) 允许同一个包（package）内的所有模块调用该函数，但包外的模块无法访问。它取代了早期版本中的 friend 机制：

module book::package_example;

// 包内可见 —— 同一个包的模块可以调用，外部包不行
public(package) fun package_helper(): u64 {
    100
}

// 公共函数调用包内函数
public fun public_api(): u64 {
    package_helper() * 2
}

#[test]
fun package_visibility() {
    assert_eq!(package_helper(), 100);
    assert_eq!(public_api(), 200);
}

public(package) 非常适合用于包内多个模块之间的协作函数，这些函数需要被包内其他模块使用，但不应该暴露给外部。

入口可见性（entry）

交易的入口点

entry 函数可以直接从 Sui 交易中被调用，但不能从其他 Move 模块调用。它是连接链下客户端和链上逻辑的桥梁：

module book::entry_example;

public struct Greeting has key {
    id: UID,
    text: vector<u8>,
}

// 入口函数 —— 只能从交易调用，不能被其他模块调用
entry fun create_greeting(text: vector<u8>, ctx: &mut TxContext) {
    let greeting = Greeting {
        id: object::new(ctx),
        text,
    };
    transfer::transfer(greeting, ctx.sender());
}

// entry 函数作为交易入口，不可被其他模块调用，也不返回值（与 public 二选一，不要写 public entry）
entry fun update_greeting(greeting: &mut Greeting, text: vector<u8>) {
    greeting.text = text;
}

可见性对比示例

完整的可见性示例

将所有可见性级别放在一个模块中对比：

module book::visibility_example;

// 私有 —— 仅本模块可调用
fun internal_helper(): u64 { 42 }

// 公共 —— 任何模块都可调用
public fun public_api(): u64 { internal_helper() }

// 包内可见 —— 同一包的模块可调用
public(package) fun package_helper(): u64 { 100 }

// 入口 —— 仅从交易调用
entry fun do_something(ctx: &mut TxContext) {
    let _ = ctx;
}

从其他模块调用

下面展示在同一包的另一个模块中，哪些函数可以调用，哪些不行：

module book::try_access;

use book::visibility_example;

fun test() {
    visibility_example::public_api();      // OK —— 公共函数
    visibility_example::package_helper();   // OK —— 同一包内
    // visibility_example::internal_helper(); // 错误！私有函数不可调用
    // visibility_example::do_something();    // 错误！entry 函数不能被模块调用
}

结构体字段的可见性

字段始终是私有的

Move 中结构体的字段始终是私有的，无法直接从模块外部访问。需要通过公共函数来提供读写接口：

module book::field_visibility;

public struct User has drop {
    name: vector<u8>,
    age: u64,
}

public fun new(name: vector<u8>, age: u64): User {
    User { name, age }
}

// 通过公共函数提供读取接口
public fun name(user: &User): &vector<u8> {
    &user.name
}

public fun age(user: &User): u64 {
    user.age
}

// 通过公共函数提供修改接口
public fun set_age(user: &mut User, new_age: u64) {
    user.age = new_age;
}

#[test]
fun field_access() {
    let mut user = new(b"Alice", 25);
    assert_eq!(age(&user), 25);

    set_age(&mut user, 26);
    assert_eq!(age(&user), 26);
}

重要提示：虽然结构体字段在代码层面是私有的，但这并不意味着数据是机密的。链上对象的所有数据都是公开可读的。字段的私有性是一种编程封装，不是数据隐私保护。

小结

Move 提供四种可见性级别来控制函数的访问范围：private（默认）仅模块内部可见，public 对所有模块开放，public(package) 限制在同一包内，entry 仅供交易直接调用。结构体的字段始终是私有的，需要通过公共函数暴露读写接口。合理运用可见性修饰符是良好模块设计的基础——暴露最小必要的接口，隐藏内部实现细节。

第五章 · 实战练习

实战一：跟踪一节一包 — 从编译到改代码

1. 任选一节目录，例如 src/05_move_basics/code/04-integers/（对应 §5.5）。
2. 在对应 sources/*.move 中新增一个 public fun，做简单整数运算（注意溢出与类型）。
3. 执行 sui move build。
4. 验收：编译通过；你能在模块中定位到自己的新函数。

实战二：断言与错误路径

1. 打开 src/05_move_basics/code/18-assert-and-abort/。
2. 故意引入一个会触发 assert! 失败的条件，运行 sui move test 或写最小 #[test] 观察失败信息。
3. 再改回合理条件，使测试/构建恢复通过。
4. 验收：保留或记录一条「失败时 Move VM 的报错样式」，便于以后对照 Clever Errors / 错误码。

实战三：entry 与脚本调用

1. 使用 src/05_move_basics/code/20-entry-and-public/，阅读其中的 entry 函数。
2. 将该包发布到测试网后，用 sui client call 或 TypeScript Transaction 构造一笔只调该 entry 的交易（参数按函数签名填）。
3. 验收：链上交易成功；你能从 Effects 里看到被调用的函数名。

第六章 · Move 语法进阶

本章在语法基础之上，介绍标准库与常用集合类型、枚举与模式匹配、方法语法、宏函数，以及所有权与引用，帮助你写出结构清晰、可维护的 Move 模块；最后一节集中整理 Move 2024 Edition 与清单约定，供系统对照与迁移旧代码。

本章内容

节与正文、示例代码

学习目标

读完本章后，你将能够：

• 熟练使用标准库中的 Vector、Option、String 等类型
• 用枚举与模式匹配表达多分支逻辑与错误处理
• 用结构体方法和宏函数组织与复用代码
• 理解所有权与引用，写出正确且高效的 Move 代码
• 能解释 Move.toml 中 edition / rev 的约定，并对照 Move 2024 与旧版语法差异（§6.11）

本章实战练习

每章 1～3 个动手任务见 hands-on.md（目录中亦列为「本章实战练习」）。

Move 标准库概览

Move 标准库（Move Standard Library，简称 std）是 Move 语言内置的基础工具集，发布在地址 0x1 上。它提供了字符串处理、集合操作、序列化、哈希计算等核心功能，是每个 Move 开发者日常使用的基石。了解标准库的模块结构和常用接口，可以避免重复造轮子，写出更高效、更安全的代码。

标准库地址

Move 标准库的包地址为 0x1，在 Move.toml 中通常以命名地址 std 引用：

[addresses]
std = "0x1"

在代码中，所有标准库模块都以 std:: 前缀访问，例如 std::string、std::vector。

常用模块一览

以下是 Move 标准库中最常用的模块及其功能：

字符串模块

std::string — UTF-8 字符串

std::string 提供 UTF-8 编码的字符串类型，是最常用的字符串模块：

module book::std_string_demo;

use std::string::{Self, String};

#[test]
fun string_demo() {
    let s: String = b"Hello, Move!".to_string();
    assert_eq!(s.length(), 12);

    let mut greeting = b"Hello".to_string();
    greeting.append(b", World!".to_string());
    assert_eq!(greeting, b"Hello, World!".to_string());

    // 安全创建：返回 Option<String>
    let valid = string::try_utf8(b"valid");
    assert!(valid.is_some());
}

std::ascii — ASCII 字符串

std::ascii 用于处理纯 ASCII 字符串，限制每个字节在 0~127 范围内：

module book::std_ascii_demo;

use std::ascii;

#[test]
fun ascii_demo() {
    let s = b"Hello".to_ascii_string();
    assert_eq!(ascii::length(&s), 5);
}

集合与容器模块

std::vector — 动态数组

vector 是 Move 中唯一的原生集合类型，std::vector 提供了丰富的操作函数：

module book::std_vector_demo;

#[test]
fun vector_demo() {
    let mut v = vector[10u64, 20, 30];

    v.push_back(40);
    assert_eq!(v.length(), 4);
    assert!(v.contains(&20));

    let last = v.pop_back();
    assert_eq!(last, 40);
}

std::option — 可选值

Option<T> 表示一个可能存在也可能不存在的值，是处理缺失值的安全方式：

module book::std_option_demo;

#[test]
fun option_demo() {
    let some_val: Option<u64> = option::some(42);
    let none_val: Option<u64> = option::none();

    assert!(some_val.is_some());
    assert!(none_val.is_none());

    let val = some_val.destroy_some();
    assert_eq!(val, 42);
}

序列化与哈希

std::bcs — BCS 序列化

BCS（Binary Canonical Serialization）是 Move 和 Sui 使用的序列化格式。std::bcs 可以将任意拥有 copy 能力的值转换为字节序列：

module book::std_bcs_demo;

use std::bcs;

#[test]
fun bcs_demo() {
    let value: u64 = 1234;
    let bytes: vector<u8> = bcs::to_bytes(&value);
    assert!(bytes.length() > 0);

    let flag = true;
    let flag_bytes = bcs::to_bytes(&flag);
    assert_eq!(flag_bytes, vector[1u8]); // true 序列化为 [1]
}

std::hash — 哈希函数

标准库提供了两种常用的密码学哈希函数：

module book::std_hash_demo;

use std::hash;

#[test]
fun hash_demo() {
    let data = b"hello";
    let sha2 = hash::sha2_256(data);
    let sha3 = hash::sha3_256(data);

    assert_eq!(sha2.length(), 32); // SHA2-256 输出 32 字节
    assert_eq!(sha3.length(), 32); // SHA3-256 输出 32 字节
    assert!(sha2 != sha3);        // 不同算法，结果不同
}

类型反射

std::type_name — 运行时类型信息

std::type_name 允许在运行时获取类型的完全限定名称，常用于泛型编程和调试：

module book::std_type_name_demo;

use std::type_name;
use std::ascii::String;

#[test]
fun type_name_demo() {
    let name = type_name::get<u64>();
    let name_str: String = name.into_string();
    assert_eq!(name_str, b"u64".to_ascii_string());
}

整数工具模块

标准库为每种整数类型提供了实用函数模块：std::u8、std::u16、std::u32、std::u64、std::u128、std::u256。

这些模块提供的常用函数：

module book::std_integer_demo;

use std::u64;

#[test]
fun integer_utils() {
    assert_eq!(u64::max(10, 20), 20);
    assert_eq!(u64::diff(30, 10), 20);
    assert_eq!(u64::diff(10, 30), 20);  // 绝对差值
    assert_eq!(u64::pow(2, 10), 1024);
    assert_eq!(u64::sqrt(144), 12);
}

调试模块

std::debug — 测试专用调试

std::debug 仅在测试环境中有效，用于在 sui move test 时打印调试信息：

module book::std_debug_demo;

use std::debug;
use std::string::String;

#[test]
fun debug_demo() {
    let value: u64 = 42;
    debug::print(&value);

    let name: String = b"Sui Move".to_string();
    debug::print(&name);

    debug::print_stack_trace();
}

注意：debug::print 在链上执行时不会产生任何输出，仅用于本地测试调试。

隐式导入

编译器会自动导入以下标准库模块，无需在代码中编写 use 语句：

• std::vector — 向量操作函数
• std::option — Option 模块及其函数
• std::option::Option — Option 类型

因此，你可以直接在代码中使用 vector[1, 2, 3]、option::some(x)、Option<T> 等。

标准库 vs Sui Framework

初学者容易混淆 Move 标准库（std，地址 0x1）和 Sui Framework（sui，地址 0x2）。两者的核心区别：

简单来说，std 提供数据处理的基础工具，sui 提供链上对象和交易的高级功能。两者互补，共同构成了 Sui Move 的开发基础。

小结

Move 标准库是开发 Sui 智能合约的基础工具集。本节核心要点：

• 地址：标准库位于地址 0x1，通过 std::module 访问
• 字符串：std::string（UTF-8）和 std::ascii（ASCII）两种字符串类型
• 集合：std::vector 提供动态数组，std::option 提供可选值
• 序列化：std::bcs 进行 BCS 序列化
• 哈希：std::hash 提供 SHA2-256 和 SHA3-256
• 类型反射：std::type_name 获取运行时类型信息
• 整数工具：std::u64 等模块提供 max、diff、pow、sqrt
• 调试：std::debug 仅用于测试时的打印输出
• 隐式导入：vector、option、Option 自动可用
• 区别 Sui Framework：std 是通用工具，sui 提供链上功能

向量（Vector）

向量（Vector）是 Move 语言中唯一的原生集合类型，用于存储同一类型的有序元素序列。它类似于其他语言中的动态数组或列表，可以在运行时添加、删除和访问元素。向量是 Move 中最基础、最常用的数据结构，几乎所有复杂的数据组织都建立在它之上。

创建向量

字面量语法

Move 提供了简洁的字面量语法来创建向量：

module book::vector_create;

#[test]
fun create() {
    let empty: vector<u64> = vector[];     // 空向量，需要类型标注
    let nums = vector[1u64, 2, 3];         // 带初始元素的向量
    let bools = vector[true, false, true]; // 布尔向量
    let bytes = vector[0u8, 1, 2, 255];   // 字节向量

    assert_eq!(empty.length(), 0);
    assert_eq!(nums.length(), 3);
    assert_eq!(bools.length(), 3);
    assert_eq!(bytes.length(), 4);
}

泛型类型

向量的类型表示为 vector<T>，其中 T 可以是任何合法的 Move 类型：

module book::vector_types;

use std::string::String;

public struct Item has copy, drop {
    name: String,
    value: u64,
}

#[test]
fun vector_types() {
    let _strings: vector<String> = vector[];
    let _nested: vector<vector<u64>> = vector[];    // 向量的向量
    let _items: vector<Item> = vector[];             // 结构体向量
    let _options: vector<Option<u64>> = vector[];    // Option 向量
}

基本操作

向量内置于语言中，无需导入即可使用。以下是最常用的操作方法：

添加与移除元素

module book::vector_ops;

#[test]
fun push_pop() {
    let mut v = vector<u64>[];

    // 尾部添加元素
    v.push_back(10);
    v.push_back(20);
    v.push_back(30);
    assert_eq!(v.length(), 3);

    // 尾部移除元素（返回被移除的值）
    let last = v.pop_back();
    assert_eq!(last, 30);
    assert_eq!(v.length(), 2);

    // 在指定位置移除元素
    let removed = v.remove(0);  // 移除第一个元素
    assert_eq!(removed, 10);
    assert_eq!(v.length(), 1);
}

访问元素

module book::vector_access;

#[test]
fun access() {
    let v = vector[10u64, 20, 30, 40];

    // 索引访问（语法糖，等价于 *vector::borrow(&v, 0)）
    assert_eq!(v[0], 10);
    assert_eq!(v[3], 40);

    // 通过 borrow 获取不可变引用
    let first: &u64 = &v[0];
    assert_eq!(*first, 10);
}

修改元素

module book::vector_modify;

#[test]
fun modify() {
    let mut v = vector[10u64, 20, 30];

    // 通过索引修改元素
    v[1] = 200;
    assert_eq!(v[1], 200);

    // 通过 borrow_mut 获取可变引用
    let second = &mut v[1];
    *second = 999;
    assert_eq!(v[1], 999);
}

下标语法

v[i] 是 Move 的下标语法：编译器会将其转换为对 vector::borrow（只读）或 vector::borrow_mut（可写）的调用。标准库中的 vector 通过 #[syntax(index)] 标记了 borrow 与 borrow_mut，因此支持 v[i] 和 &v[i]、&mut v[i]。

自定义类型也可以为“索引访问”定义类似语法：在同一模块中为类型定义带有 #[syntax(index)] 的 public fun borrow(...) 和 public fun borrow_mut(...)，第一个参数为 &Self / &mut Self，返回 &T / &mut T，即可对该类型的值使用 obj[index_expr] 形式的读写。详见语言参考中的 Index Syntax。

查询操作

module book::vector_query;

#[test]
fun query() {
    let v = vector[10u64, 20, 30, 40, 50];

    // 长度
    assert_eq!(v.length(), 5);

    // 是否为空
    assert!(!v.is_empty());
    assert!(vector<u64>[].is_empty());

    // 是否包含某个元素
    assert!(v.contains(&30));
    assert!(!v.contains(&99));
}

排列操作

module book::vector_arrange;

#[test]
fun arrange() {
    let mut v = vector[1u64, 2, 3, 4, 5];

    // 交换两个位置的元素
    v.swap(0, 4);
    assert_eq!(v[0], 5);
    assert_eq!(v[4], 1);

    // swap_remove：将指定位置元素与最后一个交换，然后 pop_back
    // 比 remove 更高效（O(1)），但不保持顺序
    let mut v2 = vector[10u64, 20, 30, 40];
    let removed = v2.swap_remove(1);  // 移除索引 1 的元素 (20)
    assert_eq!(removed, 20);
    // v2 现在是 [10, 40, 30]（40 被换到了索引 1）

    // 反转向量
    let mut v3 = vector[1u64, 2, 3];
    v3.reverse();
    assert!(v3 == vector[3u64, 2, 1]);
}

遍历向量

while 循环遍历

Move 中遍历向量最常见的方式是使用 while 循环配合索引：

module book::vector_iterate;

#[test]
fun while_loop() {
    let v = vector[10u64, 20, 30, 40, 50];

    let mut i = 0;
    let mut sum = 0u64;
    while (i < v.length()) {
        sum = sum + v[i];
        i = i + 1;
    };

    assert_eq!(sum, 150);
}

消耗式遍历

如果不再需要向量，可以使用 pop_back 逐个取出元素：

module book::vector_consume;

#[test]
fun consume() {
    let mut v = vector[1u64, 2, 3];
    let mut sum = 0u64;

    while (!v.is_empty()) {
        sum = sum + v.pop_back();
    };

    assert_eq!(sum, 6);
    assert!(v.is_empty());
    v.destroy_empty(); // 显式销毁空向量
}

销毁向量

destroy_empty

对于元素类型没有 drop 能力的向量，必须在向量为空后使用 destroy_empty 显式销毁：

module book::vector_destroy;

public struct NoDrop { value: u64 }

fun consume(_item: NoDrop) {
    let NoDrop { value: _ } = _item;
}

#[test]
fun destroy() {
    let mut v = vector[NoDrop { value: 1 }, NoDrop { value: 2 }];

    // 必须逐个取出并消耗元素
    consume(v.pop_back());
    consume(v.pop_back());

    // 向量为空后才能销毁
    v.destroy_empty();
}

如果元素类型有 drop 能力，向量在作用域结束时会自动销毁，无需手动处理。

向量的向量

Move 支持嵌套向量，即向量的元素本身也是向量：

module book::nested_vector;

#[test]
fun nested() {
    let mut matrix: vector<vector<u64>> = vector[];

    matrix.push_back(vector[1, 2, 3]);
    matrix.push_back(vector[4, 5, 6]);
    matrix.push_back(vector[7, 8, 9]);

    assert_eq!(matrix.length(), 3);
    assert_eq!(matrix[0][0], 1);
    assert_eq!(matrix[1][1], 5);
    assert_eq!(matrix[2][2], 9);
}

结构体向量

向量可以存储自定义结构体，这在实际开发中非常常见：

module book::struct_vector;

use std::string::String;

public struct Player has copy, drop {
    name: String,
    score: u64,
}

public fun top_scorer(players: &vector<Player>): String {
    assert!(!players.is_empty());

    let mut best_idx = 0;
    let mut i = 1;
    while (i < players.length()) {
        if (players[i].score > players[best_idx].score) {
            best_idx = i;
        };
        i = i + 1;
    };

    players[best_idx].name
}

#[test]
fun struct_vector() {
    let players = vector[
        Player { name: b"Alice".to_string(), score: 100 },
        Player { name: b"Bob".to_string(), score: 250 },
        Player { name: b"Charlie".to_string(), score: 180 },
    ];

    let top = top_scorer(&players);
    assert_eq!(top, b"Bob".to_string());
}

完整示例

下面的例子综合展示了向量的常用操作：

module book::vector_example;

#[test]
fun vector_example() {
    let mut v = vector[10u64, 20, 30];

    // 添加元素
    v.push_back(40);
    assert_eq!(v.length(), 4);

    // 访问元素
    assert_eq!(v[0], 10);
    assert_eq!(v[3], 40);

    // 移除最后一个元素
    let last = v.pop_back();
    assert_eq!(last, 40);

    // 按索引移除
    let removed = v.remove(1); // 移除 20
    assert_eq!(removed, 20);

    // 查询
    assert!(v.contains(&10));
    assert!(!v.contains(&20));

    // 遍历求和
    let mut i = 0;
    let mut sum = 0u64;
    while (i < v.length()) {
        sum = sum + v[i];
        i = i + 1;
    };

    assert_eq!(sum, 40); // 10 + 30
}

小结

向量是 Move 中最基础也是最重要的集合类型。本节核心要点：

• 创建：使用 vector[] 字面量语法，类型为 vector<T>
• 添加/移除：push_back 尾部添加，pop_back 尾部移除，remove 按索引移除
• 访问：通过 v[i] 索引访问，borrow 获取引用，borrow_mut 获取可变引用
• 查询：length()、is_empty()、contains() 检查向量状态
• 排列：swap 交换、swap_remove 高效删除、reverse 反转
• 遍历：使用 while 循环配合索引进行遍历
• 销毁：元素有 drop 时自动销毁，否则需要清空后调用 destroy_empty
• 嵌套：支持 vector<vector<T>> 等嵌套结构

Option 类型

Option<T> 表示一个可能存在也可能不存在的值。它是处理缺失值的安全方式——与使用哨兵值（如 0 或 -1 表示“无“）不同，Option 在类型层面强制开发者处理值可能不存在的情况。在 Sui Move 中，Option 广泛用于可选的结构体字段、函数返回值等场景。

基本概念

内部实现

Option<Element> 的底层实现是一个最多包含一个元素的 vector<Element>：

• option::some(value) — 创建包含值的 Option（vector 长度为 1）
• option::none() — 创建空的 Option（vector 长度为 0）

这种实现方式简洁高效，复用了 vector 的内存管理机制。

隐式导入

Option 类型和 option 模块由编译器自动导入，无需手动编写 use 语句即可直接使用：

module book::option_auto;

public struct Example has drop {
    value: Option<u64>,  // 直接使用，无需 use std::option
}

#[test]
fun auto_import() {
    let some_val = option::some(42u64);  // 直接使用 option::some
    let none_val: Option<u64> = option::none();

    assert!(some_val.is_some());
    assert!(none_val.is_none());
}

创建 Option

module book::option_create;

use std::string::String;

#[test]
fun create() {
    // 创建包含值的 Option
    let some_int = option::some(42u64);
    let some_bool = option::some(true);
    let some_string = option::some(b"hello".to_string());

    // 创建空的 Option
    let none_int: Option<u64> = option::none();
    let none_string: Option<String> = option::none();

    assert!(some_int.is_some());
    assert!(none_int.is_none());
}

检查 Option 状态

is_some() 和 is_none() 用于检查 Option 是否包含值：

module book::option_check;

#[test]
fun check() {
    let has_value = option::some(100u64);
    let no_value: Option<u64> = option::none();

    assert!(has_value.is_some());     // true
    assert!(!has_value.is_none());    // false

    assert!(no_value.is_none());      // true
    assert!(!no_value.is_some());     // false
}

提取 Option 中的值

borrow — 不可变借用

borrow() 返回内部值的不可变引用。如果 Option 为空，会触发 abort：

module book::option_borrow;

#[test]
fun borrow() {
    let opt = option::some(42u64);
    let value_ref: &u64 = opt.borrow();
    assert_eq!(*value_ref, 42);
}

borrow_mut — 可变借用

borrow_mut() 返回内部值的可变引用，允许直接修改 Option 中的值：

module book::option_borrow_mut;

#[test]
fun borrow_mut() {
    let mut opt = option::some(10u64);
    let value_ref = opt.borrow_mut();
    *value_ref = 20;

    assert_eq!(*opt.borrow(), 20);
}

extract — 取出并清空

extract() 从 Option 中取出值，Option 变为 none。值被移出后 Option 仍然存在但为空：

module book::option_extract;

#[test]
fun extract() {
    let mut opt = option::some(42u64);
    let value = opt.extract();

    assert_eq!(value, 42);
    assert!(opt.is_none());  // 提取后变为 none
}

destroy_some — 销毁并取值

destroy_some() 销毁 Option 并返回内部的值。与 extract 不同的是，它会消耗整个 Option：

module book::option_destroy_some;

#[test]
fun destroy_some() {
    let opt = option::some(42u64);
    let value = opt.destroy_some();
    assert_eq!(value, 42);
    // opt 已被销毁，不再可用
}

get_with_default — 带默认值的获取

get_with_default() 在 Option 有值时返回该值的副本，为空时返回提供的默认值：

module book::option_default;

#[test]
fun default() {
    let some_val = option::some(42u64);
    let none_val: Option<u64> = option::none();

    let a = some_val.get_with_default(0);  // 返回 42
    let b = none_val.get_with_default(0);  // 返回默认值 0

    assert_eq!(a, 42);
    assert_eq!(b, 0);
}

销毁 Option

destroy_none — 销毁空 Option

destroy_none() 销毁一个空的 Option。如果 Option 包含值，会触发 abort：

module book::option_destroy_none;

#[test]
fun destroy_none() {
    let empty: Option<u64> = option::none();
    empty.destroy_none();  // 安全销毁空 Option
}

修改 Option

fill 和 swap

module book::option_modify;

#[test]
fun fill_swap() {
    let mut opt: Option<u64> = option::none();

    // fill：向空 Option 中填入值
    opt.fill(100);
    assert_eq!(*opt.borrow(), 100);

    // swap：替换 Option 中的值，返回旧值
    let old = opt.swap(200);
    assert_eq!(old, 100);
    assert_eq!(*opt.borrow(), 200);
}

常见使用场景

可选的结构体字段

Option 最常见的用途是表示结构体中的可选字段：

module book::option_example;

use std::string::String;

public struct UserProfile has drop {
    name: String,
    middle_name: Option<String>,
    bio: Option<String>,
}

public fun new_profile(name: String): UserProfile {
    UserProfile {
        name,
        middle_name: option::none(),
        bio: option::none(),
    }
}

#[test]
fun option_profile() {
    let mut profile = new_profile(b"Alice".to_string());

    assert!(profile.middle_name.is_none());

    // 设置中间名
    profile.middle_name = option::some(b"Marie".to_string());
    assert!(profile.middle_name.is_some());

    // 借用内部值
    let middle = profile.middle_name.borrow();
    assert_eq!(*middle, b"Marie".to_string());

    // 获取带默认值的字段
    let bio = profile.bio.get_with_default(b"No bio".to_string());
    assert_eq!(bio, b"No bio".to_string());
}

安全的查找操作

在集合中查找元素时，使用 Option 表示可能找不到的情况：

module book::option_search;

public fun find_index(v: &vector<u64>, target: u64): Option<u64> {
    let mut i = 0;
    while (i < v.length()) {
        if (v[i] == target) {
            return option::some(i)
        };
        i = i + 1;
    };
    option::none()
}

#[test]
fun find() {
    let nums = vector[10u64, 20, 30, 40];

    let found = find_index(&nums, 30);
    assert!(found.is_some());
    assert_eq!(found.destroy_some(), 2);

    let not_found = find_index(&nums, 99);
    assert!(not_found.is_none());
}

Option 的能力

Option<T> 的能力取决于内部元素类型 T：

module book::option_abilities;

public struct Copyable has copy, drop { value: u64 }

#[test]
fun option_copy() {
    let opt = option::some(Copyable { value: 42 });
    let opt_copy = opt;       // Option<Copyable> 有 copy
    assert!(opt.is_some());   // 原值仍然可用
    assert!(opt_copy.is_some());
}

小结

Option 是 Move 中处理可选值的标准方式。本节核心要点：

• 概念：Option<T> 表示“有值“或“无值“，底层通过 vector<T> 实现
• 创建：option::some(value) 创建有值，option::none() 创建空值
• 检查：is_some() 和 is_none() 判断状态
• 提取：borrow() 借用、extract() 取出、destroy_some() 销毁并取值
• 默认值：get_with_default() 安全获取，避免 abort
• 修改：fill() 填入值、swap() 替换值
• 隐式导入：Option 类型和 option 模块自动可用，无需 use
• 常见场景：可选结构体字段、安全的查找/返回操作

字符串

Move 语言提供了两种字符串类型：std::string::String（UTF-8 编码）和 std::ascii::String（ASCII 编码）。两者的底层都是 vector<u8> 的封装，但在编码验证和使用场景上有所不同。UTF-8 字符串是日常开发中最常用的字符串类型，而 ASCII 字符串适用于需要严格限制字符范围的场景。

UTF-8 字符串

创建字符串

std::string::String 是最常用的字符串类型，支持完整的 UTF-8 字符集：

module book::string_create;

use std::string::{Self, String};

#[test]
fun create() {
    // 最常用的方式：字节字面量转换
    let s1: String = b"Hello, Sui!".to_string();

    // 通过 string::utf8 函数创建
    let bytes = b"Hello";
    let s2 = string::utf8(bytes);

    assert_eq!(s1.length(), 11);
    assert_eq!(s2.length(), 5);
}

安全创建

string::try_utf8 返回 Option<String>，在输入不是合法 UTF-8 时不会 abort，而是返回 none：

module book::string_safe;

use std::string;

#[test]
fun try_utf8() {
    let valid = string::try_utf8(b"valid utf8");
    assert!(valid.is_some());

    let invalid = string::try_utf8(vector[0xFF, 0xFE]);
    assert!(invalid.is_none());
}

常用字符串操作

拼接与子串

module book::string_ops;

use std::string::String;

#[test]
fun ops() {
    let mut str = b"Hello".to_string();
    let world = b", World!".to_string();

    // 拼接（会修改原字符串）
    str.append(world);
    assert_eq!(str, b"Hello, World!".to_string());
    assert_eq!(str.length(), 13);

    // 提取子串（按字节索引）
    let hello = str.sub_string(0, 5);
    assert_eq!(hello, b"Hello".to_string());

    let world_part = str.sub_string(7, 13);
    assert_eq!(world_part, b"World!".to_string());
}

长度与空值检查

module book::string_check;

use std::string::String;

#[test]
fun length() {
    let s = b"Sui Move".to_string();
    assert_eq!(s.length(), 8);
    assert!(!s.is_empty());

    let empty: String = b"".to_string();
    assert_eq!(empty.length(), 0);
    assert!(empty.is_empty());
}

获取底层字节

bytes() 方法返回字符串底层 vector<u8> 的不可变引用：

module book::string_bytes;

use std::string::String;

#[test]
fun bytes() {
    let s: String = b"ABC".to_string();
    let bytes: &vector<u8> = s.bytes();

    assert_eq!(bytes.length(), 3);
    assert_eq!(bytes[0], 65);  // 'A' 的 ASCII 值
    assert_eq!(bytes[1], 66);  // 'B'
    assert_eq!(bytes[2], 67);  // 'C'
}

插入与删除

module book::string_insert;

use std::string::String;

#[test]
fun insert() {
    let mut s = b"Hello World".to_string();

    // insert: 在指定字节位置插入另一个字符串
    s.insert(5, b",".to_string());
    assert_eq!(s, b"Hello, World".to_string());
}

UTF-8 的限制

length() 返回的是 字节数，而非字符数。对于多字节 UTF-8 字符（如中文），字节数和字符数不同：

module book::string_utf8_limit;

use std::string::String;

#[test]
fun utf8_length() {
    let ascii_str: String = b"Hello".to_string();
    assert!(ascii_str.length() == 5);  // 5 个 ASCII 字符 = 5 字节

    // 注意：sub_string 按字节索引操作
    // 如果在多字节字符的中间截断，会导致非法 UTF-8
    // 因此在处理非 ASCII 字符时需格外小心
}

注意：Move 的字符串 API 基于字节操作，不支持字符级别的访问。在处理包含非 ASCII 字符（如中文、emoji）的字符串时，需要特别注意字节边界问题。

ASCII 字符串

创建和使用

std::ascii::String 严格限制每个字节在 0~127 范围内：

module book::ascii_example;

use std::ascii;

#[test]
fun ascii() {
    // 使用 to_ascii_string 创建
    let s = b"Hello, ASCII!".to_ascii_string();
    assert!(ascii::length(&s) == 13);

    // 安全创建：返回 Option
    let valid = ascii::try_string(b"valid");
    assert!(valid.is_some());

    // 包含非 ASCII 字节的输入会返回 none
    let invalid = ascii::try_string(vector[200u8]);
    assert!(invalid.is_none());
}

UTF-8 与 ASCII 的选择

在大多数场景下，推荐使用 UTF-8 的 std::string::String。ASCII 字符串主要用于那些需要严格限制字符范围的场景，例如 URL、标识符等。

字符串与字节向量的转换

字符串本质上是带有编码验证的 vector<u8> 封装：

module book::string_conversion;

use std::string::{Self, String};

#[test]
fun conversion() {
    // 字节向量 -> 字符串
    let bytes = b"Hello";
    let s: String = string::utf8(bytes);

    // 字符串 -> 字节向量引用
    let bytes_ref: &vector<u8> = s.bytes();
    assert!(bytes_ref == &b"Hello");

    // 字符串 -> 字节向量（消耗字符串）
    let owned_bytes: vector<u8> = s.into_bytes();
    assert!(owned_bytes == b"Hello");
}

完整示例

module book::string_example;

use std::string::String;

#[test]
fun string_example() {
    let mut str = b"Hello".to_string();
    let world = b", World!".to_string();

    // 拼接
    str.append(world);
    assert_eq!(str.length(), 13);

    // 子串
    let hello = str.sub_string(0, 5);
    assert_eq!(hello, b"Hello".to_string());

    // 空值检查
    assert!(!str.is_empty());

    // 安全创建
    let valid = std::string::try_utf8(b"valid utf8");
    assert!(valid.is_some());

    // 获取字节
    let bytes: &vector<u8> = str.bytes();
    assert_eq!(bytes.length(), 13);
}

小结

字符串是 Move 中处理文本数据的核心类型。本节核心要点：

• 两种字符串：std::string::String（UTF-8）和 std::ascii::String（ASCII）
• 底层结构：都是 vector<u8> 的封装，带有编码验证
• 创建方式：b"text".to_string() 创建 UTF-8，string::try_utf8() 安全创建
• 常用操作：append() 拼接、sub_string() 子串、length() 长度、is_empty() 检查空值
• 字节访问：bytes() 获取底层字节引用，into_bytes() 转换为字节向量
• UTF-8 限制：length() 返回字节数而非字符数，无字符级别访问
• ASCII 字符串：适用于标识符等需要限制字符范围的场景
• 选择建议：大多数情况下使用 UTF-8 字符串

枚举

枚举（Enum）是一种能表示多个变体（Variant）的类型，每个变体可以携带不同的数据。枚举是 Move 2024 引入的重要特性，极大地增强了类型系统的表达能力。

基本语法

枚举使用 public enum 关键字定义，每个变体用逗号分隔：

module book::enum_basic;

public enum Direction has copy, drop {
    North,
    South,
    East,
    West,
}

#[test]
fun direction() {
    let d = Direction::North;
    let _e = Direction::East;
}

带数据的变体

变体可以携带数据，支持两种形式：

• 位置参数：Variant(Type) — 类似元组
• 命名字段：Variant { field: Type } — 类似结构体

module book::enum_data;

use std::string::String;

public enum Shape has copy, drop {
    Circle(u64),                           // 位置参数：半径
    Rectangle { width: u64, height: u64 }, // 命名字段
    Point,                                 // 无数据
}

public enum Message has copy, drop {
    Quit,
    Text(String),
    Move { x: u64, y: u64 },
}

能力声明

枚举可以声明能力，但所有变体中携带的数据类型必须满足这些能力的要求：

module book::enum_abilities;

public enum Status has copy, drop, store {
    Active,
    Inactive,
    Suspended { reason: vector<u8> },
}

实例化枚举

使用 EnumName::VariantName 语法创建枚举实例：

module book::enum_instantiate;

public enum Color has copy, drop {
    Red,
    Green,
    Blue,
    Custom { r: u8, g: u8, b: u8 },
}

#[test]
fun instantiate() {
    let _red = Color::Red;
    let _custom = Color::Custom { r: 128, g: 0, b: 255 };
}

枚举的限制

• 一个枚举最多可以有 100 个变体
• 不支持递归枚举（变体不能包含自身类型）
• 枚举的变体访问是 模块内部 的（类似结构体字段），外部模块不能直接构造或解构变体

小结

• 定义：public enum Name has abilities { Variant1, Variant2(Type), Variant3 { field: Type } }
• 变体形式：无数据、位置参数、命名字段
• 实例化：EnumName::VariantName 或带数据形式
• 限制：最多 100 个变体、不支持递归、变体访问仅限模块内部

模式匹配

match 表达式根据枚举的变体进行分支处理，支持解构变体数据、通配符与穷尽性检查。配合枚举使用，可以安全、优雅地处理多种情况。

基本模式匹配

match 根据枚举的变体进行分支，每个分支用 => 连接模式与结果：

module book::match_basic;

public enum Coin has copy, drop {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

public fun value_in_cents(coin: &Coin): u64 {
    match (coin) {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

穷尽性检查

match 必须 穷尽 所有可能的变体，遗漏变体会导致编译错误。

通配符模式

使用 _ 匹配所有未显式列出的变体：

public fun is_urgent(p: &Priority): bool {
    match (p) {
        Priority::Critical => true,
        Priority::High => true,
        _ => false,
    }
}

解构变体数据

在 match 中可以解构变体携带的数据；使用 .. 可忽略命名字段变体中的全部字段：

public fun get_click_x(event: &Event): Option<u64> {
    match (event) {
        Event::Click { x, y: _ } => option::some(*x),
        _ => option::none(),
    }
}

// 忽略所有字段
Color::Custom { .. } => b"Custom"

match 作为表达式

match 是表达式，可以返回值；所有分支的返回类型必须一致。

常见模式

• is_variant 检查函数：用 match 实现 is_active(s)、is_paused(s) 等
• try_into 转换函数：变体匹配时返回 option::some(...)，否则返回 option::none()

小结

• match：必须穷尽所有变体，支持通配符 _
• 解构：在 match 中绑定变体数据，.. 忽略所有字段
• 作为表达式：match 可返回值，分支类型必须一致

结构体方法

Move 支持接收者语法（receiver syntax），允许使用点号 e.f() 的方式调用结构体的方法，这使得代码更加直观和面向对象。当函数的第一个参数是模块内定义的结构体类型时，就可以通过点号语法调用。理解方法的定义与调用方式，是编写优雅 Move 代码的重要一步。

方法定义

基本语法

如果一个函数的第一个参数是当前模块内定义的结构体类型（或其引用），那么该函数可以通过点号语法调用。第一个参数被称为“接收者“（receiver）：

module book::method_basic;

public struct Counter has drop {
    value: u64,
}

public fun new(): Counter {
    Counter { value: 0 }
}

// 第一个参数是 &Counter，可通过 counter.value() 调用
public fun value(self: &Counter): u64 {
    self.value
}

#[test]
fun method_call() {
    let counter = new();
    assert_eq!(counter.value(), 0);  // 点号语法调用
    assert_eq!(value(&counter), 0);  // 传统调用方式，效果相同
}

三种接收者类型

接收者参数有三种形式，分别对应不同的访问权限：

module book::method_example;

public struct Counter has drop {
    value: u64,
}

public fun new(): Counter {
    Counter { value: 0 }
}

// &self —— 不可变引用：只读访问
public fun value(self: &Counter): u64 {
    self.value
}

// &mut self —— 可变引用：可以修改
public fun increment(self: &mut Counter) {
    self.value = self.value + 1;
}

// &mut self 带额外参数
public fun add(self: &mut Counter, n: u64) {
    self.value = self.value + n;
}

// self（按值传递）—— 获取所有权，消耗该实例
public fun destroy(self: Counter): u64 {
    let Counter { value } = self;
    value
}

#[test]
fun methods() {
    let mut counter = new();
    assert_eq!(counter.value(), 0);

    counter.increment();
    counter.increment();
    counter.add(8);
    assert_eq!(counter.value(), 10);

    let final_value = counter.destroy();
    assert_eq!(final_value, 10);
}

三种接收者的适用场景：

方法链式调用

当方法返回 &mut self 或可修改的引用时，可以进行链式调用。对于返回 void 的可变方法，需要分步调用：

module book::method_chain;

public struct Builder has drop {
    name: vector<u8>,
    value: u64,
}

public fun new(): Builder {
    Builder { name: b"", value: 0 }
}

public fun set_name(self: &mut Builder, name: vector<u8>) {
    self.name = name;
}

public fun set_value(self: &mut Builder, value: u64) {
    self.value = value;
}

// getter 以字段名命名，无 get_ 前缀
public fun value(self: &Builder): u64 {
    self.value
}

#[test]
fun builder() {
    let mut builder = new();
    builder.set_name(b"test");
    builder.set_value(42);
    assert_eq!(builder.value(), 42);
}

方法别名

use fun 语法

use fun 可以为函数创建方法别名，使得非当前模块定义的函数也能用点号语法调用：

module book::method_alias;

public struct Wallet has drop {
    balance: u64,
}

public fun new(balance: u64): Wallet {
    Wallet { balance }
}

fun is_empty_check(w: &Wallet): bool {
    w.balance == 0
}

// 为 is_empty_check 创建方法别名
use fun is_empty_check as Wallet.is_empty;

#[test]
fun alias() {
    let wallet = new(100);
    assert!(!wallet.is_empty());  // 通过别名调用

    let empty_wallet = new(0);
    assert!(empty_wallet.is_empty());
}

public use fun

public use fun 可以导出方法别名，使得其他模块在导入该类型时也能使用点号语法调用。只能对当前模块定义的类型使用 public use fun：

module book::public_alias;

public struct Token has drop {
    amount: u64,
}

public fun new(amount: u64): Token {
    Token { amount }
}

fun token_amount(t: &Token): u64 {
    t.amount
}

fun token_is_zero(t: &Token): bool {
    t.amount == 0
}

// 导出别名，其他模块导入 Token 后也能使用这些方法
public use fun token_amount as Token.amount;
public use fun token_is_zero as Token.is_zero;

#[test]
fun public_alias() {
    let token = new(50);
    assert_eq!(token.amount(), 50);
    assert!(!token.is_zero());
}

自动关联

当一个模块被导入时，该模块中以其定义的结构体类型作为第一个参数的公共函数会自动关联为该类型的方法。无需手动创建别名，导入后即可使用点号语法：

module book::auto_method;

public struct Circle has drop {
    radius: u64,
}

public fun new(radius: u64): Circle {
    Circle { radius }
}

public fun area_approx(self: &Circle): u64 {
    // 简化计算，使用 3 * r * r 近似
    3 * self.radius * self.radius
}

在其他模块中导入后直接使用：

module book::use_circle;

use book::auto_method::{Self, Circle};

fun calculate() {
    let circle: Circle = auto_method::new(10);
    let area = circle.area_approx();  // 自动关联，直接使用点号语法
    assert_eq!(area, 300);
}

小结

Move 的接收者语法让代码具有面向对象的风格，使得函数调用更加直观。方法的第一个参数决定了访问权限：&self 只读、&mut self 可修改、self 获取所有权。use fun 为函数创建方法别名，public use fun 可以将别名导出供其他模块使用。当模块被导入时，符合条件的公共函数会自动关联为方法，无需额外配置。

宏函数（导读）

宏函数（macro fun）在编译期展开，调用写为 name!(...)，可接收 lambda 参数，用于表达「遍历向量」「处理 Option」等重复模式。第六章此处只保留最短上手；系统讲解（为什么需要宏、编译期管线、展开语义、标准库向量/Option 宏、assert! 与 BCS 相关宏、排错与选型）见 第十一章 · Move 宏函数详解（目录上位于第十章之后）。

最小示例

macro fun add($a: u64, $b: u64): u64 { $a + $b }

public fun three(): u64 { add!(1u64, 2u64) }

标准库中优先使用 vector 的 do!、fold!、tabulate! 等，以及 option 的 do!、destroy_or!，详见第十一章各节。

配套代码

本章配套仍为 code/08-macros/（sui move build）。与第十一章示例 ../11_move_macros/code/macro_lab/ 可对照阅读。

所有权与作用域

Move 语言采用所有权（Ownership）模型来管理值的生命周期。每个变量都有一个所有者和一个作用域，当作用域结束时，变量会被丢弃（drop）。所有权可以通过赋值或函数调用来转移，这种机制从根本上杜绝了悬垂引用和双重释放等内存安全问题。

作用域

函数作用域

每个函数定义一个作用域。在函数内声明的变量属于该函数所有，当函数执行结束时，所有局部变量都会被丢弃：

module book::scope_basic;

public struct Ticket has drop {
    event: vector<u8>,
}

fun create_and_drop() {
    let _ticket = Ticket { event: b"Concert" };
    // 函数结束时，_ticket 自动被丢弃（需要 drop 能力）
}

#[test]
fun scope() {
    create_and_drop();
}

块作用域

花括号 { } 创建子作用域（block scope）。子作用域中声明的变量在块结束时被丢弃，但可以通过块的最后一个表达式将值转移出去：

module book::block_scope;

#[test]
fun block_scope() {
    let x = {
        let inner = 42u64;
        inner  // 将所有权转移到外部作用域
    };
    // inner 在这里不可用，但它的值已经转移给了 x
    assert_eq!(x, 42);

    let result = {
        let a = 10u64;
        let b = 20u64;
        a + b  // 块的返回值
    };
    assert_eq!(result, 30);
}

嵌套作用域

作用域可以嵌套。内层作用域可以访问外层作用域的变量，但外层作用域无法访问内层的局部变量：

module book::nested_scope;

#[test]
fun nested() {
    let outer = 100u64;

    {
        let _inner = outer + 1;  // 可以访问外层变量
        assert_eq!(_inner, 101);
        // _inner 在块结束时被丢弃
    };

    // _inner 在这里不可用
    assert_eq!(outer, 100);  // outer 依然有效
}

所有权转移

函数调用时的所有权转移

当将一个不可复制的值作为参数传递给函数时，所有权会转移到被调用的函数。原变量变得无效，不能再使用：

module book::ownership_example;

public struct Ticket has drop {
    event: vector<u8>,
}

public struct UniqueItem {
    value: u64,
}

public fun create_ticket(): Ticket {
    Ticket { event: b"Concert" }  // 所有权转移给调用者
}

public fun use_ticket(ticket: Ticket) {
    let Ticket { event: _ } = ticket;  // ticket 在这里被消耗
}

#[test]
fun ownership() {
    let ticket = create_ticket();    // ticket 归当前函数所有
    // ticket 的所有权转移给 use_ticket，此后不再有效
    use_ticket(ticket);
    // let _ = ticket.event;  // 错误！ticket 已经被移动
}

赋值时的所有权转移

将一个不可复制的值赋给另一个变量时，所有权也会转移：

module book::ownership_transfer;

public struct Token has drop {
    value: u64,
}

#[test]
fun assignment_move() {
    let token_a = Token { value: 100 };
    let _token_b = token_a;  // 所有权从 token_a 转移到 token_b
    // assert!(token_a.value == 100);  // 错误！token_a 已经被移动
    assert_eq!(_token_b.value, 100);    // token_b 是有效的所有者
}

返回值的所有权转移

函数的返回值将所有权转移给调用者：

module book::ownership_return;

public struct Wrapper has drop {
    value: u64,
}

fun make_wrapper(): Wrapper {
    Wrapper { value: 42 }
    // 所有权转移给调用者，不会在函数结束时被丢弃
}

#[test]
fun return_ownership() {
    let wrapper = make_wrapper();  // 接收所有权
    assert_eq!(wrapper.value, 42);
    // wrapper 在测试函数结束时被丢弃
}

复制与移动

可复制类型

拥有 copy 能力的类型在赋值和传参时会自动复制，原变量仍然有效：

module book::copy_example;

#[test]
fun copy_vs_move() {
    // u64 拥有 copy 能力，赋值时自动复制
    let a = 10u64;
    let b = a;      // a 被复制，仍然有效
    assert_eq!(a, 10);
    assert_eq!(b, 10);

    // bool 也拥有 copy 能力
    let flag = true;
    let flag_copy = flag;
    assert_eq!(flag, true);
    assert_eq!(flag_copy, true);
}

不可复制类型

没有 copy 能力的类型在赋值时会移动，原变量失效：

module book::move_example;

public struct UniqueItem has drop {
    value: u64,
}

#[test]
fun unique_move() {
    let item = UniqueItem { value: 1 };
    let item2 = item;  // item 被移动到 item2
    // assert!(item.value == 1);  // 错误！item 已被移动
    assert_eq!(item2.value, 1);
}

move 关键字

可以使用 move 关键字显式地表达所有权转移的意图，让代码更加清晰：

module book::explicit_move;

public struct Resource has drop {
    data: u64,
}

fun consume(resource: Resource) {
    let Resource { data: _ } = resource;
}

#[test]
fun explicit_move() {
    let resource = Resource { data: 42 };
    consume(move resource);  // 显式移动
    // resource 在这里不再有效
}

析构与 drop

显式析构

对于没有 drop 能力的类型，必须显式析构（解包）来消耗它们：

module book::destruct_example;

public struct Receipt {
    amount: u64,
    paid: bool,
}

public fun create_receipt(amount: u64): Receipt {
    Receipt { amount, paid: true }
}

const ENotPaid: u64 = 0;

// 必须通过解包来消耗 Receipt
public fun verify_and_consume(receipt: Receipt): u64 {
    let Receipt { amount, paid } = receipt;
    assert!(paid, ENotPaid);
    amount
}

#[test]
fun destruct() {
    let receipt = create_receipt(500);
    let amount = verify_and_consume(receipt);
    assert_eq!(amount, 500);
}

drop 能力

拥有 drop 能力的类型可以在作用域结束时自动丢弃，无需显式析构：

module book::drop_example;

public struct Droppable has drop {
    value: u64,
}

public struct NotDroppable {
    value: u64,
}

#[test]
fun auto_drop() {
    let _d = Droppable { value: 1 };
    // 函数结束时自动丢弃，无需处理

    let nd = NotDroppable { value: 2 };
    // 必须显式析构
    let NotDroppable { value: _ } = nd;
}

小结

Move 的所有权模型确保了每个值在任意时刻只有一个所有者。值通过赋值、函数参数和返回值来转移所有权。拥有 copy 能力的类型可以复制，不可复制类型在赋值时会移动，原变量随即失效。作用域（函数和块）限定了变量的生命周期，作用域结束时变量被丢弃。没有 drop 能力的类型必须显式析构，这一机制可以用来实现“不可丢弃“的资源模式，保证重要操作不会被遗漏。

引用

引用（Reference）允许在不转移所有权的情况下访问值。Move 提供两种引用类型：不可变引用 &T（只读访问）和可变引用 &mut T（读写访问）。引用是 Move 中最常用的参数传递方式，通过借用检查器（borrow checker）在编译期保证引用的安全使用。

引用运算符一览

&e.f / &mut e.f 既可对结构体直接取字段引用，也可在已有引用上“延伸”（如 &s_ref.f）。同一模块内的嵌套结构体可链式写：&a.b.c。注意：引用不能再次取引用，即不存在 &&T。

引用类型

不可变引用 &T

不可变引用提供只读访问，不能通过它修改值：

module book::immutable_ref;

public struct Wallet has drop {
    balance: u64,
}

public fun new(balance: u64): Wallet {
    Wallet { balance }
}

// 接收不可变引用，只能读取
public fun balance(wallet: &Wallet): u64 {
    wallet.balance
}

#[test]
fun immutable_ref() {
    let wallet = new(100);
    let b = balance(&wallet);   // 创建不可变引用
    assert_eq!(b, 100);
    // wallet 仍然有效，所有权没有转移
    assert_eq!(balance(&wallet), 100);
}

可变引用 &mut T

可变引用提供读写访问，可以修改被引用的值：

module book::mutable_ref;

public struct Wallet has drop {
    balance: u64,
}

public fun new(balance: u64): Wallet {
    Wallet { balance }
}

// 接收可变引用，可以修改值
public fun deposit(wallet: &mut Wallet, amount: u64) {
    wallet.balance = wallet.balance + amount;
}

public fun balance(wallet: &Wallet): u64 {
    wallet.balance
}

#[test]
fun mutable_ref() {
    let mut wallet = new(100);
    deposit(&mut wallet, 50);      // 创建可变引用
    assert_eq!(balance(&wallet), 150);
    deposit(&mut wallet, 30);
    assert_eq!(balance(&wallet), 180);
}

实际案例：地铁卡

用一个地铁卡的例子来理解引用的三种使用方式——购买（获取所有权）、出示（不可变借用）、刷卡（可变借用）、回收（转移所有权）：

module book::reference_example;

public struct Card has drop {
    rides: u64,
}

const ENoRides: u64 = 0;

// 购买：返回拥有的 Card
public fun purchase(): Card {
    Card { rides: 5 }
}

// 出示：不可变借用（只读）
public fun remaining_rides(card: &Card): u64 {
    card.rides
}

// 刷卡：可变借用（修改）
public fun use_ride(card: &mut Card) {
    assert!(card.rides > 0, ENoRides);
    card.rides = card.rides - 1;
}

// 回收：获取所有权（消耗）
public fun recycle(card: Card) {
    let Card { rides: _ } = card;
}

#[test]
fun references() {
    let mut card = purchase();

    // 不可变借用 —— 只是查看
    assert_eq!(remaining_rides(&card), 5);

    // 可变借用 —— 修改状态
    use_ride(&mut card);
    use_ride(&mut card);
    assert_eq!(remaining_rides(&card), 3);

    // 移动 —— 转移所有权
    recycle(card);
    // card 在这里不再有效
}

解引用

使用 * 解引用

对引用使用 * 运算符可以获取引用指向的值的副本。被引用的类型必须拥有 copy 能力：

module book::deref_example;

#[test]
fun deref() {
    let value = 42u64;
    let ref_value = &value;

    // 解引用获取值的副本
    let copied = *ref_value;
    assert_eq!(copied, 42);
    assert_eq!(value, 42);  // 原值不受影响
}

通过可变引用修改

可以通过解引用可变引用来修改值。读 *e 要求被引用类型有 copy 能力（读会复制值）；写 *e1 = e2 要求被引用类型有 drop 能力（写会丢弃旧值）。因此不能通过引用复制或销毁“资源”类型（如无 copy/drop 的资产）。

module book::deref_mut;

#[test]
fun deref_mut() {
    let mut value = 10u64;
    let ref_mut = &mut value;
    *ref_mut = 20;
    assert_eq!(value, 20);
}

freeze 与子类型

在需要 &T 的地方可以传入 &mut T：编译器会在需要时插入 freeze，将可变引用视为不可变使用。因此类型系统把 &mut T 当作 &T 的子类型：任何接受 &T 的表达式也可以接受 &mut T，反之则不成立（不能把 &T 赋给 &mut T 或传给需要 &mut T 的参数）。

引用的复制与写入规则

在 Move 中，引用可以被多次复制，同一时刻存在多个对同一值的引用（包括多个 &mut）在类型上是被允许的；只有在通过可变引用写入时，才要求该可变引用是“唯一可写”的。这与许多语言里“同一时刻仅一个可变借用”的直觉不同，但写入前的唯一性保证同样严格。

引用不可存储

引用和元组是仅有的不能作为结构体字段类型存储的类型，因此引用不能进入全局存储或 Sui 对象，只能在一次执行过程中临时存在，程序结束时全部销毁。

借用规则

基本规则

Move 的借用检查器确保引用的安全使用，遵循以下规则：

1. 在任意时刻，对同一个值要么有一个可变引用，要么有多个不可变引用，但不能同时拥有两者
2. 引用不能悬垂——被引用的值在引用存在期间不能被移动或丢弃
3. 不能返回对局部变量的引用——局部变量在函数结束时被丢弃，引用会变成悬垂引用

module book::borrow_rules;

public struct Data has drop, copy {
    value: u64,
}

#[test]
fun multiple_immutable() {
    let data = Data { value: 42 };
    let ref1 = &data;
    let ref2 = &data;
    // 多个不可变引用可以同时存在
    assert_eq!(ref1.value, 42);
    assert_eq!(ref2.value, 42);
}

#[test]
fun mutable_exclusive() {
    let mut data = Data { value: 42 };
    let ref_mut = &mut data;
    // 可变引用期间，不能有其他引用
    ref_mut.value = 100;
    assert_eq!(data.value, 100);
}

引用不能返回局部变量

函数不能返回对局部变量的引用，因为局部变量在函数结束后就不存在了：

module book::no_dangling;

public struct Container has drop {
    value: u64,
}

// 这是正确的 —— 返回对参数的引用（getter 以字段名命名，无 get_ 前缀）
public fun value(container: &Container): &u64 {
    &container.value
}

// 以下代码无法编译：
// fun dangling_ref(): &u64 {
//     let local = 42u64;
//     &local  // 错误！local 在函数结束时被丢弃
// }

#[test]
fun ref_to_field() {
    let container = Container { value: 99 };
    let value_ref = value(&container);
    assert_eq!(*value_ref, 99);
}

引用与所有权的选择

在设计函数签名时，选择合适的参数类型：

module book::ref_choice;

public struct Account has drop {
    balance: u64,
}

// 获取所有权 —— 消耗 Account
public fun close(account: Account): u64 {
    let Account { balance } = account;
    balance
}

// 不可变借用 —— 只读查询（getter 以字段名命名）
public fun balance(account: &Account): u64 {
    account.balance
}

// 可变借用 —— 修改状态
public fun deposit(account: &mut Account, amount: u64) {
    account.balance = account.balance + amount;
}

#[test]
fun ref_choice() {
    let mut account = Account { balance: 100 };

    // 查询 —— 不可变借用
    assert_eq!(balance(&account), 100);

    // 修改 —— 可变借用
    deposit(&mut account, 50);
    assert_eq!(balance(&account), 150);

    // 关闭 —— 转移所有权
    let final_balance = close(account);
    assert_eq!(final_balance, 150);
}

小结

引用是 Move 中访问值的核心机制。不可变引用 &T 提供只读访问，可变引用 &mut T 提供读写访问，两者都不会转移所有权。借用检查器在编译期确保同一时刻不会同时存在可变引用和不可变引用，也不允许返回对局部变量的引用。在设计函数签名时，应根据需要选择参数类型：只读查询用 &T，需要修改用 &mut T，需要消耗或转移用 T。

Move 2024 版本新特性

为何放在第六章末尾：前文 6.1–6.10 已分别用到 let mut、方法语法、public(package)、枚举与 match 等特性；若你刚完成第三～五章、能顺利 sui move build，不必提前通读本节——把 edition 与 Framework rev 的约定当作「随示例对齐」即可。本节把 Move 2024 与旧版语法集中对照，便于系统复习、阅读旧仓库或运行 sui move migrate。

Move 2024 是 Move 语言的一次重要更新，引入了大量现代化的语法特性，使代码更简洁、更符合直觉。本书所有代码均基于 Move 2024 版本编写。本节将详细介绍这些新特性，并通过前后对比帮助你理解每项改进。

启用 Move 2024

在 Move.toml 中设置版本：

[package]
name = "my_package"
edition = "2024"

[dependencies]
Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/mainnet" }

[addresses]
my_package = "0x0"

重要：edition = "2024" 必须在 [package] 下显式声明。如果省略，默认使用旧版本语法。

部分工具或旧模板仍可能写出 edition = "2024.beta"，与 "2024" 指向同一套 Move 2024 语法；本书全文示例统一写 "2024"，便于检索与复制。

Sui Framework 依赖：rev 与网络

Move.toml 里对 Sui Framework 的 Git 依赖需写 rev = "framework/<分支名>"。Mysten 在 sui 仓库中维护 framework/mainnet 与 framework/testnet 等分支，分别与主网、测试网方向的 Framework 发布节奏对齐；应与你使用 sui client 连接的环境一致，避免链上类型与本地编译所用 Framework 严重错位。

本书正文中的 Move.toml 片段默认使用 framework/mainnet；若在测试网演练，将 rev 改为 framework/testnet 即可。清单文件详解中另有 [dev-dependencies] 等组合示例。

可变绑定：let mut

Move 2024 要求显式标注可变变量，使代码意图更清晰。

旧版本

let x = 5;
x = 10;  // 隐式可变，容易产生误解

新版本

let mut x = 5;
x = 10;  // 显式声明可变性

let y = 5;
// y = 10;  // 编译错误！未声明 mut

这样可以在声明处就标明变量是否可变，意图更清晰。函数参数同样适用：

public fun process(mut value: u64): u64 {
    value = value + 1;
    value
}

结构体可见性：public struct

结构体声明现在需要显式指定可见性。

旧版本

struct MyStruct has key {
    id: UID,
    value: u64,
}

新版本

public struct MyStruct has key {
    id: UID,
    value: u64,
}

如果结构体只在模块内部使用，可以省略 public：

struct InternalConfig {
    max_retries: u64,
    timeout_ms: u64,
}

包可见性：public(package) 替代 friend

friend 机制已被弃用，取而代之的是更简洁的 public(package) 可见性。

旧版本

module my_package::module_a {
    friend my_package::module_b;

    public(friend) fun internal_helper(): u64 {
        42
    }
}

新版本

module my_package::module_a;

public(package) fun internal_helper(): u64 {
    42
}

public(package) 允许同一包内的所有模块调用该函数，无需逐一声明 friend 关系，更加灵活且易于维护。

三种函数可见性总结：

方法语法：接收者风格调用

Move 2024 支持使用 . 语法在结构体实例上调用方法，类似于面向对象语言。

旧版本

let len = vector::length(&my_vec);
let val = vector::borrow(&my_vec, 0);
vector::push_back(&mut my_vec, 42);

新版本

let len = my_vec.length();
let val = my_vec.borrow(0);
my_vec.push_back(42);

编译器会自动将 e.f(args) 转换为 f(e, args)，其中 e 作为第一个参数传入。这要求函数的第一个参数类型与调用者匹配。

自定义结构体同样支持方法语法：

public struct Counter has key {
    id: UID,
    value: u64,
}

public fun increment(counter: &mut Counter) {
    counter.value = counter.value + 1;
}

// 调用时可以写成：
// counter.increment();

内置类型方法

Move 2024 为基本类型和内置类型添加了便捷方法。

字节串转 String

// 旧版本
use std::string;
let s = string::utf8(b"Hello, Move!");

// 新版本
let s = b"Hello, Move!".to_string();

地址转字节

// 旧版本
use sui::address;
let bytes = address::to_bytes(@0xa11ce);

// 新版本
let bytes = @0xa11ce.to_bytes();

常用方法一览

// vector 方法
let mut v = vector[1, 2, 3];
v.push_back(4);
let len = v.length();
let first = v[0];         // 索引访问
let is_empty = v.is_empty();

// u64 方法
let s = 42u64.to_string();

索引语法

使用 [] 操作符直接访问集合元素，替代冗长的 borrow 调用。

旧版本

let val = *vector::borrow(&my_vec, 0);
*vector::borrow_mut(&mut my_vec, 1) = 42;

新版本

let val = my_vec[0];       // 不可变索引
my_vec[1] = 42;            // 可变索引

对于自定义类型，可以通过 #[syntax(index)] 属性实现索引访问：

public struct Registry has key {
    id: UID,
    entries: Table<address, u64>,
}

#[syntax(index)]
public fun borrow_entry(registry: &Registry, addr: address): &u64 {
    table::borrow(&registry.entries, addr)
}

#[syntax(index)]
public fun borrow_entry_mut(registry: &mut Registry, addr: address): &mut u64 {
    table::borrow_mut(&mut registry.entries, addr)
}

// 使用：
// let value = registry[addr];
// registry[addr] = 100;

方法别名

use fun 和 public use fun 允许你为类型关联自定义方法名。

module my_package::my_module;

use sui::coin::Coin;
use sui::sui::SUI;

public use fun coin_value as Coin<SUI>.value;

public fun coin_value(coin: &Coin<SUI>): u64 {
    coin.value()
}

通过 use fun，你可以为不属于你的类型添加方法调用语法，增强代码可读性。

枚举类型与模式匹配

Move 2024 引入了枚举类型（enum）和 match 表达式，这是一项重大功能增强。

定义枚举

public enum Color has copy, drop {
    Red,
    Green,
    Blue,
    Custom { r: u8, g: u8, b: u8 },
}

模式匹配

public fun color_to_rgb(color: &Color): (u8, u8, u8) {
    match (color) {
        Color::Red => (255, 0, 0),
        Color::Green => (0, 255, 0),
        Color::Blue => (0, 0, 255),
        Color::Custom { r, g, b } => (*r, *g, *b),
    }
}

实际应用示例

public enum Action has copy, drop {
    Transfer { to: address, amount: u64 },
    Burn { amount: u64 },
    Freeze,
}

public fun describe_action(action: &Action): String {
    match (action) {
        Action::Transfer { to: _, amount } => {
            b"Transfer".to_string()
        },
        Action::Burn { amount: _ } => {
            b"Burn".to_string()
        },
        Action::Freeze => {
            b"Freeze".to_string()
        },
    }
}

注意：match 必须是穷尽的 —— 你必须覆盖枚举的所有变体，或使用通配符 _ 作为兜底。

模块声明简化

Move 2024 允许省略模块的花括号包裹，整个文件即为一个模块：

旧版本

module my_package::my_module {
    use std::string::String;

    public fun hello(): String {
        b"Hello".to_string()
    }
}

新版本

module my_package::my_module;

use std::string::String;

public fun hello(): String {
    b"Hello".to_string()
}

文件级模块声明以分号结尾，后续所有代码都属于该模块，更加简洁。

迁移工具

如果你有旧版本的 Move 代码需要迁移到 2024 版本，可以使用官方迁移工具：

sui move migrate

该工具会自动执行以下转换：

• 添加 mut 标注
• 添加 public 结构体可见性
• 将 friend + public(friend) 替换为 public(package)
• 更新 Move.toml 中的 edition

提示：迁移工具会尽可能自动转换，但某些复杂情况可能需要手动调整。建议在迁移后运行 sui move build 和 sui move test 确认一切正常。

特性对照表

小结

Move 2024 通过引入 let mut、public struct、public(package)、方法语法、索引语法、枚举和模式匹配等特性，大幅提升了语言的表达力和开发体验。这些改进使 Move 代码更简洁、更安全、更易读。本书后续所有代码都将使用 Move 2024 语法。如果你需要迁移旧代码，可以使用 sui move migrate 工具自动完成大部分转换。

第六章 · 实战练习

实战一：Vector 累加

1. 进入 src/06_move_intermediate/code/02-vector/。
2. 在模块中新增函数：输入 vector<u64>，返回所有元素之和（注意空 vector）。
3. sui move build，并可选添加 #[test] 验证。
4. 验收：测试或编译通过。

实战二：Option 与模式匹配

1. 使用 src/06_move_intermediate/code/03-option/ 或 06-pattern-matching/。
2. 实现「从 Option<u64> 取值，若为 None 则返回默认 0」的函数，用 match 或 if let 风格编写。
3. 验收：代码风格符合本章「安全取值」习惯。

实战三：宏展开心智演练

1. 打开 src/06_move_intermediate/code/08-macros/sources/macros.move。
2. 在不改坏编译的前提下，为 add! 再增加一个调用点（例如 add!(10u64, 20u64) 的包装函数）。
3. 验收：sui move build 成功；能向同伴解释「宏在编译期展开」与函数调用的区别。
4. （可选）对照 第十一章 · macro_lab 示例，尝试为 vector 写一个 fold! 用例。

实战四：Move.toml 与 Move 2024 对照

1. 阅读§6.11 Move 2024 Edition 与语法对照中的「启用 Move 2024」与「Sui Framework 依赖：rev 与网络」。
2. 任选本书一章配套包，打开其 Move.toml，指出 edition 与 [dependencies]（或隐式框架）与当前 sui client 环境是否匹配。
3. 验收：能口头说明 framework/mainnet 与 framework/testnet 的选用场景；sui move build 仍通过。

第八章 · Move 语法高级

本章介绍泛型与类型反射，涉及类型参数、能力约束以及运行时类型信息，是编写可复用、类型安全的 Move 库与框架的必备内容。

本章内容

节与正文、示例代码

学习目标

读完本章后，你将能够：

• 编写泛型函数与泛型结构体，并正确施加能力约束
• 正确使用 phantom，区分「仅类型标签」与「字段中使用的类型参数」
• 在需要时使用类型反射获取运行时类型信息
• 使用编译模式控制调试/测试等不可发布代码的编入与发布安全
• 为自定义类型定义下标语法（#[syntax(index)]）并遵守只读/可写成对规则

本章实战练习

每章 1～3 个动手任务见 hands-on.md（目录中亦列为「本章实战练习」）。

泛型基础

泛型（Generics）允许在未指定具体类型的情况下定义函数和结构体，实现代码复用与抽象。Move 使用尖括号 <T> 声明类型参数，类型参数可用于参数类型、返回类型和函数体。

泛型函数

module book::generic_fun;

public fun identity<T>(value: T): T {
    value
}

public fun make_pair<T, U>(first: T, second: U): (T, U) {
    (first, second)
}

#[test]
fun generic_fun() {
    let x = identity(42u64);
    assert_eq!(x, 42);
    let (a, b) = make_pair(10u64, true);
    assert_eq!(a, 10);
    assert_eq!(b, true);
}

编译器通常可根据上下文推断类型参数。无法推断时，可使用 function_name<Type>() 显式指定。

泛型结构体

结构体也可以使用泛型类型参数：

module book::generic_struct;

public struct Container<T: drop> has drop {
    value: T,
}

public fun new<T: drop>(value: T): Container<T> {
    Container { value }
}

public fun value<T: drop + copy>(container: &Container<T>): T {
    container.value
}

多类型参数

函数和结构体可以有多个类型参数：

public struct Pair<T: copy + drop, U: copy + drop> has copy, drop {
    first: T,
    second: U,
}

小结

• 泛型函数：fun name<T>(...)，类型参数可用于参数与返回值
• 泛型结构体：struct Name<T> { ... }
• 类型推断：多数情况可省略显式类型；必要时使用 name<Type>()

类型参数与能力约束

对泛型类型参数施加 能力约束（ability constraints），可以要求类型具备 copy、drop、store、key 等能力。若类型参数只作类型标签、不出现在字段中，则需使用 phantom，详见下一节 §8.3 phantom 类型参数。

能力约束

对类型参数添加能力约束，要求传入的类型必须满足相应能力：

module book::generic_constraints;

public struct Copyable<T: copy + drop> has copy, drop {
    value: T,
}

public struct Storable<T: store> has store {
    value: T,
}

public fun duplicate<T: copy>(value: &T): T {
    *value
}

常见约束组合：

泛型与对象

在 Sui 中，泛型常与对象结合，实现通用对象容器（如 Container<T: store> has key, store），并通过 store 等能力约束保证类型可安全存储。

小结

• 能力约束：T: copy + drop、T: store 等，确保类型参数满足所需能力
• phantom：单独成章，见 §8.3
• 泛型对象：结合 key/store 实现可存储的泛型对象

phantom 类型参数

在泛型基础与类型参数与能力约束中，你已经能为类型参数加上 copy、store 等约束。本节专门讲 phantom：当某个类型参数只用于在类型层面区分不同泛型实例、不出现在结构体字段里时，必须用 phantom 声明——否则编译器会拒绝「未使用的类型参数」。

为什么需要 phantom

Move 要求：若类型参数 T 没有出现在结构体的任何字段类型中，则必须标记为 phantom T。这样编译器知道：T 不参与该值的运行时布局，只参与静态类型检查。

典型用途：

• 代币 / 资产类型标签：Coin<phantom T>、Balance<phantom T>，用 T 区分 SUI、USDC 等，链上数据里仍只有余额等字段。
• 关联某类型但不存储该类型值：如 Display<phantom T: key>、TypeKey<phantom T>，在类型系统里「记住」T，字段里只放 UID 等。

基本写法