CPS/SPS系统包结构设计与多模块工程实践

1. 为什么CPS/SPS系统需要特别关注包结构设计在电商和供应链领域摸爬滚打多年后我深刻体会到CPSCost Per Sale和SPSSupply Platform System这类系统的复杂性。与普通业务系统不同它们通常需要同时处理多层级的分佣计算涉及复杂的树形结构关系实时订单流水与异步结算的对账供应商、分销商、平台方的多角色权限体系动态规则引擎如分佣比例、促销活动叠加去年我们重构一个日订单量50万的CPS系统时就曾因为初期包结构设计不合理导致核心分佣逻辑散落在service、util、manager等多个包中新同事花了2周才理清一个简单订单的分佣调用链路想加个新的分佣规则类型需要修改6个不同包下的类2. 多模块工程的顶层设计原则2.1 模块划分的黄金法则根据领域驱动设计DDD和实际项目经验我总结出CPS/SPS系统的模块划分公式[系统简称]-[层级]-[功能域]例如cps-domain // 领域模型核心 cps-service // 业务逻辑实现 cps-api // 对内/对外接口 cps-job // 定时任务 cps-admin // 管理后台关键点domain模块必须保持纯净只包含实体类Entity值对象Value领域服务接口无实现仓储接口Repository2.2 依赖关系的控制技巧通过maven的dependencyManagement实现精准控制!-- 父pom中定义版本 -- dependencyManagement dependencies dependency groupIdcom.cps/groupId artifactIdcps-domain/artifactId version${project.version}/version /dependency /dependencies /dependencyManagement !-- 子模块按需引用 -- dependencies dependency groupIdcom.cps/groupId artifactIdcps-domain/artifactId /dependency /dependencies禁止出现的情况service模块依赖api模块domain模块引入spring-boot-starter-webjob模块直接调用dao层3. 业务模块内部的包结构设计3.1 按业务能力划分包反面案例按技术分层com.cps.order ├── controller ├── service ├── dao └── entity推荐方案按业务语义com.cps.order ├── command // 下单相关 ├── settlement // 结算相关 ├── promotion // 促销活动 └── sharing // 分佣逻辑每个子包内包含该业务能力的所有层次代码com.cps.order.sharing ├── SharingController.java ├── SharingService.java ├── SharingRepository.java ├── SharingCalculator.java // 核心分佣算法 └── model ├── SharingRule.java // 分佣规则值对象 └── SharingRecord.java // 分佣记录实体3.2 领域事件的包设计技巧对于CPS系统常见的订单完成触发分佣场景com.cps.order.event ├── OrderCompletedEvent.java ├── OrderEventPublisher.java └── handler ├── SharingHandler.java // 处理分佣 ├── SettlementHandler.java // 生成结算单 └── StatsHandler.java // 更新统计数据使用Spring的ApplicationEvent实现解耦// 事件发布 eventPublisher.publishEvent(new OrderCompletedEvent(orderId)); // 事件处理 TransactionalEventListener public void handle(OrderCompletedEvent event) { sharingService.calculate(event.getOrderId()); }4. 复杂业务场景的包结构实践4.1 多级分佣的场景实现对于涉及推广员→代理商→区域总监的多级分佣com.cps.sharing ├── calculator │ ├── AbstractSharingCalculator.java │ ├── DirectSharingCalculator.java // 直接分佣 │ └── TreeSharingCalculator.java // 树形分佣 ├── model │ ├── SharingRule.java │ └── SharingNode.java // 分佣节点树 └── service ├── SharingRuleService.java └── SharingExecuteService.java使用策略模式避免if-elsepublic interface SharingCalculator { SharingResult calculate(Order order); } Service public class SharingService { private MapSharingType, SharingCalculator calculators; public SharingResult calculate(Order order) { return calculators.get(order.getSharingType()) .calculate(order); } }4.2 动态规则引擎的包设计对于需要支持动态配置的分佣规则com.cps.rule ├── engine │ ├── RuleEngine.java │ └── RuleExecutor.java ├── loader │ ├── DatabaseRuleLoader.java │ └── CacheRuleLoader.java └── model ├── RuleDefinition.java └── RuleCondition.java使用Groovy实现动态规则// 规则定义示例 rule { name VIP用户加倍分佣 when { order.amount 10000 user.level VIP } then { sharingRate baseRate * 2 } }5. 实际项目中的避坑指南5.1 循环依赖的破解方法当出现order模块依赖sharing模块sharing模块又需要查询order信息时提取公共模型到core模块com.cps.core ├── model │ ├── OrderInfo.java // 精简的订单信息 │ └── SharingInfo.java └── service └── SharingQueryService.java使用事件驱动// order模块发布事件 eventPublisher.publishEvent(new OrderPaidEvent(orderId)); // sharing模块监听处理 EventListener public void onOrderPaid(OrderPaidEvent event) { // 处理分佣逻辑 }5.2 多环境配置管理建议的配置文件结构src/main/resources ├── application.yml // 公共配置 ├── application-dev.yml // 开发环境 ├── application-test.yml // 测试环境 └── application-prod.yml // 生产环境模块特有配置使用ConfigurationPropertiesConfigurationProperties(prefix cps.sharing) public class SharingProperties { private boolean asyncMode; private int queueSize; // getters/setters }5.3 接口版本控制方案对于频繁变更的CPS接口com.cps.api ├── v1 │ ├── SharingApiV1.java │ └── model │ └── SharingRequestV1.java └── v2 ├── SharingApiV2.java └── model └── SharingRequestV2.java使用URL路径版本控制RestController RequestMapping(/api/v1/sharing) public class SharingApiV1 { // 旧版实现 } RestController RequestMapping(/api/v2/sharing) public class SharingApiV2 { // 新版实现 }6. 我的实战经验总结经过多个CPS系统的迭代有几个血泪教训值得分享领域模型要早定型分佣规则的核心模型如SharingRule一旦确定后续修改成本极高。建议前期用Excel模拟各种分佣场景用单元测试验证模型边界数据库预留20%的扩展字段包结构要留扩展空间我在com.cps.sharing下预留了这些包├── extension // 各业务方扩展 ├── callback // 第三方回调 └── adapter // 外部系统适配文档即代码每个重要包下放package-info.java/** * 分佣核心计算包 * - 包含多级分佣算法实现 * - 修改计算逻辑需同步更新 {link SharingTest} * - 新增计算器需注册到 {link SharingCalculatorRegistry} */ package com.cps.sharing.calculator;监控埋点要内置在包设计阶段就考虑com.cps.sharing.monitor ├── SharingMetrics.java └── SharingLogAspect.java最后提醒好的包结构应该让新成员在3天内能定位到90%的业务代码位置。如果你发现团队频繁出现这个功能在哪实现的这样的问题就是时候重新审视包结构了。