module.pub

简体中文

English

简体中文

English

外观

跨模块协作规范

约 1662 字大约 6 分钟

2026-06-02

跨模块协作规范

本文档约定 TG-boot 模块化单体下模块间如何协作：何时用 MQ、何时用同步 Api**Service，以及如何保证消息可靠性与幂等。

设计目标

跨模块协作遵循两条原则：

  1. 避免耦合：模块只依赖 *-api 契约，不依赖他域 *-biz 实现；发布方不应感知、更不应硬编码订阅方列表。
  2. 保持独立性：各业务域可独立演进、按需订阅或退订；新增消费者时，发布方代码与契约通常无需改动。

协作模式总览

TG-boot 将模块分为 公共通用组件（spring-boot-starter-components，如 system、verification、sms、trade）与 业务域模块（spring-boot-starter-business，如 customer、dating、distribution）。二者协作方式如下：

┌─────────────────────────────────────────────────────────────────┐
│  业务模块  ──同步 Api**Service──▶  公共通用组件 / 其他业务模块   │
│           （需立即结果：查用户、发短信、强一致编排）              │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  公共通用组件  ──MQ 发布-订阅──▶  各依赖它的业务模块（0～N 个）  │
│              （异步通知：登录、资料变更、支付成功等副作用）        │
└─────────────────────────────────────────────────────────────────┘
方式方向与模式适用场景契约位置典型调用方
MQ（发布-订阅）公共组件 → 业务模块；Pub/Sub 广播异步通知、多订阅方广播、解耦副作用、跨 runner / 未来拆服务*-api/messaging/XxxConsumer.java发布：MqPublisher；消费：实现 XxxConsumer.{Slot}
同步 Api**Service任意模块 → 任意模块；请求-响应同进程内强一致编排、需立即得到结果（含业务模块调用公共组件）*-api/service@Resource ApiXxxService 注入

要点

  • 公共通用组件的异步通知 → 走 MQ 发布-订阅：发布方只负责投递事件，不关心有多少订阅方；各业务域在自身 *-api 声明订阅槽位，在 *-biz 实现消费逻辑。
  • 业务模块使用公共组件能力（查用户、发短信、支付等）→ 走 同步 Api**Service：需要立即返回结果，不走 MQ。
  • 不要用 Spring ApplicationEvent 做跨模块协作（仅限模块内）。
  • 不要在 *-biz 的 Maven 依赖中引入其他域的 *-biz（仅允许 *-api + common）。
  • 不要在 *-api 的 Maven 依赖或 Java 源码中引用 *-biz（含本模块 crud.entity、crud.service）；Api**Service 契约必须使用 *-api/dto。
  • 不要在 *-api 中定义 Spi* 接口（模块内多实现 SPI 只在 *-biz/service）。
  • MQ 消费者内若需调用其他模块，优先注入 Api**Service（接口在 api、实现在对方 biz），而不是引用对方 crud 或 biz.impl。
  • 不要在 yml 中声明 domain binding；渠道契约统一在 XxxConsumer 接口，由 common 自动注册。
  • 跨模块写库后发 MQ 须使用 MqPublisher.publishAfterCommit（实现见 common 的 TransactionAfterCommit），禁止在 @Transactional 写库流程中直接 publish。

链路分类总表

一、MQ 异步链路（发布-订阅，跨模块副作用）

以下链路均为 单向广播或单向投递：发布方在公共/业务组件的 *-biz 中调用 MqPublisher，订阅方各自独立消费，互不影响。

Destination模式发布方消费方 group幂等键 / 策略说明
trade.order-goods.paid发布-订阅trade-bizdating / distributiontdOdGdCode（充值类由 customer 侧记录表保证）支付成功后履约 / 分佣
customer.profile.updated发布-订阅customer-biz各订阅域自定 groupcusCode + 字段比对跳过通用广播；槽位在订阅方 api（如 dating-api）
system.user.login发布-订阅system-bizcustomeruser.userCode 查重登录后初始化客户档案
system.user-info.updated发布-订阅system-bizcustomeruserCode + 昵称相同则跳过同步客户昵称
system.user.registered发布-订阅system-bizdistribution业务侧按推荐关系查重注册后绑定推荐
verification.phone-two-factor.verified发布-订阅verification-bizcustomer实名状态幂等更新二要素通过后更新客户
distribution.promoter-role.queryrequest-replydistribution-bizdating（应答）读查询，无写幂等分佣前查推广人角色（例外：需一问一答时用 request-reply）

发布-订阅契约约定

  • 根契约定义在 发布方 *-api/messaging/XxxConsumer.java（含 @MqChannel、消息体、发布方法）。
  • 订阅方在 自身 *-api 中声明嵌套 @MqSubscribe 子接口（如 SystemUserLoginConsumer.Customer），在 *-biz 中 @Component implements XxxConsumer.{Slot}。
  • 通用广播事件（如 customer.profile.updated）仅在 producer api 定义根契约；各订阅方按需新增槽位，发布方零改动。

契约：pub.module.*.api.messaging.*Consumer；运维基线：application-messaging-baseline.yml（common）。

二、同步 Api**Service 链路（同进程强一致）

以下场景 故意保留同步调用：在 HTTP 请求链路或 MQ 消费者内部，需要同一事务/立即结果，暂不拆 RPC。

调用方（biz）被调接口（api）触发上下文说明
dating-bizApiCustomerServiceMQ 消费者履约内充值会员权益等
dating-bizApiDtCusMatchmakerRelService同上合约类商品关联红娘
dating-bizApiSysUserService / ApiCustomerService 等HTTP 业务接口编排查询与写操作
各 bizApiSmsSendService / ApiSysUserService 等HTTP 业务接口业务模块调用公共组件，同步获取结果
distribution-bizApiSysUserService分佣 / 用户相关读取用户信息
customer-bizApiSysUserService客户资料与系统用户同步双向昵称/实名同步
各 biz本域或他域 Api**ServiceController / Service仅依赖 *-api，不依赖他域 -biz

演进：拆分为独立服务时，上表「同步 Api」行应改为 Feign/gRPC 或改为 Saga + MQ；MQ 表中的契约可保持不变。

三、模块内 SPI（非跨模块）

机制定义位置路由方式示例
Spi**Service*-biz/service注册表或 List<实现>短信、文件、支付渠道、二要素渠道

新增跨模块 MQ 能力检查清单

  1. 调用方是否需要 立即返回结果？是 → Api**Service；否 → MQ。
  2. 是否为 公共组件向依赖方异步通知？是 → MQ 发布-订阅；发布方不得依赖具体订阅方。
  3. 是否 多订阅方广播？是 → MQ 单向 Pub/Sub；通用事件仅在 producer api 定义根契约，各订阅方在自身 api 声明 @MqSubscribe 子接口。
  4. 是否 一问一答？是 → @MqChannel(mode=REQUEST_REPLY) + MqRequestReplyClient（少数读查询场景）。
  5. 消费者是否 幂等？必须声明幂等键（表唯一键 / 状态比对 / 业务编码查重）。
  6. *-biz/pom.xml 是否 只新增 -api 依赖？
  7. 消费者 biz 是否 @Component implements XxxConsumer.{Slot}（勿直接实现根接口）？

MQ 运维基线

详见 application-messaging-baseline.yml 与 common/README.md。

  • 重试：默认 max-attempts: 3，指数退避。
  • DLQ：消费失败后进入 DLQ.{destination}.{group}，交换机 DLX。
  • 监控：生产环境对 DLQ.* 队列深度告警；日志关键字 婚恋履约失败、推广人角色查询失败 等需接入日志平台。
  • 嵌入式 Rabbit：仅开发环境（tg.messaging.embedded-rabbit.enabled=true）；生产关闭并配置真实 broker。
welcome to tg.
copyright@module.pub