Fun.CQRS 1.0.0 版本迁移指南：从旧版本平滑升级

前言

Fun.CQRS 是一个基于 Scala 的 CQRS/ES 框架，1.0.0 版本带来了重大的 API 重构。本文将详细介绍如何将现有应用迁移到这个新版本。虽然内部实现没有变化，但用户接口的改动需要开发者进行相应的代码调整。

迁移概览

1.0.0 版本将分三个阶段发布：

1. 里程碑1 (1.0.0-M1)
2. 里程碑2 (1.0.0-M2)
3. 最终版 (1.0.0)

建议开发者按照里程碑顺序逐步迁移，每个阶段完成后进行测试验证。

1.0.0-M1 迁移要点

1. 移除 AggregateLike 特质

旧版本要求聚合体必须继承 AggregateLike 特质：

case class Foo(n: String) extends AggregateLike

新版本移除了这个限制：

case class Foo(n: String)

但聚合体ID仍需实现 AggregateId 特质。

2. 移除 ProtocolLike 特质

旧版本需要定义协议对象：

object FooProtocol extend ProtocolLike {
  sealed trait FooCommand extends ProtocolCommand
  sealed trait FooEvent extends ProtocolEvent
}

新版本简化了定义：

sealed trait FooCommand
sealed trait FooEvent

这种改变使得：

• 命令和事件不再与框架强耦合
• 可以自由使用 Protobuf/Avro 等工具生成命令和事件类

3. 移除 Metadata 相关特质

旧版本的元数据处理：

case class FooMetadata(...) extends Metadata
sealed trait FooEvent extends MetadataFacet[FooMetadata]

新版本改为：

case class FooMetadata(...)
sealed trait FooEvent {
  def metadata: FooMetadata
  // 提供便捷访问方法
  final def id = metadata.eventId
  // 其他方法...
}

4. 引入 Types 特质

新版本通过 Types 特质来组织类型关系：

object Foo extends Types[Foo] {
  type Id = FooId  // 必须实现 AggregateId
  type Command = FooCommand
  type Event = FooEvent
}

推荐在聚合体的伴生对象中实现此特质，这样会自动提供隐式实例。

5. 命令和事件处理器重构

事件处理器

从普通函数改为偏函数：

// 旧
handleEvent { evt: FooEvent => ... }

// 新
eventHandler { case evt: FooEvent => ... }

命令处理器

现在需要显式指定返回类型：

import io.funcqrs.behavior.handlers._
commandHandler {
  OneEvent { case cmd: FooCommand => FooEvent(...) }
}

支持多种返回类型包装：

• OneEvent/ManyEvents - 直接返回事件
• maybe.OneEvent/maybe.ManyEvents - Option包装
• attempt.OneEvent/attempt.ManyEvents - Try包装
• eventually.OneEvent/eventually.ManyEvents - Future包装

6. Behavior DSL 变更

更明确的链式调用：

// 旧
Behavior { 
  createActions(...)
} {
  case foo => foo.someOtherActions
}

// 新
Behavior
  .first { createActions(...) }
  .andThen {
    case foo => foo.someOtherActions
  }

7. 后端配置调整

聚合体引用获取方式变化：

// 旧
backend.aggregateRef[Foo](id)

// 新 
backend.aggregateRef[Foo].forId(id)

1.0.0-M2 迁移要点

1. 投影API重构

主要变化：

• 事件查询不再与后端强耦合
• 每个投影需要定义自己的事件源

2. 定义 PublisherFactory

new PublisherFactory[Long, RaffleEvent] {
  override def from(offset: Option[Long]): Publisher[(Long, RaffleEvent)] = {
    // 实现具体的事件发布逻辑
  }
}

3. 投影配置

backend.configure {
  projection(
    projection = new MyProjection(repo),
    publisherFactory = myPublisherFactory,
    name = "MyProjection"
  )
}

4. 偏移量持久化策略

projection(...)
  .withCustomOffsetPersistence(
    AkkaOffsetPersistenceStrategy.offsetAsLong(actorSys, "ProjectionName")
  )

最佳实践建议

1. 逐步迁移：按照里程碑顺序分阶段进行
2. 类型安全：充分利用新的Types特质
3. 明确性：命令处理器返回类型要显式声明
4. 测试验证：每个迁移阶段后进行全面测试
5. 自定义扩展：考虑实现自己的偏移量持久化策略

结语

Fun.CQRS 1.0.0 通过API重构，降低了框架侵入性，提高了灵活性和明确性。虽然迁移需要一定工作量，但这些改进为长期维护和扩展奠定了更好的基础。建议开发团队预留足够时间进行迁移和测试，确保系统稳定性。