Appearance

Bundle ​

动机 ​

ECShopX Java 以 Bundle 划分业务域，避免单工程无限膨胀、便于团队并行开发与按需启用模块。每个业务域对应一个 Maven 子模块，由 ecshopx-bootstrap 统一装配为单个 Spring Boot 应用。

在 Java 工程中，Bundle 边界由 Maven Module + 包名前缀 共同体现：模块名 ecshopx-<domain> 对应根包 cn.shopex.ecshopx.<domain>。

核心约定 ​

1 Bundle = 1 Maven Module = ecshopx-<domain>
概念示例
Maven 模块名ecshopx-goods、ecshopx-orders
Java 根包cn.shopex.ecshopx.goods、cn.shopex.ecshopx.orders
启动装配ecshopx-bootstrap 的 pom.xml 引入所需模块依赖

公共能力不在业务 Bundle 内重复实现：

  • ecshopx-common — 异常、注解、MyBatis 元数据、Web 工具等
  • ecshopx-dispatch — 跨模块同步 / 异步事件
  • ecshopx-openapi — 开放 API 网关与 v1/v2 控制器（业务模块通过 Port 提供实现）

以 ecshopx-goods 为例的目录职责 ​

根包：cn.shopex.ecshopx.goods（ecshopx-goods/src/main/java/cn/shopex/ecshopx/goods/）

目录职责示例
apiHTTP 控制器，按受众分子包api/admin/v1、api/front/v1
service业务编排与领域逻辑service/items/GoodsItemsListFacadeService
mapperMyBatis-Plus BaseMapper 接口mapper/ItemsCategoryMapper
domain表映射实体（@MpTable / @MpField）domain/Items
repository在 Mapper 之上的查询/写入封装（复杂条件、批量、容错）repository/ItemsRepository
integration跨模块 Port 实现、外部系统适配integration/order/OrderCancelItemStoreRestorePortImpl
dispatch本模块发出的事件类型、payload、发布辅助类dispatch/ItemCreateEventDispatchPublisher
event领域事件类（若模块有定义）ecshopx-goods 当前为占位目录
cron@XxlJob 定时任务处理器本模块暂无处理器；参见 ecshopx-orders 的 cron
openapi开放接口 Port 实现及 v2 业务服务openapi/OpenapiItemStoreGetPortImpl、openapi/thirdapi/v2/*
config模块级 Spring 配置、异常 Advice 等config/GoodsAdminV1ExceptionAdvice
web模块级 Web 支撑（解析器、过滤器辅助等）web/DatapassBlockResolver

repository 与 mapper 的分工（以 goods 为准） ​

  • mapper：MyBatis-Plus 生成的单表 CRUD 与简单 LambdaQueryWrapper 访问。
  • repository：在 Mapper 上封装可复用的领域查询（多条件组合、批量、空表降级、公司维度隔离等），供 service 注入使用。

示例：ItemsRepository 注入 ItemsMapper，对外提供 getByItemIdAndCompany 等方法，避免 Service 层散落重复 Wrapper 代码。

并非所有模块都有 repository 包；新增时仅在 Mapper 不足以表达查询语义时引入。

跨模块规则 ​

  1. 禁止 Bundle A 直接 import Bundle B 的 mapper / domain（会形成紧耦合与循环依赖风险）。
  2. 推荐 通过以下方式协作：
    • ecshopx-common 中的 Port 接口 + 提供方模块的 integration / openapi 实现
    • ecshopx-dispatch 事件：发布方在 dispatch 定义并发送，消费方注册监听
  3. 装配：所有实现类由 Spring 扫描；模块能否生效取决于 ecshopx-bootstrap 是否引入该模块依赖。

新增业务模块检查清单 ​

  • [ ] 父工程 pom.xml <modules> 增加 ecshopx-<domain>
  • [ ] ecshopx-bom（或父 POM dependencyManagement）登记模块坐标
  • [ ] ecshopx-bootstrap/pom.xml 增加对 ecshopx-<domain> 的依赖
  • [ ] 根包命名为 cn.shopex.ecshopx.<domain>
  • [ ] 按上表建立 api / service / mapper / domain 等目录
  • [ ] 跨模块能力先定义 Port（ecshopx-common 或领域 Port 模块），再在 integration 实现
  • [ ] 若有定时任务，在 cron 包声明 @XxlJob，并在 XXL-JOB Admin 配置同名 JobHandler
  • [ ] Flyway 迁移脚本放在 ecshopx-bootstrap/src/main/resources/db/migration（全库统一版本化）

相关章节 ​