Disruptor 学习项目

基于 JDK 21 + Spring Boot 3 的 LMAX Disruptor 高性能学习项目，包含详细的中文注释和单元测试，便于深入学习和理解 Disruptor 框架的核心原理。

项目简介

本项目是一个完整的 Disruptor 学习示例，演示了 Disruptor 框架的核心功能和最佳实践。通过实际代码和详细注释，帮助开发者理解：

• RingBuffer 环形缓冲区的工作原理
• 事件发布-订阅模式
• 序列号（Sequence）机制
• 等待策略（WaitStrategy）的选择
• 多消费者并行/串行处理

技术栈

• JDK: 21
• Spring Boot: 3.5.0
• Disruptor: 3.4.4
• 构建工具: Maven
• 测试框架: JUnit 5

项目结构

disruptor-learn/
├── src/main/java/com/example/disruptor/
│   ├── event/
│   │   ├── OrderEvent.java          # 订单事件类
│   │   └── OrderEventFactory.java   # 事件工厂
│   ├── handler/
│   │   └── OrderEventHandler.java   # 事件处理器
│   ├── producer/
│   │   └── OrderEventProducer.java  # 事件生产者
│   ├── config/
│   │   └── DisruptorConfig.java     # Disruptor 配置
│   ├── controller/
│   │   └── OrderController.java     # REST API 控制器
│   ├── ringbuffer/
│   │   └── RingBufferDemo.java      # RingBuffer 核心演示
│   └── DisruptorLearnApplication.java
├── src/test/java/com/example/disruptor/
│   ├── DisruptorCoreFunctionalityTest.java  # Disruptor 核心功能测试
│   ├── RingBufferCoreTest.java              # RingBuffer 核心测试
│   └── WaitStrategyPerformanceTest.java     # 等待策略性能测试
└── pom.xml

快速开始

环境要求

• JDK 21 或更高版本
• Maven 3.6 或更高版本

编译项目

mvn clean compile

运行测试

mvn test

启动应用

mvn spring-boot:run

应用启动后，访问 http://localhost:8080

核心功能

1. Disruptor 核心功能

事件发布和消费

// 发布事件
OrderEventProducer producer = new OrderEventProducer(ringBuffer);
producer.publishEvent(orderId, amount, orderType);

// 消费事件
disruptor.handleEventsWith(new OrderEventHandler("订单处理器"));

多消费者处理

// 并行处理
disruptor.handleEventsWith(handler1, handler2, handler3);

// 串行处理
disruptor.handleEventsWith(handler1).then(handler2).then(handler3);

批量发布

// 批量获取序列号
long startSequence = ringBuffer.next(batchSize);

// 填充事件
for (int i = 0; i < batchSize; i++) {
    OrderEvent event = ringBuffer.get(startSequence + i);
    // 填充数据
}

// 批量发布
ringBuffer.publish(startSequence, batchSize);

2. RingBuffer 核心功能

环形数据结构

RingBuffer 使用固定大小的环形数组，通过位运算实现高效的索引计算：

// 序列号到索引的转换（位运算）
int index = (int) (sequence & (bufferSize - 1));

序列号机制

// 获取序列号
long sequence = ringBuffer.next();

// 获取事件对象
OrderEvent event = ringBuffer.get(sequence);

// 发布事件
ringBuffer.publish(sequence);

API 文档

创建单个订单

POST /api/orders
Content-Type: application/json

{
  "amount": 100.50,
  "orderType": "NORMAL"
}

批量创建订单

POST /api/orders/batch
Content-Type: application/json

{
  "count": 10,
  "amount": 50.0,
  "orderType": "BATCH"
}

查看系统状态

GET /api/orders/status

等待策略

Disruptor 提供多种等待策略，不同的策略在性能和 CPU 使用率之间有不同的权衡：

策略	CPU 使用	延迟	吞吐量	适用场景
BlockingWaitStrategy	低	高	高	通用场景
SleepingWaitStrategy	低	中	高	平衡场景
YieldingWaitStrategy	高	低	最高	低延迟场景
BusySpinWaitStrategy	极高	最低	最高	超低延迟
PhasedBackoffWaitStrategy	自适应	自适应	高	自适应场景

选择建议

• 通用场景: 使用 SleepingWaitStrategy，在性能和 CPU 使用之间取得平衡
• 低延迟场景: 使用 YieldingWaitStrategy，牺牲 CPU 使用率换取低延迟
• 超低延迟场景: 使用 BusySpinWaitStrategy，适用于对延迟极其敏感的场景
• 资源受限场景: 使用 BlockingWaitStrategy，最小化 CPU 使用

测试说明

项目包含 27 个单元测试，覆盖以下方面：

DisruptorCoreFunctionalityTest

• Disruptor 初始化测试
• 事件发布和消费测试
• 序列号机制测试
• 环形特性测试
• 多消费者并行处理测试
• 消费者串行处理测试
• 批量发布测试
• 不同等待策略测试
• 事件对象复用测试

RingBufferCoreTest

• RingBuffer 基本属性测试
• 序列号到索引转换测试
• 游标管理测试
• 剩余容量计算测试
• 环形循环特性测试
• 事件对象获取和设置测试
• 批量序列号分配测试
• 2的幂次方判断测试
• 序列号边界情况测试
• 事件对象预分配测试
• 序列号连续性测试

WaitStrategyPerformanceTest

• BlockingWaitStrategy 性能测试
• SleepingWaitStrategy 性能测试
• YieldingWaitStrategy 性能测试
• BusySpinWaitStrategy 性能测试
• PhasedBackoffWaitStrategy 性能测试
• 所有等待策略性能对比

运行测试：

# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=DisruptorCoreFunctionalityTest

# 运行特定测试方法
mvn test -Dtest=RingBufferCoreTest#testSequenceMechanism

核心概念

RingBuffer

RingBuffer 是 Disruptor 的核心数据结构，是一个固定大小的环形数组。它的特点：

• 预分配内存: 在初始化时预分配所有事件对象，避免运行时 GC
• 环形结构: 使用位运算实现高效的索引计算
• 无锁设计: 通过序列号机制实现线程安全，无需使用锁

Sequence

Sequence 是一个原子递增的序列号，用于：

• 追踪事件在缓冲区中的位置
• 协调生产者和消费者
• 实现无锁并发

WaitStrategy

WaitStrategy 决定消费者如何等待新事件，是 Disruptor 性能调优的关键参数。

EventFactory

EventFactory 用于在 Disruptor 初始化时预分配事件对象。

EventHandler

EventHandler 是消费者处理事件的接口，每个 EventHandler 在独立的线程中运行。

学习资源

• Disruptor 官方文档
• Disruptor 源码
• Disruptor 性能测试
• LMAX Disruptor 论文

最佳实践

1. 缓冲区大小: 必须是 2 的幂次方（如 1024, 2048, 4096）
2. 事件对象: 提供清晰的 clear() 方法，在事件被复用前清理数据
3. 等待策略: 根据实际场景选择合适的等待策略
4. 批量处理: 使用 endOfBatch 标志进行批量操作优化
5. 避免阻塞: 在 EventHandler 中避免执行阻塞操作

注意事项

• 所有代码都包含详细的中文注释和 @see 引用
• 测试覆盖了核心功能和边界场景
• 项目使用 JDK 21 和 Spring Boot 3.5.0
• 确保本地已安装 Maven（项目不包含 Maven Wrapper）

许可证

本项目仅用于学习目的，遵循 Disruptor 的 Apache 2.0 许可证。