架构

模块划分与代码结构

49 个 Maven 模块怎么分、为什么按业务域成对拆成 -api 与 -server、新增一个业务域要动哪几处。

最后更新:2026/11/19

一、为什么按业务域拆,而不按技术层拆

按技术层拆(controller / service / dao 三层各一个模块)看起来整齐,但改一个业务需求要在三个模块间来回跳,模块边界与业务边界对不上,长期会变成一团。

按业务域拆的逻辑是:一个业务域的改动尽量落在一个模块里。商品的价格逻辑只在 goods 里,订单状态机只在 order 里,售后流转只在 aftersale 里。

二、模块怎么成对

每个业务域拆成两个模块:

  • zhimengdie-module-<域>-api:对外契约,只放接口、DTO、枚举、常量
  • zhimengdie-module-<域>-server:实现,放 Mapper、Service、Controller

这样拆分的好处是依赖单向:其它模块只依赖 -api,不依赖 -server。编译期就能防止「为了省事直接调别人的实现类」,跨域调用必须走契约。

三、主要业务域

域职责规模(Java 文件数)
goods商品 SPU/SKU、分类、品牌、规格属性134
order订单状态机、下单、支付回调101
member会员、等级、积分、余额89
coupon券模板、发放、领取、核销62
decorate页面装修模板、组件白名单、发布回滚57
aftersale售后单流转、质检、退款56
pay支付单、渠道适配、对账53
logistics发货单、快递公司、物流轨迹35
invoice开票申请、红冲、操作留痕35
evaluate评价、评价标签、审核27
stock库存扣减、回补、冻结、调拨26
promo促销规则、限时购23
cms运营位、专题、模板管理15
supplier供应商入驻与档案(规划中 3/6)14
report销售报表、商品 TOP、会员报表12
notify通知与消息模板12
flash限时购场次11
cart购物车5

规模数字取自当前仓库实测,随代码演进会变;如果与最新仓库不一致,以仓库为准。

四、新增一个业务域要动哪几处

  1. 在根 pom.xml 的 <modules> 里加两行(-api 与 -server)
  2. 建两个模块目录,各自 pom.xml 里声明父工程与依赖
  3. -server 的包路径遵循 com.zhimengdie.<域>.{mapper,service,web}
  4. 建表 SQL 落到 agents_workspace/sql/,并在执行日志里登记
  5. 管理端菜单与按钮权限点入库(menu_scope 必标)
  6. 如果涉及租户,Mapper 层按多租户四步改造

不要做:把新业务塞进已有的域模块。域边界一旦模糊,成对拆分带来的隔离收益就没了。

五、分层约定

  • Controller 只做参数校验与编排,不写业务判断
  • 状态流转集中在 Service,不散落到 Controller
  • Mapper 只做数据访问,不写业务规则
  • 跨域调用只走 -api 接口,不直接注入别人的 Service 实现

需要针对你的场景给建议?

不用先看完全部文档。说清产品线与当前进度,我们直接给判断。