Pigeon跨平台通信：从Flutter到鸿蒙的代码生成实战

pending, // 请求待处理success, // 请求成功failure, // 请求失败技术要点Pigeon枚举会自动转换为各平台的对应枚举在鸿蒙ArkTS中会生成对应的TypeScript枚举// 初始化方法// 搜索方法鸿蒙实现解析@HostApi标记的接口由原生平台（鸿蒙）实现Flutter端调用这些方法，请求会转发到鸿蒙原生代码用于测试，可在测试中模拟原生端响应与@HostApi

音浪豆豆_Rachel

1031人浏览 · 2025-12-24 11:06:04

音浪豆豆_Rachel · 2025-12-24 11:06:04 发布

一、我们先了解一下Pigeon是什么？为什么需要它？

在跨平台开发中，Flutter与原生平台（如Android、iOS、鸿蒙）的通信是一个常见需求。传统的MethodChannel方式虽然可用，但存在类型安全弱、容易出错等问题。Pigeon（鸽子）就是为解决这些问题而生的代码生成工具。

核心价值：

类型安全：编译时检查类型，减少运行时错误
代码自动生成：自动生成Dart、Java、Obj-C、ArkTS等多平台代码
开发体验提升：提供IDE自动补全和文档支持

在这里插入图片描述

二、以下是message.dart文件的解析

源码：https://atomgit.com/openharmony-tpc/flutter_packages/blob/master/packages/pigeon/pigeons/message.dart

2.1 文件结构概览

这个示例文件展示了Pigeon的核心语法和功能：

// 配置Pigeon生成选项
@ConfigurePigeon(PigeonOptions(
  javaOptions: JavaOptions(
    className: 'MessagePigeon',
    package: 'dev.flutter.aaclarke.pigeon',
  ),
  objcOptions: ObjcOptions(
    prefix: 'AC',
  ),
))

鸿蒙特别关注：虽然这里没有直接配置鸿蒙选项，但Pigeon的鸿蒙版本支持--arkts_out参数生成ArkTS代码。

2.2 枚举类型定义

enum MessageRequestState {
  pending,    // 请求待处理
  success,    // 请求成功
  failure,    // 请求失败
}

技术要点：

Pigeon枚举会自动转换为各平台的对应枚举
在鸿蒙ArkTS中会生成对应的TypeScript枚举

2.3 数据传输对象（DTO）

请求类：

class MessageSearchRequest {
  String? query;  // 搜索查询字符串
  int? anInt;     // 整型参数示例
  bool? aBool;    // 布尔参数示例
}

响应类：

class MessageSearchReply {
  String? result;               // 搜索结果
  String? error;                // 错误信息
  MessageRequestState? state;   // 请求状态
}

跨平台数据类型映射表：

在这里插入图片描述

2.4 原生平台API定义（@HostApi）

@HostApi(dartHostTestHandler: 'TestHostApi')
abstract class MessageApi {
  void initialize();  // 初始化方法
  
  MessageSearchReply search(MessageSearchRequest request);  // 搜索方法
}

鸿蒙实现解析：

@HostApi标记的接口由原生平台（鸿蒙）实现
Flutter端调用这些方法，请求会转发到鸿蒙原生代码
dartHostTestHandler用于测试，可在测试中模拟原生端响应

在这里插入图片描述

2.5 Flutter端API定义（@FlutterApi）

@FlutterApi()
abstract class MessageFlutterSearchApi {
  MessageSearchReply search(MessageSearchRequest request);
}

与@HostApi的区别：

@FlutterApi标记的接口由Flutter端实现
鸿蒙原生代码可以调用这些方法
适用于原生端主动向Flutter端请求数据的场景

三、在鸿蒙项目中的实际应用

3.1 生成鸿蒙ArkTS代码

# 生成多平台代码
flutter pub run pigeon \
  --input pigeons/message.dart \
  --dart_out lib/message_api.dart \
  --arkts_out harmony/message_api.ts \  # 鸿蒙ArkTS输出
  --java_out android/app/src/main/java/ \
  --objc_header_out ios/Runner/ \
  --objc_source_out ios/Runner/

3.2 鸿蒙端实现示例

// 鸿蒙ArkTS端实现
import { MessageApi, MessageSearchRequest, MessageSearchReply, MessageRequestState } from './message_api';

class MessageApiImpl implements MessageApi {
  initialize(): void {
    // 初始化鸿蒙端资源
    console.log('鸿蒙端MessageApi初始化完成');
  }

  search(request: MessageSearchRequest): MessageSearchReply {
    // 实现搜索逻辑
    const reply = new MessageSearchReply();
    
    if (!request.query) {
      reply.error = '查询内容不能为空';
      reply.state = MessageRequestState.failure;
      return reply;
    }

    // 模拟搜索过程
    reply.result = `搜索"${request.query}"的结果：找到10条相关记录`;
    reply.state = MessageRequestState.success;
    
    return reply;
  }
}

// 注册到Flutter引擎
export function setupPigeonApi(): void {
  // 这里需要根据实际Flutter引擎API进行注册
  // flutterEngine.getBridge().registerApi(MessageApi, new MessageApiImpl());
}

3.3 Flutter端调用示例

import 'package:your_app/message_api.dart';

class SearchService {
  final MessageApi _api = MessageApi();
  
  Future<void> init() async {
    await _api.initialize();
  }
  
  Future<String?> search(String query) async {
    final request = MessageSearchRequest()
      ..query = query
      ..anInt = 10
      ..aBool = true;
    
    final reply = await _api.search(request);
    
    if (reply.state == MessageRequestState.success) {
      return reply.result;
    } else {
      throw Exception(reply.error ?? '搜索失败');
    }
  }
}

四、Pigeon在鸿蒙开发中的优势

4.1 类型安全的跨平台通信

在这里插入图片描述

4.2 开发效率提升

代码自动完成：IDE能够识别生成的API
文档集成：注释会生成到各平台代码中
一致性保证：多平台接口保持完全一致
易于维护：只需维护一份接口定义文件

4.3 鸿蒙生态集成

无缝接入：生成的ArkTS代码符合鸿蒙开发规范
性能优化：比动态MethodChannel调用更高效
未来兼容：支持鸿蒙Next等未来版本

五、最佳实践与注意事项

5.1 接口设计建议

// 良好实践：使用明确的数据结构
class UserInfo {
  String id;
  String name;
  int age;
  List<String> tags;
}

// 避免实践：过多使用Map等动态类型
class BadApi {
  Map<String, dynamic> getUserInfo(); // 不推荐
}

5.2 错误处理策略

使用枚举状态码：如示例中的MessageRequestState
提供错误信息字段：便于调试和用户提示
异常边界处理：在各平台实现中捕获和处理异常

5.3 版本兼容性

# pubspec.yaml中的版本控制
dependencies:
  pigeon:
    git:
      url: "https://gitcode.com/openharmony-sig/flutter_packages.git"
      ref: "master"  # 可指定特定分支或标签
      path: "packages/pigeon"