OutboxPro 是面向 Spring Boot 的事务消息与 RabbitMQ 可靠消费组件。它解决“业务已提交、消息却没发出去”或“消息重复消费”的问题:业务方只需声明事件和编写 Handler,Outbox 落库、Relay 投递、Publisher Confirm、Inbox 幂等、重试、死信与观测由框架处理。
当前 V1 支持 Java 21 + Spring Boot 3.5.x + MySQL 8 + RabbitMQ + Spring JDBC + Jackson。
- 事务内发布:业务表与 Outbox 表在同一本地事务提交,Relay 在事务外投递并等待 Publisher Confirm。
- 至少一次投递 + Inbox 幂等:消费端以
consumerName + eventId去重,整体最终一致。 - 注解式声明:
@OutboxEvent+@OutboxHandler自动生成事件定义与订阅,启动期校验配置。 - 自动拓扑与重试:Exchange、Queue、Retry Queue、DLQ 自动声明;支持事件级重试策略与
@NonRetryable。 - 死信台账与重放:可选台账、分桶计数、告警通知,支持生产端 DEAD 与消费端死信人工重放。
- 可观测:Micrometer 积压 Gauge、耗时 Timer、Confirm 超时 Counter 与
/actuator/health健康检查。 - 容量与稳定性(V1.4):单实例多 Relay worker(
SKIP LOCKED)、空闲指数退避、租约恢复节流。 - 可扩展:Repository、Publisher、Serializer、拓扑、日志 Sink 等 SPI 可按需替换。
| 模块 | 职责 |
|---|---|
outboxpro-core |
不依赖具体中间件的领域模型与契约 |
outboxpro-spi |
Repository、Publisher、Serializer、日志 Sink 等扩展点 |
outboxpro-persistence |
Outbox Relay 与持久化无关状态模型 |
outboxpro-persistence-mysql |
MySQL 8 JDBC 实现与自动建表脚本 |
outboxpro-transport |
传输抽象 |
outboxpro-transport-rabbit |
RabbitMQ 发布确认、消费、拓扑、Retry Queue、DLQ |
outboxpro-observability |
消息生命周期日志与指标适配 |
outboxpro-spring-boot-autoconfigure |
Spring Boot 自动装配 |
outboxpro-spring-boot-starter |
业务应用开箱即用依赖 |
<dependency>
<groupId>io.github.biglv666</groupId>
<artifactId>outboxpro-spring-boot-starter</artifactId>
<version>1.4.0</version>
</dependency>应用需自行提供 Spring Boot、MySQL 与 RabbitMQ 连接配置:
spring:
application:
name: order-service
datasource:
url: jdbc:mysql://localhost:3306/order_db
username: root
password: ${MYSQL_PASSWORD}
rabbitmq:
host: localhost
port: 5672
username: guest
password: ${RABBITMQ_PASSWORD}
outboxpro:
schema-initialize: true # 默认自动建表;生产建议关闭并交给 Flyway/Liquibase
producer:
relay-enabled: true
workers: 2
consumer:
concurrency: 3声明事件与 Handler,然后在业务事务中发布:
@OutboxEvent(eventType = "order.created", exchange = "order.exchange")
public record OrderCreated(Long orderId) { }
@Component
@OutboxHandler(event = OrderCreated.class, queue = "inventory-service.queue",
consumerName = "inventory-service")
public class OrderCreatedHandler extends AnnotatedOutboxHandler<OrderCreated> {
@Override public void handle(EventContext<OrderCreated> context) {
// 只写业务逻辑;Inbox、ACK、重试、死信由框架处理
}
}
@Transactional
public void createOrder(...) {
orderRepository.insert(...);
publisher.publish(OrderCreated.class, new OrderCreated(orderId));
}生产环境关闭 schema-initialize 时,请执行
outboxpro-persistence-mysql/src/main/resources/db/migration/mysql/ 下的 V1–V6 迁移脚本。
- 生产端:至少一次投递;
- 消费端:至少一次执行 + Inbox 幂等;
- 整体:最终一致;
- V1 不承诺跨系统 Exactly Once,外部副作用需业务自行幂等。
| 文档 | 内容 |
|---|---|
| 快速开始与公共 API | 完整示例、注解式声明、类型安全发布、运维端点 |
| 运维与排障 | 数据库、RabbitMQ、积压判断、故障排查、配置调优 |
| 观测与告警 Runbook | 指标清单、健康检查、告警规则与处理流程 |
| 死信队列 (DLQ) | 死信模式、台账、重放、FAQ |
| Relay 性能基线 | 容量结论与调优建议 |
| 全量配置示例 | 所有配置项参考 |
| 订单示例 | 10 分钟跑通发布→消费→重试→DLQ→重放 |
| 变更日志 | 版本变更与升级说明 |