module.pub

简体中文

English

简体中文

English

外观

t

约 2875 字大约 10 分钟

2026-05-16

开发平台（AI 协作友好）

本文档面向 AI 助手与开发者，是 tg-boot 文档站入口：说明最新模块分层、协作边界，以及生成代码前的硬性约定。

优先级文档说明
必读AI 编码规范实体 BaseEntity、双主键、*-api 边界、检查清单
必读跨模块协作规范MQ 与同步 Api**Service 选用、依赖禁止项
部署运维说明Actuator 禁止公网暴露、MQ 生产配置
门禁架构测试ArchUnit 模块边界守护
理念树-图架构树形定边界、图形定关系

定位

TG 基于 Spring Boot 3.5.x，以 Maven 多模块划分 common / components / business / runner；默认将多个 *-biz 打进同一个 spring-boot-starter-runner 进程（模块化单体）。

  • 模块之间：只通过 *-api 中的 Api**Service 与 MQ 消息契约协作。
  • 模块内部：在 *-biz/service 用 SPI 表达多实现（支付渠道、短信、存储等），由注册表路由。
  • v3.6.0 起：移除低代码生成器与通用字典模块，改由 AI + 仓库约定 驱动开发（见 版本变更）。

模块架构（与 pom.xml 同步）

以 spring-boot-starter-module 下各聚合 pom.xml 为准；增删 runner 能力一般只改 [spring-boot-starter-runner/pom.xml](https://gitee.com/pub_module/tg-boot/blob/master/spring-boot-starter-module/spring-boot-starter-runner/pom.xml)。

Maven 模块树

tg-boot
├── spring-boot-starter-module          # Maven 反应堆根
│   ├── spring-boot-starter-common      # 公共内核（Result、BaseEntity、MQ 基础设施、安全）
│   ├── spring-boot-starter-components  # 通用能力组件（12 个子模块）
│   │   ├── spring-boot-starter-system       # 用户/组织/权限（核心）
│   │   ├── spring-boot-starter-trade        # 商品订单、支付
│   │   ├── spring-boot-starter-distribution # 分销分佣、钱包
│   │   ├── spring-boot-starter-verification # 二要素/资产认证
│   │   ├── spring-boot-starter-ai           # AI 对话、智能体、消耗明细
│   │   ├── spring-boot-starter-sms          # 短信（SPI 多厂商）
│   │   ├── spring-boot-starter-wechat       # 微信能力
│   │   ├── spring-boot-starter-file         # 文件上传/存储
│   │   ├── spring-boot-starter-cms          # CMS
│   │   ├── spring-boot-starter-im           # 即时通讯
│   │   ├── spring-boot-starter-excel        # Excel 导入导出
│   │   └── spring-boot-starter-ocr          # OCR
│   ├── spring-boot-starter-business    # 垂直业务域
│   │   └── spring-boot-starter-dating       # 婚恋/约会（含 DtCustomer 等）
│   │       ├── spring-boot-starter-dating-api
│   │       └── spring-boot-starter-dating-biz
│   ├── spring-boot-starter-runner      # 默认可执行单体（按需引入 *-biz）
│   └── spring-boot-starter-architecture-tests  # 构建期架构门禁（非运行时代码）
├── tg-vue                              # 管理端（Vue 3 + Element Plus + Vite）
├── tg-uniapp                           # 多端壳（uni-app / unibest）
└── plugins/                            # 运行时外置插件目录

协作关系图

Runner 装配原则：runner/pom.xml 显式列出需要的 *-biz；未引入的 biz 不会注册 HTTP 接口与 MQ 消费者。裁剪能力 = 删依赖，不必改上层模块树。

单个域的源码包结构（*-api / *-biz）

*-api/                              # 对外契约，被其他模块 Maven 依赖
├── api/constants/                  # XxxCodeEnum
├── api/dto/                        # 跨模块 DTO / VO
├── api/service/                    # Api**Service 接口
└── api/messaging/                  # MQ 契约（XxxConsumer）

*-biz/                              # 实现层，由 runner 聚合
├── biz/
│   ├── controller/{cus|mgt|pub}/   # 用户端 / 管理端 / 公开接口
│   ├── service/
│   │   ├── impl/                   # Api**Service 实现、SPI 实现
│   │   └── Spi**Service            # 模块内多实现（仅 biz/service）
│   └── messaging/                  # MQ 消费者 Handler
├── crud/
│   ├── entity/                     # 必须 extends BaseEntity
│   ├── mapper/
│   └── service/impl/               # MyBatis-Plus Service（含 getByCode）
└── Biz*AutoConfiguration.java

三层协作机制对照

层级机制定义位置适用场景
跨模块异步MQ + XxxConsumer*-api/messaging登录通知、支付成功副作用、资料变更广播
跨模块同步**Api**Service***-api/service同进程强一致编排、需立即返回结果
模块内多实现**Spi**Service***-biz/service短信渠道、支付渠道、文件存储等

AI 编码规范（生成代码前必读）

完整版含正反例与路径索引：AI 编码规范。Cursor / Copilot 会话开始时应 @ 该文档或本文。

阅读顺序

  1. AI 编码规范（硬性约定 + 检查清单）
  2. 本文（模块树与 MQ 原则）
  3. 目标子模块 README（如 sms、dating）
  4. 同域已有代码作模板：**SysUser、DtCustomer、DtMatchmaker、SmsTemplate**

持久层：最高频错误

必须继承 BaseEntity（pub.module.common.model.po.BaseEntity），禁止在实体上重复手写 createTime / deleted 等审计字段。

双主键模型：

层级字段说明
技术主键id在 BaseEntity 中，@TableId(type = IdType.ASSIGN_ID)，子类禁止再标 @TableId
业务主键xxxCode普通列，对外关联用语义编码（如 userCode、dtCusCode）

Service 配套（crud/service/impl）：

  • 提供 getByCode(String code) 按业务编码查询
  • updateById 前先 getByCode 取 id 再更新
  • 管理端按业务编码删除用 removeByBizCodes，不要对 xxxCode 调 removeByIds

*-api 边界（最高频架构错误）

层级规则
Maven*-api/pom.xml 只能依赖 common 或他域 *-api；禁止依赖任何 *-biz
Java*-api 内 禁止 import crud.entity、crud.mapper、biz.service.impl
Api 契约Api**Service 入参/返回值 必须是 *-api/dto 或枚举，禁止出现 crud.entity.*
// ❌ 禁止：api 返回 crud 实体
VtAssetCertRecord submitApply(...);

// ✅ 正确：api 返回 DTO
VtAssetCertRecordDTO submitApply(...);

命名摘要

  • 目录式命名：表前缀 + 字段名（如 distUserCode），省略系统层，禁止 *SysUserCode（trade 历史字段勿模仿）
  • ***Code**：字典/枚举字段；枚举放 *-api/constants，类名 XxxCodeEnum
  • ***StatusCode**：仅 0/1（否/是），null 视同否；禁止放流程中间态
  • ***ProcessCode**：多步审核流程；终态通过时同步 *StatusCode = 1
  • 已废弃：通用字典表 / spring-boot-starter-dict

跨模块 MQ 发布（硬性）

写库后投递消息 必须在事务提交后：

mqPublisher.publishAfterCommit(XxxConsumer.class, payload);

禁止在 @Transactional 写库方法内直接 publish（无事务的只读场景除外）。

生成代码后检查清单

  • crud/entity/* 全部 extends BaseEntity，无重复 @TableId 在 xxxCode 上
  • Api**Service 契约无 crud.entity 引用；*-api/pom.xml 无 *-biz 依赖
  • *-biz/pom.xml 跨域只新增 *-api 依赖，不依赖他域 *-biz
  • ServiceImpl 含 getByCode；按业务编码查询用 getByCode 而非 getById
  • 跨模块写库后发 MQ 使用 publishAfterCommit
  • 新增业务域已在 architecture-tests/pom.xml 补充 *-api 与 *-biz
  • 已执行过的 create_*.sql 勿改；新字段另写 alter_*.sql

本地校验：mvn -pl spring-boot-starter-architecture-tests -am test

MQ 通信与模块依赖原则

完整链路表与演进说明：跨模块协作规范。

两大设计原则

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

协作模式选型

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

┌─────────────────────────────────────────────────────────────────┐
│  公共组件  ──MQ 发布-订阅──▶  0～N 个订阅方（dating / distribution）│
│           （异步副作用：登录、资料变更、支付成功等）               │
└─────────────────────────────────────────────────────────────────┘
场景选用契约位置
需 立即返回 结果同步 Api**Service*-api/service
异步通知、多订阅方广播MQ 发布-订阅*-api/messaging/XxxConsumer.java
一问一答（少数读查询）MQ request-reply@MqChannel(mode=REQUEST_REPLY)

Maven 与 Java 依赖禁止项

禁止正确做法
*-biz 依赖他域 *-biz只依赖他域 *-api + common
*-api 依赖 *-biz 或 import crud.*契约只用 *-api/dto
*-api 定义 Spi* 接口SPI 只在 *-biz/service
跨模块拼 SQL 关联对方表同步表、API 组装、MQ 冗余
yml 手写 domain binding契约在 XxxConsumer，common 自动注册
Spring ApplicationEvent 跨模块仅限模块内
事务内直接 publishMqPublisher.publishAfterCommit

MQ 契约约定

  • 单文件定义：发布方 *-api/messaging/XxxConsumer.java 含 @MqChannel、消息体、嵌套 @MqSubscribe 槽位
  • 消费实现：*-biz/messaging/ 下 @Component implements XxxConsumer.{Slot}（勿直接实现根接口）
  • 通用广播：根契约在发布方 api；各订阅方在 自身 api 声明槽位，发布方零改动
  • 基础设施：common 提供 MqPublisher、MqMessagingAutoConfiguration、嵌入式 Rabbit（dev）、application-messaging-baseline.yml（重试/DLQ）

现有 MQ 链路（代码扫描）

Destination模式发布方消费方 group说明
trade.order-goods.paid单向trade-bizdating / distribution支付成功后履约 / 分佣
system.user.login单向system-bizdating登录后初始化婚恋客户档案
system.user-info.updated单向system-bizdating用户昵称变更同步
system.user.registered单向system-bizdistribution注册后绑定推荐关系
verification.phone-two-factor.verified单向verification-bizdating二要素通过后更新实名
dating.profile.updated单向dating-bizdating资料变更域内冗余同步
wx.pay.notify单向wechat-biztrade微信支付回调异步处理

契约类路径：pub.module.*.api.messaging.*Consumer；运维基线见 common。

新增 MQ 能力决策树

  1. 调用方是否需要 立即返回？→ 是：Api**Service；否：继续
  2. 是否为 公共组件向依赖方异步通知？→ 是：MQ 发布-订阅
  3. 是否 多订阅方广播？→ 各订阅方在自身 api 声明 @MqSubscribe 槽位
  4. 消费者是否 幂等？→ 必须声明幂等键（唯一键 / 状态比对 / 业务编码查重）
  5. *-biz/pom.xml 是否 只新增 -api 依赖？

技术栈

类别技术
后台Spring Boot 3.5.5、Spring Security、MyBatis-Plus
前台Vue 3、Element Plus、Vite（tg-vue）
消息Spring Cloud Stream + RabbitMQ（dev 嵌入式 Rabbit）
数据库MySQL、PostgreSQL、Oracle、SQL Server、达梦、人大金仓等

组件清单以 components 子文档为准。

快速启动

内置 JDK / Maven（tg-boot/.tools）

组件路径
JDK 21tg-boot/.tools/jdk-21
Maventg-boot/.tools/apache-maven-*/bin

启动默认 runner

先确保 MySQL / Redis 等与 application-dev.yml 一致，在 **tg-boot 根目录**：

.\scripts\run-runner.ps1

或在 **spring-boot-starter-module** 目录（须保留 -am）：

mvn -pl spring-boot-starter-runner -am spring-boot:run -DskipTests

文档索引

分区说明
AI 编码规范实体、命名、跨模块硬性约定
跨模块协作规范MQ 与 Api 选用规则
运维说明Actuator 安全、MQ 生产配置
架构测试门禁ArchUnit 模块边界
树-图架构树形定边界、图形定关系
starter-moduleMaven 聚合根
runner默认单体启动器
components通用 Starter（system、trade、ai…）
business垂直业务域（dating）
plugins运行时外置插件
tg-manage-vue管理端前端

开发约定摘要

字典与状态字段

  • ***Code**：存编码不存展示名；枚举在 *-api/constants
  • ***StatusCode**：仅 0/1；***ProcessCode**：多步流程中间态
  • v3.6.0 起：全面舍弃通用字典模块，常量走枚举、复杂选项走业务表

表设计

  • 系统字段来自 BaseEntity（id、审计、逻辑删除、版本等）
  • 业务字段：表前缀 + 字段名；跨表冗余与来源列保持同一语义

版本变更历史

v3.6.0（2026-05-20）

次版本升级（3.5.2 → 3.6.0）：以架构收敛与 AI 协作友好为主。

变更说明
移除低代码 / 代码生成改由 AI 按仓库约定从表结构 → API → biz 手写
移除通用字典模块常量用枚举、复杂选项用业务表、国标数据用专属表
客户域收敛独立 customer 模块已合并进 dating（DtCustomer）；MQ group 由 customer 改为 dating
新增 AI 组件spring-boot-starter-ai（api + biz）
分销提升为 componentspring-boot-starter-distribution 归入 components

对开发者：新功能按本文 AI 编码规范 与 MQ 原则 扩展；升级时清理对 dict / generator 的依赖。

版本说明
3.5.2上一稳定次版本

链接

文档与 tg-boot 仓库同步；若与 pom 不一致，以 spring-boot-starter-module 实际模块为准。

welcome to tg.
copyright@module.pub