Flutter Rust Bridge 中的外部类型与自定义序列化方案

在 Flutter 与 Rust 混合开发中，Flutter Rust Bridge (FRB) 作为连接两端的桥梁发挥着重要作用。然而，当项目中同时存在多种代码生成器时，类型兼容性问题便浮出水面。本文将深入探讨这一问题的本质及其解决方案。

问题背景

当项目中同时使用多种代码生成工具时，例如在 Rust 端使用 prost_build 生成 protobuf 类型，在 Dart 端使用 protoc_builder 生成对应的 Dart 类型，FRB 也会生成自己的类型版本。这就导致了同一数据类型在不同生成器下产生多个不兼容的实现版本。

例如，一个名为 AwesomeMessage 的 protobuf 消息类型：

• Rust 端：通过 prost_build 生成 awesome_proto_crate::AwesomeMessage
• Dart 端：通过 protoc_builder 生成 package:awesome_proto 中的 AwesomeMessage
• FRB 生成：package:awesome/src/rust/api/api.dart 中的 AwesomeMessage

这三个版本的 AwesomeMessage 虽然表示相同的数据结构，但由于来自不同的生成器，彼此间无法直接兼容使用。

解决方案设计

FRB 提供了优雅的解决方案，允许开发者指定使用现有的外部类型，而非生成新版本。核心思路是通过注解声明类型映射关系，并配置相应的序列化/反序列化逻辑。

基本用法

在 Rust 代码中，可以通过如下方式声明外部类型映射：

#[frb(some_marker_name_to_be_determined(
    dart = "AwesomeMessage", 
    package = "awesome_proto", 
    decode = "AwesomeMessage.from_bytes(raw)"
))]
fn encode_awesome_message(obj: AwesomeMessage) -> anyhow::Result<Vec<u8>> {
    obj.serialize_protobuf_into_bytes()
}

这个方案包含几个关键部分：

1. 类型映射：指定 Rust 类型对应到哪个 Dart 类型及所在包
2. 序列化：定义如何将 Rust 类型转换为中间格式（如字节数组）
3. 反序列化：提供 Dart 端从中间格式重建对象的逻辑

错误处理

考虑到序列化过程可能失败，方案原生支持 anyhow::Result 作为返回类型，与 FRB 现有的错误处理机制无缝集成。

实现细节

在实际实现中，FRB 会维护一个类型转换表，记录：

• Rust 序列化器：将 Rust 类型转换为中间格式
• Dart 反序列化器：将中间格式转换为 Dart 对象
• 反向路径：Dart 到 Rust 的转换逻辑

这种设计使得类型转换过程对开发者透明，只需在边界处声明一次映射关系即可。

使用场景扩展

这种机制不仅适用于 protobuf 类型，还可应用于任何需要与现有 Dart 类型集成的场景：

1. 数据库模型类型
2. 第三方库定义的数据结构
3. 项目中已有稳定接口的类型

注意事项

当前实现主要针对 SSE (Synchronous Stream Encoding) 编解码器。在使用时需要注意：

1. 避免同时启用 full_dep 选项，这可能导致编译错误
2. 对于复杂嵌套类型（如包含自定义序列化类型的结构体成员），需要确保整体类型系统一致性
3. 性能考量：某些序列化方案（如 protobuf）可能不如原生序列化高效

总结

Flutter Rust Bridge 的外部类型支持机制为解决多代码生成器环境下的类型兼容性问题提供了优雅方案。通过声明式配置和灵活的序列化扩展点，开发者可以轻松集成现有类型系统，避免重复定义和转换开销。这一特性特别适合已有成熟代码库需要逐步接入 Flutter-Rust 混合架构的场景。