Skip to content

Latest commit

 

History

History
299 lines (231 loc) · 11.2 KB

event-system.md

File metadata and controls

299 lines (231 loc) · 11.2 KB
name springboot-starter/event-system
module springboot-starter
description 事件发布-订阅系统,支持同步/异步事件、事件循环检测、事务事件
status 已实现
scope 后端
source 项目自有
import com.codingapi.springboot:springboot-starter
symbols
EventPusher
IEvent
IHandler
ISyncEvent
IAsyncEvent
DomainEventContext
ApplicationHandlerUtils
SpringHandlerConfiguration
EventTraceContext
EventStackContext
content_hash f911f56fe4d24daddc91a560d340759aa3c208f085ebc0aca84954d8b8d4ae9a

解决什么问题

在 DDD(领域驱动设计)架构中,领域事件是实现聚合间解耦、触发副作用的核心机制。然而在实际开发中,事件系统面临以下痛点:

  1. 事件与主业务事务的边界模糊:开发者容易将事件处理与主业务强绑定,导致事务范围膨胀、性能下降。框架需要明确"事件对主业务可成功可失败"的设计原则。
  2. 同步与异步事件的区分困难:部分场景要求事件在同一事务内同步执行(如数据校验),部分场景则需异步解耦(如发送通知)。手动管理线程池和执行模式增加复杂度。
  3. 事件循环调用风险:当 Handler A 处理 EventX 时又推送了 EventY,而 EventY 的 Handler 又推送了 EventX,就会形成无限循环。缺乏自动检测机制会导致栈溢出或系统挂起。
  4. 多 Handler 执行的异常隔离:同一事件可能被多个 Handler 订阅,某个 Handler 抛异常不应影响其他 Handler 的执行,同时需要收集所有异常统一上报。
  5. Handler 注册与排序繁琐:手动注册处理器、维护执行顺序的代码分散且易出错。

本模块提供了一套完整的发布-订阅事件基础设施,通过 EventPusher 统一入口、IEvent 类型体系区分同步/异步、EventTraceContext + EventStackContext 实现事件链路追踪与循环检测、ApplicationHandlerUtils 自动匹配并按序分发 Handler,以及可选的事务提交后触发模式(SpringTransactionEventHandler)。

如何使用

核心接口

接口/类 说明
IEvent 事件标记接口,继承 Serializable。默认视为同步事件
ISyncEvent 同步事件标记接口,继承 IEvent。事件在当前线程同步执行
IAsyncEvent 异步事件标记接口,继承 IEvent。事件在线程池中异步执行
IHandler<T extends IEvent> 事件处理器接口,泛型 T 指定订阅的事件类型
EventPusher 事件推送静态工具类,是发布事件的唯一入口
@Handler 注解,标记一个类为事件处理器 Bean(也可使用 @Component/@Service)

IHandler 接口方法

public interface IHandler<T extends IEvent> {
    // 执行顺序,数值越小越先执行,默认为 0
    default int order() { return 0; }

    // 事件处理逻辑
    void handler(T event);

    // 异常回调,默认重新抛出异常(阻止后续 Handler 执行)
    // 可覆盖此方法实现异常吞没或自定义处理
    default void error(Exception exception) throws Exception {
        throw exception;
    }
}

事件推送

// 推送事件(自动根据 IEvent 子接口判断同步/异步)
EventPusher.push(new MyEvent(data));

// 显式声明允许循环事件(跳过循环检测)
EventPusher.push(new MyEvent(data), true);

事件类型的判定规则:

  • 实现 IAsyncEvent → 异步执行(线程池)
  • 实现 ISyncEvent → 同步执行(当前线程)
  • 仅实现 IEvent → 默认同步执行

配置项

# 同一 trace 内的异步事件是否按推送顺序串行执行(默认值 true)
# 关闭后退回完全并发行为,适合无顺序依赖、追求极致吞吐的场景
codingapi.framework.event.async.ordered=true

# 异步事件线程池大小(默认值 20)
codingapi.framework.handler-thread-pool-size=20

# 兼容旧配置:现已不再产生行为差异(事件默认即为事务提交后分发),可不配置
codingapi.framework.event.transaction.enable=true

事件分发模式

框架通过 SpringHandlerConfiguration 自动装配 SpringDefaultEventHandler。事件监听统一使用 @TransactionalEventListener(phase = AFTER_COMMIT, fallbackExecution = true):

  • 事务提交后分发:事件在事务提交后才触发,订阅方可读到已提交数据;事务回滚则事件不分发。
  • 无事务上下文:fallbackExecution = true 保证事件即时分发,行为与事务外推送一致。
  • SpringTransactionEventHandler 已标记为 @Deprecated,仅作为按类名注入的兼容别名保留,与 SpringDefaultEventHandler 行为完全一致;codingapi.framework.event.transaction.enable 不再产生行为差异。

顺序保证与 trace 归属

异步事件的串行维度是 traceId,同一 trace 内的异步事件严格按推送顺序串行执行,不同 trace 之间保持并行(线程池大小决定并发 trace 数)。traceId 的归属规则:

  1. handler 内嵌套 push:复用当前事件链的 traceId;
  2. 批量 push:调用 EventPusher.push(e1, e2, ...),整批共享一个 traceId,异步事件按参数顺序串行执行;
  3. 事务内连续 push:共享同一事务级 traceId(TransactionSynchronizationManager 绑定,afterCompletion 解绑,避免线程复用串 trace);
  4. 无事务的独立 push:每次新建独立 traceId,不保证顺序。

因此:

需要严格顺序时,请将事件置于事务内连续 push,或使用 EventPusher.push(a, b) 批量推送;无事务的独立 push 之间不保证顺序。串行维度是 trace(约等于单事务/单批次),同一聚合在两个并发事务中的事件之间仍无顺序保证,业务方若要求聚合级串行需自行按聚合键排队。

事件循环检测

框架通过 EventTraceContext 和 EventStackContext 实现同一条事件链路内的循环检测:

  1. 每次推送事件时生成/复用 traceId,将事件类压入该 traceId 对应的事件栈。
  2. 循环检测只对 handler 内嵌套 push 生效:若同一 traceId 下出现相同事件类,立即抛出 EventLoopException,并附带完整的事件调用栈信息。
  3. 业务线程中连续 push 的多个事件(批量或事务内)属于同一批次,即使同类也不会被误判为循环。
  4. 事件处理完成后自动清理 traceId 和事件栈;若确实需要允许 handler 内嵌套循环(如状态机重试),可调用 EventPusher.push(event, true) 跳过检测。

Handler 异常处理策略

当某个 Handler 抛出异常时:

  1. 若异常为 EventLoopException,直接向上抛出,终止后续所有 Handler。
  2. 否则调用该 Handler 的 error(exception) 回调。
  3. 若 error() 也抛出异常,标记为"有异常"并继续执行下一个 Handler。
  4. 所有 Handler 执行完毕后,若存在异常,统一包装为 EventException 抛出。

使用实例

1. 定义事件

package com.example.domain.order.event;

import com.codingapi.springboot.framework.event.ISyncEvent;
import lombok.Getter;
import lombok.AllArgsConstructor;

/**
 * 订单创建事件(同步)
 */
@Getter
@AllArgsConstructor
public class OrderCreatedEvent implements ISyncEvent {
    private final String orderId;
    private final String userId;
    private final long amount;
}
package com.example.domain.order.event;

import com.codingapi.springboot.framework.event.IAsyncEvent;
import lombok.Getter;
import lombok.AllArgsConstructor;

/**
 * 订单通知事件(异步)
 */
@Getter
@AllArgsConstructor
public class OrderNotifyEvent implements IAsyncEvent {
    private final String orderId;
    private final String message;
}

2. 编写事件处理器

package com.example.handler;

import com.codingapi.springboot.framework.event.IHandler;
import com.example.domain.order.event.OrderCreatedEvent;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

/**
 * 订单创建后扣减库存(优先执行)
 */
@Slf4j
@Service
public class InventoryDeductHandler implements IHandler<OrderCreatedEvent> {

    @Override
    public int order() {
        return 1; // 最先执行
    }

    @Override
    public void handler(OrderCreatedEvent event) {
        log.info("扣减库存, orderId={}, amount={}", event.getOrderId(), event.getAmount());
        // inventoryService.deduct(event.getOrderId(), event.getAmount());
    }
}
package com.example.handler;

import com.codingapi.springboot.framework.event.IHandler;
import com.example.domain.order.event.OrderCreatedEvent;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

/**
 * 订单创建后记录积分(其次执行)
 */
@Slf4j
@Service
public class PointsRecordHandler implements IHandler<OrderCreatedEvent> {

    @Override
    public int order() {
        return 2;
    }

    @Override
    public void handler(OrderCreatedEvent event) {
        log.info("记录积分, userId={}", event.getUserId());
        // pointsService.record(event.getUserId(), event.getAmount());
    }

    @Override
    public void error(Exception exception) {
        // 积分记录失败不影响其他 Handler,仅记录日志
        log.error("积分记录失败, 但不阻断流程", exception);
    }
}
package com.example.handler;

import com.codingapi.springboot.framework.event.IHandler;
import com.example.domain.order.event.OrderNotifyEvent;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

/**
 * 异步发送订单通知
 */
@Slf4j
@Service
public class OrderNotifyHandler implements IHandler<OrderNotifyEvent> {

    @Override
    public void handler(OrderNotifyEvent event) {
        log.info("发送通知, orderId={}, message={}", event.getOrderId(), event.getMessage());
        // notificationService.send(event.getOrderId(), event.getMessage());
    }
}

3. 在领域服务中推送事件

package com.example.domain.order.service;

import com.codingapi.springboot.framework.event.EventPusher;
import com.example.domain.order.event.OrderCreatedEvent;
import com.example.domain.order.event.OrderNotifyEvent;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class OrderService {

    @Transactional
    public String createOrder(String userId, long amount) {
        String orderId = generateOrderId();
        // ... 持久化订单实体 ...

        // 同步事件:在当前事务内执行库存扣减、积分记录
        EventPusher.push(new OrderCreatedEvent(orderId, userId, amount));

        // 异步事件:事务外异步发送通知
        EventPusher.push(new OrderNotifyEvent(orderId, "您的订单已创建"));

        return orderId;
    }
}

4. 启用事务事件模式(可选)

若希望所有事件都在事务提交后再触发(避免 Handler 读到未提交数据),在 application.properties 中添加:

codingapi.framework.event.transaction.enable=true

此时 SpringTransactionEventHandler 替代默认的 SpringDefaultEventHandler,所有事件将在 AFTER_COMMIT 阶段触发。