EventBus 使用与特性总览

EventBus 优化实践：在 Flutter 中实现高性能、类型安全的事件总线

面向正在使用或考虑使用事件总线进行跨模块通信的移动开发团队，本文总结了我们对 EventBus 的优化设计与落地经验，包含架构目标、核心实现、性能优化、迁移指南与压测方法。

阅读引导：

• 如果你只想快速使用，请先看“快速上手”，再按需浏览架构与思想章节。

摘要

• 通过类型安全的事件模型、同步/异步分发分流、订阅优先级和生命周期治理，显著降低事件耦合与性能抖动。
• 引入粘性事件（sticky）、一次性订阅（once）、过滤器（where）与可选的节流/防抖，提升易用性与可维护性。
• 在高频事件与批量分发场景中，优化版 EventBus 相比旧版延迟更低、卡帧更少，压测显示在常见场景下性能和稳定性均有提升。

目录

• 快速上手
• 背景与痛点
• 设计目标
• 软件设计思想
• 架构设计概览
• 架构图与时序图
• 参考实现（精简版）
• 事件定义与使用示例
• 性能优化策略
• 压测方法与样例结果
• 迁移指南
• 常见坑位与最佳实践
• 未来规划
• 附录：节流/防抖包装示例

快速上手

• 安装与引用：直接使用入口 EventBus.I，示例见下文“事件定义与使用示例”。
• 常见需求：
  • 获取最近状态：用 emitSticky 发布状态类事件，on<T> 订阅时将自动回放最近一次。
  • 仅首次触发：用 once: true 或 EventBus.I.once<T>() 监听一次后自动解绑。
  • 高频限制：在监听侧使用防抖/节流包装（见“附录”或在 event_bus.dart 的便捷 API）。
• 解绑建议：在 State.dispose 调用 offByOwner(this)，或保存 token 后 off(token)。

术语与约定（Glossary）

• 事件（Event）：extends Event 的强类型载体，代表一种消息语义。
• 粘性事件（Sticky）：保留最近一次事件，后订阅者会立即收到回放。
• 一次性订阅（Once）：首个事件处理后自动解绑，避免泄漏。
• 订阅所有者（ownerKey）：用于批量解绑的标识，推荐传 this（State 实例）。
• 背压（Backpressure）：对高频事件进行限速（节流/防抖）以维持可预测性。

背景与痛点

• 事件耦合高：字符串事件或动态类型易误用，错误不易被及时发现。
• 性能瓶颈：大量广播时重复拷贝、无队列策略容易阻塞 UI 导致卡帧。
• 泄漏风险：订阅未解绑，页面销毁后仍接收事件。
• 可测试性差：缺少可控调度与可观察点，难以压测和定位问题。

设计目标

• 类型安全：用泛型限定事件类型，避免动态错用。
• 高性能：同步分发用于轻量快速路径，异步分发通过微任务队列避免阻塞主线程。
• 可维护：统一订阅管理，支持自动解绑与一次性订阅。
• 易扩展：支持粘性事件、优先级、过滤器、节流/防抖等能力。

软件设计思想

• 目标导向：以“跨模块消息传递的稳定性与可预测性”为核心目标，优先保障事件语义一致与运行时治理能力，而非追求极端吞吐。
• 抽象与隔离：将“事件定义、订阅管理、分发策略、生命周期治理”分离，避免单一类承载过多职责；通过命名空间或多实例支持上下文隔离。
• 类型与契约：用泛型与强类型事件定义约束生产者与消费者的契约，减少字符串/动态事件导致的隐式耦合与运行期错误。
• 性能与可预测性：同步/异步分流、微任务队列与 Copy-on-read 快照，让分发成本与 UI 流畅度可预测；对高频事件引入节流/防抖以进行背压控制。
• 生命周期治理：订阅显式可取消（Token）、按所有者批量解绑、一次性订阅自动回收，降低页面销毁后的泄漏风险。
• 可观测性：为分发异常与取消路径预留埋点/日志钩子，建议结合 Timeline 或自定义指标进行运行时观测与压测。
• 扩展性与演化：粘性事件作为状态类信息的最近值回放；优先级、过滤器作为可插拔能力，后续可引入队列长度限制与丢弃策略。
• 一致性与约束：明确粘性事件仅保存“最后一次”，避免维护列表；订阅优先级只影响回调顺序，不承担权限或路由职责。
• 失败优先策略：分发异常不应吞掉，至少做降级与记录；生产者应保证事件幂等或可重试，消费者避免产生不可逆副作用。
• 测试驱动：针对类型、生命周期与高频场景编写单元测试与基准测试，保证在演进中不破坏既有契约与性能边界。

架构设计概览

• 事件模型：按类型维护订阅表 Map<Type, List<Subscriber>>，订阅项包含处理器、优先级、过滤器与一次性标记。
• 分发策略：
  • 同步分发 emitSync：当前帧内快速调用，适用于轻量事件；
  • 异步分发 emit：通过 scheduleMicrotask 进入微任务队列，避免阻塞 UI；
  • 粘性分发 emitSticky：保留最新事件并在订阅时立即回放；
  • 背压控制：可选的节流/防抖，对高频事件进行限速。
• 生命周期治理：
  • 令牌化取消 SubscriptionToken；
  • 按 ownerKey 批量解绑（推荐在 State.dispose 中调用）；
  • 一次性订阅在首个事件后自动解绑。

架构图与时序图

事件总线架构图（Mermaid）

flowchart LR
  subgraph Producers[Event Producers]
    A[UI/Service] -->|emit/emitSync| EB
    B[Background Tasks] --> EB
  end

  subgraph EB[EventBus]
    Q[(Sticky Store / Clipboard-like)]
    M[Microtask Queue]
    S[Subscriptions Map]
  end

  EB -->|dispatch| C1[Subscriber #1]
  EB -->|dispatch| C2[Subscriber #2]

  A -.->|emitSticky| Q
  Q -->|replay on subscribe| S

  A -->|emit| M -->|schedule| S
  A -->|emitSync| S

  style Q fill:#ffe,stroke:#cc9
  style M fill:#eef,stroke:#99c
  style S fill:#efe,stroke:#9c9

图示说明：

• 生产者通过 emit/emitSync/emitSticky 进入 EventBus；异步分发经由微任务队列，粘性事件写入“最近值”存储（剪贴板式，仅保留最后一次）。
• 订阅表按类型组织；订阅时若存在粘性值则立即回放，随后正常参与分发流程。

分发与一次性订阅时序图

sequenceDiagram
  participant P as Producer
  participant EB as EventBus
  participant S1 as Subscriber(once)
  participant S2 as Subscriber

  P->>EB: emit(Event)
  EB-->>EB: scheduleMicrotask
  EB->>S1: handler(event)
  S1-->>EB: off(token) (auto)
  EB->>S2: handler(event)

  Note over EB,S1: once 订阅在首个事件处理后自动解绑

图示说明：

• emit 将事件排入微任务队列，随后按优先级分发到订阅者；标记为 once 的订阅在首次处理后自动调用 off。

订阅生命周期状态图

stateDiagram-v2
  [*] --> Created
  Created --> Active: added to Subscriptions Map
  Active --> Consumed: once=true & first event received
  Consumed --> Disposed: auto off
  Active --> Disposed: manual off / ownerKey off
  Disposed --> [*]

图示说明：

• 订阅创建后进入活跃态；once 在首个事件后进入“已消耗”并自动释放；也可通过手动解绑或按所有者批量解绑进入“释放”终态。

参考实现（精简版）

你可以将下述实现与现有 ebike_core/lib/src/utils/event_bus.dart 对照迁移。

import 'dart:async';

abstract class Event {}

typedef EventHandler<T extends Event> = void Function(T event);

class SubscriptionToken {
  final Type type;
  final Object? ownerKey;
  final EventHandler handler;
  final bool once;
  SubscriptionToken(this.type, this.handler, {this.ownerKey, this.once = false});
}

class EventBus {
  EventBus._();
  static final EventBus I = EventBus._();

  final Map<Type, List<_Subscriber>> _subs = {};
  final Map<Type, Event> _sticky = {};
  bool _shutdown = false;

  SubscriptionToken on<T extends Event>({
    required EventHandler<T> handler,
    Object? ownerKey,
    bool once = false,
    int priority = 0,
    bool Function(T e)? where,
  }) {
    final type = T;
    final sub = _Subscriber(
      token: SubscriptionToken(type, (e) => handler(e as T), ownerKey: ownerKey, once: once),
      priority: priority,
      where: (e) => where == null ? true : where(e as T),
    );
    final list = _subs.putIfAbsent(type, () => <_Subscriber>[]);
    list.add(sub);
    list.sort((a, b) => b.priority.compareTo(a.priority));
    // 粘性事件回放
    final se = _sticky[type];
    if (se != null && (where?.call(se as T) ?? true)) {
      handler(se as T);
      if (once) { off(sub.token); }
    }
    return sub.token;
  }

  void off(SubscriptionToken token) {
    final list = _subs[token.type];
    if (list == null) return;
    list.removeWhere((s) => identical(s.token, token));
    if (list.isEmpty) { _subs.remove(token.type); }
  }

  void offByOwner(Object ownerKey) {
    _subs.forEach((type, list) {
      list.removeWhere((s) => s.token.ownerKey == ownerKey);
    });
    _subs.removeWhere((_, list) => list.isEmpty);
  }

  // 同步分发：快速路径
  void emitSync<T extends Event>(T event) {
    if (_shutdown) return;
    final list = _subs[T]?.toList(growable: false);
    if (list == null || list.isEmpty) return;
    for (final s in list) {
      try {
        if (s.where == null || s.where!(event)) {
          s.token.handler(event);
          if (s.token.once) off(s.token);
        }
      } catch (e, st) {
        // 建议在此进行异常上报/埋点
      }
    }
  }

  // 异步分发：微任务队列
  void emit<T extends Event>(T event) {
    if (_shutdown) return;
    scheduleMicrotask(() => emitSync<T>(event));
  }

  // 粘性事件
  void emitSticky<T extends Event>(T event, {bool replayNow = true}) {
    _sticky[T] = event;
    if (replayNow) emit<T>(event);
  }

  void clearSticky<T extends Event>() => _sticky.remove(T);

  void shutdown() {
    _shutdown = true;
    _subs.clear();
    _sticky.clear();
  }
}

class _Subscriber {
  final SubscriptionToken token;
  final int priority;
  final bool Function(Event e)? where;
  _Subscriber({required this.token, this.priority = 0, this.where});
}

事件定义与使用示例

class LoginEvent extends Event {
  final String userId;
  LoginEvent(this.userId);
}

class BatteryChanged extends Event {
  final double percentage;
  BatteryChanged(this.percentage);
}

// 订阅
final token = EventBus.I.on<LoginEvent>(
  handler: (e) => print('login: ${e.userId}'),
  ownerKey: this, // 在 StatefulWidget 中传 this，方便 dispose 自动解绑
  priority: 10,
  where: (e) => e.userId.isNotEmpty,
);

// 一次性订阅
EventBus.I.on<BatteryChanged>(handler: (e) => print('first battery: ${e.percentage}'), once: true);

// 粘性事件：先发布，后订阅也能收到最近一次
EventBus.I.emitSticky(BatteryChanged(0.8));
EventBus.I.on<BatteryChanged>(handler: (e) => print('sticky: ${e.percentage}'));

// 分发
EventBus.I.emit(LoginEvent('u123'));
// 或同步分发（不推荐在重操作场景）
EventBus.I.emitSync(LoginEvent('u123'));

// 解绑
EventBus.I.off(token);
// 按所有者批量解绑（建议在 State.dispose 中调用）
EventBus.I.offByOwner(this);

性能优化策略

• 同步 vs 异步分发分流：轻量事件走同步，重量或批量事件走异步，避免阻塞 UI。
• 订阅表排序：按优先级降序，减少额外结构维护成本。
• 防抖/节流（可选扩展）：在 on<T> 使用调度器包装，避免高频触发导致抖动。
• 粘性事件回放走常量时间：仅保留最后一次，避免维护历史列表。
• Copy-on-read：分发时对订阅列表做快照，避免分发过程中修改影响遍历。

压测方法与样例结果（示例）

• 场景 A：1000 次轻量事件，单订阅
  • 旧版：平均约 2.1 ms/批次，偶发抖动
  • 优化版：平均约 1.2 ms/批次，抖动显著降低
• 场景 B：10000 次重量事件，5 个订阅
  • 旧版：UI 卡顿明显（主线程阻塞）
  • 优化版：异步分发下 UI 流畅，耗时由后台微任务承担
• 场景 C：高频事件（100 次/秒）
  • 增加节流至 10 次/秒后，CPU 使用率降低约 25%

压测建议：

• 在 dev profile 下，用 Timeline + dart:developer 或 Stopwatch 统计分场景数据；
• 将压测封装为 Benchmark Runner 或单元测试，避免主 APP 干扰；
• 固定设备与采样窗口，输出分布而非仅平均值。

更多 API 与使用示例：请参阅《EventBus 功能总览》文档 ./eventbus_features.md。

迁移指南

• 类型改造：将原有动态/字符串事件改为 extends Event 的类型。
• 订阅替换：将旧 subscribe('eventName', cb) 改为 on<ConcreteEvent>(handler: ...)。
• 粘性事件：旧版若使用“最后值缓存”，改为 emitSticky<T>(event) 并在订阅时自动回放。
• 生命周期治理：在 StatefulWidget 的 dispose 中调用 EventBus.I.offByOwner(this) 或持有 token 调用 off(token)。
• 错误处理：分发中的异常建议统一埋点上报，不要直接吞掉。

常见坑位与最佳实践

• 避免在高频同步事件里做重计算，尽量使用异步分发或节流。
• 粘性事件适用于状态类信息（如网络状态、电量），不适合“一次性命令”。
• 谨慎使用全局单例：如需隔离上下文（模块/子域），可以创建多实例 EventBus。
• 订阅优先级用于确定回调顺序，不要误用作权限控制。
• 警惕循环事件：处理器里再次发同类型事件且无条件，会导致无限循环。

未来规划

• Channel/命名空间：实现隔离，支持跨 isolate。
• 更丰富的调度器：内置 throttle/debounce、队列长度限制与丢弃策略。
• 可视化订阅拓扑：辅助排查复杂事件流。

附录：节流/防抖包装示例

typedef Clock = int Function();

EventHandler<T> throttle<T extends Event>(EventHandler<T> handler, Duration interval, {Clock? now}) {
  now ??= () => DateTime.now().millisecondsSinceEpoch;
  int last = 0;
  return (e) {
    final t = now!();
    if (t - last >= interval.inMilliseconds) {
      last = t;
      handler(e);
    }
  };
}

EventHandler<T> debounce<T extends Event>(EventHandler<T> handler, Duration interval) {
  Timer? timer;
  return (e) {
    timer?.cancel();
    timer = Timer(interval, () => handler(e));
  };
}