fuels-ts 中的 Sway Option 类型指南：从 Sway 合约到 TypeScript 的 `undefined` 映射实践

fuels-ts 中的 Sway Option 类型指南从 Sway 合约到 TypeScript 的undefined映射实践【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts导读本文聚焦 Fuel 生态 Sway 合约语言中的Option可选值容器类型讲解在 fuels-tsFuel Network TypeScript SDK中如何与之交互。你将掌握Option类型的本质它是 Sway 中一种特殊的 Enum、它在 TypeScript 侧如何以number | undefined的形式呈现、如何定义一个接受两个Optionu8参数的合约函数并通过 SDK 调用以及 SDK 底层OptionCoder是如何完成值 ↔ Some/None编解码的。全文配套真实的 Sway 合约与可运行 TS 示例可直接作为你接入合约时的参考。一、认识 Sway 的Option类型1.1 什么是Option在 Sway 中变量有时可能没有值。官方对Option的定义是一个用于处理可以有值、也可以标记为无值no-value的容器类型。这种能力非常适合某个变量可能被赋值、也可能未被定义的场景。Option是 Sway 中一种特殊的 Enum枚举包装类型。理解这一点非常重要因为它直接决定了 SDK 底层的编解码方式——既然它是枚举天然就有两个变体Some(value)表示持有值None表示没有值。1.2 TypeScript 侧的表示undefined由于 TypeScript 本身没有与 SwayOption完全对应的内建容器fuels-ts 采用了最贴合直觉的约定用undefined关键字表示无值状态。也就是说一个 Sway 的OptionT在 TS 的类型系统里等价于T | undefined。这一点在 SDK 源码中有明确的类型定义佐证。在 OptionCoder.ts 中可以看到type SwayOptionT { None: [] } | { Some: T }; export type OptionT T | undefined;因此在 TypeScript 侧声明一个可以是数字、也可以是 undefined的输入只需写成联合类型// 对应的 Sway 类型为 Optionu8 const input: number | undefined 10;这个例子正是 overview-of-option.ts 中演示的核心用法。二、实战案例接收两个Optionu8的合约函数为了让Option的使用不止停留在类型说明层面官方文档配套了一个完整可编译的合约示例sum-option-u8位于 apps/docs/sway/sum-option-u8/其 Forc.toml 声明了项目名与入口main.sw。2.1 合约需求假设我们有一个合约函数接收两个Optionu8参数每个参数可以有值也可以没有值undefined函数逐一检查每个输入是否有值若无值则将其按0处理最终返回两个输入的和。2.2 Sway 侧实现完整合约代码见 main.swcontract; abi SumOptionU8 { fn sum_optional_u8(input1: Optionu8, input2: Optionu8) - u8; } impl SumOptionU8 for Contract { fn sum_optional_u8(input1: Optionu8, input2: Optionu8) - u8 { let value1 match input1 { Option::Some(v) v, Option::None 0, }; let value2 match input2 { Option::Some(v) v, Option::None 0, }; value1 value2 } }要点拆解ABI 中直接使用Optionu8作为参数类型Sway 编译器会将其作为枚举写入合约 ABI 描述供 SDK 侧识别match表达式是解构Option的标准做法Some(v)分支取出真实值None分支回退为0返回值value1 value2的类型为u8说明求和在合约内完成返回值是普通标量而非Option。三、通过 fuels-ts 与合约交互3.1 调用前的基础准备从官方片段 overview-of-option.ts 可以看到一个标准的调用链路创建Provider指向本地或远程节点文档示例使用LOCAL_NETWORK_URL环境变量通过私钥创建Wallet实例WALLET_PVT_KEY使用类型生成工具产生的工厂类SumOptionU8Factory部署合约并等待部署完成拿到contract实例。在真实项目中SumOptionU8Factory由 fuels-ts 的 typegen类型生成器根据合约 ABI 自动生成部署方式对应ContractFactory的封装。3.2 场景一两个参数都有值下面的代码同时传入两个值合约应返回它们的和const input: number | undefined 10; const input2: number | undefined 5; const { value } await contract.functions.sum_optional_u8(input, input2).get(); console.log(value, value); // 153.3 场景二只传一个参数如果只传第一个参数而省略第二个参数第二个参数就是undefined合约会将缺失的参数默认为0因此结果等于所传参数本身const input: number | undefined 10; const { value } await contract.functions.sum_optional_u8(input).get(); console.log(value, value); // 103.4 返回值统一结构两次调用都使用.get()获取结果返回值结构均为{ value }。可以看到虽然合约内部解构了两个Option但对调用方而言传入侧只需遵守有值传原始值、无值传undefined的约定SDK 会自动完成到Some/None的转换——这正是下文OptionCoder的职责。四、源码纵深OptionCoder是如何工作的理解了上层用法后我们来看看 fuels-ts 底层是如何把undefined编解码成 Sway 枚举的。其核心实现在 OptionCoder.ts。4.1 Option 本质上是枚举所以它继承 EnumCoder因为 Sway 中Option是特殊的 Enum 包装类型所以OptionCoder直接继承自 EnumCoder.tsexport class OptionCoderTCoders extends Recordstring, Coder extends EnumCoderTCoders {这保证了 ABI 编解码层面复用枚举的编码协议先编码变体序号tag再编码变体关联的数据。4.2 编码方向TS 值 →Some/None编码时 SDK 把上层传入的 JS 值翻译为 Sway 枚举变体private toSwayOption(input?: Optionunknown): SwayOptionunknown { if (input ! undefined) { return { Some: input }; } return { None: [] }; }逻辑非常直观传入值不是undefined→ 包装为{ Some: input }传入undefined→ 包装为{ None: [] }None不携带额外数据故为空元组。随后encode把转换后的对象交给父类EnumCoder.encode完成字节序列化。4.3 解码方向Some/None→ TS 值读取链上返回数据时做对称逆操作private toOption(output?: DecodedValueOfTCoders): Optionunknown { if (output Some in output) { return output.Some; } return undefined; }解码结果若含有Some键则取出其内部值返回否则None返回undefined。这样TS 侧拿到的就永远是T | undefined与 1.2 节约定的类型完全一致。4.4 设计带来的体验由于 Option 的特殊枚举地位fuels-ts 可以在运行时根据 ABI 类型信息自动选择OptionCoder与普通枚举如带业务含义的StateError共用同一套编码基础却对外暴露更友好的 TS 类型。你可以在同目录的 OptionCoder.test.ts 中看到针对该编解码行为的单元测试进一步印证这一实现约定。五、总结与实用建议回到本次实践我们可以提炼出三条可直接套用的经验类型映射规则是固定的SwayOptionT⇄ TypeScriptT | undefined。编写合约接口文档或前端 DTO 时可直接按此换算。无值时不传 / 传undefined即可fuels-ts 会把undefined映射为None把任何真实值映射为Some无需手写枚举包装对象返回值若为NoneSDK 也会还原为undefined。合约侧用match处理缺省Option::Some(v) v与Option::None 默认值的写法可以让业务逻辑天然覆盖参数可能缺失的边界情况。需要说明的是本文示例运行在LOCAL_NETWORK_URL指向的本地 Fuel 节点环境并依赖 fuels-ts 类型生成工具产出的SumOptionU8Factory。在你的项目中只需保证 Sway 合约已编译出 ABI并通过fuelsCLI 的 typegen 生成对应工厂类即可原样复用上述调用模式。若你希望进一步了解普通枚举与枚举嵌套枚举在 SDK 中的表示差异可继续阅读同目录下的 Enums 指南 作为延伸。【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址: https://gitcode.com/GitHub_Trending/fu/fuels-ts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考