从零上手 Fuel Rust SDK：Sway 工程搭建、Rust 集成测试与 fuels-rs 源码探索

从零上手 Fuel Rust SDKSway 工程搭建、Rust 集成测试与 fuels-rs 源码探索【免费下载链接】fuels-rsFuel Network Rust SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-rs本文基于 getting-started.md 编写系统讲解 Fuel Network Rust SDKfuels-rs的两种典型使用路径其一是在forc创建的 Sway 工程中通过cargo generate注入 Rust 集成测试框架其二是把fuelscrate 作为普通依赖导入独立 Rust 工程。读完本文你将掌握完整的环境准备、工程初始化、合约编译与测试命令并了解如何借助仓库内e2e集成测试与examples示例代码快速验证 SDK 的每一项能力。开始之前认识 Fuel 工具链的两个关键角色Fuels-rs 并不是一座孤岛它运行在 Fuel 生态的完整工具链之上。在动手之前需要先理解两个与 SDK 配合最紧密的二进制forcSway 的包管理器与构建工具地位等同于 Rust 生态中的cargo。它负责创建工程、编译 Sway 源码、管理工程依赖。仓库内e2e下散布的每一个Forc.toml就是forc所管理的 Sway 工程清单。fuel-coreFuel 全节点full node的实现。测试链上行为、部署合约、执行交易都需要它提供链端支撑SDK 的本地测试场景正是通过内嵌或拉起fuel-core节点来完成的。两者的安装属于官方 Fuel 工具链范畴推荐通过fuelup安装可参考官方安装指南完成前置准备。从仓库根目录 README.md 的 FAQ 也可确认运行 SDK 需要最新 stable 版 Rust 工具链、forc与fuel-core二进制三样依赖。使用 Fuel Rust SDK 的两种主要方式SDK 的文档将使用方式归纳为两条清晰路径选择哪条取决于你从何处起步先有 Sway 工程再补测试用forc创建新的 Sway 项目然后通过模板为它生成 Rust 集成测试。这是接触合约开发与 SDK 测试的最快路径。先有独立 Rust 工程再接入链能力在任意 Rust 工程中把fuelscrate 作为依赖引入从而获得部署合约、调用合约、构造与签名交易、生成类型安全绑定等全部能力。下文分别对两条路径展开。路径一用forc创建新的 Sway 工程在安装了forc的前提下创建一个全新 Sway 工程forc new Project name如果文件夹已经存在、不想新建目录可以在该文件夹内部直接初始化forc initforc new生成的是一个可独立编译的最小 Sway 工程骨架其中包含工程清单Forc.toml与默认的src/main.sw。仓库内大量示例展示了这种结构例如 e2e/sway/contracts/contract_test/Forc.toml 与同目录下的 main.sw。为 Sway 工程添加 Rust 集成测试框架拿到一个能编译的 Sway 工程后就可以注入 Rust 集成测试了。这一环节借助cargo generate从官方模板拉取一套完整的测试脚手架。若尚未安装cargo generate先执行cargo install cargo-generate随后用官方维护的测试模板生成默认的测试工程cargo generate --init fuellabs/sway templates/sway-test-rs --name Project name --force这里对模板与参数做几点说明该命令使用的模板fuellabs/sway templates/sway-test-rs会为当前 Sway 工程配套生成一个 Rust 测试 harness测试代码可通过fuelsSDK 去加载、部署并调用你写的合约。--init表示在当前已有目录中初始化而不是新建一个目录再写入模板这与前面forc init的思路保持一致。--name Project name决定模板中{{project-name}}占位符最终被替换成什么。关于--force标志的真实作用cargo-generate默认会把--name传入的工程名自动规范为kebab-case短横线小写风格。如果你传入的名字本身带有下划线等自定义大小写风格默认行为会把它们改写掉。而--force会强制保留你输入的大小写风格不做 kebab-case 转换。举个文档中的例子有了--forcemy_fuel_project与my-fuel-project都可以按你的实际需求成为合法工程名而不是被统一强行改写。提示cargo-generate本身是独立于 Fuel 生态的通用工具它有更丰富的模板能力与配置项需要深度定制时可自行查阅其说明文档。先编译 Sway 再跑 Rust 测试模板就位后测试要跑通需要两个前置产物一是 Sway 侧编译出的字节码与 ABI 文件二是 Rust 侧基于这些产物生成的绑定与调用逻辑。因此在运行测试之前务必先构建 Sway 工程forc build之后运行 Rust 集成测试cargo test如果你需要捕获测试中打印的输出例如验证合约返回值的println!、调试日志请使用不捕获 stdout 的模式cargo test -- --nocaptureforc build的产物是值得关注的它会在工程的out/release/目录下生成.bin字节码与*-abi.json的 ABI 描述文件。这两类文件是 SDK 侧后续操作的基础——Contract::load_from读取.bin用于部署abigen!解析*-abi.json用于生成类型安全的合约方法绑定。仓库内的真实示例可以印证这一点例如 examples/contracts/src/lib.rs 中的部署代码就是加载../../e2e/sway/contracts/contract_test/out/release/contract_test.bin来部署的。路径二把fuelscrate 导入独立 Rust 工程如果你已经有一个普通 Rust 工程例如想用它管理链上账户、发交易、连外部节点SDK 提供了标准的 crate 化接入方式。第一步在Cargo.toml中声明依赖在工程根目录的Cargo.toml中加入fuels 0.66.0文档撰写当时标注0.66.0为最新可用版本。版本号属于持续演进的动态信息本文所在仓库的根 Cargo.toml 中[workspace.package]声明的当前版本已是0.77.0因此实际使用时应将上面的版本占位符替换为你所依赖的 SDK 发行版本在Cargo.toml中可采用fuels 0.77之类允许兼容升级的写法具体以 crates.io 上的实际发布为准。值得一提是fuels是一个聚合型顶层 crate。从 packages/fuels/Cargo.toml 的依赖表可以看到它内部把职责拆分成了多个子 crate 再统一对外导出fuels-accounts账户、钱包、签名器、Provider 等账户层能力fuels-core编码解码codec、类型系统与核心 traitfuels-macrosabigen!、setup_program_test!等过程宏fuels-programs合约/脚本调用、响应解析等程序层抽象fuels-test-helpers本地节点、测试钱包等测试辅助设施默认特性开启。聚合后再由fuels统一暴露使用者只需要关心一个依赖。特性开关也集中在顶层 crate 上默认开启std、test-helpers与coin-cache同时可选的accounts-signer-aws-kms、accounts-signer-google-kms、accounts-keystore、rocksdb、fuel-core-lib、fault-proving等特性分别对应 KMS 云签名、密钥库、RocksDB 数据库后端、内嵌fuel-core库等场景。第二步用prelude一键引入全部常用类型在将使用 SDK 的 Rust 源文件顶部写入use fuels::prelude::*;prelude的价值在于开箱即用。从 packages/fuels/src/lib.rs 的prelude模块实现可以看出它聚合了大量高频类型与 trait包括但不限于Account、ViewOnlyAccount、Wallet、各类signers如PrivateKeySigner、FakeSigner与provider相关类型核心 traitSigner以及 codec 侧的LogDecoder、LogResult等宏abigen、setup_program_test程序抽象CallHandler、CallParameters、Execution、Contract、LoadConfiguration、StorageConfiguration常用交易与工具类型Receipt、Address、AssetId、Bytes、ContractId、RawSlice、Salt以及各种transaction_builders。因此新手只需要这一行导入就能覆盖绝大多数入门场景当你需要更深层的能力时再按需从fuels::accounts、fuels::programs、fuels::core等模块直接引入如 examples/contracts/src/lib.rs 中所示混合导入的写法。落地体验从集成测试源码中学习真实用法导入 SDK 后最能验证能力的方式是直接阅读并运行仓库自带的示例与集成测试。仓库目录布局中藏着两份高价值教材第一份examples/下的分主题示例examples/按主题拆分为多个独立 crate每个 crate 的src/lib.rs都是带 anchor 注释的可运行测试片段例如在 examples/contracts/src/lib.rs 中instantiate_client展示了如何用FuelService::start拉起一个本地 Fuel 节点再用Provider::from(server.bound_address())建立客户端连接deploy_contract则完整演示了从二进制加载到部署的链路use fuels::prelude::*; // 启动本地节点并拿到与之绑定的测试钱包 let wallet launch_provider_and_get_wallet().await?; // 从二进制加载合约并部署上链得到 contract_id let contract_id Contract::load_from( ../../e2e/sway/contracts/contract_test/out/release/contract_test.bin, LoadConfiguration::default(), )? .deploy(wallet, TxPolicies::default()) .await? .contract_id;同文件中的setup_program_test_example展示了更高级的宏式测试编排——setup_program_test!可一次性完成创建钱包、基于 Sway 工程生成绑定Abigen、部署合约Deploy三步随后直接通过.methods()调用合约方法setup_program_test!( Wallets(wallet), Abigen(Contract( name TestContract, project e2e/sway/contracts/contract_test )), Deploy( name contract_instance, contract TestContract, wallet wallet ), ); let response contract_instance .methods() .initialize_counter(42) .call() .await?; assert_eq!(42, response.value);第二份e2e/tests/下的全量集成测试正如入门文档强调的e2e/tests/覆盖了 SDK 的几乎所有方面是理解能做什么、怎么用的活文档。从文件命名即可管中窥豹contracts.rs、wallets.rs、predicates.rs、scripts.rs、types_contracts.rs、providers.rs……分别覆盖合约调用、钱包与签名、谓词、脚本、类型编解码、Provider 行为等主题测试中还演示了与setup_program_test!宏、launch_custom_provider_and_get_wallets等测试设施组合使用的完整姿势。从源码运行 SDK 的全部集成测试在仓库内跑通整套测试是深入理解 SDK 的最直接方式。完整的步骤与关键命令如下。前提构建全部 Sway 测试工程测试运行前必须先构建测试所依赖的所有 Sway 工程。入门文档指出这些工程在packages/fuels/Forc.toml的[workspace]中登记而从当前仓库源码的实际布局看这个 Sway workspace 清单已经收敛到 e2e/Forc.toml——它列出了sway/contracts/、sway/predicates/、sway/scripts/、sway/types/、sway/bindings/下几十个工程如contract_test、token_ops、basic_predicate、basic_script等并且通过[patch]将标准库std指向官方 Sway 仓库保证与最新编译器语义对齐。因此对应命令为forc build --release --path e2eforc同样可以用来对测试工程做清理与格式化等维护操作需要了解这些子命令时可直接查看forc的help输出。运行测试Sway 工程全部构建完成后即可运行 Rust 侧测试cargo test如果你需要覆盖所有编译目标并开启全部 featurecargo test --all-targets --all-features需要捕获测试输出时例如观察部署日志、合约返回值等cargo test -- --nocapture根目录 README.md 还给出了更精细的运行姿势仅运行types.rs集成测试中名称包含in_vector的用例并显示其输出cargo test --test types in_vector -- --show-output这条命令印证了e2e/tests下每个.rs文件在 Cargo 中即一个独立的集成测试目标test target。排错小贴士README.md 的 FAQ 提供了一套在master分支测试失败时优先尝试的复位命令序列清理 Cargo 构建缓存与锁文件重新构建全部 Sway 工程再跑测试cargo clean rm Cargo.lock forc build --release --path e2e cargo test由于 e2e 测试通过 e2e/Cargo.toml 以fuels为依赖并开启test-helpers等特性本地若要执行全量 e2e环境需满足这些特性所对应的外部依赖条件。需要注意的是本节所有命令面向的是在当前仓库源码内部探索与验证的场景常规用户在自己的 Sway 工程中使用 SDK则回到前文路径一/路径二的轻量命令即可。更进一步阅读 Sway 与 SDK 的配合源码入门文档最后提示更深入的 Sway 语言知识应参考 The Sway Book——Sway 是 Fuel 虚拟机的官方智能合约语言。这份语言功底在阅读本仓库时几乎不可或缺因为e2e/sway/下每个测试工程都用 Sway 编写例如 e2e/sway/contracts/contract_test/src/main.sw 中的initialize_counter、increment_counter等方法正是 SDK 集成测试反复调用、并在 examples/contracts/src/lib.rs 中被断言返回值42 → 52的对象docs/src/下以 SUMMARY.md 为目录的整本 mdBook 手册配置见 docs/book.toml按主题串联了连接节点、账户与钱包、abigen!绑定生成、合约部署与调用、谓词与脚本、类型与编解码等进阶主题可作为 SDK 深入学习的下一站。至此你已经掌握了 Fuel Rust SDK 从环境准备、工程初始化、测试编写到阅读源码级示例的完整闭环一条路是forc newcargo generate快速搭建 Sway 合约的 Rust 测试工程另一条路是在独立 Rust 工程中use fuels::prelude::*;直接接入链上能力而e2e/tests与examples则是随取随用的进阶字典配合forc build --release --path e2e与cargo test即可在你自己的机器上把 SDK 的每一项能力跑起来。【免费下载链接】fuels-rsFuel Network Rust SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考