前言

欢迎阅读《Move on Sui: 从零到精通》。这本书是为所有希望深入理解 Sui 区块链及 Move 智能合约语言的开发者而编写的，无论你是从 Solidity 转型的以太坊开发者、有一定编程基础的系统工程师，还是对 Web3 充满好奇的通用程序员，本书都将为你提供一条从入门到精通的清晰路径。本书全面覆盖 Move 2024 Edition 在 Sui 上的最新特性，确保你学到的每一行代码都与当前主网保持同步。

目标读者

本书面向以下几类读者：

区块链开发者

如果你已经在以太坊、Solana 或其他链上有开发经验，本书将帮助你快速理解 Sui 的对象模型与 Move 语言的独特设计哲学。你会发现 Move 在资源安全性和类型系统上相比 Solidity 有质的飞跃。

Solidity 开发者

本书在关键章节中穿插了与 Solidity 的对比，包括存储模型差异（账户模型 vs 对象模型）、安全机制（重入攻击在 Move 中为何不存在）以及编程范式的根本区别。这些对比将大幅缩短你的学习曲线。

通用程序员

即使你没有任何区块链经验，本书也从最基础的概念讲起。只要你熟悉至少一门编程语言（如 Rust、TypeScript、Python 或 Go），就能跟上本书的节奏。Move 语言的语法借鉴了 Rust，如果你有 Rust 背景会感到尤其亲切。

学习路线

本书采用循序渐进的结构，共分为五个阶段：

第一阶段：基础认知（第 1–2 章）

了解区块链与智能合约的基本原理，认识 Sui 的技术架构与生态系统，搭建完整的开发环境。这一阶段为后续所有内容打下坚实基础。

第二阶段：Move 语言精通（第 3–5 章）

从 Hello World 开始，逐步掌握 Move 的类型系统、Abilities 机制、所有权与引用、泛型编程等核心语言特性。每个知识点都配有可编译运行的代码示例。

第三阶段：Sui 对象模型（第 6–8 章）

深入 Sui 最具创新性的对象模型——理解对象所有权、共享对象与快速路径、动态字段、Balance 与 Coin 等核心概念。这是区分“会写 Move“和“会用 Sui“的关键分水岭。

第四阶段：设计模式与工程实践（第 9–10 章）

掌握 Capability、Witness、Hot Potato 等经典设计模式，学习编写高质量测试。这些模式是生产级 Sui 合约的基石。

第五阶段：应用实战（第 11–17 章）

从代币发行、NFT 市场到全栈 DApp 开发，再到 ZKLogin、DeepBook、Walrus 等前沿技术，将所学知识付诸实践。

// 你将在本书中编写的第一个 Move 模块
module hello::hello_world;

use std::string::String;
use std::unit_test::assert_eq;

public fun greeting(): String {
    b"Hello, Move on Sui!".to_string()
}

#[test]
fun greeting_returns_hello() {
    assert_eq!(greeting(), b"Hello, Move on Sui!".to_string());
}

如何使用本书

动手实践

本书采用边学边练的教学方法。每一章都包含完整的代码示例，我们强烈建议你在本地环境中亲手输入、编译和运行每一段代码，而不是简单地复制粘贴。肌肉记忆是掌握新语言最有效的方式。

章节递进

各章节之间存在依赖关系——后面的章节会引用前面介绍的概念和代码。建议你按照章节顺序阅读，至少在第一遍学习时不要跳读。当然，如果你已有一定基础，可以从目录中选择感兴趣的章节开始。

代码仓库

本书所有代码示例均可在配套的 GitHub 仓库中找到。每一章的代码都是独立可编译的 Move 项目，你可以直接 clone 下来运行：

git clone https://github.com/hoh-zone/learning-sui.git
cd learning-sui

版本说明

本书内容基于以下版本编写：

• Move 语言：2024 Edition
• Sui 框架：与当前 Sui 主网版本保持同步
• Sui CLI：最新稳定版

由于 Sui 生态发展迅速，部分 API 可能会随版本更新而变化。如果遇到编译错误，请先检查依赖版本是否与书中一致。

前置知识

为了顺利阅读本书，你需要具备以下基础：

• 编程基础：熟悉至少一门编程语言的基本概念（变量、函数、控制流、数据结构）
• 命令行操作：能够在终端中执行基本命令
• Git 基础：了解 clone、commit、push 等基本操作
• 区块链概念（可选）：如果你了解公钥/私钥、交易、区块等基本概念会更有帮助，但这不是必须的——第一章会从头讲起

不需要提前学习 Rust，虽然 Move 的语法与 Rust 相似，但本书会在引入每个语法特性时给出充分的解释。

小结

本书将带你从零开始，系统地掌握 Sui 区块链上的 Move 智能合约开发。通过理论讲解与实战演练相结合的方式，你将不仅学会 Move 语言本身，更会深入理解 Sui 的对象模型、设计模式与最佳实践。无论你的最终目标是构建 DeFi 协议、NFT 市场，还是创新的链上应用，本书都将为你提供坚实的技术基础。

让我们开始这段旅程吧。

第一章 · 走进 Sui 与 Move

本章将带你了解 Sui 区块链的核心理念和技术架构，认识 Move 语言的独特优势，并安装好开发所需的工具链。

本章内容

学习目标

读完本章后，你将能够：

• 理解 Sui 区块链相对于其他链的核心差异
• 说出 Move 语言在安全性和资产建模上的优势
• 使用 suiup 安装和管理 Sui 开发工具

区块链与智能合约

区块链是一种去中心化的分布式账本技术，它通过密码学和共识机制保证数据的不可篡改性与一致性。智能合约则是运行在区块链上的程序，它们能够在无需信任第三方的情况下自动执行预定义的逻辑。理解这两个基础概念，是踏入 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 类共识机制能够在部分节点存在恶意行为的情况下仍然达成一致。Sui 采用的 Bullshark 协议就属于此类。

• 优势：确定性终局（Finality），无需等待多个区块确认
• 劣势：通常对验证者数量有一定限制

Sui 的共识设计尤为独特——对于仅涉及**已拥有对象（Owned Objects）**的交易，Sui 甚至可以绕过共识协议，直接通过拜占庭一致广播实现亚秒级确认。我们将在后续章节中详细讨论这一机制。

什么是智能合约

定义与核心思想

智能合约（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）**而非账户为核心，通过对象级别的并行执行和创新的共识协议，实现了亚秒级的交易终局和水平可扩展的吞吐量。本节将深入剖析 Sui 的技术架构，帮助你从系统层面理解 Sui 的设计哲学。

对象中心模型 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 核心和验证者节点，就能处理更多的并发交易。这种水平可扩展性是传统区块链所不具备的。

共识架构：Narwhal + Bullshark

Sui 的共识系统由两个关键组件协同工作：Narwhal 负责交易的传播和排序，Bullshark 负责在验证者之间达成最终共识。

Narwhal：基于 DAG 的内存池

Narwhal 是一个高吞吐量的**内存池（Mempool）协议。它使用有向无环图（DAG）**结构来组织交易批次，而非传统的线性区块链结构。

Narwhal DAG 结构（简化示意）:

轮次 1       轮次 2       轮次 3
┌─────┐    ┌─────┐    ┌─────┐
│ V1  │───▶│ V1  │───▶│ V1  │
└─────┘  ╲ └─────┘ ╲  └─────┘
          ╲  ▲    ╲  ╲  ▲
┌─────┐    ╲│      ╲  ╲│
│ V2  │────▶│ V2  │───▶│ V2  │
└─────┘  ╱  └─────┘ ╱  └─────┘
        ╱     ▲    ╱     ▲
┌─────┐╱     │   ╱     │
│ V3  │────▶│ V3  │───▶│ V3  │
└─────┘    └─────┘    └─────┘

V1, V2, V3 = 验证者节点
每个方块 = 该验证者在该轮次提交的交易批次
箭头 = 对前一轮次批次的引用（因果关系）

Narwhal 的关键设计：

• 数据传播与共识解耦：交易数据的分发不需要等待共识完成
• 高吞吐量：每个验证者可以独立地持续提交交易批次
• 可靠性：即使部分节点故障，已提交的交易也不会丢失

Bullshark：共识协议

Bullshark 是建立在 Narwhal DAG 之上的共识协议。它的工作是在 DAG 结构中确定一个所有验证者都认同的交易排序。

Bullshark 的核心特性：

• 零消息开销：Bullshark 不需要额外的消息交换，完全利用 Narwhal DAG 中已有的信息
• 确定性终局：一旦共识达成，交易顺序不可更改，无需等待多个区块确认
• 拜占庭容错：能够在最多 1/3 的验证者存在恶意行为时正常运作

已拥有对象 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
}

快速路径（Fast Path）

这是 Sui 最具突破性的设计之一。对于仅涉及已拥有对象的交易，Sui 可以跳过 Bullshark 共识，直接通过拜占庭一致广播（Byzantine Consistent Broadcast）实现确认。

交易执行路径:

              ┌─────────────────────┐
              │     交易提交         │
              └──────────┬──────────┘
                         │
                   ┌─────▼─────┐
                   │ 对象分析   │
                   └─────┬─────┘
                         │
              ┌──────────┴──────────┐
              │                     │
       ┌──────▼──────┐      ┌──────▼──────┐
       │ 仅已拥有对象  │      │ 涉及共享对象  │
       └──────┬──────┘      └──────┬──────┘
              │                     │
       ┌──────▼──────┐      ┌──────▼──────┐
       │  快速路径     │      │ Bullshark   │
       │ (~400ms)     │      │  共识排序     │
       └──────┬──────┘      │ (~2-3s)     │
              │              └──────┬──────┘
              │                     │
              └──────────┬──────────┘
                         │
                  ┌──────▼──────┐
                  │  交易终局    │
                  └─────────────┘

快速路径的意义：

• 亚秒级终局：仅涉及已拥有对象的交易可以在约 400 毫秒内完成确认
• 适用场景：个人代币转账、NFT 铸造和转移、个人资产更新等
• 无需共识：减少了验证者之间的通信开销，大幅提升吞吐量

设计选择的影响

理解已拥有对象和共享对象的区别，对于 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    │                     │
│              │  ┌────────────┐ │                     │
│              │  │ 交易路由    │ │                     │
│              │  │ 状态查询    │ │                     │
│              │  │ 事件索引    │ │                     │
│              │  └────────────┘ │                     │
│              └────────┬────────┘                     │
└───────────────────────┼─────────────────────────────┘
                        │
┌───────────────────────┼─────────────────────────────┐
│                   验证者层                            │
│     ┌─────────────────▼─────────────────────┐       │
│     │            交易处理引擎                  │       │
│     │  ┌───────────┐      ┌───────────────┐ │       │
│     │  │ 快速路径   │      │ Bullshark     │ │       │
│     │  │ (Owned)   │      │ 共识 (Shared)  │ │       │
│     │  └───────────┘      └───────────────┘ │       │
│     └───────────────────────────────────────┘       │
│     ┌───────────────────────────────────────┐       │
│     │           Narwhal (DAG Mempool)        │       │
│     └───────────────────────────────────────┘       │
│     ┌───────────────────────────────────────┐       │
│     │           Move 虚拟机 (MoveVM)          │       │
│     └───────────────────────────────────────┘       │
│     ┌───────────────────────────────────────┐       │
│     │          对象存储 (Object Store)        │       │
│     └───────────────────────────────────────┘       │
└─────────────────────────────────────────────────────┘

小结

本节深入介绍了 Sui 的技术架构。Sui 的对象中心模型从根本上改变了区块链的状态管理方式，使得并行执行成为可能；Narwhal + Bullshark 共识架构提供了高吞吐量和确定性终局；快速路径机制让已拥有对象的交易实现了亚秒级确认。这些设计创新使 Sui 成为当前性能最强的 Layer 1 区块链之一。在下一节中，我们将纵览 Sui 的生态系统，了解在这个强大基础设施之上构建的各类应用和协议。

Sui 生态全景

Sui 自主网上线以来，围绕其高性能基础设施构建了一个快速增长的生态系统。从去中心化存储到链上订单簿交易所，从零知识登录到数字资产市场框架，Sui 生态中的项目充分利用了对象模型和并行执行的优势，探索着 Web3 应用的全新可能性。本节将按类别全面介绍 Sui 生态中的关键项目和基础设施。

基础设施

Walrus：去中心化存储

Walrus 是 Sui 生态中的去中心化存储协议，专门为大规模非结构化数据（如图片、视频、网页等）设计。它使用 Red Stuff 纠删编码技术，将数据分片后分布存储在全球节点上，以极低的冗余度（约 4-5 倍，远低于传统全副本方案的 N 倍）实现高可用性。

Walrus 的核心特点：

• 与 Sui 深度集成：存储元数据和可用性证明记录在 Sui 链上
• 成本高效：纠删编码大幅降低存储成本
• 可编程存储：通过 Move 合约控制存储策略和访问权限
• 去中心化网站托管：支持通过 Walrus Sites 直接部署前端应用

module examples::walrus_integration;

/// 链上记录 Walrus 存储引用
public struct StorageRecord has key, store {
    id: UID,
    blob_id: vector<u8>,
    content_type: vector<u8>,
    size: u64,
    owner: address,
}

/// 注册一条存储记录
public fun register_blob(
    blob_id: vector<u8>,
    content_type: vector<u8>,
    size: u64,
    ctx: &mut TxContext,
) {
    let record = StorageRecord {
        id: object::new(ctx),
        blob_id,
        content_type,
        size,
        owner: ctx.sender(),
    };
    transfer::transfer(record, ctx.sender());
}

Sui Bridge：跨链桥

Sui Bridge 是 Sui 的原生跨链桥，支持在 Sui 和以太坊之间安全地转移资产。它采用了基于验证者委员会的多签机制，确保跨链操作的安全性。

主要功能：

• 资产转移：支持 ETH、USDC、USDT 等主流资产的跨链转移
• 原生集成：桥接逻辑内置于 Sui 协议中，而非第三方方案
• 安全机制：由 Sui 验证者委员会共同保障跨链交易安全

SuiNS：域名服务

SuiNS 是 Sui 上的去中心化域名系统，类似于以太坊上的 ENS。用户可以将难以记忆的地址映射为人类可读的名称。

地址映射示例:
alice.sui → 0x1a2b3c4d5e6f...
bob.sui   → 0x7a8b9c0d1e2f...

SuiNS 域名本身就是 Sui 上的 NFT 对象，可以自由交易和转让。开发者可以在合约中直接解析 SuiNS 域名，获取对应地址。

Move Registry

Move Registry 是 Sui 上的包管理和命名系统，为 Move 包提供人类可读的名称和版本管理。开发者可以通过名称引用依赖包，而不需要使用原始的包地址。

去中心化金融（DeFi）

DeepBook：链上订单簿

DeepBook 是 Sui 上的原生链上中央限价订单簿（CLOB）协议。与使用自动做市商（AMM）的 DEX 不同，DeepBook 提供了类似中心化交易所的交易体验：

• 限价单和市价单：支持完整的订单类型
• 链上撮合：所有订单匹配都在链上完成，完全透明
• 高性能：利用 Sui 的并行执行能力，实现高吞吐量的订单处理
• 共享流动性：作为基础设施层，其他 DeFi 协议可以直接接入 DeepBook 的流动性

module examples::deepbook_usage;

use deepbook::clob_v2;

/// DeepBook 交易示例（概念性代码）
/// 在真实场景中需要引入 deepbook 依赖
public fun place_limit_order_example() {
    // 1. 创建交易池
    // clob_v2::create_pool<BaseAsset, QuoteAsset>(...)

    // 2. 创建托管账户
    // clob_v2::create_account(...)

    // 3. 存入资产
    // clob_v2::deposit_base(...)

    // 4. 下限价单
    // clob_v2::place_limit_order(...)

    // 5. 撮合引擎自动匹配订单
}

主要 DeFi 协议

Sui 上已经涌现出众多 DeFi 协议，覆盖了去中心化金融的各个领域：

DEX（去中心化交易所）

借贷协议

流动性质押

稳定币与收益

身份与认证

zkLogin：零知识登录

zkLogin 是 Sui 最具创新性的功能之一，它允许用户使用 Google、Facebook、Apple 等社交账号直接登录 Sui 应用，而无需创建和管理加密钱包。

zkLogin 工作流程:

用户                 应用                OAuth 提供商        Sui 网络
 │                    │                    │                 │
 │  1. 点击登录       │                    │                 │
 │──────────────────▶│                    │                 │
 │                    │  2. OAuth 请求      │                 │
 │                    │──────────────────▶│                 │
 │  3. 社交登录       │                    │                 │
 │◀──────────────────────────────────────│                 │
 │                    │  4. JWT Token       │                 │
 │                    │◀──────────────────│                 │
 │                    │                    │                 │
 │                    │  5. 生成零知识证明   │                 │
 │                    │  (证明 JWT 有效，    │                 │
 │                    │   但不泄露身份信息)  │                 │
 │                    │                    │                 │
 │                    │  6. 提交交易 + ZK证明│                 │
 │                    │──────────────────────────────────▶│
 │                    │                    │  7. 验证并执行   │
 │                    │                    │                 │

zkLogin 的核心价值：

• 零门槛：用户不需要记住助记词或管理私钥
• 隐私保护：零知识证明确保社交身份信息不会泄露到链上
• 无缝体验：Web2 用户可以像使用传统应用一样使用 DApp

多签（Multisig）

Sui 原生支持多签钱包，允许设置 M-of-N 的签名策略。组织和团队可以共同管理资金，提高安全性。

NFT 与数字资产

Kiosk：数字资产市场框架

Kiosk 是 Sui 的原生数字资产交易框架。它提供了一个标准化的方式来展示、出售和管理 NFT 等数字资产，同时支持创作者自定义转移策略（Transfer Policy）。

module examples::kiosk_demo;

use sui::kiosk;
use sui::transfer_policy;

/// Kiosk 核心概念:
///
/// 1. Kiosk（展柜）:
///    - 类似一个个人商店
///    - 所有者可以在其中放置和展示 NFT
///    - 支持上架出售和下架操作
///
/// 2. Transfer Policy（转移策略）:
///    - 创作者定义 NFT 转移时的规则
///    - 可以强制收取版税
///    - 可以限制转移目标
///
/// 3. Purchase Cap（购买凭证）:
///    - 买家获得购买凭证后才能完成交易
///    - 确保所有转移都遵循转移策略

/// 一个简单的 NFT
public struct ArtNFT has key, store {
    id: UID,
    name: vector<u8>,
    artist: address,
}

/// 铸造 NFT 并放入 Kiosk
public fun mint_to_kiosk(
    kiosk: &mut kiosk::Kiosk,
    cap: &kiosk::KioskOwnerCap,
    name: vector<u8>,
    ctx: &mut TxContext,
) {
    let nft = ArtNFT {
        id: object::new(ctx),
        name,
        artist: ctx.sender(),
    };
    kiosk.place(cap, nft);
}

Kiosk 的设计优势：

• 创作者保护：强制执行版税，创作者在每次转售中获得收益
• 标准化交易：统一的交易接口，方便市场聚合
• 灵活策略：支持自定义规则，如白名单、冻结期等

链上游戏

Sui 的对象模型和高性能使其成为链上游戏的理想平台：

• 游戏资产即对象：武器、装备、角色等都是 Sui 对象，玩家真正拥有它们
• 低延迟：快速路径确保游戏内交易的即时确认
• 可组合性：不同游戏之间的资产可以互操作
• 动态 NFT：利用动态字段，NFT 的属性可以随游戏进程演变

生态全景图

┌─────────────────────────────────────────────────────────────┐
│                    Sui 生态全景                               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─── 基础设施 ───────────────────────────────────────────┐ │
│  │  Walrus (存储)  │  Sui Bridge (跨链)  │  SuiNS (域名)  │ │
│  │  Move Registry  │  Mysten Labs 索引器  │  GraphQL API   │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
│  ┌─── DeFi ──────────────────────────────────────────────┐ │
│  │  DeepBook (CLOB) │  Cetus (AMM)  │  Scallop (借贷)    │ │
│  │  NAVI (借贷)     │  Aftermath    │  Turbos (AMM)      │ │
│  │  Bucket (稳定币) │  Suilend      │  Typus (结构化)    │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
│  ┌─── 身份与认证 ────────────────────────────────────────┐ │
│  │  zkLogin (零知识登录)   │  Multisig (多签)             │ │
│  │  Enoki (开发者身份工具) │  zkSend (隐私转账)           │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
│  ┌─── NFT / 游戏 ───────────────────────────────────────┐ │
│  │  Kiosk (市场框架)    │  SuiFrens (官方 NFT)           │ │
│  │  Clutchy (游戏平台)  │  BlueMove (NFT 市场)           │ │
│  │  Mysticeti (游戏)   │  各种 PFP / 艺术 NFT 系列       │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
│  ┌─── 开发工具 ──────────────────────────────────────────┐ │
│  │  Sui CLI        │  Move Analyzer (LSP)                │ │
│  │  Sui TypeScript SDK   │  dApp Kit (React)             │ │
│  │  Sui Rust SDK   │  Move Formatter / Linter            │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
│  ┌─── 前沿技术 ──────────────────────────────────────────┐ │
│  │  Nautilus (TEE 可信计算)   │  Seal (密钥管理)          │ │
│  │  链上随机数 (drand)       │  Sponsored Transactions    │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

开发者工具链

Sui 为开发者提供了完善的工具链：

Sui CLI

命令行工具，支持项目创建、编译、测试、部署和链上交互：

# 创建新项目
sui move new my_project

# 编译
sui move build

# 运行测试
sui move test

# 发布到测试网
sui client publish

TypeScript SDK 与 dApp Kit

Sui 提供了功能完备的 TypeScript SDK 和 React dApp Kit，让前端开发者能快速构建 DApp：

// TypeScript SDK 使用示例
import { SuiGrpcClient } from '@mysten/sui/grpc';
import { Transaction } from '@mysten/sui/transactions';

const client = new SuiGrpcClient({
  network: 'mainnet',
  baseUrl: 'https://fullnode.mainnet.sui.io:443',
});

// 构建可编程交易块
const tx = new Transaction();
tx.moveCall({
    target: '0x...::module::function',
    arguments: [tx.pure.u64(100)],
});

Move Analyzer

Move 语言的 LSP（Language Server Protocol）实现，为 VS Code 等编辑器提供代码补全、类型检查、跳转定义等功能。

小结

Sui 生态正在快速发展，涵盖了从基础设施到上层应用的完整技术栈。Walrus 解决了去中心化存储问题，DeepBook 提供了专业级的链上交易体验，zkLogin 消除了 Web3 的用户门槛，Kiosk 为数字资产交易建立了标准框架。丰富的开发者工具链让构建 Sui 应用变得高效而愉快。随着更多创新项目的涌现，Sui 生态的边界还将持续扩展。在下一节中，我们将追溯 Move 语言的起源与演进，理解它是如何从 Facebook 的实验性项目成长为 Sui 的核心编程语言的。

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 之旅。

Suiup — Sui 生态工具链管理器

Suiup 是 Mysten Labs 官方推出的 Sui 生态 CLI 安装与版本管理工具，类似于 Rust 生态中的 rustup。通过 suiup，你可以一键安装、升级和切换 Sui CLI 及其他生态工具，无需手动下载二进制文件或从源码编译。

为什么使用 Suiup

在没有 suiup 之前，安装 Sui CLI 通常需要：

• 安装 Rust 工具链
• 从源码编译 sui（耗时较长）
• 手动管理不同网络版本的切换

suiup 解决了这些痛点：

安装 Suiup

macOS / Linux（推荐方式）

打开终端，运行以下命令：

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

安装脚本会自动：

1. 检测操作系统（macOS / Linux）和 CPU 架构（x86_64 / ARM64）
2. 下载对应的 suiup 二进制文件
3. 安装到 ~/.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

通过 Cargo 安装

如果你已经安装了 Rust 工具链，也可以通过 Cargo 安装：

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

Windows

1. 从 GitHub Releases 下载最新的 suiup-Windows-msvc-x86_64.zip
2. 解压后将 suiup.exe 放到 PATH 目录中

支持的平台

安装 Sui CLI

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

安装 Debug 版本

如果你需要使用 sui move test --coverage（测试覆盖率），需要安装 debug 版本：

suiup install sui --debug

从源码编译安装（Nightly）

如果你需要最新开发分支的功能（需要 Rust 工具链）：

# 默认从 main 分支编译
suiup install sui --nightly

# 指定分支
suiup install sui --nightly releases/sui-v1.45.0-release

可安装的工具

suiup 不仅管理 Sui CLI，还支持整个 Sui 生态的工具链：

suiup list

推荐的开发环境安装

对于 Move 开发者，建议至少安装以下工具：

suiup install sui@testnet
suiup install move-analyzer
suiup install mvr

版本管理与切换

suiup 的核心优势在于可以同时管理多个版本。

查看已安装的版本

suiup show

输出示例：

sui:
  testnet-1.44.2 (default)
  devnet-1.45.0
  mainnet-1.43.1
move-analyzer:
  mainnet-2024.1.1 (default)
mvr:
  0.0.8 (default)

切换默认版本

当你同时安装了多个版本，可以随时切换：

# 切换 sui 到 devnet 版本
suiup default set sui@devnet

# 切换到特定版本
suiup default set sui@testnet-1.40.0

# 切换 debug 版本为默认
suiup default set sui@testnet-1.44.2 --debug

也可以使用 switch 命令快速切换：

suiup switch sui@testnet
suiup switch sui@devnet
suiup switch sui@mainnet

查看当前默认版本

suiup default get

查看工具的安装路径

suiup which

升级工具

升级已安装的工具

# 升级 sui 到对应网络的最新版本
suiup update sui

# 升级特定网络的 sui
suiup update sui@testnet
suiup update sui@devnet

# 跳过确认
suiup update sui -y

# 升级其他工具
suiup update walrus
suiup update mvr

升级 Suiup 自身

suiup self update

环境诊断

如果遇到问题，使用 doctor 命令进行环境检查：

suiup doctor

该命令会检查：

• PATH 配置是否正确
• 已安装的二进制文件是否完整
• GitHub API 是否可访问
• 配置文件是否正常

缓存清理

suiup 会缓存下载的安装包，可以定期清理：

# 清理 30 天前的缓存（默认）
suiup cleanup

# 清理 7 天前的缓存
suiup cleanup --days 7

# 清理所有缓存
suiup cleanup --all

# 预览会清理什么（不实际删除）
suiup cleanup --dry-run

卸载

卸载已安装的工具

suiup remove sui
suiup remove walrus

注意： remove 命令目前可能不太稳定，建议手动删除对应的二进制文件。

卸载 Suiup 自身

suiup self uninstall

CI / CD 集成

在 CI 环境中使用 suiup，推荐设置 GitHub Token 以避免 API 速率限制：

GITHUB_TOKEN=your_token suiup install sui -y

GitHub Actions 示例：

name: Build and Test
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install Sui
        run: suiup install sui@testnet -y
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and Test
        run: |
          sui move build
          sui move test

环境变量

常用命令速查

# 安装
suiup install sui@testnet          # 安装 Sui（testnet）
suiup install sui@devnet           # 安装 Sui（devnet）
suiup install move-analyzer        # 安装 Move 语言分析器

# 查看
suiup show                         # 查看所有已安装的工具和版本
suiup list                         # 查看所有可安装的工具
suiup which                        # 查看默认二进制路径
suiup default get                  # 查看当前默认版本

# 版本切换
suiup switch sui@testnet           # 切换到 testnet 版本
suiup default set sui@devnet       # 设置 devnet 为默认

# 升级
suiup update sui                   # 升级 Sui
suiup self update                  # 升级 suiup 自身

# 维护
suiup doctor                       # 环境诊断
suiup cleanup                      # 清理缓存

小结

suiup 是 Sui 开发者的必备工具，它让工具链管理变得简单高效：

• 安装简单：一行命令安装 suiup，再一行命令安装 sui
• 版本管理：轻松在 testnet / devnet / mainnet 之间切换
• 生态覆盖：统一管理 sui、walrus、mvr、move-analyzer 等所有生态工具
• 持续更新：一条命令完成升级，始终保持最新版本

建议所有 Sui 开发者使用 suiup 作为工具链管理的标准方式，取代手动安装和源码编译。

第二章 · 开发环境搭建

本章将指导你从零搭建完整的 Sui Move 开发环境，包括 CLI 工具、IDE 配置、钱包创建和网络连接。

本章内容

学习目标

读完本章后，你将能够：

• 在本地运行 sui 命令并查看版本
• 在 VS Code 中获得 Move 代码的语法高亮和错误提示
• 拥有一个 devnet/testnet 钱包并持有测试 SUI

安装 Sui CLI

Sui CLI 是开发 Move 智能合约和与 Sui 网络交互的核心工具。它集成了项目创建、编译、测试、部署和链上交互等全套功能，是每位 Sui 开发者的必备工具。本节将介绍多种安装方式，并帮助你完成环境验证。

安装方式

使用 suiup 安装（推荐）

suiup 是 Sui 官方提供的版本管理工具，类似于 Rust 的 rustup。它可以方便地安装、切换和管理不同版本的 Sui CLI。

# 安装 suiup
curl -fsSL https://sui.io/suiup.sh | bash

# 使用 suiup 安装最新稳定版 Sui CLI
suiup install sui

安装完成后，sui 命令将自动添加到你的 PATH 中。如果终端提示找不到命令，请重新打开终端或执行 source ~/.bashrc（或 source ~/.zshrc）。

使用 Homebrew 安装（macOS）

macOS 用户可以通过 Homebrew 快速安装：

brew install sui

使用 Chocolatey 安装（Windows）

Windows 用户可以通过 Chocolatey 包管理器安装：

choco install sui

下载预编译二进制文件

你也可以直接从 GitHub Releases 页面下载对应平台的预编译二进制文件：

1. 访问 Sui Releases
2. 选择目标版本，下载对应操作系统的压缩包
3. 解压后将 sui 二进制文件移动到系统 PATH 目录下

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

从源码编译安装

如果你需要最新的开发版本，或者想要自定义编译选项，可以通过 Cargo 从源码编译：

# 前提：已安装 Rust 工具链
# 安装 mainnet 分支版本
cargo install --git https://github.com/MystenLabs/sui.git sui --branch mainnet

# 安装 testnet 分支版本
cargo install --git https://github.com/MystenLabs/sui.git sui --branch testnet

注意：从源码编译需要较长时间（通常 10-30 分钟），且需要足够的磁盘空间和内存。建议至少预留 2GB 内存和 10GB 磁盘空间。

验证安装

安装完成后，运行以下命令验证：

sui client --version

你应该看到类似如下的输出：

sui 1.45.2-abc1234

你还可以查看所有可用命令：

sui --help

使用 suiup 管理版本

在实际开发中，你可能需要在不同网络环境之间切换。例如，testnet 和 mainnet 可能运行着不同版本的 Sui 协议。suiup 可以帮助你轻松管理多个版本。

# 查看当前安装的版本
suiup show

# 安装特定网络对应的版本
suiup install sui --network testnet
suiup install sui --network mainnet

# 切换到 testnet 版本
suiup use --network testnet

# 切换到 mainnet 版本
suiup use --network mainnet

最佳实践：在部署合约到特定网络前，确保你使用的 Sui CLI 版本与目标网络的协议版本兼容。使用 suiup 切换到对应版本可以避免兼容性问题。

常见问题排查

命令找不到

如果安装后终端提示 command not found: sui：

# 检查安装路径
which sui

# 如果使用 suiup，确保 PATH 包含 ~/.sui/bin
echo $PATH | tr ':' '\n' | grep sui

# 手动添加到 PATH（添加到 ~/.zshrc 或 ~/.bashrc）
export PATH="$HOME/.sui/bin:$PATH"
source ~/.zshrc

依赖缺失（源码编译）

从源码编译时可能遇到依赖问题：

# macOS：安装 Xcode 命令行工具
xcode-select --install

# Ubuntu/Debian：安装必要依赖
sudo apt-get update
sudo apt-get install -y build-essential libssl-dev pkg-config cmake clang

版本不匹配

如果遇到与网络版本不兼容的错误：

# 查看当前版本
sui client --version

# 检查网络协议版本
sui client envs

# 使用 suiup 切换到匹配版本
suiup install sui --network <target-network>
suiup use --network <target-network>

权限问题

在 Linux/macOS 上可能遇到权限问题：

# 确保二进制文件有执行权限
chmod +x /usr/local/bin/sui

# 如果安装到系统目录需要 sudo
sudo mv sui /usr/local/bin/

小结

本节介绍了五种安装 Sui CLI 的方式：suiup（推荐）、Homebrew、Chocolatey、预编译二进制和源码编译。推荐使用 suiup，因为它不仅安装简便，还提供了版本管理功能，方便你在不同网络环境间切换。安装完成后，请务必通过 sui client --version 验证安装是否成功。下一节我们将配置 IDE 开发环境，为编写 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.lint": true
}

其他编辑器

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 语言服务器的核心组件。在安装 Sui CLI 后，它通常已包含在内。你可以验证：

# 检查 move-analyzer 是否可用
sui move analyzer --version

如果 VSCode 无法找到 Move Analyzer，可能需要手动指定路径。在 VSCode 设置中搜索 “move” 并设置 Move: Sui Path 为 sui 二进制文件的完整路径：

# 查找 sui 的安装位置
which 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）、代码格式化（通过 Move Formatter）和语法高亮（通过 Move Syntax）。配合集成终端和自动化任务，你将拥有一个流畅的 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 版本的新特性。

Move 2024 版本新特性

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] 下显式声明。如果省略，默认使用旧版本语法。

可变绑定：let mut

Move 2024 要求显式标注可变变量，使代码意图更清晰。

旧版本

let x = 5;
x = 10;  // 隐式可变，容易产生误解

新版本

let mut x = 5;
x = 10;  // 显式声明可变性

let y = 5;
// y = 10;  // 编译错误！未声明 mut

这一改变与 Rust 的 let 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 工具自动完成大部分转换。

第三章 · 第一个 Move 程序

本章将带你动手编写、编译、测试和部署第一个 Move 智能合约，完成从代码到链上的全流程。

本章内容

学习目标

读完本章后，你将能够：

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

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.beta"

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

[addresses]
hello_world = "0x0"

各字段含义：

[package]

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

[dependencies]

声明项目依赖。默认依赖 Sui Framework，它提供了核心类型和函数（如 UID、TxContext、transfer 等）。

[addresses]

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

编写模块

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

module hello_world::hello_world;

use std::string::String;

/// 返回 "Hello, World!" 字符串
public fun hello_world(): String {
    b"Hello, World!".to_string()
}

让我们逐行解析：

模块声明

module hello_world::hello_world;

• hello_world（第一个）：对应 Move.toml 中 [addresses] 下定义的地址别名
• hello_world（第二个）：模块名称
• 以分号结尾：这是 Move 2024 的文件级模块声明语法

导入

use std::string::String;

从标准库导入 String 类型。std 是 Sui 框架隐式包含的 Move 标准库。

函数定义

public fun hello_world(): String {
    b"Hello, World!".to_string()
}

• public：该函数可以被其他模块调用
• fun：函数声明关键字
• hello_world()：函数名和参数（此处无参数）
• : String：返回类型
• b"Hello, World!"：字节串字面量
• .to_string()：Move 2024 的内置方法，将字节串转换为 String

注意：Move 函数中最后一个表达式会自动作为返回值，无需 return 关键字。

编写测试

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

#[test_only]
module hello_world::hello_world_tests;

use hello_world::hello_world;

#[test]
fun hello_world() {
    assert_eq!(hello_world::hello_world(), b"Hello, World!".to_string());
}

测试模块属性

#[test_only]
module hello_world::hello_world_tests;

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

测试函数

#[test]
fun hello_world() {
    assert_eq!(hello_world::hello_world(), b"Hello, World!".to_string());
}

• #[test]：标记该函数为测试函数
• assert!：断言宏，条件为 false 时测试失败
• 测试函数不需要 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_hello_world
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

项目结构最佳实践

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

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 配置文件，编写模块和测试代码，最后通过 sui move build 构建和 sui move test 测试。虽然 “Hello, World!” 很简单，但它涵盖了 Move 开发的核心工作流。下一节我们将编写一个更有实际意义的合约，并将其部署到 Sui 网络上。

部署合约到 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 语言的核心概念。

第四章 · 核心概念

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

本章内容

学习目标

读完本章后，你将能够：

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

包（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 项目、Cargo.toml 之于 Rust 项目。

完整示例

先看一个典型的 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 语法基础

本章讲解 Move 的基础语法：模块与组织、类型与表达式、结构体与能力、控制流与函数，为后续进阶与 Sui 开发打下扎实基础。进阶与高级内容见第六章、第七章。

本章内容

学习目标

读完本章后，你将能够：

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

模块（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.beta"

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

[addresses]
book = "0x0"

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

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 关键字：在分组导入中代表模块本身
• 自动导入：vector、option、Option 无需手动导入
• 外部依赖：通过 Move.toml 配置，CLI v1.45+ 自动包含系统包

整数类型

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 类型的错误码作为参数：

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);
}

错误常量约定

命名规范

Move 社区约定使用 E 前缀加大驼峰命名法（EPascalCase）来定义错误常量，类型统一为 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(abort_code = ECustomNotFound)]
fun not_found() {
    find_item(0);
}

使用 #[error] 属性后，当交易失败时，Sui CLI 与 GraphQL 等工具会将 abort 码解码为可读信息（如 Error from '0x...::module::fun' (line N), abort 'EConstName': "message"）。不写错误码的 assert!(cond) 或 abort 也会自动从源码行号派生一个“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 仅供交易直接调用。结构体的字段始终是私有的，需要通过公共函数暴露读写接口。合理运用可见性修饰符是良好模块设计的基础——暴露最小必要的接口，隐藏内部实现细节。

第六章 · Move 语法进阶

本章在语法基础之上，介绍标准库与常用集合类型、枚举与模式匹配、方法语法、宏函数，以及所有权与引用，帮助你写出结构清晰、可维护的 Move 模块。

本章内容

学习目标

读完本章后，你将能够：

• 熟练使用标准库中的 Vector、Option、String 等类型
• 用枚举与模式匹配表达多分支逻辑与错误处理
• 用结构体方法和宏函数组织与复用代码
• 理解所有权与引用，写出正确且高效的 Move 代码

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> 表示一个可能存在也可能不存在的值，借鉴自 Rust 语言的设计理念。它是处理缺失值的安全方式——与使用哨兵值（如 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 function）在编译时在调用处展开，参数按表达式替换而非先求值再传参，并可接收 lambda 形式的代码块。Move 的宏仍然有类型约束，因此可以像普通函数一样使用，也支持方法语法和 use fun。

语法

宏用 macro fun 定义；类型参数和值参数名必须以 $ 开头，以区别于普通函数：

module book::macro_basic;

macro fun add_three($x: u64, $y: u64, $z: u64): u64 {
    $x + $y + $z
}

#[test]
fun use_macro() {
    let sum = add_three!(1, 2, 3);
    assert_eq!(sum, 6);
}

• 以 $ 开头的参数在编译期按表达式替换（不是先求值再代入）。
• 调用宏时使用 macro_name!(...)，与普通函数调用的括号形式区分。
• 若宏需要接收“一段代码”，可使用 lambda 类型参数（见下文）。

Lambda

Lambda 只能作为宏的参数出现，用于把“一段代码”传给宏。类型写法为 |T1, T2, ...| -> R，无返回类型时默认为 ()：

|u64, u64| -> u128        // 两个 u64，返回 u128
|&mut vector<u8>|         // 一个参数，返回 ()

定义 lambda 时：

|x| 2 * x
|x: u64| -> u64 { x + 1 }
|a, b| a + b

Lambda 可以捕获外层变量（在 lambda 内使用当前作用域中的变量）。

标准库中的向量宏

Move 标准库为 vector 提供了一批宏，替代手写 while 循环，使代码更简洁：

示例：

module book::vector_macros;

#[test]
fun do_and_fold() {
    let v = vector[1u64, 2, 3, 4, 5];
    let mut sum = 0u64;
    v.do_ref!(|e| sum = sum + *e);
    assert_eq!(sum, 15);

    let folded = v.fold!(0u64, |acc, e| acc + e);
    assert_eq!(folded, 15);
}

#[test]
fun tabulate() {
    let indices = vector::tabulate!(5, |i| i);
    assert_eq!(indices, vector[0u64, 1, 2, 3, 4]);
}

Option 宏

option::do!(opt, |value| ...) 在为 some 时执行 lambda；opt.destroy_or!(default) 或 opt.destroy_or!(abort E) 用于取出值或提供默认/中止。

小结

• 宏用 macro fun 定义，类型与值参数以 $ 开头，调用形式为 name!(...)。
• Lambda 类型为 |T1, T2| -> R，只能作为宏参数，可捕获外层变量。
• 标准库提供 vector 的 do!、fold!、tabulate!、destroy! 等宏，以及 option 的 do!、destroy_or!，推荐优先使用宏替代手写循环。

所有权与作用域

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 与 Rust 的差异

在 Move 中，引用可以被多次复制，同一时刻存在多个对同一值的引用（包括多个 &mut）在类型上是被允许的；只有在通过可变引用写入时，才要求该可变引用是“唯一可写”的。这与 Rust 的“同一时刻只能有一个 &mut”的规则不同，但写入前的唯一性保证同样严格。

引用不可存储

引用和元组是仅有的不能作为结构体字段类型存储的类型，因此引用不能进入全局存储或 Sui 对象，只能在一次执行过程中临时存在，程序结束时全部销毁。这是 Move 与允许在结构体中存引用的 Rust 的又一区别。

借用规则

基本规则

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 语法高级

本章介绍泛型与类型反射，涉及类型参数、能力约束以及运行时类型信息，是编写可复用、类型安全的 Move 库与框架的必备内容。

本章内容

学习目标

读完本章后，你将能够：

• 编写泛型函数与泛型结构体，并正确施加能力约束
• 理解 phantom 类型参数的作用与用法
• 在需要时使用类型反射获取运行时类型信息
• 使用编译模式控制调试/测试等不可发布代码的编入与发布安全
• 为自定义类型定义下标语法（#[syntax(index)]）并遵守只读/可写成对规则

泛型基础

泛型（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）不占用存储空间，仅用于类型层面的区分，常用于实现类型安全的抽象（如不同货币）。

能力约束

对类型参数添加能力约束，要求传入的类型必须满足相应能力：

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
}

常见约束组合：

幻影类型参数

当类型参数未在结构体字段中使用、仅用于类型区分时，需用 phantom 标记：

module book::generics_phantom;

public struct USD {}
public struct EUR {}

public struct Balance<phantom Currency> has store, drop {
    amount: u64,
}

public fun new_balance<Currency>(amount: u64): Balance<Currency> {
    Balance { amount }
}

public fun merge<Currency>(b1: &mut Balance<Currency>, b2: Balance<Currency>) {
    let Balance { amount } = b2;
    b1.amount = b1.amount + amount;
}

这样只能合并相同“货币”类型的余额，在编译期防止类型混用。

泛型与对象

在 Sui 中，泛型常与对象结合，实现通用对象容器（如 Container<T: store> has key, store），并通过 store 等能力约束保证类型可安全存储。

小结

• 能力约束：T: copy + drop、T: store 等，确保类型参数满足所需能力
• phantom：不占存储，仅用于类型区分；零运行时开销、编译期类型安全
• 泛型对象：结合 key/store 实现可存储的泛型对象

类型反射

Move 提供有限的运行时类型反射能力，主要通过 std::type_name 模块实现。类型反射允许在运行时获取类型的名称、模块信息和包地址等元数据，常用于在集合中存储类型信息、实现类型分发逻辑或调试。虽然反射能力有限，但在很多场景下已经足够实用。

type_name 模块

获取类型名称

type_name::get<T>() 函数返回一个 TypeName 结构体，包含类型 T 的元数据信息：

module book::reflection_basic;

use std::type_name;

public struct MyType has drop {}

#[test]
fun get_type_name() {
    let my_type_name = type_name::get<MyType>();
    let u64_type_name = type_name::get<u64>();
    let bool_type_name = type_name::get<bool>();

    // 不同类型的 TypeName 不相等
    assert!(u64_type_name != bool_type_name);

    let _ = my_type_name;
}

类型名称字符串

通过 into_string() 方法可以将 TypeName 转换为 ASCII 字符串，获取完整的类型名称：

module book::reflection_string;

use std::type_name;
use std::ascii::String;

public struct Token has drop {}

#[test]
fun type_string() {
    let type_name = type_name::get<Token>();
    let name_str: String = type_name.into_string();

    // name_str 包含完整的类型路径，如 "0x...::reflection_string::Token"
    let _ = name_str;
}

TypeName 方法

提取模块和地址信息

TypeName 提供了多个方法来提取类型的各部分信息：

module book::reflection_example;

use std::type_name;
use std::ascii::String;

public struct MyType has drop {}

#[test]
fun type_reflection() {
    let type_name = type_name::get<MyType>();

    // 获取完整的类型名称字符串
    let name_str: String = type_name.into_string();

    // 获取模块名称
    let module_name = type_name.get_module();

    // 获取包地址
    let address = type_name.get_address();

    // 类型比较
    let u64_name = type_name::get<u64>();
    let bool_name = type_name::get<bool>();
    assert!(u64_name != bool_name);

    let _ = name_str;
    let _ = module_name;
    let _ = address;
}

原始类型的判断

is_primitive() 方法可以判断一个类型是否为原始类型（如 u8、u64、bool、address 等）：

module book::reflection_primitive;

use std::type_name;

public struct CustomType has drop {}

#[test]
fun is_primitive() {
    let u64_name = type_name::get<u64>();
    let bool_name = type_name::get<bool>();
    let custom_name = type_name::get<CustomType>();

    assert!(u64_name.is_primitive());
    assert!(bool_name.is_primitive());
    assert!(!custom_name.is_primitive());
}

Defining ID 与 Original ID

两种包标识

Move 在类型反射中区分两种包标识：

• Original ID（原始 ID）：类型首次发布时所在的包地址
• Defining ID（定义 ID）：引入该类型的包地址（在包升级后可能不同）

当包没有被升级时，两者相同。当包经过升级后，新版本的包地址与原始包地址不同，这时两个 ID 的区别就显现出来了：

module book::reflection_ids;

use std::type_name;

public struct VersionedType has drop {}

#[test]
fun type_ids() {
    // get 方法使用 defining ID
    let with_defining = type_name::get<VersionedType>();

    // get_with_original_ids 使用 original ID
    let with_original = type_name::get_with_original_ids<VersionedType>();

    // 未升级时两者相同
    let _ = with_defining;
    let _ = with_original;
}

实际应用场景

在集合中存储类型信息

类型反射常用于在动态字段或表中以类型作为键：

module book::reflection_usage;

use std::type_name::{Self, TypeName};
use std::ascii::String;

public struct TypeRegistry has drop {
    registered: vector<TypeName>,
}

public fun new_registry(): TypeRegistry {
    TypeRegistry { registered: vector[] }
}

public fun register<T>(registry: &mut TypeRegistry) {
    let type_name = type_name::get<T>();
    registry.registered.push_back(type_name);
}

public fun is_registered<T>(registry: &TypeRegistry): bool {
    let type_name = type_name::get<T>();
    let mut i = 0;
    while (i < registry.registered.length()) {
        if (registry.registered[i] == type_name) {
            return true
        };
        i = i + 1;
    };
    false
}

public struct TokenA has drop {}
public struct TokenB has drop {}
public struct TokenC has drop {}

#[test]
fun registry() {
    let mut registry = new_registry();

    register<TokenA>(&mut registry);
    register<TokenB>(&mut registry);

    assert!(is_registered<TokenA>(&registry));
    assert!(is_registered<TokenB>(&registry));
    assert!(!is_registered<TokenC>(&registry));
}

类型信息调试

在开发和测试阶段，类型反射可以帮助调试泛型代码：

module book::reflection_debug;

use std::type_name;
use std::ascii::String;

public fun type_info<T>(): String {
    let type_name = type_name::get<T>();
    type_name.into_string()
}

#[test]
fun debug_info() {
    let u64_info = type_info<u64>();
    let bool_info = type_info<bool>();

    // 可以在测试中打印或断言类型信息
    assert!(u64_info != bool_info);
}

小结

Move 通过 std::type_name 模块提供有限但实用的运行时类型反射能力。type_name::get<T>() 返回 TypeName 结构体，可以获取类型的完整名称、模块名、包地址等元数据。is_primitive() 用于判断是否为原始类型。Move 还区分 Defining ID 和 Original ID 来处理包升级后的类型标识问题。类型反射在动态集合的类型键、类型注册表和调试等场景中非常有用。

编译模式（Modes）

编译模式（Modes）允许你只在显式启用某个命名构建模式时，才把不可发布的代码编入包中。可以把它理解为 #[test_only] 的泛化：除了内置的 test 模式外，你还可以定义 debug、benchmark、spec 等任意模式，用于调试、压测或规范代码。

要点一览

• 使用 #[mode(name, ...)] 标注模块或成员；#[test_only] 是 #[mode(test)] 的简写。
• 使用 --mode <name>（或 --test 跑单测）构建时，只有标注了该模式的项会被编入；未匹配的项会被排除。
• 只要启用了任意模式（包括 --test），生成的产物都不可发布，从而保证调试/测试代码不会上链。
• 未标注 #[mode(...)] / #[test_only] 的项始终会被编入。

提示：模式是编译期过滤，不影响运行时字节码。适合用于调试辅助、模拟器和不应发布的 mock 类型与函数。

语法

与 #[test_only] 一样，可以把模式属性挂在模块或单个成员上：

// 整个模块仅在启用对应模式时编入
#[mode(debug)]
module my_pkg::debug_tools {
    public fun dump_state() { /* ... */ }
}

module my_pkg::library {
    // 仅在 debug 或 test 构建中存在
    #[mode(debug, test)]
    public fun assert_invariants() { /* ... */ }

    // 仅测试；等价于 #[mode(test)]
    #[test_only]
    fun mk_fake() { /* ... */ }
}

一个属性中可以写多个模式：#[mode(name1, name2, ...)]。只要任一列出的模式被启用，该项就会被编入。没有模式标注的项始终编入。

#[mode(test)] 与 #[test_only] 等价。

如何按模式构建

用 Sui CLI 在构建或测试时启用模式：

# 启用自定义模式构建
sui move build --mode debug

# 跑单测（自动包含 #[test_only]）
sui move test --test

# 同时启用 test 与 debug（例如带调试输出的测试）
sui move test --test --mode debug

启用某模式时，标注了该模式的项会被编入；只标注了其他模式的项会被排除；未标注的项始终编入。

发布前：只要用过 --mode 或 --test 构建，产物都不可发布。发布前请用不带 --mode/--test 的干净构建：sui move build。

test 模式（单元测试）

#[test_only] 即内置的 test 模式，行为与 #[mode(test)] 一致。使用 sui move test --test 时，会自动启用 test 模式，从而编入所有 #[test_only] 的模块和函数。详见第十二章「测试」。

自定义模式示例：debug

例如你希望只在开发/调试时编入带日志的包装函数，而不影响正式构建：

#[mode(debug)]
module my_pkg::bank_debug {
    use std::debug;
    use my_pkg::bank;

    public fun transfer_with_logs(from: &signer, to: address, amount: u64) {
        debug::print(&b"[DEBUG] transfer".to_vector());
        bank::transfer(from, to, amount);
    }
}

构建时若不加 --mode debug，bank_debug 不会被编入；用 sui move build --mode debug 或 sui move test --test --mode debug 时才会包含。

小结

• 编译模式：#[mode(name, ...)] 控制项在何种构建下被编入；#[test_only] ≡ #[mode(test)]。
• 构建：sui move build --mode <name>、sui move test --test（自动启用 test）。
• 发布：启用任意模式后的产物不可发布；发布前必须执行不带 --mode/--test 的 sui move build。

下标语法（Index Syntax）

Move 通过 语法属性 允许你为自定义类型定义像内置语法一样的操作，在编译期将写法“降级”为你提供的函数调用。下标语法（#[syntax(index)]）让你可以为类型定义类似 v[i]、m[i,j] 的索引访问，使 API 更直观、可链式使用。

概述

标准库中的 vector 通过 #[syntax(index)] 标记了 borrow 与 borrow_mut，因此支持 v[i]、&v[i]、&mut v[i]。你可以在定义该类型的同一模块内为自定义类型声明只读和可写的“下标”函数，满足一定规则后，该类型的值就可以使用 obj[index_expr] 形式的读写。

示例：矩阵类型

下面为矩阵类型定义下标访问，支持 m[i, j] 和 &mut m[i, j]：

module matrix::matrix;

public struct Matrix<T> has drop {
    v: vector<vector<T>>,
}

#[syntax(index)]
public fun borrow<T>(s: &Matrix<T>, i: u64, j: u64): &T {
    vector::borrow(vector::borrow(&s.v, i), j)
}

#[syntax(index)]
public fun borrow_mut<T>(s: &mut Matrix<T>, i: u64, j: u64): &mut T {
    vector::borrow_mut(vector::borrow_mut(&mut s.v, i), j)
}

public fun make_matrix<T>(v: vector<vector<T>>): Matrix<T> {
    Matrix { v }
}

使用方式：

let mut m = matrix::make_matrix(vector[
    vector[1, 0, 0],
    vector[0, 1, 0],
    vector[0, 0, 1],
]);
assert!(m[0, 0] == 1);
*(&mut m[1, 1]) = 2;

编译期如何翻译

编译器根据“只读 / 可变”和“是否再取引用”将下标表达式翻译为对应的函数调用：

下标可与字段访问混合：&input.vs[0].v[0] 会按嵌套的 borrow 链正确解析。

定义规则

1. 属性与模块：带有 #[syntax(index)] 的函数必须与“被索引的类型”在同一模块中定义。
2. 可见性：下标函数必须是 public，以便在使用该类型的任意位置都能解析到。
3. 第一个参数（接收者）：第一个参数必须是引用（&T 或 &mut T），且类型 T 必须是本模块定义的类型（不能是元组、类型参数或按值）。
4. 返回值：只读版本返回 &Element，可写版本返回 &mut Element；可变性与第一个参数一致。
5. 成对：每个类型最多一个“只读下标”和一个“可写下标”；只读与可写版本在类型参数个数、约束、其余参数类型上必须一致（仅可变性不同）。

不可作为下标接收者的类型

• 元组：(A, B) 不能作为第一个参数类型。
• 类型参数：T 不能作为接收者类型。
• 按值：第一个参数不能是值（必须是 & / &mut）。

只读与可写版本的类型兼容

两个版本必须：

• 类型参数个数、约束、使用方式一致；
• 除可变性外，第一个参数类型和返回类型一致；
• 除接收者外的所有参数类型完全一致。

这样无论当前表达式是只读还是可写，下标语义都一致。

小结

• 使用 #[syntax(index)] 在同一模块内为类型定义 borrow（只读）和 borrow_mut（可写），即可对该类型的值使用 obj[index_expr] 和 &mut obj[index_expr]。
• 编译器将下标按“是否可变、是否再取引用”翻译为对应函数调用。
• 自定义下标可带多个索引参数（如 m[i, j]），也可用于实现“带默认值的索引”等更复杂语义；具体规则见 Move Reference - Index Syntax。

第八章 · 对象模型

本章深入讲解 Sui 独创的对象模型，这是 Sui 区别于其他区块链的核心设计，也是理解 Sui Move 编程的关键。

本章内容

学习目标

读完本章后，你将能够：

• 解释 Sui 对象模型与 EVM 账户模型的区别
• 根据场景选择合适的所有权类型
• 理解快速路径对性能的影响

数字资产的语言

Move 语言从设计之初就将数字资产作为一等公民（first-class citizen）来对待。与传统的智能合约语言不同，Move 通过其类型系统在语言层面保障资产的安全性，让开发者可以像操作普通数据类型一样自然地表达数字资产的创建、转移和销毁。本章将探讨 Move 为何是表达数字资产的理想语言，以及它如何从根本上解决了区块链资产管理中的常见问题。

传统区块链语言的资产表达困境

在理解 Move 的优势之前，我们需要先了解传统方案的不足。

ERC-20 与 ERC-721 的本质问题

以太坊的 ERC-20（同质化代币）和 ERC-721（非同质化代币）标准本质上只是记账模型——它们使用 mapping(address => uint256) 这样的映射表来记录谁拥有多少代币。这带来了几个根本性问题：

• 资产不是独立实体：代币余额只是合约内部状态中的一个数字，它没有独立的身份和生命周期。
• 安全性依赖开发者自律：重入攻击、整数溢出、授权漏洞等问题反复出现，因为语言本身不提供资产安全的保障。
• 标准碎片化：ERC-20、ERC-721、ERC-1155……每种资产类型需要独立的标准和实现，增加了复杂性。

Move 的解决方案

Move 采用了完全不同的思路：资产即类型。一个数字资产就是一个 Move 结构体（struct），其安全属性由类型系统在编译期强制保证。不需要任何外部标准或约定，语言本身就知道如何正确处理资产。

数字资产的三大本质属性

任何真正的数字资产都应具备三个关键属性。Move 通过其独特的能力（ability）系统来强制保障这些属性。

所有权（Ownership）

每个数字资产必须有明确的所有者。在 Move on Sui 中，每个对象都有一个确定的所有者——可以是一个地址、另一个对象，或者被共享/冻结。

所有权不是通过查询合约内部映射表来确定的，而是由运行时直接追踪的。这意味着：

• 只有所有者可以在交易中使用该对象
• 所有权的转移是原子性的
• 无需担心授权和代理的复杂逻辑

不可复制（Non-copyable）

现实世界中，你不能复制一幅画或一枚金币。数字资产也应如此。Move 中，除非显式声明 copy 能力，结构体默认是不可复制的。这意味着：

• 数字资产不会被意外或恶意地“复制“
• 资产的总量始终是可控的
• “双重支付“在类型系统层面就被杜绝了

不可丢弃（Non-discardable）

你不能让一枚有价值的代币凭空消失。在 Move 中，除非显式声明 drop 能力，结构体在作用域结束时必须被显式处理——要么转移给他人，要么通过解构（destructure）来销毁。编译器会强制检查这一点：

• 忘记处理资产会导致编译错误
• 资产不会因为编程疏忽而丢失
• 每个资产的完整生命周期都是可追踪的

Move 的类型系统如何保障资源安全

Move 的线性类型系统（linear type system）是其安全保障的核心。它的四种能力（abilities）精确控制了类型的行为：

一个典型的数字资产只需要 key 能力（可能加上 store），而刻意不赋予 copy 和 drop。这样，Move 编译器就会自动保证该资产不能被复制或丢弃。

代码示例：一个简单的数字资产

下面的示例展示了如何在 Sui 上定义一个数字资产——一幅画作（Painting）。注意它只有 key 能力，没有 copy 和 drop：

module examples::digital_asset;

/// A simple digital asset - a Painting
public struct Painting has key {
    id: UID,
    artist: address,
    title: vector<u8>,
    year: u64,
}

/// Create a new painting - ownership is granted to the creator
public fun create(
    title: vector<u8>,
    year: u64,
    ctx: &mut TxContext,
): Painting {
    Painting {
        id: object::new(ctx),
        artist: ctx.sender(),
        title,
        year,
    }
}

/// Transfer a painting to a new owner
/// After this call, the original owner loses all control
public fun give_to(painting: Painting, recipient: address) {
    transfer::transfer(painting, recipient);
}

代码要点分析

1. has key：Painting 具有 key 能力，这使它成为一个 Sui 对象，可以被独立拥有和追踪。
2. id: UID：每个 Sui 对象的第一个字段必须是 id: UID，这是其全局唯一标识符。
3. 没有 copy：你无法复制一幅画，let copy = painting; 这样的代码会编译失败。
4. 没有 drop：你不能忽略一幅画，函数结束时如果 Painting 没有被转移或解构，编译器会报错。
5. give_to 接收值而非引用：painting: Painting 是按值传递的。调用此函数后，调用者完全失去对这幅画的控制权——这就是真正的所有权转移。

与传统方案的对比

让我们用一个表格来对比 Move 和传统 ERC 标准在资产管理上的差异：

更复杂的资产示例

在实际开发中，数字资产通常更复杂。以下示例展示了一个带有稀有度和属性的游戏道具：

module examples::game_item;

use std::string::String;

/// 稀有度枚举
public struct Rarity has store, copy, drop {
    level: u8, // 1=普通, 2=稀有, 3=史诗, 4=传说
}

/// 游戏道具 - 不可复制、不可丢弃的数字资产
public struct GameItem has key, store {
    id: UID,
    name: String,
    rarity: Rarity,
    power: u64,
    creator: address,
}

/// 铸造一个新的游戏道具
public fun mint(
    name: String,
    rarity_level: u8,
    power: u64,
    ctx: &mut TxContext,
): GameItem {
    assert!(rarity_level >= 1 && rarity_level <= 4, 0);
    GameItem {
        id: object::new(ctx),
        name,
        rarity: Rarity { level: rarity_level },
        power,
        creator: ctx.sender(),
    }
}

/// 销毁道具（回收），只有创建者可以销毁
public fun burn(item: GameItem, ctx: &TxContext) {
    assert!(item.creator == ctx.sender(), 1);
    let GameItem { id, name: _, rarity: _, power: _, creator: _ } = item;
    id.delete();
}

/// 读取道具的属性
public fun power(item: &GameItem): u64 {
    item.power
}

public fun rarity_level(item: &GameItem): u8 {
    item.rarity.level
}

在这个例子中：

• Rarity 是一个值类型（有 store、copy、drop），它不是对象，可以自由复制和丢弃。
• GameItem 是一个数字资产（有 key、store），它是不可复制、不可丢弃的对象。
• burn 函数是销毁资产的唯一途径——必须显式解构每个字段，并删除 UID。

这种设计确保了即使在复杂的游戏经济中，每个道具的生命周期都是完整可追踪的。

小结

Move 语言从本质上重新定义了区块链上数字资产的表达方式。通过将资产建模为具有线性类型约束的结构体，Move 在编译期就能保证三大核心属性：

• 所有权明确：每个资产都有唯一的所有者，所有权转移是原子性的。
• 不可复制：类型系统阻止了任何非法的资产复制。
• 不可丢弃：编译器确保每个资产都被正确处理，不会因编程失误而丢失。

这些保障不需要开发者额外编写任何安全检查代码——它们是语言内建的。这就是 Move 被称为“数字资产的语言“的原因。在接下来的章节中，我们将深入探讨 Sui 的对象模型，了解这些资产在链上是如何被组织和管理的。

什么是对象