Uniffi-rs 中回调接口与错误处理的实践指南

回调接口与错误处理的常见问题

在使用 Uniffi-rs 进行跨语言绑定时，开发者经常会遇到回调接口与错误处理相结合的场景。一个典型的案例是定义了一个带有错误抛出的回调接口，但在实现过程中遇到了编译错误。

错误案例分析

开发者定义了一个名为 SyncUpdate 的回调接口，其中包含一个可能抛出 LightWalletError 错误的 update 方法。LightWalletError 被定义为包含三种情况的枚举错误类型：InvalidUri、InvalidHandle 和带消息的 Other。

在 Rust 实现中，错误类型使用了 thiserror 宏来定义，其中 Other 变体包含了一个 message 字段。这种定义方式导致了 Uniffi-rs 代码生成时出现 "expected value, found struct variant Self::Other" 的编译错误。

问题根源

问题的核心在于 Uniffi-rs 的"扁平错误"(flat error)机制。当使用 [Error] 属性标记枚举时，Uniffi 期望所有变体都是简单的枚举值，不能包含结构体形式的变体。这是因为 Uniffi 需要将这些错误类型映射到多种目标语言，而复杂变体会增加跨语言兼容性的难度。

解决方案

正确的做法是使用 [Error] interface 语法来定义错误类型，而不是 [Enum] interface。具体修改如下：

[Error]
interface LightWalletError {
    InvalidUri();
    InvalidHandle();
    Other(string message);
};

这种定义方式明确告诉 Uniffi 这是一个错误类型，同时允许 Other 变体携带消息参数。Uniffi 会正确处理这种定义并生成相应的跨语言绑定代码。

最佳实践建议

1. 错误类型设计：在设计跨语言的错误类型时，尽量保持简单。如果必须携带额外信息，使用 [Error] interface 语法。

2. 回调接口定义：当回调接口可能抛出错误时，确保错误类型定义正确，并在 UDL 中正确声明 [Throws=ErrorType]。

3. 代码生成检查：在修改 UDL 定义后，检查生成的 Rust 代码是否符合预期，特别是错误类型的处理部分。

4. 跨语言兼容性：考虑目标语言对错误类型的支持情况，避免使用过于复杂的错误变体结构。

通过遵循这些实践指南，开发者可以避免常见的回调接口与错误处理集成问题，确保 Uniffi-rs 项目能够顺利编译并在各目标语言中正常工作。