模块命名规范

Maven 模块

必须 使用 ecshopx-<domain> 作为 Maven 子模块名，与业务域一一对应。

概念	规范	示例
Maven 模块	ecshopx-<domain>	ecshopx-goods、ecshopx-orders
Java 根包	cn.shopex.ecshopx.<domain>	cn.shopex.ecshopx.goods
启动装配	ecshopx-bootstrap 引入依赖	见 Bundle

新增模块时同步更新：父 POM <modules>、ecshopx-bom、ecshopx-bootstrap/pom.xml。

包内目录

以 ecshopx-goods 为例，根包下常见目录：

目录	职责
api	HTTP 控制器，admin/v1、front/v1 分子包
service	业务编排与领域逻辑
mapper	MyBatis-Plus BaseMapper
domain	表映射实体
repository	Mapper 之上的可复用查询封装（按需）
integration	跨模块 Port 实现
dispatch	本模块事件发布
openapi	开放 API Port 实现
cron	@XxlJob 定时任务
config	模块级 Spring 配置

类命名

类型	规范	示例
实体	单数名词，与表语义一致	Items、NormalOrders
Mapper	<Entity>Mapper	ItemsMapper
Repository	<领域>Repository	ItemsRepository
Service	<业务>Service 或 <动作>FacadeService	GoodsItemsListFacadeService
Controller	<资源>Controller，放 api.admin.v1 或 api.front.v1	ItemsController
领域事件	<业务>Event	按模块约定
XXL-JOB	@XxlJob("handler-name") 与 Admin 配置同名	aliyunsms-run-task

实体（domain）

• 必须 放在对应模块的 domain 包下；
• 字段 推荐 使用 Lombok 或显式 getter/setter，与 MyBatis-Plus 映射一致；
• 布尔字段在 Java 侧 不要 加 is 前缀（与 MySQL 规范 中 is_xxx 列名映射约定一致）。

控制器

控制器方法 应该 只承担：

1. 校验入参（含鉴权注解）；
2. 调用 service；
3. 封装统一响应（ApiResult、@DingoResponse）。

• 单方法 应该 控制在约 80 行以内；超出则将逻辑下沉 service；
• 禁止 在 Controller 中直接注入 Mapper / Repository；
• 禁止 跨模块直接注入对方 Bundle 的持久化类，应通过 Port 或事件。

详见 Controller、API 控制器规范。