Flutter Pigeon 跨端通信实战指南

Flutter Pigeon 跨端通信实战指南：打造医疗级硬件 SDK 的通信基石

在 Flutter 混合开发中，传统的 MethodChannel 虽然灵活，但高度依赖字符串匹配和动态类型转换，极易在大型项目中引发拼写错误和运行时崩溃。对于医疗级硬件 SDK 这种对稳定性和类型安全要求极高的场景，Flutter 官方推荐的代码生成工具 Pigeon 是最佳选择。

本文将结合医疗硬件 SDK 的实际业务场景，详细梳理 Pigeon 的完整接入流程、项目结构设计以及核心注意事项。

一、核心工作流：从接口定义到业务落地

Pigeon 的核心思想是"契约优先（Contract First）"。开发者只需在 Dart 中定义好接口协议，Pigeon 便会自动生成双端的通信样板代码，让开发者专注于原生业务逻辑的实现。

1. 配置开发依赖

在 Flutter 项目的 pubspec.yaml 中，将 Pigeon 添加为开发依赖：

yaml 复制代码

dev_dependencies:
  pigeon: ^11.0.0 # 建议根据实际项目选择最新稳定版

执行 flutter pub get 完成依赖拉取。

2. 定义通信协议与输出路径

在项目根目录创建 pigeons/messages.dart 文件。在此文件中，使用 @ConfigurePigeon 注解集中配置各平台的代码输出路径，并定义数据模型与通信接口：

dart 复制代码

import 'package:pigeon/pigeon.dart';

// 1. 集中配置代码生成规则
@ConfigurePigeon(PigeonOptions(
  dartOut: 'lib/src/messages.g.dart',
  kotlinOut: 'android/app/src/main/kotlin/com/example/sdk/Messages.g.kt',
  swiftOut: 'ios/Runner/Messages.g.swift',
))

// 2. 定义强类型数据模型
class MeasurementConfig {
  late String patientId;
  late String deviceSn;
}

// 3. 定义 Flutter 调用原生的接口
@HostApi()
abstract class DeviceApi {
  Future<void> startMeasurement(MeasurementConfig config);
  Future<void> stopMeasurement();
}

3. 执行代码生成

在终端运行生成命令。由于已在 Dart 文件中配置了 @ConfigurePigeon，命令被大幅简化：

bash 复制代码

flutter pub run pigeon --input pigeons/messages.dart

执行后，Pigeon 会自动生成 Dart 调用代理类以及 Android/iOS 的原生接口模板。

4. 原生端实现与通道注册

这是最关键的一步。 原生端需要创建具体的业务实现类（如 DeviceApiImpl），去继承或实现 Pigeon 生成的接口，并在其中对接底层的 BLE 硬件和 C++ 算法。随后，在原生应用的生命周期起点（如 MainActivity 或 AppDelegate）调用生成的 setup 方法，完成通信通道的激活与注册。

二、标准项目结构设计

为了保证 SDK 的高内聚低耦合，建议采用以下目录结构，将"接口契约"、"生成代码"与"业务实现"严格物理隔离：

text 复制代码

medical_hardware_sdk/
├── pigeons/                      # 接口协议定义目录（仅包含声明，不含实现）
│   └── messages.dart             # Pigeon 接口定义文件（含 @ConfigurePigeon 配置）
│
├── lib/                          # Flutter 业务代码目录
│   ├── src/
│   │   └── messages.g.dart       # Pigeon 自动生成的 Dart 代码（直接调用即可）
│   └── device_sdk.dart           # SDK 对外暴露的 Dart API 抽象层
│
├── android/                      # Android 原生端目录
│   └── app/src/main/kotlin/com/example/sdk/
│       ├── Messages.g.kt         # 自动生成的 Kotlin 接口模板（勿修改）
│       ├── DeviceApiImpl.kt      # 核心：手写的业务实现类（对接 BLE 和 C++ 算法）
│       └── MainActivity.kt       # 注册通道入口（调用 DeviceApiImpl.setup(...)）
│
├── ios/                          # iOS 原生端目录
│   └── Runner/
│       ├── Messages.g.swift      # 自动生成的 Swift 协议模板（勿修改）
│       ├── DeviceApiImpl.swift   # 核心：手写的业务实现类（对接 CoreBluetooth 等）
│       └── AppDelegate.swift     # 注册通道入口（调用 DeviceApiImpl.setup(...)）
│
└── pubspec.yaml                  # 项目依赖配置

三、核心注意事项与避坑指南

在实际工程落地中，以下几点必须严格遵守：

绝对禁止修改生成文件 ：所有带 .g 后缀的文件（如 messages.g.dart、Messages.g.kt）均由工具自动生成。每次执行生成命令都会被完全覆盖，业务逻辑必须写在独立的 Impl 实现类中。
pigeon 依赖不可删除 ：pigeon 必须始终保留在 dev_dependencies 中。它相当于"模具"，当接口发生变更时，团队其他成员或 CI/CD 流水线仍需依赖它来重新生成最新的通信代码。
接口定义文件的纯粹性 ：pigeons/messages.dart 只能包含接口声明和数据模型定义，绝对不能包含任何方法的具体实现逻辑。
高频数据流的特殊处理 ：对于医疗硬件的实时波形数据，建议使用 Pigeon 的 @EventChannelApi 或配合原生的 EventChannel 进行单向高频推送，避免在 @HostApi 中频繁调用导致性能瓶颈。
保持双端代码同步：每次修改 Dart 接口定义后，必须重新执行生成命令，并确保原生端实现类及时补全新增的接口方法，否则会导致编译报错。

通过 Pigeon 的强类型代码生成机制，我们可以彻底告别跨端通信中的"字符串魔法值"陷阱，为医疗级硬件 SDK 构建一条安全、高效、易维护的跨平台通信桥梁。

Flutter Pigeon 跨端通信实战指南