简介Guava-Event-Bus 是一份针对 Guava 18.0 版本 EventBus 的源码学习笔记面向想深入理解发布/订阅框架的 Java 开发者。笔记从背景与功能入手解析 EventBus 如何通过解耦发布者和订阅者简化事件传递并说明 AsyncEventBus 异步机制、Executor 线程控制以及 AllowConcurrentEvents 注解的适用场景帮助读者掌握事件总线设计思路与 Guava 源码风格。资源共 26 个文件以 15 个 Java 源文件为核心配合 6 张 PNG 流程示意图、3 份 UML 类图、1 份 Markdown 说明和 Maven 配置覆盖注册、注销、发布事件的完整调用链路图文结合便于按图索骥。整体约 775KB体量轻量、目录清晰适合利用零散时间精读。当前已有 1897 人学习下载无论用于框架源码研究、事件驱动设计参考还是 Guava 内部机制排查都具备不错的参考价值。1. 事件总线为什么一行注解就能让两个毫不相关的类对话在大型 Java 服务里最折磨人的不是算法而是对象之间那套越缠越紧的调用关系。A 组件要通知 B 更新B 又要通知 C 刷新缓存C 出错了还要回调 A 回滚——代码里到处是手动维护的监听器列表每个注册点都要自己写增删改查稍不注意就整出内存泄漏。Guava 的 EventBus 给出的答案是你只要在方法上标一个Subscribe再调用eventBus.post(event)事件就能自动找到所有关心它的方法。这不仅省掉了大量样板代码更把「谁关心什么」的耦合从编译期搬到了运行时。但这个机制能 work靠的不是什么玄学。注解不会自己跑去注册事件也不会长腿自己找监听器。背后是三个精密配合的组件一个SubscriberRegistry负责在注册时扫描并缓存所有订阅方法一个Dispatcher负责把事件按分发策略送到对应的订阅者手上一个Subscriber包装层负责反射调用、异常捕获和线程调度。把这套设计的底层逻辑拆开你就会发现自己手动写的监听器框架究竟在哪些地方埋了雷而 EventBus 又是怎么用工程化方式把这些雷排掉的。2. 订阅注册机制注解扫描背后的数据结构与缓存设计2.1 注册时的核心动作不是只存一个对象而是拆成一条条订阅关系当你调用eventBus.register(object)时它把工作全部委托给了内部的SubscriberRegistry。很多人会以为这就像往一个Map里扔一个对象那么简单但实际上它做的是反射遍历这个类的整个继承体系找出所有标注了Subscribe的方法然后把「事件类型 → 订阅者包装对象」这条映射关系存起来。// Guava SubscriberRegistry 中的核心存储结构 private final ConcurrentMapClass?, CopyOnWriteArraySetSubscriber subscribers Maps.newConcurrentMap();这里的对象不是一个简单的监听器而是一个Subscriber包装层。它保存了三个关键信息监听器实例本身、被Subscribe标注的方法、以及所属的 EventBus。为什么这么设计因为同一类里可能有两个方法分别订阅不同类型的事件如果不拆开你就只能把一个对象整体绑定到某一种事件类型上那多订阅类型就只能靠重复注册来解决了。拆成Subscriber粒度之后每个方法独立匹配、独立分发、独立处理异常语义非常清楚。2.2 方法扫描与校验为什么强制只有一个参数SubscriberRegistry在构造时对整个类层次做方法收集用的是TypeToken.of(clazz).getTypes()这可以拿到类本身、所有父类和接口的TypeToken。对每个方法它会检查Subscribe注解并做参数个数校验// Guava Subscriber 构造时的参数校验逻辑 checkArgument(subscriberMethod.getParameterTypes().length 1, Method %s must have exactly 1 parameter, subscriberMethod);这个校验是硬性的因为事件总线的语义就是「发布一个事件对象所有订阅者消费它」。如果允许两个参数那第二个参数代表什么监听器实例已经在注册时确定了没理由再传一遍事件源信息也不是post时能提供的。所以单参数是唯一自洽的设计它不仅简化了反射调用的复杂度还让事件类型匹配变成了纯粹的Class比较问题。我一般会这么理解Subscribe方法的参数类型就是这个方法的事件过滤器。比如参数是OrderEvent那么只有post(new OrderEvent(...))时这个方法才会被触发。运行时匹配只关心参数的Class关联的是SubscriberRegistry里的MapClass?, SetSubscriber这个映射。2.3 CopyOnWriteArraySet 的选择读多写少的并发场景SubscriberRegistry用CopyOnWriteArraySet来存储同一事件类型下的所有订阅者这是个很有讲究的选择。订阅者的注册和反注册通常发生在启动阶段或配置变更时频率很低而事件发布是业务主路径频率极高。CopyOnWriteArraySet的底层是CopyOnWriteArrayList写操作会复制整个数组开销很大但读操作不加锁直接遍历旧数组的副本并发性能极好。// CopyOnWriteArraySet 的 add 操作会创建新数组每次注册都是 O(n) 复制 public boolean add(E e) { return al.addIfAbsent(e); // 内部是 ReentrantLock 数组全量复制 }这就是典型的「写少读多」场景下的取舍。如果换成ConcurrentHashMap的 key 对应的普通Set并发遍历时可能出现脏读或者需要加锁影响分发性能如果换成同步HashSet每次post时所有读操作都会被锁阻塞在高频事件场景下就是灾难。EventBus 这里的选择是在注册时多付一点复制成本换分发路径的无锁读非常划算。2.4 register 同一个实例两次是幂等还是重复消费必须注意一个问题同一个实例上标了Subscribe的方法如果对同一个 EventBus 实例register两次那么每次post事件这个监听器方法会被调用两次。因为CopyOnWriteArraySet的去重是按Subscriber对象相等性判断的而Subscriber的equals和hashCode沿用了默认的Object实现。每次register都会new Subscriber(instance, method)是两个不同的对象。// Subscriber 没有重写 equals/hashCode所以每次 register 都是新对象 final class Subscriber { private final Object target; private final Method method; // equals/hashCode 是 Object 的默认实现基于对象地址 }这里有个常见的翻车点有人以为 EventBus 做了「同一个监听器只注册一次」的去重于是在初始化流程里重复register导致线上事件被重复执行。标准做法是在初始化流程的最外层确保每个监听器在同一个 EventBus 上只注册一次或者用状态位标记而不是依赖注册表去重。3. 事件分发机制从 post 到 method.invoke 的完整链路3.1 post 的入口逻辑先拆事件类型再逐个找订阅者EventBus.post(Object event)是整个核心它做的事情比看起来要多得多。post不是简单地从Map里 get 一次就完事而是要遍历事件的整个继承链把所有能处理这个事件的订阅者全部找出来。public void post(Object event) { // 1. 把事件类的所有父类和接口都摊平 SetClass? eventTypes SubscriberRegistry.flattenHierarchy(event.getClass()); boolean dispatched false; // 2. 对每个类型从注册表里找订阅者 for (Class? eventType : eventTypes) { SetSubscriber wrappers subscribers.get(eventType); if (wrappers ! null !wrappers.isEmpty()) { dispatched true; dispatcher.dispatch(event, wrappers); } } // 3. 如果没有任何订阅者包装成 DeadEvent 再发一次 if (!dispatched !(event instanceof DeadEvent)) { post(new DeadEvent(this, event)); } }代码里最容易被忽略的是flattenHierarchy。post一个AppleEvent如果它继承自FruitEvent那么订阅了FruitEvent的方法也会收到这个事件。这是通过把AppleEvent的整个继承链全部摊平成一组Class实现的包括父类、祖类、以及实现的接口。这意味着事件分发天然支持多态发布者不需要知道订阅者关心的是哪个粒度的事件。3.2 Dispatcher 的三种实现这里藏着并发和重入问题的关键Dispatcher是真正派发动作的执行者它有三种实现对应不同的分发策略。跟直觉相反Guava 默认使用的不是简单粗暴的「拿到订阅者就调用」而是一个带队列和重入保护的精巧机制。// PerEventQueuedDispatcher 的核心线程局部变量标记 并发队列 private final ThreadLocalBoolean dispatching new ThreadLocalBoolean() { Override protected Boolean initialValue() { return false; } }; private void enqueueEvent(Object event, SetSubscriber subscribers) { for (Subscriber subscriber : subscribers) { queue.add(new EventWithSubscriber(event, subscriber)); } }每个线程维护一个dispatching标志如果当前线程已经在分发事件那么再往同一个线程post新事件比如订阅者方法里又调用了post事件不会立刻递归分发而是进入队列排队。等当前这一批事件分发完之后再从队列里取出来一个个处理。这个设计的核心价值在于它防止了深层递归调用栈。如果事件 A 的订阅者发布了事件 BB 的订阅者又发布了事件 C不做队列保护的话调用栈可能几十层深既容易栈溢出又让异常排查变成噩梦。3.3 为什么选队列而不是递归重入保护背后的工程智慧想象一下不加保护的场景每次post都立即同步调用所有订阅者订阅者在处理过程中又post新事件就会形成post → invoke → post → invoke的递归链。如果这个链足够长StackOverflowError是必然的。PerEventQueuedDispatcher 的做法是第一个事件直接处理后续的重入事件全部queue.add处理完当前事件后统一从队列里轮询。void dispatch(Object event, SetSubscriber subscribers) { enqueueEvent(event, subscribers); if (!dispatching.get()) { dispatching.set(true); try { EventWithSubscriber e; while ((e queue.poll()) ! null) { e.subscriber.dispatchEvent(e.event); } } finally { dispatching.set(false); } } }这其实是把递归改写成了队列 循环把系统调用栈换成了堆上的队列数据结构。好处显而易见无论多少层重入调用栈深度恒定不会爆栈而且同一线程的事件严格按照「先进先出」的顺序处理不会出现后发布的事件反而先执行的情况。3.4 异步分发executor 在哪里插入Subscriber.dispatchEvent是真正执行反射调用的地方它引入了executor。默认情况下EventBus用的是MoreExecutors.directExecutor()也就是在调用线程同步执行。但EventBus也提供了asyncEventBus允许你传入一个线程池把每个订阅者方法的调用丢到线程池里异步执行。void dispatchEvent(final Object event) { // executor 可以是 directExecutor 也可以是线程池 executor.execute(new Runnable() { Override public void run() { try { invokeSubscriberMethod(event); } catch (InvocationTargetException e) { bus.exceptionEvent(e.getCause(), context(event)); } } }); }这里有个很隐蔽的设计点异步模式下队列机制已经保证了解耦而 executor 只负责「订阅者方法在哪个线程跑」不负责去重或不丢事件。线程池的阻塞队列本质上成了另一个缓冲层。所以异步模式下事件的顺序性不再保证多个订阅者可能在多个线程并发执行——如果你的业务逻辑依赖事件的先后顺序异步模式是有风险的。一个常见的踩坑点是有人用asyncEventBus后发现事务回滚失效了。因为post方法立刻返回了订阅者方法里的数据库操作在其他线程执行脱离了你外层方法的事务上下文。这种问题排查起来极其隐蔽唯一的办法是在设计阶段就明确「同步事务边界」和「异步解耦」不能混用。4. 继承匹配与注销机制flattenHierarchy 和 unregister 的边界4.1 flattenHierarchy 的实现细节TypeToken.getTypes 的语义SubscriberRegistry.flattenHierarchy看似简单但它依赖TypeToken的getTypes()来返回类型层次。这个结果是个ImmutableSet天然去重也就是说如果一个类既在父类链上又在接口链上出现常见的菱形继承它只会被收录一次。private ImmutableSetClass? flattenHierarchy(Class? concreteClass) { ImmutableSet.BuilderClass? builder ImmutableSet.builder(); for (TypeToken? type : TypeToken.of(concreteClass).getTypes()) { builder.add(type.getRawType()); } return builder.build(); }getTypes()返回的顺序是先自身、再父类、再接口。这个顺序很重要吗对于同一条继承链上的订阅者来说如果父类和子类都订阅了同一个事件post子类事件时两个订阅者都会收到但子类订阅者先执行。如果你的业务里有「父处理完子再处理」的隐含依赖这个顺序反而是反直觉的——父类订阅者会先被遍历到先执行。4.2 监听器继承父类的 Subscribe 方法会被子类实例触发很多人在register时忽略了一个事实如果你的监听器类继承了某个父类而父类里有一个Subscribe方法那么注册子类实例时父类的那个方法也会被收集进来。因为前面提到的方法扫描是TypeToken.of(clazz).getTypes()它会遍历父类。这可能带来意外行为。class BaseListener { Subscribe public void onBase(BaseEvent event) { ... } } class ChildListener extends BaseListener { Subscribe public void onChild(ChildEvent event) { ... } } // registry 在收集时会同时找到 onBase 和 onChild eventBus.register(new ChildListener());这究竟算特性还是坑取决于你怎么用。如果你的BaseListener里本来就有通用的处理逻辑比如日志打印那子类实例复用无可厚非但如果你的父类里有一个方法只是恰好叫onXXX且被你标了注解它就会在子类注册时被意外触发。我见过的一次线上事故就是这个原因一个基类里有Subscribe方法用于测试桩被业务子类继承后测试桩逻辑在线上环境被触发了。4.3 unregister 为什么要求「必须精确匹配」unregister的设计比register更严格这一点很多人没注意。register是幂等的当然同一实例重复注册会重复消费但unregister要求你传入的对象必须能精确匹配到注册表里已有的订阅关系否则直接抛IllegalArgumentException。public void unregister(Object object) { // 遍历该对象类的所有类型从注册表中移除对应的订阅者 for (Class? eventType : SubscriberRegistry.flattenHierarchy(object.getClass())) { SetSubscriber wrappers subscribers.get(eventType); if (wrappers ! null) { for (Subscriber subscriber : wrappers) { if (subscriber.target object) { // 这里比较的是实例引用 wrappers.remove(subscriber); } } } } }这里的坑是如果你在register之后修改了监听器对象的某个字段导致hashCode变化假设你重写了 hashCode 但没重写 equals那unregister时可能因为equals匹配失败而找不到对应的Subscriber。所以对放入 EventBus 的监听器一个安全习惯是不要重写hashCode/equals或者保证这些方法基于不变字段实现。4.4 DeadEvent没人接的事件去了哪里聊完继承和注销必须提一下DeadEvent。post的事件如果没有任何订阅者包括没有订阅其任何父类或接口类型的监听器就会被包装成DeadEvent重新post一次。这是一个非常容易引起死循环的设计点如果你在DeadEvent的订阅方法里又post了原始事件就会无限递归。public static class DeadEvent { private final EventBus source; // 来自哪个总线 private final Object event; // 原始事件对象 } // 危险写法在 DeadEvent 订阅里重新 post 原始事件 Subscribe public void onDead(DeadEvent deadEvent) { eventBus.post(deadEvent.event); // 如果原始事件还是没人订阅会再次产生 DeadEvent }正确做法是在DeadEvent订阅方法里只做记录或告警不要再把原始事件丢回去。否则每次没人处理的事件都会造成一次额外的总线往返而且每一轮都会触发一次日志错误线上日志量直接爆炸。我自己就见过这种代码把日志系统打到 OOM 的。5. 常见问题排查指南EventBus 使用中的三个典型事故现场5.1 现象订阅方法没被调用但 register 明明执行了最气人的排查就是这种方式——代码确实执行了register也标了Subscribe但post之后方法像没听见一样。原因通常有两类一类是eventBus的实例不一致。比如你在两个地方分别new EventBus()往 A 实例注册往 B 实例post那么 A 里的订阅者自然是收不到的。解决方案是把一个 EventBus 实例放在全局单例或 Spring 容器里所有组件通过依赖注入拿到同一个对象。另一类原因是事件类型的继承关系处理错了。post(new ChildEvent())但监听方法参数是ParentEvent。这种情况按理说 EventBus 支持但如果ChildEvent是一个内部类它的getClass()是Outer$ChildflattenHierarchy 会把它自身、Outer里的父类链都跑一遍可如果你的 ParentEvent 根本不在 ChildEvent 的继承链上匹配失败自然不触发。所以排查这类问题第一个动作是在post入口打印event.getClass()和它的父类链确认监听方法的参数类型真的在这个链上。5.2 现象register 了同一个对象两次事件被重复处理这个我在前面提过但值得放进排查清单里。表现是每次post事件监听方法被调用两次且两次执行上下文完全一致。原因是Subscriber.equals没有重写重复 register 产生了两个不同的Subscriber实例。排查方式是在post时对subscribers.get(eventType)打印 size如果 size 大于预期就能定位到重复注册的源头。解决方法是检查初始化的调用路径确保在应用生命周期中每个监听器只注册一次。5.3 现象订阅方法抛异常后主流程的表现完全不一致这是最玄学的一类问题同步模式下订阅方法如果抛了 RuntimeException会通过SubscriberExceptionContext被SubscriberExceptionHandler捕获默认 handler 是LoggingHandler把异常和上下文打日志。主流程post不抛这个异常所以看起来像被吞掉了。如果你在同步模式下想「监听器失败就回滚主流程」EventBus 默认做不到因为它定位就不是强一致性消息系统。private static final class LoggingHandler implements SubscriberExceptionHandler { public void handleException(Throwable exception, SubscriberExceptionContext context) { // 只打 error 日志不往外抛 } }异步模式下情况更糟异常发生在线程池线程里连业务线程都感知不到。解决方法是自定义SubscriberExceptionHandler在回调里把异常信息透传到你的监控告警系统。另一个方案是让订阅方法捕获异常后把结果写入一个可查的存储比如数据库表或内存队列主流程在post之后按需轮询结果。我从那以后给自己定了个规矩EventBus 只做事件通知不做结果回传要回传结果就显式走方法调用或消息队列。5.4 现象asyncEventBus 模式下事件顺序乱了用asyncEventBus时如果你传的是一个单线程线程池事件在多数情况下还是有序的但如果用了多线程线程池两个关联事件的执行顺序就是完全随机的。比如「下单事件」和「扣库存事件」先后post可能扣库存先执行、下单后执行业务直接出乱子。这不是 EventBus 的缺陷而是异步的固有代价。解决方案是有顺序依赖的事件用同步EventBus或者把有依赖关系的操作合成一个事件类型让订阅者在一次调用里完成所有步骤。6. 设计取舍简单接口背后的每一条分叉路都是选择把所有源码展开之后最值得琢磨的反而不是某个数据结构的细节而是 Guava 对事件总线做的几个关键取舍。第一个选择是默认同步。很多初学 EventBus 的人第一反应是「事件总线应该异步解耦」但 Guava 的EventBus默认是directExecutor同步执行。这个选择背后是「机制简单、语义明确、便于排查」的哲学同步执行时post返回就意味着所有订阅者执行完毕调用栈完整保留异常上下文清晰单元测试不需要等待或 mock 线程池。异步是显式选择的进阶用法需要自己承担顺序乱、事务分离、异常难追踪的后果。第二个选择是把「监听器是否有 parent」这件事做成类型系统的一部分而不是由用户在注册时手动声明。如果你自己手写监听管理器通常需要用户传入要监听的类型而 Guava 通过Subscribe方法参数类型自动推导注册时的flattenHierarchy把类型匹配统一交给Class比较让用户不感知类型继承的存在。这减少了 API 的认知负担但代价是如果你想要「严格精确匹配、不触发父类订阅」EventBus 做不到你必须自己筛选事件类型。第三个选择是队列而不是递归处理重入事件。这个我之前从栈深度角度说过它同时也保证了同一线程内的事件处理顺序不会因为重入而被穿插打乱。代价是事件不会「立刻」被第二个订阅者处理必须等到当前订阅者方法返回。如果某个订阅者方法执行时间很长后续重入事件全被堵在后面这个特性你迟早会遇到。从那以后我每次选型都会先把默认策略、异常策略、顺序保证这三件事问清楚而不是只看文档里那句「简单好用」。EventBus 的价值不在于「异步」或「高性能」而在于它用极小的 API 面把发布订阅这个模式做得可预测、可排查。希望帮到你。本文还有配套的精品资源点击获取