Flutter Rust Bridge 中 Web 目标下的枚举类型问题解析

问题背景

在使用 Flutter Rust Bridge 进行跨平台开发时，开发者遇到了一个关于枚举类型在不同平台表现不一致的问题。具体表现为：当使用 Rust 定义的枚举类型时，在 Android 平台上编译运行正常，但在 Web 平台（Chrome）上却出现了类型不匹配的错误。

问题现象

开发者定义了一个 Rust 枚举类型 CollectMetaValue，包含四种变体：

pub enum CollectMetaValue {
    Text { data: String },
    Int { data: i64 },
    Nat { data: u64 },
    Blob { data: Vec<u8> },
}

在 Android 平台上编译运行正常，但在 Web 平台上出现以下错误：

1. 构造函数类型不匹配：CollectMetaValue_Int Function({int data}) 不是 CollectMetaValue Function({BigInt data}) 的子类型
2. 参数类型 BigInt 不能赋值给参数类型 int
3. 参数类型 int 不能赋值给参数类型 BigInt

根本原因分析

这个问题源于 Web 平台和原生平台对数字类型处理方式的差异：

1. Web 平台：由于 JavaScript 的限制，WebAssembly 在处理 64 位整数时会自动使用 BigInt 类型
2. 原生平台：可以直接使用普通的 int 类型处理 64 位整数

当 Flutter Rust Bridge 生成 Dart 代码时，freezed 包在处理类型别名时存在局限性，无法正确处理平台特定的类型转换。具体表现为：

• 在原生平台上，i64 被映射为 Dart 的 int
• 在 Web 平台上，i64 应该被映射为 Dart 的 BigInt，但 freezed 生成的代码仍然使用 int

解决方案

针对这个问题，开发者可以采用以下几种解决方案：

方案一：统一使用 i128 类型

将 Rust 中的 i64 改为 i128，这样 Flutter Rust Bridge 会在所有平台上都使用 BigInt 类型：

pub enum CollectMetaValue {
    Text { data: String },
    Int { data: i128 },  // 改为 i128
    Nat { data: u128 },  // 改为 u128
    Blob { data: Vec<u8> },
}

方案二：配置 flutter_rust_bridge.yml

在项目的 flutter_rust_bridge.yml 配置文件中添加以下配置：

type_64bit_int: true

这个配置会让 Flutter Rust Bridge 在 Web 平台上将 64 位整数处理为 53 位 JavaScript 安全整数，从而避免使用 BigInt。但需要注意这会限制数值范围。

方案三：等待 freezed 修复

这个问题本质上是 freezed 包对平台特定类型别名支持不足导致的。开发者可以向 freezed 项目提交 issue，等待其未来版本支持这种场景。

最佳实践建议

1. 跨平台一致性：在设计跨平台数据结构时，应优先考虑各平台的一致性。使用 i128/u128 配合 BigInt 是一个较为稳妥的方案。

2. 类型选择：根据实际需求选择合适的数据类型：

   • 如果数值可能超过 53 位，必须使用 BigInt
   • 如果确定数值范围在安全范围内，可以使用 type_64bit_int 配置

3. 测试策略：对于跨平台项目，应建立完善的跨平台测试机制，尽早发现并解决这类平台差异问题。

总结

Flutter Rust Bridge 在 Web 平台上的枚举类型问题揭示了跨平台开发中类型系统处理的重要性。开发者需要理解不同平台底层实现的差异，并采取适当的策略来保证代码的跨平台一致性。通过合理选择数据类型和配置，可以有效解决这类问题，确保应用在各个平台上都能正常运行。

对于未来项目，建议在设计阶段就考虑平台差异，特别是在处理数字类型时，提前规划好跨平台兼容方案，避免后期出现难以调试的类型不匹配问题。