search-aptos-examples

搜索 Aptos 示例技能

概述

此技能可帮助你在编写新合约前，在 Aptos 官方仓库中查找相关示例。务必先搜索示例，以遵循成熟的模式。

仓库：

• aptos-labs/aptos-core/aptos-move/move-examples/ — 53 个以上展示最佳实践的官方 Move 示例
• aptos-labs/daily-move/snippets/ — 17 个精选教学示例，涵盖设计模式、Move 2 特性、可组合 NFT 等

核心工作流

第 1 步：确定要构建的内容

为合约分类：

• NFT/代币：NFT 集合、数字资产、收藏品
• 同质化资产：代币、货币、通货
• DeFi：DEX、AMM、借贷、质押
• 治理：DAO、投票、提案
• 市场：交易、托管、拍卖
• 游戏：物品、角色、游戏逻辑
• 基础设施：注册表、配置、实用工具

第 2 步：搜索相关示例

按类别划分的优先示例：

NFT 和代币对象

1. token_objects/ - 现代对象式代币（V2 模式）
2. mint_nft/ - NFT 铸造模式
3. nft_dao/ - 由 NFT 访问权限控制的治理
4. collection_manager/ - 集合管理
5. （daily-move）composable-nfts/ - 包含其他 NFT 的 NFT
6. （daily-move）modifying-nfts/ - 可变 NFT 元数据模式
7. （daily-move）parallel-nfts/ - 并发铸造 NFT
8. （daily-move）liquid-nfts/ - 分割所有权/流动性 NFT

适用场景： 构建 NFT 集合、数字收藏品、代币化资产

同质化资产

1. fungible_asset/ - 现代同质化代币标准
2. coin/ - 基础代币实现
3. managed_fungible_asset/ - 受控同质化资产
4. （daily-move）fa-lockup-example/ - FA 锁仓和托管模式
5. （daily-move）fractional-token/ - 代币分割所有权
6. （daily-move）controlled-mint/ - 带访问控制的受控铸造

适用场景： 创建代币、货币、奖励积分

DeFi 和交易

1. marketplace/ - NFT 市场模式
2. swap/ - 简单代币交换
3. liquidity_pool/ - AMM 池实现
4. staking/ - 质押机制

适用场景： 构建 DEX、市场、交易平台

治理和 DAO

1. dao/ - DAO 治理模式
2. voting/ - 投票机制
3. multisig/ - 多重签名账户

适用场景： 构建 DAO、治理系统、投票系统

基础模式

1. hello_blockchain/ - 模块结构基础
2. message_board/ - 简单状态管理
3. resource_account/ - 资源模式（旧版，不建议用于新代码）
4. （daily-move）error-codes/ - 错误代码约定和模式
5. （daily-move）private-vs-public/ - 函数可见性和访问权限
6. （daily-move）objects/ - 对象模型基础知识

适用场景： 学习 Move 基础知识、编写简单合约

高级模式

1. object_playground/ - 探索对象模型
2. capability/ - 基于能力的安全机制
3. upgradeable/ - 可升级合约
4. （daily-move）design-patterns/ - 自主对象和其他设计模式
5. （daily-move）struct-capabilities/ - 基于结构体的能力模式
6. （daily-move）move-2/ - Move 2 语言特性和惯用法
7. （daily-move）storage/ - 存储布局和优化模式
8. （daily-move）data-structures/ - 堆数据结构实现

适用场景： 复杂架构、安全模式

游戏

1. （daily-move）lootbox/ - 随机战利品箱机制

适用场景： 构建游戏、随机奖励、战利品系统

步骤 3：查看示例代码

关注要点：

1. 模块结构：

   • 导入是如何组织的？
   • 定义了哪些结构体？
   • 错误代码是如何组织的？

2. 对象创建：

   • 如何创建对象？
   • 会生成哪些引用？
   • 如何管理所有权？

3. 访问控制：

   • 如何验证签名者权限？
   • 如何检查对象所有权？
   • 有哪些角色／权限？

4. 操作：

   • 如何处理转账？
   • 如何确保更新的安全？
   • 执行了哪些验证？

5. 测试：

   • 使用了哪些测试模式？
   • 如何实现覆盖？

步骤 4：根据你的用例调整模式

不要盲目照搬——应灵活调整：

1. 理解模式： 为什么要采用这种结构？
2. 找出核心概念： 哪些安全检查至关重要？
3. 根据需求调整： 针对你的具体需求进行修改
4. 确保安全： 保留所有安全检查
5. 充分测试： 确保达到 100% 覆盖率

示例查找表

构建内容	搜索内容	来源	关键文件
NFT 集合	token_objects, mint_nft	aptos-core	token_objects/sources/token.move
同质化代币	fungible_asset	aptos-core	fungible_asset/sources/fungible_asset.move
市场	marketplace	aptos-core	marketplace/sources/marketplace.move
DAO	dao, voting	aptos-core	dao/sources/dao.move
代币兑换	swap, liquidity_pool	aptos-core	swap/sources/swap.move
质押	staking	aptos-core	staking/sources/staking.move
简单合约	hello_blockchain, message_board	aptos-core	hello_blockchain/sources/hello.move
对象模式	object_playground	aptos-core	object_playground/sources/playground.move
可组合 NFT	composable-nfts	daily-move	snippets/composable-nfts/
FA 锁定／托管	fa-lockup-example	daily-move	snippets/fa-lockup-example/
设计模式	design-patterns	daily-move	snippets/design-patterns/
Move 2 功能	move-2	daily-move	snippets/move-2/
数据结构	data-structures	daily-move	snippets/data-structures/
存储模式	storage	daily-move	snippets/storage/
战利品箱模式	lootbox	daily-move	snippets/lootbox/

如何访问示例

选项 1：GitHub 网页界面

https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples

在线浏览并直接阅读源文件。

选项 2：克隆代码仓库（推荐）

# Clone Aptos core
git clone https://github.com/aptos-labs/aptos-core.git

# Navigate to examples
cd aptos-core/aptos-move/move-examples

# List all examples
ls -la

# View specific example
cd token_objects
cat sources/token.move

选项 3：daily-move 代码仓库

在线浏览：

https://github.com/aptos-labs/daily-move/tree/main/snippets

克隆到本地：

git clone https://github.com/aptos-labs/daily-move.git
cd daily-move/snippets
ls -la

选项 4：搜索 Aptos 文档

https://aptos.dev/build/smart-contracts

许多示例都附有说明文档。

示例中的常见模式

模式 1：对象创建（来自 token_objects）

// From: token_objects/sources/token.move
public entry fun create_token(
    creator: &signer,
    collection_name: String,
    description: String,
    name: String,
    uri: String,
) {
    let constructor_ref = token::create_named_token(
        creator,
        collection_name,
        description,
        name,
        option::none(),
        uri,
    );
    // ... additional setup
}

要点： 集合使用命名代币，唯一项目使用 create_object 创建。

模式 2：访问控制（来自 dao）

// From: dao/sources/dao.move
public entry fun execute_proposal(
    proposer: &signer,
    proposal_id: u64
) acquires DAO, Proposal {
    let dao = borrow_global_mut<DAO>(@dao_addr);
    let proposal = vector::borrow_mut(&mut dao.proposals, proposal_id);

    // Verify proposal passed
    assert!(proposal.votes_for > proposal.votes_against, E_PROPOSAL_NOT_PASSED);

    // Execute actions
    // ...
}

要点： 执行关键操作前，先验证状态条件。

模式 3：转账控制（来自 fungible_asset）

// From: fungible_asset/sources/fungible_asset.move
public fun transfer<T: key>(
    from: &signer,
    to: address,
    amount: u64
) acquires FungibleStore {
    // Verify sender has sufficient balance
    let from_store = borrow_global_mut<FungibleStore<T>>(signer::address_of(from));
    assert!(from_store.balance >= amount, E_INSUFFICIENT_BALANCE);

    // Deduct from sender
    from_store.balance = from_store.balance - amount;

    // Add to recipient
    let to_store = borrow_global_mut<FungibleStore<T>>(to);
    to_store.balance = to_store.balance + amount;
}

要点： 检查－效果－交互模式（验证、扣减、增加）。

ALWAYS 规则

• ✅ 始终先搜索示例，再编写新合约
• ✅ 始终检查 aptos-core（规范）和 daily-move（教学）仓库
• ✅ 始终先理解模式，再进行复制
• ✅ 始终根据你的使用场景调整模式
• ✅ 始终保留示例中的安全检查
• ✅ 始终注明改编自哪个示例
• ✅ 始终彻底测试改编后的代码

NEVER 规则

• ❌ 切勿在未理解代码的情况下复制代码
• ❌ 切勿跳过示例中的安全检查
• ❌ 切勿使用已弃用的模式（资源账户、基于地址的模式）
• ❌ 切勿假设示例始终是最新的（请根据文档进行验证）
• ❌ 切勿混用 V1 和 V2 模式
• ❌ 改编示例时切勿包含真实私钥或凭据——请使用 "0x..." 占位符

搜索检查清单

编写合约代码前：

• 确定类别（NFT、DeFi、DAO 等）
• 在 aptos-core 中找到 2-3 个相关示例
• 检查 daily-move 代码片段中的教学示例
• 查看模块结构
• 确定安全模式
• 理解对象创建模式
• 记录访问控制机制
• 检查测试模式
• 准备好根据我的使用场景进行改编

示例改编工作流

分步操作：构建 NFT 集合

1. 搜索： 查找 token_objects 示例

2. 查看结构：

   token_objects/
   ├── sources/
   │   ├── collection.move  # Collection management
   │   ├── token.move       # Token operations
   │   └── property_map.move # Metadata handling
   └── tests/
       └── token_tests.move
   

3. 确定关键模式：

   • 使用 create_collection 创建集合
   • 使用 create_named_token 铸造代币
   • 使用 PropertyMap 存储元数据
   • 使用 TransferRef 控制转移

4. 根据你的需求进行改编：

   • 保留对象创建模式
   • 保留安全检查
   • 添加自定义字段
   • 添加业务逻辑
   • 编写全面的测试

5. 在代码中注明来源：

   // Adapted from: aptos-core/move-examples/token_objects
   module my_addr::custom_nft {
       // ... your implementation
   }
   

参考资料

官方示例：

• aptos-core：https://github.com/aptos-labs/aptos-core/tree/main/aptos-move/move-examples
• daily-move：https://github.com/aptos-labs/daily-move/tree/main/snippets
• 文档：https://aptos.dev/build/smart-contracts

相关技能：

• write-contracts - 搜索后应用模式
• security-audit - 验证改编后代码的安全性
• generate-tests - 测试改编后的模式

---

请记住： 先搜索示例。理解模式。安全地进行改编。彻底测试。