COLA使用配置

一、COLA 核心理念与结构

1. 主要分层

• Client 层（接口层）：对外暴露 API（如 Controller、OpenAPI、RPC 等）。
• Application 层（应用层）：编排用例（UseCase），不写具体业务逻辑，负责协调和事务控制。
• Domain 层（领域层）：核心业务逻辑和领域模型，领域服务、实体、聚合根等。
• Infrastructure 层（基础设施层）：与技术细节相关，如数据库、消息中间件、第三方服务等。

2. 关键模式

• Command-Query Responsibility Segregation（CQRS）：命令和查询分离。
• 扩展点机制（Extension Point）：方便业务扩展和插件化。
• Event 机制：领域事件驱动业务解耦。

---

二、COLA 快速搭建

1. 创建项目

官方推荐使用 cola-template 脚手架或 Spring Initializr 手动分层创建。

目录结构示例

src
├── client         # 对外接口（Controller/DTO/Facade）
├── application    # 应用服务/编排
├── domain         # 领域模型/服务
├── infrastructure # 基础设施（DB、MQ、RPC等）
└── test           # 单元测试

2. 添加依赖

Maven 依赖（以 4.x 版本为例）：

<dependency>
    <groupId>com.alibaba.cola</groupId>
    <artifactId>cola-component</artifactId>
    <version>4.2.0</version>
</dependency>

你还需要添加 Spring Boot、MyBatis、Lombok 等常用依赖。

---

三、COLA 配置详解

1. 基本配置（application.yml）

server:
  port: 8080

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/cola_demo
    username: root
    password: yourpassword
  main:
    allow-bean-definition-overriding: true

cola:
  extension:
    scanPackages: com.example.demo # 指定扩展点扫描包路径

2. 各分层职责和配置

1）Client 层

• 只暴露 API，不包含业务逻辑。
• 通常为 Spring MVC Controller 或 Dubbo Service。
• DTO、Command、Query、VO 等对象定义于此。

@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    private UserServiceI userService;

    @PostMapping("/register")
    public SingleResponse<UserVO> register(@RequestBody UserRegisterCmd cmd) {
        return userService.register(cmd);
    }
}

2）Application 层

• 用例编排，调用 domain 层服务。
• 用 ServiceI 接口 + Impl 实现，通常 ServiceI 在 client 层，Impl 在 application 层。

@Service
public class UserServiceImpl implements UserServiceI {
    @Autowired
    private UserDomainService userDomainService;

    @Override
    public SingleResponse<UserVO> register(UserRegisterCmd cmd) {
        // 参数校验、流程编排
        User user = userDomainService.createUser(cmd.getName(), cmd.getPwd());
        return SingleResponse.of(UserVO.from(user));
    }
}

3）Domain 层

• 纯业务逻辑，不依赖 Spring、数据库等技术栈。
• 包括实体（Entity）、聚合根（Aggregate）、领域服务（DomainService）、工厂、仓储接口（Repository）。

public class User {
    private String name;
    private String pwd;
    // 领域行为
    public void changePwd(String newPwd) { ... }
}

4）Infrastructure 层

• 依赖具体技术实现，如 MyBatis Mapper、Redis、MQ 等。
• 实现 domain 层定义的 Repository 接口。

@Repository
public class UserRepositoryImpl implements UserRepository {
    @Autowired
    private UserMapper userMapper;

    @Override
    public void save(User user) {
        userMapper.insert(user);
    }
}

---

四、COLA 扩展点与插件机制

1. 扩展点定义

• ExtensionPoint：业务可扩展点（如不同地区、租户、场景下的实现）。

public interface PromotionExtPt extends ExtensionPointI {
    void applyPromotion(Order order);
}

2. 扩展实现

• 用 @Extension 注解标记，并指定扩展点的业务场景（如 BizId、UseCase、场景等）。

@Extension(bizId = "CN", useCase = "Order", scenario = "Discount")
public class ChinaPromotionExt implements PromotionExtPt {
    @Override
    public void applyPromotion(Order order) {
        // 中国区促销逻辑
    }
}

• 在业务流程中通过 ExtensionExecutor 调用：

@Autowired
private ExtensionExecutor extensionExecutor;

extensionExecutor.execute(PromotionExtPt.class, order.getBizId(), ext -> ext.applyPromotion(order));

---

五、COLA 事件机制

• 支持领域事件、应用事件，便于业务解耦。
• 可用 Spring 的 @EventListener 或自定义 COLA 事件。

---

六、常见问题与实践建议

1. 分层职责要清晰，Client 只做接口，Application 只做编排，Domain 只做业务，Infrastructure 只做技术实现。
2. DTO/Command/Query/VO 要分离，避免混用。
3. 扩展点要聚焦可变业务，通用逻辑不要滥用扩展点。
4. Repository 只定义于 Domain 层，具体实现放 Infrastructure 层。
5. 领域模型不要依赖 Spring、MyBatis 等技术类库，保持纯净。

---

七、常见问题排查

• 扩展点不生效：检查 scanPackages 配置，扩展实现类包路径是否正确。
• 分层依赖错误：确保依赖只从上往下（Client→Application→Domain→Infrastructure），不要反向依赖。
• 领域模型污染：Domain 层不要引用 Spring、MyBatis、DTO 等。

八、COLA 扩展点进阶

1. 多维扩展点（BizId、UseCase、Scenario）

COLA 的扩展点支持多维度组合，便于应对复杂业务场景。

示例

@Extension(bizId = "CN", useCase = "Order", scenario = "Discount")
public class ChinaOrderDiscountExt implements PromotionExtPt { ... }

@Extension(bizId = "US", useCase = "Order", scenario = "Discount")
public class USOrderDiscountExt implements PromotionExtPt { ... }

调用时可指定维度：

extensionExecutor.execute(PromotionExtPt.class, "CN", "Order", "Discount", ext -> ext.applyPromotion(order));

2. 扩展点优先级与排序

• 可以通过实现 Ordered 接口为扩展点设置优先级。
• 支持按优先级链式调用，适合“责任链”模式处理。

---

九、事件驱动与领域事件

1. 领域事件定义

领域事件用于解耦领域层与应用层、基础设施层的变化。

示例

public class UserRegisteredEvent extends DomainEvent {
    private Long userId;
    // ...
}

2. 事件发布与监听

• 在领域层业务发生后发布事件：

DomainEventPublisher.publish(new UserRegisteredEvent(user.getId()));

• 在 Application 或 Infrastructure 层监听事件：

@EventListener
public void handleUserRegistered(UserRegisteredEvent event) {
    // 发送欢迎邮件等
}

---

十、分层测试策略

1. Client 层

• 测试接口的参数校验、DTO 映射、API 返回值。

2. Application 层

• 测试用例编排、事务控制、异常处理。
• 推荐使用 Mock 测试 Domain 层服务。

3. Domain 层

• 重点测试业务逻辑、领域服务、聚合根行为。
• 保持无依赖，易于单元测试。

4. Infrastructure 层

• 测试技术实现，如数据库 CRUD、MQ 消息发送。
• 可用集成测试验证数据一致性。

---

十一、与 Spring Boot 深度集成

1. 自动装配扩展点

• 在 application.yml 指定扩展点扫描包路径，COLA 自动发现扩展实现。

cola:
  extension:
    scanPackages: com.example.demo.extension

2. 分层包结构推荐

• 推荐每层独立 package，避免循环依赖。
• 例如：com.example.demo.client、com.example.demo.application、com.example.demo.domain、com.example.demo.infrastructure

3. 事务管理

• 事务建议只在 Application 层控制（如 @Transactional），Domain 层保持无事务。

---

十二、性能与运维建议

1. 扩展点扫描优化

• 只扫描实际用到的扩展包，减少启动时间。
• 扩展点实现类保持轻量，避免复杂依赖。

2. 分层日志管理

• 各层日志分开记录，便于定位问题。
• 推荐在 Application 层统一异常和日志处理。

3. 监控与健康检查

• 可在 Application 层暴露健康检查 API。
• 关键扩展点、领域事件建议埋点监控。

---

十三、实际业务场景案例

1. 多租户场景

• 不同租户（BizId）可有不同扩展点实现，灵活适配业务差异。

2. 复杂促销规则

• 促销逻辑作为扩展点，按地区/场景定制，易于灰度发布和动态切换。

3. 订单流程编排

• Application 层编排支付、发货、通知等用例，Domain 层定义订单聚合根和行为。

---

十四、常见问题补充

1. 扩展点未被发现

   • 检查 scanPackages 配置和扩展实现类包路径。
   • 确认扩展实现类加了 @Extension 注解。

2. 领域事件未被消费

   • 检查事件发布和监听方法是否在 Spring 容器中。
   • 确认事件类和监听类包路径无误。

3. 分层依赖混乱

   • 重新梳理依赖关系，确保上层只依赖下层，避免跨层引用。

十五、扩展点动态注册与卸载

COLA 默认通过注解和包扫描发现扩展点实现，但在一些高级场景（如插件化、运行时扩展）可能需要动态注册或卸载扩展。

1. 动态注册扩展点

可通过编程方式将扩展点实现类注册到 ExtensionRepository：

ExtensionRepository.registerExtension(PromotionExtPt.class, "CN", new ChinaPromotionExt());

• 支持运行时动态添加、替换扩展实现，适合插件式业务。

2. 动态卸载扩展点

如果某些扩展点需要禁用或卸载，也可以通过 ExtensionRepository 移除：

ExtensionRepository.removeExtension(PromotionExtPt.class, "CN");

注意： 动态注册/卸载需保证线程安全和业务一致性，适合对业务稳定性要求较高的场景。

---

十六、分层解耦的演进与治理

1. 分层依赖治理

• 使用 maven 多模块（client/application/domain/infrastructure）强制分层依赖，防止代码污染。
• 可以用 ArchUnit、SonarQube 等工具做分层依赖扫描和治理。

2. 领域模型演进

• 随着业务增长，领域模型可能变复杂，建议定期做领域驱动设计复盘和聚合根拆分。
• 领域服务应保持单一职责，避免变成“万能服务”。

---

十七、复杂领域事件处理

1. 事件溯源与幂等

• 事件处理建议设计事件ID，保证消费幂等。
• 可将领域事件持久化，支持分布式事务和事件溯源。

2. 事件异步处理

• 推荐用 Spring 的异步事件监听（@Async），提升业务解耦和系统吞吐量。

@Async
@EventListener
public void handleOrderCreated(OrderCreatedEvent event) {
    // 异步处理逻辑
}

3. 事件跨服务传递

• 领域事件可通过 MQ、RocketMQ、Kafka等实现跨服务/微服务的异步通知。
• 推荐事件消息体只包含领域数据，避免耦合技术细节。

---

十八、COLA 与微服务架构结合

1. 分层服务化

• 每个微服务都可以采用 COLA 分层结构，清晰职责分离。
• 服务间通过 API（client 层）或 RPC（infrastructure 层）调用。

2. 扩展点跨服务调用

• 扩展点可通过 RPC 或 MQ 实现分布式扩展，支持多租户或多业务线场景。

3. 领域事件分布式处理

• 领域事件发布后，可通过 MQ 推送到其他微服务，实现最终一致性和业务解耦。

---

十九、常见落地问题与解决方案

1. 领域模型膨胀

• 定期重构聚合根和领域服务，保持单一职责。
• 复杂业务建议拆分为多个子领域模型。

2. 扩展点滥用

• 扩展点只用于业务可变部分，通用逻辑建议直接写在 domain/application 层。
• 定期评审扩展点实现，避免无效扩展。

3. 事件处理失效

• 检查事件发布和监听是否在同一个 Spring 容器中。
• 对于分布式事件，确保消息队列配置和消费逻辑正确。

4. 分层依赖混乱

• 强制依赖治理，禁止 client/application 层直接依赖 infrastructure 层实现类。
• 用接口隔离，基础设施实现只在 infrastructure 层。

---

二十、最佳实践总结

1. 分层独立：每层职责清晰，接口与实现分离。
2. 扩展点聚焦业务可变性：让业务扩展灵活且可控。
3. 领域事件驱动：用事件解耦复杂业务流程，提升系统弹性。
4. 多模块治理：用 maven 多模块、代码扫描工具保证分层干净。
5. 测试分层：每层独立测试，保证业务和技术实现的可靠性。
6. 文档与流程图：复杂业务流程建议配备建模文档和流程图，便于团队协作和知识传承。