1. 事务消息在SpringBoot里的完整链路半消息到底半在哪很多人第一次在SpringBoot里接RocketMQ事务消息都是被事务两个字带偏的。以为发了消息就等同于数据库事务出问题能自动回滚。实际跑通一次之后才发现它能给的只是生产者本地事务和消息投递之间的一致消费端成不成功它管不着中间件也不负责帮你回滚订单表。我见过的翻车现场十次里有七八次不是代码写错而是对这条链路的边界理解错了。这一篇要聊的是更靠后的一步当你的应用里不止一个业务需要发事务消息时SpringBoot这边该怎么摆。这个标题看着像是基础整合实际上多事务消息四个字才是真正的难点也是rocketmq-spring这个starter设计上最别扭的地方。先把底层链路捋清楚后面配置多个生产者时才知道自己到底在动哪颗螺丝。1.1 半消息不是发一半是先扣在Broker的暂存区半消息Half Message这个名字起得很有迷惑性。它不是把消息体切一半发出去而是整条消息完整写进Broker但被藏进一个系统内部Topic里消费端在这个阶段完全看不见。整个动作拆开是四步生产者把消息发给BrokerBroker不投递给任何消费者而是把它写到RMQ_SYS_TRANS_HALF_TOPIC这个系统Topic下然后给生产者回一个我收到了。生产者收到这个确认后才开始执行本地事务也就是你那段操作数据库的代码。本地事务有结果了生产者再向Broker发一次结束事务的请求告诉它Commit还是Rollback。Broker收到Commit把之前扣住的那条消息从暂存区里还原到真正的业务Topic此时消费端才能拉到收到Rollback就直接丢弃并记一笔操作日志。这个设计的关键在于第一步和第二步之间那道确认是整个方案能成立的地基。如果生产者刚发出去就执行本地事务那消息丢没丢、Broker收没收到都不知道本地事务提交了消息却没落地一致性直接崩。反过来先让Broker表态我已经安全存下了生产者再动数据库最坏情况也只是消息多存了一条待定的不会少。提醒一句半消息落在磁盘上是有成本的。一次事务消息网络往返至少两次写入至少两次暂存一次、还原一次吞吐天然比普通消息低一截。对账类、订单类业务可以接受秒杀扣库存那种高并发热点路径就别往上套了。1.2 回查不是兜底而是主流程的一个分支绝大多数人把回查Check Local Transaction当成异常兜底觉得正常情况下用不到。这个认知偏差会直接影响你的表设计后面写回查逻辑时就会开始糊弄。真实情况是生产者在执行完本地事务后向Broker发确认这一步本身可能失败。网络抖一下、进程刚好被发布重启、机器被摘流都会导致Broker迟迟等不到那个Commit/Rollback。这时候Broker不会傻等它会启一个定时任务主动反查生产者刚才那条消息你那边到底成了没成反查的默认节奏大致是这样的半消息落盘后约6秒还没收到二次确认就进入待回查队列之后每隔约60秒回查一次最多回查15次。超过15次还没拿到明确答复Broker会认定这条消息失败了直接丢弃并记日志。这就意味着回查走的是一条完全独立的网络请求它拿不到你发送时传的业务参数对象。很多人在这里踩坑发送时把订单对象作为arg传给了sendMessageInTransaction本地事务里用得好好的回查一进来发现arg是 null直接NPE。因为回查是Broker发起的它只能把消息体原封不动送回来arg这个只在生产者本地内存里存在的参数跨进程传不过去。所以一条铁律消息体里必须带上能唯一定位本地事务状态的业务ID比如订单号、流水号。回查时只能靠它去数据库里捞状态。1.3 rocketmq-spring替你封了什么又没封什么rocketmq-spring-boot-starter这个包把原生的TransactionMQProducer包装成了RocketMQTemplate你只要在配置文件里写上nameserver地址和生产者组再实现一个RocketMQLocalTransactionListener加个注解就能用sendMessageInTransaction一把梭。开箱体验确实好但它封装的边界值得说清楚。它帮你做的自动创建生产者实例并启动、把TransactionListener注册进去、维护回查线程池、处理发送结果和异常包装、跟Spring生命周期挂钩做优雅关闭。它没帮你做的也是坑最多的部分它不理解你的本地事务。executeLocalTransaction返回什么状态完全取决于你代码怎么写中间件不会去校验你有没有真的提交数据库。它不保证消费成功。Commit之后消息进了业务Topic消费端失败重试、重试耗尽进死信这套流程跟事务消息毫无关系。它不处理消息重复。Broker在极端情况下还原消息后生产者没收到响应会重投消费端必须自己做幂等。它的一个Template只对应一个事务监听器。这一条就是多事务消息卡壳的直接原因下一节细说。另外补一句版本相关的经验rocketmq-spring-boot-starter2.0.2 及更早的版本RocketMQTransactionListener注解上还有个txProducerGroup属性用来区分不同的监听器。到了 2.0.3 这个属性开始被弱化2.1.0 之后干脆移除了。如果你在网上抄到的示例代码里出现了txProducerGroup基本可以判断那是好几年前的版本直接套到新版本上编译都过不去。2. 多事务消息卡壳的根因一个Template只认一个监听器业务一旦长起来一个SpringBoot应用里同时存在订单创建、积分发放、库存预占、账单生成这些需要保证一致性的场景太正常了。每个场景的事务边界不一样本地事务表不一样回查逻辑更不一样你不可能把它们塞进同一个监听器里用 if-else 分流——那样代码会烂掉而且回查时连消息属于哪类业务都判断不出来。但如果你直接建两个类都加上RocketMQTransactionListener启动阶段大概率会挂。2.1 版本差异带来的假象在比较老的版本里2.0.2及之前靠txProducerGroup属性是可以同时挂多个监听器的每个监听器声明自己归属哪个生产者组RocketMQTemplate发送时指定组名就能路由到对应的监听器。这套机制在当时的写法大概长这样RocketMQTransactionListener(txProducerGroup order_tx_group) public class OrderTxListener implements RocketMQLocalTransactionListener { ... }到了 2.1.0 之后txProducerGroup被移除RocketMQTemplate内部只维护一个TransactionListener引用。容器里如果同时存在多个RocketMQLocalTransactionListener类型的Bean启动时会直接抛异常日志大意是当前版本只允许一个事务监听器具体异常文案各小版本略有出入但意思一致。于是网上出现了一堆降版本到2.0.2就好了的偏方。这招在短期能跑通代价是锁死在老版本上后面的安全补丁、协议兼容都跟你没关系了。长期看不是办法。2.2 两种多的诉求要分开看在动手改代码之前先问清楚自己到底要的是哪一种多因为这两种诉求的解法完全不同。诉求类型具体表现解法方向多生产者一个应用里同时有订单、积分、库存等多套事务消息场景各有独立的事务表和回查逻辑建多个RocketMQTemplate每个挂独立的TransactionMQProducer和监听器多消息一次业务操作要发多条事务消息比如下单后同时通知库存和积分收敛为一条消息多Tag或统一事务日志补偿任务第一种是结构性问题靠配置类和Bean隔离解决。第二种是一致性问题靠业务设计解决配多少个生产者都没用——两个事务消息之间没有任何原子性保证第一条Commit了第二条Rollback了业务就半截了。很多人把两者混为一谈以为多配几个生产者组就能一次发多条了这是南辕北辙。下面先解决第一种。3. 手搓多个TransactionMQProducer的完整配置思路很直白绕过starter的自动装配手动new出多个TransactionMQProducer每个绑定不同的生产者组和不同的监听器再用RocketMQTemplate包一层注册成不同的Bean。这样每个Template都是独立的互不干扰回查请求进来时Broker会带上生产者组能精确路由回对应的监听器。3.1 公共参数抽出来group单独定先把公共的连接参数抽到配置文件里避免每个Template重复写死rocketmq: name-server: 10.0.0.11:9876;10.0.0.12:9876 tx: order: group: order_tx_producer_group send-timeout: 3000 retry-times: 2 point: group: point_tx_producer_group send-timeout: 3000 retry-times: 2这里有个细节值得展开send-timeout指的是发送半消息的超时不是本地事务的超时。本地事务执行多久中间件完全不管你写个30秒的慢SQL它也只能干等着等不到二次确认就进入回查队列。所以本地事务一定要短超过几秒的操作应该拆成异步。这是我第一次上线时吃的亏本地事务里同步调了一个外部接口对方偶尔卡顿七八秒结果大量半消息进入回查回查线程池被打满整个生产者堵死。3.2 配置类代码下面是完整可运行的配置类两个业务各一套Configuration public class MultiTxProducerConfig { Value(${rocketmq.name-server}) private String nameServer; Bean(destroyMethod destroy) public RocketMQTemplate orderTxTemplate(OrderTxListener orderTxListener) { return buildTxTemplate(order_tx_producer_group, orderTxListener); } Bean(destroyMethod destroy) public RocketMQTemplate pointTxTemplate(PointTxListener pointTxListener) { return buildTxTemplate(point_tx_producer_group, pointTxListener); } private RocketMQTemplate buildTxTemplate(String group, RocketMQLocalTransactionListener listener) { TransactionMQProducer producer new TransactionMQProducer(group); producer.setNamesrvAddr(nameServer); producer.setSendMsgTimeout(3000); producer.setRetryTimesWhenSendFailed(2); producer.setTransactionListener(listener); // 回查线程池必须自己指定原因见 3.3 ThreadPoolExecutor checkPool new ThreadPoolExecutor( 2, 8, 60L, TimeUnit.SECONDS, new ArrayBlockingQueue(2000), r - { Thread t new Thread(r, group -check- r.hashCode()); t.setDaemon(true); return t; }, new ThreadPoolExecutor.AbortPolicy()); producer.setExecutorService(checkPool); RocketMQTemplate template new RocketMQTemplate(); template.setProducer(producer); return template; } }Bean(destroyMethod destroy)这个别省。RocketMQTemplate实现了销毁回调不显式声明的话应用优雅停机时生产者没有shutdownBroker那边还认为连接活着回查请求会打到已经死掉的客户端上日志里一片连接超时。RocketMQTemplate本身实现了初始化回调接口被Spring容器创建时会自动调afterPropertiesSet()触发producer.start()不需要你手动调。这一点如果搞错了会重复start启动时直接抛状态异常。3.3 回查线程池为什么必须自己给TransactionMQProducer如果不设置executorService内部会用一个默认线程池核心线程数和最大线程数都是1队列长度2000。单线程意味着回查请求是串行处理的。这个默认值在业务量小的时候看不出问题一旦进入回查的量上来比如某次发布导致几百条半消息集中待回查单线程一条条处理每条回查里还要查数据库200毫秒一条200条就是40秒。后面的回查请求全堆在队列里队列满了之后新的回查直接拒绝Broker那边判定回查失败继续等待下一轮最后15次耗尽消息被丢弃。所以自建线程池不是优化项是必需品。核心线程给2到4最大给8到16队列别开太大2000偏大了队列长意味着延迟高且不易察觉关键是要配拒绝策略。默认的AbortPolicy会抛异常回查失败进入下一轮比你用CallerRunsPolicy把线程卡死要好。线程名前缀带上group名排查日志时能一眼看出是哪个业务的回查在堵。3.4 注入RocketMQTemplate时的Bean冲突多个RocketMQTemplate类型的Bean同时存在如果你在业务代码里直接Autowired RocketMQTemplate template启动会报NoUniqueBeanDefinitionExceptionSpring不知道你要哪个。正确做法是配合限定符Service public class OrderService { private final RocketMQTemplate orderTxTemplate; public OrderService(Qualifier(orderTxTemplate) RocketMQTemplate orderTxTemplate) { this.orderTxTemplate orderTxTemplate; } }或者用Resource(name orderTxTemplate)按名字注入效果一样但少一层Qualifier看着清爽点。我个人偏爱构造器注入加Qualifier依赖关系在构造参数上就写明了不会有人误用。还有一个隐蔽的坑如果你同时保留了rocketmq.producer.group这行配置starter的自动装配仍然会创建一个默认的RocketMQTemplateBean名固定为rocketMQTemplate跟你的两个自建Template一起变成三个。既然走自建路线就把rocketmq.producer.group这条配置删掉否则多一个不受控的生产者实例白占连接。消费者侧的rocketmq.consumer.group不受影响正常保留。4. 本地事务表回查能不能扛住全看这张表配置搞定了真正决定稳定性的是这张事务表。回查进来的那一刻你只有消息体里的业务ID能不能在几十毫秒内给出准确答复全靠表结构和状态机的设计。4.1 表结构与状态机一个够用的表长这样CREATE TABLE tx_message_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, biz_id VARCHAR(64) NOT NULL COMMENT 业务唯一ID,与消息体一致, biz_type VARCHAR(32) NOT NULL COMMENT 业务类型,区分不同事务场景, tx_status TINYINT NOT NULL DEFAULT 0 COMMENT 0待执行 1已提交 2已回滚 3处理中, payload TEXT COMMENT 消息体快照,用于补偿重发, check_count INT NOT NULL DEFAULT 0 COMMENT 被回查次数, create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_biz (biz_id, biz_type), KEY idx_status_time (tx_status, create_time) );几个设计要点解释一下biz_id和biz_type建联合唯一索引不是单列。因为不同业务场景的订单号可能撞号比如一个用了自增ID一个用了雪花ID理论上不撞但保不齐加上业务类型隔离更稳。tx_status里留了一个处理中状态。为什么需要因为本地事务执行过程中如果进程挂了数据库里留下一条待执行的记录回查时你无法判断这条业务到底是还没开始还是执行到一半。有了处理中执行前先抢占式更新成这样回查看到这个状态就返回UNKNOWN等下一轮再审。这个状态不要省省了之后回查会误判。check_count是自检用的。回查次数异常增长的记录说明你的本地事务经常拿不到确定结果值得单独拉出来看。idx_status_time这个索引是给补偿任务用的扫待处理且超过N分钟的记录后面第5节会用到。4.2 executeLocalTransaction的执行顺序顺序错了一致性就废了。正确顺序是插入事务日志tx_status 3处理中用INSERT IGNORE或捕获唯一键冲突保证幂等。执行真正的业务逻辑扣款、下单、改库存。业务成功则更新tx_status 1返回COMMIT。业务明确失败则更新tx_status 2返回ROLLBACK。业务结果不确定超时、依赖服务异常、抛了非业务异常则保持3返回UNKNOWN。注意第5条不要图省事把异常都catch了返回ROLLBACK。ROLLBACK是不可逆的消息一旦回滚就彻底丢了。如果那次异常其实只是网络抖动业务在数据库里已经提交了你返回ROLLBACK就等于消息永久丢失业务数据改了但下游不知道这才是最麻烦的不一致。拿不准就返回UNKNOWN让Broker回查回查时会重新读表多一次机会总比直接丢强。另外executeLocalTransaction里的业务逻辑必须幂等。因为发送半消息失败重试时同一笔业务可能被调用两次。用biz_id做唯一约束重复插入直接忽略是成本最低的幂等手段。4.3 checkLocalTransaction的三种返回值与数据注意事项回查逻辑本身很简单查表按状态映射Override public RocketMQLocalTransactionState checkLocalTransaction(Message msg) { String bizId extractBizId(msg); TxMessageLog log txMessageLogMapper.selectByBizId(bizId); if (log null) { // 记录不存在:可能本地事务还没落库,也可能压根没执行 return RocketMQLocalTransactionState.UNKNOWN; } if (log.getCheckCount() 0) { txMessageLogMapper.incrCheckCount(bizId); } switch (log.getTxStatus()) { case 1: return RocketMQLocalTransactionState.COMMIT; case 2: return RocketMQLocalTransactionState.ROLLBACK; default: return RocketMQLocalTransactionState.UNKNOWN; } }三个返回值各自的后果得背下来COMMIT—— Broker把暂存区的消息还原到业务Topic消费端开始消费。这是不可撤销的。ROLLBACK—— Broker丢弃消息业务Topic永远收不到。同样不可撤销。UNKNOWN—— Broker保持原样等到下一个回查周期再来问。如果连续15次都是UNKNOWNBroker最终按失败处理丢弃消息日志里记一笔。这里有个极其容易踩的坑记录不存在时该返回什么。有人写return null有人写死ROLLBACK。返回null直接NPE返回ROLLBACK则是把可能还没执行完的业务判了死刑。稳妥的做法是返回UNKNOWN。但要注意executeLocalTransaction的第一步就是插记录正常情况下记录不存在只说明半消息发出去了、本地事务一行还没执行这时候UNKNOWN是合理的下一轮回查大概率就能查到。代价是极端情况会多耗几轮回查次数可以接受。还有一个数据上的细节回查时消息体的反序列化。checkLocalTransaction(Message msg)拿到的Message是Broker原样返回的payload字节数组也在但如果你发送时用的是Spring的MessageBuilder包装的自定义对象回查时要自己按相同方式反序列化一次。类型对不上会抛MessageConversionException。建议消息体统一用JSON字符串或Protobuf字节别依赖具体的序列化器实现跨版本升级时少一层麻烦。5. 一次业务下发多条事务消息一致性怎么收口配置多个生产者只是解决了不同场景各用各的还有一种更隐蔽的需求同一笔业务要通知好几个下游。比如下单成功既要通知库存预占又要通知积分冻结还要通知风控留痕。有同学会想我配了三个Template挨个发三次事务消息不就完了。这条路走不通原因很直接三条事务消息之间不存在任何原子性。第一条Commit了第二条Broker没收到半消息确认第三条本地事务炸了返回ROLLBACK结果库存扣了、积分没冻、风控没记。你在业务层想回滚这时候第一条消息已经被消费端处理了回滚链条会变得极其复杂。5.1 拆多条事务消息还是一条消息多Tag对比一下两种落法方案做法优点缺点多条事务消息每个下游发一条独立的tx消息下游解耦彻底各自消费无原子性故障时状态散乱补偿复杂一条消息多Tag发一条tx消息多个消费组用不同Tag订阅原子性天然保证只有一次ACK消息体较大下游要按Tag过滤在绝大多数场景下第二条路明显更优。一条事务消息Commit之后所有订阅它的消费组都会收到各自处理各自的部分。库存消费组按Tag过滤只处理库存相关字段积分消费组只处理积分字段风控消费组只做留痕。生产侧只需要保证一次本地事务和一次消息投递的一致性复杂度直接降一个量级。Tag的设计建议是带上业务动作比如ORDER_CREATED、ORDER_PAID消费端用consumer.subscribe(order_topic, ORDER_CREATED || ORDER_PAID)这种表达式过滤。一个topic下的Tag别超过10个多了之后消费端的过滤逻辑会失控。如果下游的消费吞吐差异极大比如风控组要跑重计算库存组要毫秒级响应一个topic会互相拖累。这种情况下可以拆topic但生产侧仍然发一条消息由消费端做扇出——第一个消费组收到后用普通消息非事务转发给其他topic。这里的事务性要求就降级成普通消息可靠投递用本地消息表加定时补偿就能兜住。5.2 统一事务日志 补偿扫描即使收敛成一条消息仍然存在一个窗口本地事务提交成功了但executeLocalTransaction在返回COMMIT之前进程被killBroker收不到确认进入回查。这时候回查能查到tx_status 1返回COMMIT消息就出去了这条路径是安全的。真正需要补偿的是另一种情况Broker回查15次全部失败比如回查期间生产者一直不可用消息被丢弃但本地业务数据已经改了。这条数据永远不会被下游知道。补一个扫描任务兜住这个缺口Scheduled(fixedDelay 60_000) public void compensate() { // 捞取已提交但超过5分钟未被确认消费的记录 ListTxMessageLog list txMessageLogMapper.selectNeedCompensate( Duration.ofMinutes(5), 200); for (TxMessageLog log : list) { try { // 用普通消息重投,消费端靠biz_id幂等 rocketMQTemplate.syncSend( order_topic:ORDER_CREATED, log.getPayload()); txMessageLogMapper.markCompensated(log.getId()); } catch (Exception e) { log.warn(补偿重发失败, id{}, log.getId(), e); } } }这个任务的关键在于消费端必须按biz_id做幂等否则补偿重发会让下游重复处理。幂等的实现方式最朴素的就是下游也存一张消费记录表biz_id唯一键插入冲突就跳过。别指望Redis的setnx那玩意儿有丢失风险涉及钱的场景还是得落库。扫描的批次别开太大200条一次比较稳每批之间留点间隔避免把数据库和Broker同时打满。6. 实测踩坑与排查链路配置和表都齐了剩下的是线上跑起来才会暴露的问题。挑四个我实际遇到过的把排查过程写出来遇到类似现象时能少绕几圈。6.1 回查压根没进来现象应用日志里executeLocalTransaction有输出但checkLocalTransaction从来没被调用过半消息堆积持续增长。排查链路第一步确认监听器有没有真正注册到生产者上。自建Template时如果template.setProducer(producer)之前忘了producer.setTransactionListener(listener)发送照样能成但回查永远进不来。这个错误特别隐蔽因为发送日志一切正常。在启动日志里搜 transaction listener 相关的注册信息或者打个断点在setTransactionListener上确认执行了。第二步检查生产者组是否和Broker侧记录的一致。半消息在Broker上会记录生产者组回查时按组发请求。如果发送时用的组名和配置的Bean里的组名对不上比如一个带了下划线一个没带回查请求会找不到目标客户端。第三步看Broker日志里有没有回查请求的记录。如果Broker侧压根没发起回查问题在Broker配置transactionCheckInterval是不是被调得极大或者事务消息处理线程池被占满了。第四步检查客户端的instanceName。同一台机器上多个生产者实例如果instanceName相同但连接了不同的nameserver客户端实例会被复用导致注册关系混乱。稳妥做法是给每个生产者设一个独立的instanceName比如group - pid。6.2 半消息堆积现象RMQ_SYS_TRANS_HALF_TOPIC的消息量持续上涨消费延迟也跟着涨。排查链路先看是不是回查返回大量UNKNOWN。把check_count拉出来按业务类型分组统计如果某一类的平均值明显偏高说明那个业务的事务状态判定逻辑有问题可能一直返回UNKNOWN。常见原因是事务日志没能及时更新——比如业务代码在更新tx_status之前就抛异常了记录永远停在处理中。再看回查线程池的队列深度。前面说过默认单线程如果队列堆到几百说明回查处理速度跟不上。这时候要么扩线程要么检查回查里的SQL有没有走索引。回查是高频短请求一次慢查询就能拖垮整条链路。还有一种情况是Broker的transactionTimeOut配得太小半消息刚写完就被拉去回查了而本地事务其实还在跑回查必然返回UNKNOWN。这个参数默认6秒如果你的本地事务平均耗时超过3秒建议往上调否则会白白浪费回查次数。6.3 UNKNOWN之后消息消失现象某笔业务日志显示返回了UNKNOWN之后既没有Commit也没有Rollback下游一直没收到。根因往往是回查次数耗尽。默认最多15次每次间隔60秒理论上15分钟内会被反复问到。如果这15分钟里生产者一直重启或者回查持续异常消息就被按失败丢弃了。这个丢弃不会给你发告警只在Broker日志里有一行。规避手段是把check_count用起来超过10次还是UNKNOWN的记录主动打一条告警日志出来别等它被默默丢掉。同时补偿任务要覆盖这种记录靠定时扫描重新投递一次普通消息用消费端幂等兜住重复。6.4 事务消息和延迟、批量不兼容这个坑纯粹是文档没写清楚。事务消息的发送接口只接受单条消息批量接口sendMessageInTransaction压根没有。至于延迟级别实测下来在半消息阶段设置不生效Commit还原之后也不会带上延迟属性。所以如果你的业务需要下单30分钟后自动关单正确姿势是事务消息负责可靠投递下单成功事件消费端收到之后再发一条普通延迟消息用于超时关单。别想着一步到位。还有一个容易忽略的事务消息不支持顺序发送。半消息的还原是Broker内部异步完成的还原后的队列选择不一定和发送时的队列一致。要求严格顺序的场景这条链路得另做设计。7. 版本、参数与容量清理几个必须记住的数字把散落在各处的关键参数汇总成一张表调优和排障时对着看参数位置默认值调优建议transactionTimeOutBroker6000ms本地事务P99超过3秒时上调至10000~15000transactionCheckMaxBroker15不建议下调下调等于缩短容错窗口transactionCheckIntervalBroker60s单次回查耗时高时可上调减少无效回查回查线程池coreSize生产者1按回查QPS给2~8回查线程池queue生产者2000建议降到200~500配合拒绝策略sendMsgTimeout生产者3000ms跨机房时适当放大retryTimesWhenSendFailed生产者2保持默认事务消息重试代价高版本上还有一条经验rocketmq-spring-boot-starter2.2.x 对应的客户端是4.9.x2.3.x 才对齐到5.x。如果你的broker是4.x别硬上2.3.x的starter协议层虽然大体兼容但事务消息的回查协议在5.x里做过调整混搭时出问题极难排查。升级路径要么整套升要么老老实实锁在2.2.x。最后提一下监控。事务消息这条链路上至少有四个指标值得盯半消息堆积量、回查调用QPS、回查UNKNOWN占比、tx_message_log里状态为处理中且超过10分钟的记录数。前两个看整体健康度第三个看业务判定逻辑是否合理第四个看补偿任务有没有漏。前面三个上中间件的监控面板就能拿到最后一个得自己写个定时统计打点到日志里成本很低但救过我好几次。我在实际项目里最大的体会是事务消息这东西的价值不在于它能保证一致性而在于它把不一致暴露在了可观测的位置。半消息堆积、回查次数、UNKNOWN比例这些都是非常直接的信号比业务层自己埋一堆对账逻辑要清晰得多。真正省事的做法不是把代码写得多聪明而是把事务日志表当成核心资产来设计——字段留足、索引建对、状态机管好剩下的交给中间件和补偿任务出问题的概率会低很多。 
长河君 · 2026/10/27 13:30:43 · 阅读 1.2k SpringBoot多事务消息：RocketMQ半消息与回查配置实践
1. 事务消息在SpringBoot里的完整链路半消息到底半在哪很多人第一次在SpringBoot里接RocketMQ事务消息都是被事务两个字带偏的。以为发了消息就等同于数据库事务出问题能自动回滚。实际跑通一次之后才发现它能给的只是生产者本地事务和消息投递之间的一致消费端成不成功它管不着中间件也不负责帮你回滚订单表。我见过的翻车现场十次里有七八次不是代码写错而是对这条链路的边界理解错了。这一篇要聊的是更靠后的一步当你的应用里不止一个业务需要发事务消息时SpringBoot这边该怎么摆。这个标题看着像是基础整合实际上多事务消息四个字才是真正的难点也是rocketmq-spring这个starter设计上最别扭的地方。先把底层链路捋清楚后面配置多个生产者时才知道自己到底在动哪颗螺丝。1.1 半消息不是发一半是先扣在Broker的暂存区半消息Half Message这个名字起得很有迷惑性。它不是把消息体切一半发出去而是整条消息完整写进Broker但被藏进一个系统内部Topic里消费端在这个阶段完全看不见。整个动作拆开是四步生产者把消息发给BrokerBroker不投递给任何消费者而是把它写到RMQ_SYS_TRANS_HALF_TOPIC这个系统Topic下然后给生产者回一个我收到了。生产者收到这个确认后才开始执行本地事务也就是你那段操作数据库的代码。本地事务有结果了生产者再向Broker发一次结束事务的请求告诉它Commit还是Rollback。Broker收到Commit把之前扣住的那条消息从暂存区里还原到真正的业务Topic此时消费端才能拉到收到Rollback就直接丢弃并记一笔操作日志。这个设计的关键在于第一步和第二步之间那道确认是整个方案能成立的地基。如果生产者刚发出去就执行本地事务那消息丢没丢、Broker收没收到都不知道本地事务提交了消息却没落地一致性直接崩。反过来先让Broker表态我已经安全存下了生产者再动数据库最坏情况也只是消息多存了一条待定的不会少。提醒一句半消息落在磁盘上是有成本的。一次事务消息网络往返至少两次写入至少两次暂存一次、还原一次吞吐天然比普通消息低一截。对账类、订单类业务可以接受秒杀扣库存那种高并发热点路径就别往上套了。1.2 回查不是兜底而是主流程的一个分支绝大多数人把回查Check Local Transaction当成异常兜底觉得正常情况下用不到。这个认知偏差会直接影响你的表设计后面写回查逻辑时就会开始糊弄。真实情况是生产者在执行完本地事务后向Broker发确认这一步本身可能失败。网络抖一下、进程刚好被发布重启、机器被摘流都会导致Broker迟迟等不到那个Commit/Rollback。这时候Broker不会傻等它会启一个定时任务主动反查生产者刚才那条消息你那边到底成了没成反查的默认节奏大致是这样的半消息落盘后约6秒还没收到二次确认就进入待回查队列之后每隔约60秒回查一次最多回查15次。超过15次还没拿到明确答复Broker会认定这条消息失败了直接丢弃并记日志。这就意味着回查走的是一条完全独立的网络请求它拿不到你发送时传的业务参数对象。很多人在这里踩坑发送时把订单对象作为arg传给了sendMessageInTransaction本地事务里用得好好的回查一进来发现arg是 null直接NPE。因为回查是Broker发起的它只能把消息体原封不动送回来arg这个只在生产者本地内存里存在的参数跨进程传不过去。所以一条铁律消息体里必须带上能唯一定位本地事务状态的业务ID比如订单号、流水号。回查时只能靠它去数据库里捞状态。1.3 rocketmq-spring替你封了什么又没封什么rocketmq-spring-boot-starter这个包把原生的TransactionMQProducer包装成了RocketMQTemplate你只要在配置文件里写上nameserver地址和生产者组再实现一个RocketMQLocalTransactionListener加个注解就能用sendMessageInTransaction一把梭。开箱体验确实好但它封装的边界值得说清楚。它帮你做的自动创建生产者实例并启动、把TransactionListener注册进去、维护回查线程池、处理发送结果和异常包装、跟Spring生命周期挂钩做优雅关闭。它没帮你做的也是坑最多的部分它不理解你的本地事务。executeLocalTransaction返回什么状态完全取决于你代码怎么写中间件不会去校验你有没有真的提交数据库。它不保证消费成功。Commit之后消息进了业务Topic消费端失败重试、重试耗尽进死信这套流程跟事务消息毫无关系。它不处理消息重复。Broker在极端情况下还原消息后生产者没收到响应会重投消费端必须自己做幂等。它的一个Template只对应一个事务监听器。这一条就是多事务消息卡壳的直接原因下一节细说。另外补一句版本相关的经验rocketmq-spring-boot-starter2.0.2 及更早的版本RocketMQTransactionListener注解上还有个txProducerGroup属性用来区分不同的监听器。到了 2.0.3 这个属性开始被弱化2.1.0 之后干脆移除了。如果你在网上抄到的示例代码里出现了txProducerGroup基本可以判断那是好几年前的版本直接套到新版本上编译都过不去。2. 多事务消息卡壳的根因一个Template只认一个监听器业务一旦长起来一个SpringBoot应用里同时存在订单创建、积分发放、库存预占、账单生成这些需要保证一致性的场景太正常了。每个场景的事务边界不一样本地事务表不一样回查逻辑更不一样你不可能把它们塞进同一个监听器里用 if-else 分流——那样代码会烂掉而且回查时连消息属于哪类业务都判断不出来。但如果你直接建两个类都加上RocketMQTransactionListener启动阶段大概率会挂。2.1 版本差异带来的假象在比较老的版本里2.0.2及之前靠txProducerGroup属性是可以同时挂多个监听器的每个监听器声明自己归属哪个生产者组RocketMQTemplate发送时指定组名就能路由到对应的监听器。这套机制在当时的写法大概长这样RocketMQTransactionListener(txProducerGroup order_tx_group) public class OrderTxListener implements RocketMQLocalTransactionListener { ... }到了 2.1.0 之后txProducerGroup被移除RocketMQTemplate内部只维护一个TransactionListener引用。容器里如果同时存在多个RocketMQLocalTransactionListener类型的Bean启动时会直接抛异常日志大意是当前版本只允许一个事务监听器具体异常文案各小版本略有出入但意思一致。于是网上出现了一堆降版本到2.0.2就好了的偏方。这招在短期能跑通代价是锁死在老版本上后面的安全补丁、协议兼容都跟你没关系了。长期看不是办法。2.2 两种多的诉求要分开看在动手改代码之前先问清楚自己到底要的是哪一种多因为这两种诉求的解法完全不同。诉求类型具体表现解法方向多生产者一个应用里同时有订单、积分、库存等多套事务消息场景各有独立的事务表和回查逻辑建多个RocketMQTemplate每个挂独立的TransactionMQProducer和监听器多消息一次业务操作要发多条事务消息比如下单后同时通知库存和积分收敛为一条消息多Tag或统一事务日志补偿任务第一种是结构性问题靠配置类和Bean隔离解决。第二种是一致性问题靠业务设计解决配多少个生产者都没用——两个事务消息之间没有任何原子性保证第一条Commit了第二条Rollback了业务就半截了。很多人把两者混为一谈以为多配几个生产者组就能一次发多条了这是南辕北辙。下面先解决第一种。3. 手搓多个TransactionMQProducer的完整配置思路很直白绕过starter的自动装配手动new出多个TransactionMQProducer每个绑定不同的生产者组和不同的监听器再用RocketMQTemplate包一层注册成不同的Bean。这样每个Template都是独立的互不干扰回查请求进来时Broker会带上生产者组能精确路由回对应的监听器。3.1 公共参数抽出来group单独定先把公共的连接参数抽到配置文件里避免每个Template重复写死rocketmq: name-server: 10.0.0.11:9876;10.0.0.12:9876 tx: order: group: order_tx_producer_group send-timeout: 3000 retry-times: 2 point: group: point_tx_producer_group send-timeout: 3000 retry-times: 2这里有个细节值得展开send-timeout指的是发送半消息的超时不是本地事务的超时。本地事务执行多久中间件完全不管你写个30秒的慢SQL它也只能干等着等不到二次确认就进入回查队列。所以本地事务一定要短超过几秒的操作应该拆成异步。这是我第一次上线时吃的亏本地事务里同步调了一个外部接口对方偶尔卡顿七八秒结果大量半消息进入回查回查线程池被打满整个生产者堵死。3.2 配置类代码下面是完整可运行的配置类两个业务各一套Configuration public class MultiTxProducerConfig { Value(${rocketmq.name-server}) private String nameServer; Bean(destroyMethod destroy) public RocketMQTemplate orderTxTemplate(OrderTxListener orderTxListener) { return buildTxTemplate(order_tx_producer_group, orderTxListener); } Bean(destroyMethod destroy) public RocketMQTemplate pointTxTemplate(PointTxListener pointTxListener) { return buildTxTemplate(point_tx_producer_group, pointTxListener); } private RocketMQTemplate buildTxTemplate(String group, RocketMQLocalTransactionListener listener) { TransactionMQProducer producer new TransactionMQProducer(group); producer.setNamesrvAddr(nameServer); producer.setSendMsgTimeout(3000); producer.setRetryTimesWhenSendFailed(2); producer.setTransactionListener(listener); // 回查线程池必须自己指定原因见 3.3 ThreadPoolExecutor checkPool new ThreadPoolExecutor( 2, 8, 60L, TimeUnit.SECONDS, new ArrayBlockingQueue(2000), r - { Thread t new Thread(r, group -check- r.hashCode()); t.setDaemon(true); return t; }, new ThreadPoolExecutor.AbortPolicy()); producer.setExecutorService(checkPool); RocketMQTemplate template new RocketMQTemplate(); template.setProducer(producer); return template; } }Bean(destroyMethod destroy)这个别省。RocketMQTemplate实现了销毁回调不显式声明的话应用优雅停机时生产者没有shutdownBroker那边还认为连接活着回查请求会打到已经死掉的客户端上日志里一片连接超时。RocketMQTemplate本身实现了初始化回调接口被Spring容器创建时会自动调afterPropertiesSet()触发producer.start()不需要你手动调。这一点如果搞错了会重复start启动时直接抛状态异常。3.3 回查线程池为什么必须自己给TransactionMQProducer如果不设置executorService内部会用一个默认线程池核心线程数和最大线程数都是1队列长度2000。单线程意味着回查请求是串行处理的。这个默认值在业务量小的时候看不出问题一旦进入回查的量上来比如某次发布导致几百条半消息集中待回查单线程一条条处理每条回查里还要查数据库200毫秒一条200条就是40秒。后面的回查请求全堆在队列里队列满了之后新的回查直接拒绝Broker那边判定回查失败继续等待下一轮最后15次耗尽消息被丢弃。所以自建线程池不是优化项是必需品。核心线程给2到4最大给8到16队列别开太大2000偏大了队列长意味着延迟高且不易察觉关键是要配拒绝策略。默认的AbortPolicy会抛异常回查失败进入下一轮比你用CallerRunsPolicy把线程卡死要好。线程名前缀带上group名排查日志时能一眼看出是哪个业务的回查在堵。3.4 注入RocketMQTemplate时的Bean冲突多个RocketMQTemplate类型的Bean同时存在如果你在业务代码里直接Autowired RocketMQTemplate template启动会报NoUniqueBeanDefinitionExceptionSpring不知道你要哪个。正确做法是配合限定符Service public class OrderService { private final RocketMQTemplate orderTxTemplate; public OrderService(Qualifier(orderTxTemplate) RocketMQTemplate orderTxTemplate) { this.orderTxTemplate orderTxTemplate; } }或者用Resource(name orderTxTemplate)按名字注入效果一样但少一层Qualifier看着清爽点。我个人偏爱构造器注入加Qualifier依赖关系在构造参数上就写明了不会有人误用。还有一个隐蔽的坑如果你同时保留了rocketmq.producer.group这行配置starter的自动装配仍然会创建一个默认的RocketMQTemplateBean名固定为rocketMQTemplate跟你的两个自建Template一起变成三个。既然走自建路线就把rocketmq.producer.group这条配置删掉否则多一个不受控的生产者实例白占连接。消费者侧的rocketmq.consumer.group不受影响正常保留。4. 本地事务表回查能不能扛住全看这张表配置搞定了真正决定稳定性的是这张事务表。回查进来的那一刻你只有消息体里的业务ID能不能在几十毫秒内给出准确答复全靠表结构和状态机的设计。4.1 表结构与状态机一个够用的表长这样CREATE TABLE tx_message_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, biz_id VARCHAR(64) NOT NULL COMMENT 业务唯一ID,与消息体一致, biz_type VARCHAR(32) NOT NULL COMMENT 业务类型,区分不同事务场景, tx_status TINYINT NOT NULL DEFAULT 0 COMMENT 0待执行 1已提交 2已回滚 3处理中, payload TEXT COMMENT 消息体快照,用于补偿重发, check_count INT NOT NULL DEFAULT 0 COMMENT 被回查次数, create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_biz (biz_id, biz_type), KEY idx_status_time (tx_status, create_time) );几个设计要点解释一下biz_id和biz_type建联合唯一索引不是单列。因为不同业务场景的订单号可能撞号比如一个用了自增ID一个用了雪花ID理论上不撞但保不齐加上业务类型隔离更稳。tx_status里留了一个处理中状态。为什么需要因为本地事务执行过程中如果进程挂了数据库里留下一条待执行的记录回查时你无法判断这条业务到底是还没开始还是执行到一半。有了处理中执行前先抢占式更新成这样回查看到这个状态就返回UNKNOWN等下一轮再审。这个状态不要省省了之后回查会误判。check_count是自检用的。回查次数异常增长的记录说明你的本地事务经常拿不到确定结果值得单独拉出来看。idx_status_time这个索引是给补偿任务用的扫待处理且超过N分钟的记录后面第5节会用到。4.2 executeLocalTransaction的执行顺序顺序错了一致性就废了。正确顺序是插入事务日志tx_status 3处理中用INSERT IGNORE或捕获唯一键冲突保证幂等。执行真正的业务逻辑扣款、下单、改库存。业务成功则更新tx_status 1返回COMMIT。业务明确失败则更新tx_status 2返回ROLLBACK。业务结果不确定超时、依赖服务异常、抛了非业务异常则保持3返回UNKNOWN。注意第5条不要图省事把异常都catch了返回ROLLBACK。ROLLBACK是不可逆的消息一旦回滚就彻底丢了。如果那次异常其实只是网络抖动业务在数据库里已经提交了你返回ROLLBACK就等于消息永久丢失业务数据改了但下游不知道这才是最麻烦的不一致。拿不准就返回UNKNOWN让Broker回查回查时会重新读表多一次机会总比直接丢强。另外executeLocalTransaction里的业务逻辑必须幂等。因为发送半消息失败重试时同一笔业务可能被调用两次。用biz_id做唯一约束重复插入直接忽略是成本最低的幂等手段。4.3 checkLocalTransaction的三种返回值与数据注意事项回查逻辑本身很简单查表按状态映射Override public RocketMQLocalTransactionState checkLocalTransaction(Message msg) { String bizId extractBizId(msg); TxMessageLog log txMessageLogMapper.selectByBizId(bizId); if (log null) { // 记录不存在:可能本地事务还没落库,也可能压根没执行 return RocketMQLocalTransactionState.UNKNOWN; } if (log.getCheckCount() 0) { txMessageLogMapper.incrCheckCount(bizId); } switch (log.getTxStatus()) { case 1: return RocketMQLocalTransactionState.COMMIT; case 2: return RocketMQLocalTransactionState.ROLLBACK; default: return RocketMQLocalTransactionState.UNKNOWN; } }三个返回值各自的后果得背下来COMMIT—— Broker把暂存区的消息还原到业务Topic消费端开始消费。这是不可撤销的。ROLLBACK—— Broker丢弃消息业务Topic永远收不到。同样不可撤销。UNKNOWN—— Broker保持原样等到下一个回查周期再来问。如果连续15次都是UNKNOWNBroker最终按失败处理丢弃消息日志里记一笔。这里有个极其容易踩的坑记录不存在时该返回什么。有人写return null有人写死ROLLBACK。返回null直接NPE返回ROLLBACK则是把可能还没执行完的业务判了死刑。稳妥的做法是返回UNKNOWN。但要注意executeLocalTransaction的第一步就是插记录正常情况下记录不存在只说明半消息发出去了、本地事务一行还没执行这时候UNKNOWN是合理的下一轮回查大概率就能查到。代价是极端情况会多耗几轮回查次数可以接受。还有一个数据上的细节回查时消息体的反序列化。checkLocalTransaction(Message msg)拿到的Message是Broker原样返回的payload字节数组也在但如果你发送时用的是Spring的MessageBuilder包装的自定义对象回查时要自己按相同方式反序列化一次。类型对不上会抛MessageConversionException。建议消息体统一用JSON字符串或Protobuf字节别依赖具体的序列化器实现跨版本升级时少一层麻烦。5. 一次业务下发多条事务消息一致性怎么收口配置多个生产者只是解决了不同场景各用各的还有一种更隐蔽的需求同一笔业务要通知好几个下游。比如下单成功既要通知库存预占又要通知积分冻结还要通知风控留痕。有同学会想我配了三个Template挨个发三次事务消息不就完了。这条路走不通原因很直接三条事务消息之间不存在任何原子性。第一条Commit了第二条Broker没收到半消息确认第三条本地事务炸了返回ROLLBACK结果库存扣了、积分没冻、风控没记。你在业务层想回滚这时候第一条消息已经被消费端处理了回滚链条会变得极其复杂。5.1 拆多条事务消息还是一条消息多Tag对比一下两种落法方案做法优点缺点多条事务消息每个下游发一条独立的tx消息下游解耦彻底各自消费无原子性故障时状态散乱补偿复杂一条消息多Tag发一条tx消息多个消费组用不同Tag订阅原子性天然保证只有一次ACK消息体较大下游要按Tag过滤在绝大多数场景下第二条路明显更优。一条事务消息Commit之后所有订阅它的消费组都会收到各自处理各自的部分。库存消费组按Tag过滤只处理库存相关字段积分消费组只处理积分字段风控消费组只做留痕。生产侧只需要保证一次本地事务和一次消息投递的一致性复杂度直接降一个量级。Tag的设计建议是带上业务动作比如ORDER_CREATED、ORDER_PAID消费端用consumer.subscribe(order_topic, ORDER_CREATED || ORDER_PAID)这种表达式过滤。一个topic下的Tag别超过10个多了之后消费端的过滤逻辑会失控。如果下游的消费吞吐差异极大比如风控组要跑重计算库存组要毫秒级响应一个topic会互相拖累。这种情况下可以拆topic但生产侧仍然发一条消息由消费端做扇出——第一个消费组收到后用普通消息非事务转发给其他topic。这里的事务性要求就降级成普通消息可靠投递用本地消息表加定时补偿就能兜住。5.2 统一事务日志 补偿扫描即使收敛成一条消息仍然存在一个窗口本地事务提交成功了但executeLocalTransaction在返回COMMIT之前进程被killBroker收不到确认进入回查。这时候回查能查到tx_status 1返回COMMIT消息就出去了这条路径是安全的。真正需要补偿的是另一种情况Broker回查15次全部失败比如回查期间生产者一直不可用消息被丢弃但本地业务数据已经改了。这条数据永远不会被下游知道。补一个扫描任务兜住这个缺口Scheduled(fixedDelay 60_000) public void compensate() { // 捞取已提交但超过5分钟未被确认消费的记录 ListTxMessageLog list txMessageLogMapper.selectNeedCompensate( Duration.ofMinutes(5), 200); for (TxMessageLog log : list) { try { // 用普通消息重投,消费端靠biz_id幂等 rocketMQTemplate.syncSend( order_topic:ORDER_CREATED, log.getPayload()); txMessageLogMapper.markCompensated(log.getId()); } catch (Exception e) { log.warn(补偿重发失败, id{}, log.getId(), e); } } }这个任务的关键在于消费端必须按biz_id做幂等否则补偿重发会让下游重复处理。幂等的实现方式最朴素的就是下游也存一张消费记录表biz_id唯一键插入冲突就跳过。别指望Redis的setnx那玩意儿有丢失风险涉及钱的场景还是得落库。扫描的批次别开太大200条一次比较稳每批之间留点间隔避免把数据库和Broker同时打满。6. 实测踩坑与排查链路配置和表都齐了剩下的是线上跑起来才会暴露的问题。挑四个我实际遇到过的把排查过程写出来遇到类似现象时能少绕几圈。6.1 回查压根没进来现象应用日志里executeLocalTransaction有输出但checkLocalTransaction从来没被调用过半消息堆积持续增长。排查链路第一步确认监听器有没有真正注册到生产者上。自建Template时如果template.setProducer(producer)之前忘了producer.setTransactionListener(listener)发送照样能成但回查永远进不来。这个错误特别隐蔽因为发送日志一切正常。在启动日志里搜 transaction listener 相关的注册信息或者打个断点在setTransactionListener上确认执行了。第二步检查生产者组是否和Broker侧记录的一致。半消息在Broker上会记录生产者组回查时按组发请求。如果发送时用的组名和配置的Bean里的组名对不上比如一个带了下划线一个没带回查请求会找不到目标客户端。第三步看Broker日志里有没有回查请求的记录。如果Broker侧压根没发起回查问题在Broker配置transactionCheckInterval是不是被调得极大或者事务消息处理线程池被占满了。第四步检查客户端的instanceName。同一台机器上多个生产者实例如果instanceName相同但连接了不同的nameserver客户端实例会被复用导致注册关系混乱。稳妥做法是给每个生产者设一个独立的instanceName比如group - pid。6.2 半消息堆积现象RMQ_SYS_TRANS_HALF_TOPIC的消息量持续上涨消费延迟也跟着涨。排查链路先看是不是回查返回大量UNKNOWN。把check_count拉出来按业务类型分组统计如果某一类的平均值明显偏高说明那个业务的事务状态判定逻辑有问题可能一直返回UNKNOWN。常见原因是事务日志没能及时更新——比如业务代码在更新tx_status之前就抛异常了记录永远停在处理中。再看回查线程池的队列深度。前面说过默认单线程如果队列堆到几百说明回查处理速度跟不上。这时候要么扩线程要么检查回查里的SQL有没有走索引。回查是高频短请求一次慢查询就能拖垮整条链路。还有一种情况是Broker的transactionTimeOut配得太小半消息刚写完就被拉去回查了而本地事务其实还在跑回查必然返回UNKNOWN。这个参数默认6秒如果你的本地事务平均耗时超过3秒建议往上调否则会白白浪费回查次数。6.3 UNKNOWN之后消息消失现象某笔业务日志显示返回了UNKNOWN之后既没有Commit也没有Rollback下游一直没收到。根因往往是回查次数耗尽。默认最多15次每次间隔60秒理论上15分钟内会被反复问到。如果这15分钟里生产者一直重启或者回查持续异常消息就被按失败丢弃了。这个丢弃不会给你发告警只在Broker日志里有一行。规避手段是把check_count用起来超过10次还是UNKNOWN的记录主动打一条告警日志出来别等它被默默丢掉。同时补偿任务要覆盖这种记录靠定时扫描重新投递一次普通消息用消费端幂等兜住重复。6.4 事务消息和延迟、批量不兼容这个坑纯粹是文档没写清楚。事务消息的发送接口只接受单条消息批量接口sendMessageInTransaction压根没有。至于延迟级别实测下来在半消息阶段设置不生效Commit还原之后也不会带上延迟属性。所以如果你的业务需要下单30分钟后自动关单正确姿势是事务消息负责可靠投递下单成功事件消费端收到之后再发一条普通延迟消息用于超时关单。别想着一步到位。还有一个容易忽略的事务消息不支持顺序发送。半消息的还原是Broker内部异步完成的还原后的队列选择不一定和发送时的队列一致。要求严格顺序的场景这条链路得另做设计。7. 版本、参数与容量清理几个必须记住的数字把散落在各处的关键参数汇总成一张表调优和排障时对着看参数位置默认值调优建议transactionTimeOutBroker6000ms本地事务P99超过3秒时上调至10000~15000transactionCheckMaxBroker15不建议下调下调等于缩短容错窗口transactionCheckIntervalBroker60s单次回查耗时高时可上调减少无效回查回查线程池coreSize生产者1按回查QPS给2~8回查线程池queue生产者2000建议降到200~500配合拒绝策略sendMsgTimeout生产者3000ms跨机房时适当放大retryTimesWhenSendFailed生产者2保持默认事务消息重试代价高版本上还有一条经验rocketmq-spring-boot-starter2.2.x 对应的客户端是4.9.x2.3.x 才对齐到5.x。如果你的broker是4.x别硬上2.3.x的starter协议层虽然大体兼容但事务消息的回查协议在5.x里做过调整混搭时出问题极难排查。升级路径要么整套升要么老老实实锁在2.2.x。最后提一下监控。事务消息这条链路上至少有四个指标值得盯半消息堆积量、回查调用QPS、回查UNKNOWN占比、tx_message_log里状态为处理中且超过10分钟的记录数。前两个看整体健康度第三个看业务判定逻辑是否合理第四个看补偿任务有没有漏。前面三个上中间件的监控面板就能拿到最后一个得自己写个定时统计打点到日志里成本很低但救过我好几次。我在实际项目里最大的体会是事务消息这东西的价值不在于它能保证一致性而在于它把不一致暴露在了可观测的位置。半消息堆积、回查次数、UNKNOWN比例这些都是非常直接的信号比业务层自己埋一堆对账逻辑要清晰得多。真正省事的做法不是把代码写得多聪明而是把事务日志表当成核心资产来设计——字段留足、索引建对、状态机管好剩下的交给中间件和补偿任务出问题的概率会低很多。