CodeGuide 本地任务消息组件：基于门牌号分片扫描的动态任务补偿处理，兜住 HTTP/MQ 通知的最终一致性

文档教程后端【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址https://gitcode.com/gh_mirrors/code/CodeGuide点击查看免费下载在 CodeGuide 仓库的《本地任务消息组件》课程中动态任务补偿处理是整个最终一致性方案的最后一块拼图当 Spring Event 事件触发 MQ 推送或 HTTP 远程调用失败网络超时、服务宕机、线程阻塞、流量洪峰时靠本地消息表 定时任务补偿扫描来反复重试直到通知成功。读完本篇你可以掌握组件的补偿扫描流程门牌号 houseNumber 分片、最小游标查询、 id limit x批量拉取、通知完成后回写任务状态的设计边界以及下游必须做幂等的工程原因从而能独立实现一套可靠的本地消息补偿机制。一、为什么必须做任务补偿本组件要解决的问题是业务系统在完成数据库事务写库的同时还要对外发送 MQ 消息或发起 HTTP 调用。但 MQ 的发送和 HTTP 的调用都无法与数据库写操作处于同一个事务中这就天然存在失败的可能网络超时下游服务宕机线程阻塞流量洪峰导致调用失败。组件的整体链路是上游业务通过注解LocalTaskMessage AOP或直接调用组件服务ILocalTaskMessageHandleService在同一个事务内完成业务数据写入与本地消息表写入事务内写入完成后组件同步推送 Spring Event 事件由 trigger 层的监听器以Async异步方式触发事务外的 MQ 推送或 HTTP 回调HTTP 通道基于 Retrofit2 OkHttp3 封装MQ 通道使用 RabbitTemplate 推送。这条链路中从事务业务数据 任务表数据写入往后的一切操作——执行 http/mq 通知、更新数据库任务状态——都不是同一个事务的也就是说全部有可能失败。因此补偿机制的定位是兜底当首次异步通知失败后不能让这条任务记录停留在未通知状态必须由定时任务持续检测本地消息表并重试通知直到成功从而保证消息最终一致性和业务流程的可靠执行。二、补偿扫描流程设计门牌号分片 最小游标查询补偿的核心是一个定时任务扫描库表的过程。组件针对扫描效率做了两个关键设计。1. 门牌号houseNumber分片扫描为了提高整体扫描效率组件设计了门牌号机制可以配置多个任务每个任务只扫描自己门牌号范围内的任务记录多个任务并行扫描同一张表互不重叠。这一设计在仓库另一篇方案文档中也有明确阐述针对一张表的扫描如果数据量较大又不希望只是一个任务扫描一张表就需要多个任务扫描同一张表来加大扫描体量此时就需要门牌号来隔离不同任务扫描的范围避免多个任务扫描出重复的任务数据参见 方案设计基于库表分段扫描和数据Redis预热优化分布式延迟任务触达时效性。门牌号本质上把一张任务表切成了 N 个逻辑分片N 个调度任务各自认领一个分片从而在不引入分库分表的前提下提升了补偿扫描的吞吐量。2. 最小游标查询 批量拉取扫描库表时不是简单的limit x全表翻页而是先根据条件获取一个最小符合条件的 id之后以id minId limit x的方式获取数据列表。这样每一轮扫描都从当前最小的待处理记录开始批量拉取配合每轮处理完成后对任务状态的更新可以保证任务按插入顺序被逐步推进处理也避免了深分页带来的性能问题。3. 多任务组的动态调度配置从 组件总览文档 给出的能力清单可以确认补偿调度的落地形态是使用ConfigurationProperties驱动多任务组动态调度配置每个任务组配置自己的门牌号范围、触发方式和批次大小 limit触发方式支持cron与fixedDelay两种适配按时间表达式扫描和按固定间隔持续补偿两类场景调度底层使用ThreadPoolTaskScheduler做线程池化调度管理合理设置线程名与池大小提升任务调度的可观测性与稳定性数据访问层使用原生 JDBC 访问与 DAO 封装完成插入、状态更新、分片条件查询、最小游标查询四类操作——其中后两类正是补偿扫描流程直接依赖的能力。组件刻意选择 JDBC 而非引入 MyBatis原因在 第3节任务表设计和数据写入 中说明得很清楚组件需要引入上游系统的 DataSource 数据源与业务数据走同一个库连接操作直接用 JDBC 是为了避免上游系统引入组件时产生 ORM 框架版本冲突最原始的方法兼容性也是最好的。三、流程补充通知完成后必须回写任务状态仅靠定时扫描还不够。补偿机制生效的前提是任务状态真实反映通知结果因此原流程需要做补充http 调用操作、MQ 推送操作完成后都要调用 DAO 更新本地消息表中的任务记录状态——成功或失败。完整的状态流转是Spring Event 监听器接收消息执行通知操作http 或 mq通知成功更新任务记录状态为成功通知失败更新为失败定时补偿任务按门牌号分片 最小游标批量扫描出未成功的任务记录重新执行通知并再次回写状态。这里的关键认知是事务边界只覆盖业务数据 任务表数据的写入事务提交后的事件监听、远程调用、状态回写全部处于事务之外任何一环失败都不会回滚已提交的业务数据——这正是本地消息表模式宁可重复、不可丢失的设计哲学代价则是由补偿重试和下游幂等来消化。四、补偿的代价重复通知与下游幂等补偿重试必然引入一个问题补偿就可能重复。一次任务可能被首次异步通知执行了一次又被定时补偿扫描再次执行——http 可能被重复调用一次mq 可能被重复发送一次。文档给出的工程约束是对接下游业务时一定要做幂等操作例如以 OrderId 做唯一索引处理。也就是说本地消息表模式把消息可能丢失问题转化为消息可能重复问题而后者可以通过下游基于业务唯一键订单号等的幂等设计来彻底消化。这是接入本组件时下游服务必须满足的契约而不是组件的可选建议。五、组件定位与接入方式回顾理解补偿机制后可以回看组件在整体中的位置详见 项目总览、第1节组件需求分析、第4节通知策略处理组件按 DDD 分层与端口-适配器模式组织清晰划分 domain / infrastructure / trigger / config 模块领域层负责通知服务的策略分发按 notifyType 区分 http、mq扩展新通道在此处添加基础设施层完成 Retrofit2 封装的 HTTP 调用与 RabbitTemplate 的 MQ 推送trigger 层承载 Spring Event 监听config 层承载调度配置与切面逻辑本地消息表由引入组件的上游系统自行在自己的数据库中创建组件以同一数据源操作保证任务写入与业务写入处于同一事务上游可以通过自定义注解 切面拦截见 第6节切面拦截任务操作或直接调用handleService.acceptTaskMessage(taskMessageEntityCommand)的方式接入入参为TaskMessageEntityCommand命令对象。六、小结本篇覆盖的动态任务补偿处理回答了本地消息表模式的三个关键问题如何高效扫描门牌号 houseNumber 分片让多个定时任务并行扫描互不重叠最小游标查询配合 id limit x保证批量拉取的低成本与顺序性ConfigurationPropertiesThreadPoolTaskScheduler提供 cron / fixedDelay 双触发方式与 limit 批次大小的可配置调度如何保证状态闭环http、mq 通知完成后必须回写任务表状态事务外的每一步失败都由下一轮扫描兜住如何处理重复补偿天然可能重复通知下游必须以业务唯一键如 OrderId 唯一索引做幂等。三者合起来构成了本地事务写消息表 事件异步通知 分片定时补偿 下游幂等的完整最终一致性方案。赞分享文档教程后端【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址https://gitcode.com/gh_mirrors/code/CodeGuide点击查看免费下载相关推荐CodeGuide 本地任务消息组件通知策略处理用策略模式落地 HTTP 与 RabbitMQ 双通道通知CodeGuide 本地任务消息组件通知策略处理用策略模式落地 HTTP 与 RabbitMQ 双通道通知 本文基于 CodeGuide 开源仓库中《本地任文档教程后端Java 本地任务消息组件需求分析数据库事务与 MQ/HTTP 外部调用的最终一致性方案Java 本地任务消息组件需求分析数据库事务与 MQ/HTTP 外部调用的最终一致性方案 本篇基于 CodeGuide 仓库中《本地任务消息组件》项目的第 1文档教程后端本地任务消息组件让数据库事务与外部消息推送HTTP/RabbitMQ达成最终一致性的通用组件方案本地任务消息组件让数据库事务与外部消息推送HTTP/RabbitMQ达成最终一致性的通用组件方案 本文基于 CodeGuide 仓库中的《本地任务消息组件文档教程后端上一篇最完整的Spyder与AI伦理AI Fairness 360集成指南下一篇跨框架模型性能预测预估不同后端的执行时间创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考