Akka.NET 自定义持久化插件开发指南:手写 Journal 与 SnapshotStore 全流程实战

原创2026-10-15 15:57:402,321 阅读
文章标签:后端微服务

Akka.NET 自定义持久化插件开发指南:手写 Journal 与 SnapshotStore 全流程实战

导读

本文基于 Akka.NET 官方文档与仓库内的完整 SQLite 示例项目(src/examples/Akka.Persistence.Custom),系统讲解如何从零编写一个属于自己的 Akka.Persistence 持久化插件。Akka.Persistence 将事件溯源存储抽象为 Journal(事件日志) 与 SnapshotStore(快照存储) 两类插件,各自拥有独立的 API 与职责;读完本文你将掌握:继承 AsyncWriteJournal 与 SnapshotStore 实现全部必需方法、理解 AtomicWrite 与回放/熔断语义、编写插件专属 HOCON 配置、将插件封装为 Akka.NET Extension、将其适配到 Native AOT,以及借助官方 TCK 测试套件验证插件兼容性。

一、Akka.Persistence 插件架构:一次事件溯源的职责划分

Akka.Persistence 事件溯源插件(Event Sourcing Plugin)的目标是:在底层存储机制之上,提供一套一致的事件溯源 API 抽象层。这套抽象被划分为两个独立插件:

插件 基类 核心职责
Journal(事件日志) AsyncWriteJournal 存储持久化 Actor 产生的全部事件,供恢复(Recovery)时回放
SnapshotStore(快照存储) SnapshotStore 存储状态快照,加速恢复、跳过大量事件回放

在 src/core/Akka.Persistence/Journal/AsyncWriteJournal.cs 中,AsyncWriteJournal 被定义为“面向异步、非阻塞写入优化的抽象日志”;而 src/core/Akka.Persistence/Snapshot/SnapshotStore.cs 中的 SnapshotStore 则继承自 ActorBase。二者本质上都是 Actor,由 Akka 负责调度消息,插件作者只需实现各自声明的抽象方法。

本文所有示例均以 SQLite 为后端,完整可运行的工程位于 src/examples/Akka.Persistence.Custom(Journal 与 SnapshotStore 实现),配套测试位于 src/examples/Akka.Persistence.Custom.Tests。

二、实现 Journal:继承 AsyncWriteJournal

Journal 负责存储全部事件,以便 Actor 恢复时回放。下文采用的事件日志表结构如下(定义于 SqliteJournal.cs):

CREATE TABLE IF NOT EXISTS event_journal (
    ordering INTEGER PRIMARY KEY NOT NULL,
    persistence_id VARCHAR(255) NOT NULL,
    sequence_nr INTEGER(8) NOT NULL,
    is_deleted INTEGER(1) NOT NULL,
    manifest VARCHAR(255) NULL,
    timestamp INTEGER NOT NULL,
    payload BLOB NOT NULL,
    serializer_id INTEGER(4),
    UNIQUE (persistence_id, sequence_nr));

CREATE TABLE IF NOT EXISTS journal_metadata (
    persistence_id VARCHAR(255) NOT NULL,
    sequence_nr INTEGER(8) NOT NULL,
    PRIMARY KEY (persistence_id, sequence_nr));

注意:event_journal 通过 UNIQUE (persistence_id, sequence_nr) 保证同一 Actor 的事件序号唯一;journal_metadata 表用于在删除事件时保存“最高序号”水位线(详见 DeleteMessagesToAsync 一节)。ordering 是单调递增的全局排序键,可供查询侧(Persistence Query)使用。

2.1 ReplayMessagesAsync:回放事件

Task ReplayMessagesAsync(
    IActorContext context,
    string persistenceId,
    long fromSequenceNr,
    long toSequenceNr,
    long max,
    Action<IPersistentRepresentation> recoveryCallback)

各参数含义:

  • context:正在处理回放消息的 Actor 的上下文信息;
  • persistenceId:持久化 Actor 标识;
  • fromSequenceNr:回放起始序号(包含);
  • toSequenceNr:回放结束序号(包含);
  • max:最多回放的消息条数;
  • recoveryCallback:回放单条消息时调用,可能从任意线程被调用。

关键语义(务必遵守):

  • 实现通过调用 recoveryCallback 逐条回放消息;
  • 返回的 Task 必须在全部(满足序号范围约束的)消息回放完毕后完成;
  • 只要有任何一条持久化消息回放失败,Task 就必须以失败(fault)状态完成;
  • toSequenceNr 取 ReadHighestSequenceNrAsync 的返回值与用户指定的 Recovery 参数的较小值——也就是说,本调用总是先被“读取最高序号”调用所前置;
  • 本调用不受熔断器保护,因为它可能耗时很长;插件实现必须自行防范后端存储无响应,并确保返回的 Task 在合理时间内以成功或失败完成,绝不允许忽略完成该 Task。

在核心实现 AsyncWriteJournal.cs 的 HandleReplayMessages 中可以看到:核心会先用熔断器调用 ReadHighestSequenceNrAsync 取得 highSequenceNr,再取 Math.Min(message.ToSequenceNr, highSequenceNr) 作为回放上限,随后不加熔断器直接调用你的 ReplayMessagesAsync——这正是文档强调“回放不被熔断器保护”的源码级印证。

示例 SQL 与实现(完整代码见 SqliteJournal.cs):

-- ByPersistenceIdSql
SELECT e.persistence_id as PersistenceId, e.sequence_nr as SequenceNr,
       e.timestamp as Timestamp, e.is_deleted as IsDeleted,
       e.manifest as Manifest, e.payload as Payload,
       e.serializer_id as SerializerId
FROM event_journal e
WHERE e.persistence_id = @PersistenceId
  AND e.sequence_nr BETWEEN @FromSequenceNr AND @ToSequenceNr
ORDER BY sequence_nr ASC;

实现要点:用 CommandBehavior.SequentialAccess 顺序读取,用 while (i++ < max && await reader.ReadAsync(...)) 限制条数,随后用 _serialization.Deserialize(bytes, serializerId, manifest) 反序列化负载,再以 new Persistent(...) 构造持久化表示并调用 recoveryCallback,最后 command.Cancel() 提前终止读取。

2.2 ReadHighestSequenceNrAsync:读取最高序号

Task<long> ReadHighestSequenceNrAsync(
    string persistenceId,
    long fromSequenceNr)

参数含义:

  • persistenceId:持久化 Actor 标识;
  • fromSequenceNr:搜索最高序号的起始提示。Actor 恢复时,若使用了快照则为快照对应的序号,否则为 0L。

本调用受熔断器保护。语义要求:

  • 异步读取指定 persistenceId 的最高已存储序号;Actor 恢复后将以该序号作为持久化新事件的起点;
  • 该序号还会被用作后续 ReplayMessagesAsync 的 toSequenceNr(除非用户显式指定了更小的值);
  • Journal 必须维护最高序号且永不回退(never decrease);
  • 注意:最高序号的读取请求可能与同一 persistenceId 的写入并发执行——特别是重启中的 Actor 可能在未完成的写入之前就尝试恢复。此时强烈建议推迟读取最高序号,直到所有未完成写入完成,否则 PersistentActor 可能复用序号。

示例 SQL 与实现(见 SqliteJournal.cs):

-- HighestSequenceNrSql:取事件表与元数据表两者中的最大序号
SELECT MAX(u.SeqNr) as SequenceNr
FROM (
    SELECT MAX(e.sequence_nr) as SeqNr FROM event_journal e
        WHERE e.persistence_id = @PersistenceId
    UNION
    SELECT MAX(m.sequence_nr) as SeqNr FROM journal_metadata m
        WHERE m.persistence_id = @PersistenceId) as u

实现通过 ExecuteScalarAsync 取单一标量,result is long ? Convert.ToInt64(result) : 0L 处理空结果。这里 UNION 两张表的原因正对应 2.4 节:删除事件后,最高序号保存在 journal_metadata 中,保证“永不回退”。

2.3 WriteMessagesAsync:批量写入事件

protected abstract Task<IImmutableList<Exception>> WriteMessagesAsync(
    IEnumerable<AtomicWrite> messages)

本调用受熔断器保护。语义要点:

  • 调用由包裹的 journal Actor 串行化:如果你在异步任务中派发工作,任务完成顺序无关紧要,但同一 persistenceId 的实际写入必须串行——否则后写入的事件可能先于先写入的事件被消费者(查询侧或回放)看到。PersistentActor 在前一次 WriteMessages 完成前不会发送新的写入请求;
  • 传入的 IPersistentRepresentation.Sender 已被置为 null(即 ActorRefs.NoSender),以节省日志空间并避免保存回放时已过期的 Sender 引用;
  • 与 ReadHighestSequenceNrAsync 同样存在并发风险:重启中的 Actor 可能在写入完成前发起恢复,应尽量推迟读取最高序号。

Batching(批处理)

批处理纯粹出于性能考虑,不代表整批必须原子写入。相比逐条插入,批量插入通常吞吐更高,但取决于底层存储;Journal 实现可以按最高效的方式实现。对于给定 persistenceId,Journal 应尽量按序持久化事件,否则故障时持久化状态可能不一致。

AtomicWrite(原子写单元)

每个 AtomicWrite 的 Payload 属性包含:

  • 单个 IPersistentRepresentation:对应 PersistentActor.Persist<TEvent>(TEvent, Action<TEvent>) 传入的事件;或
  • 多个 IPersistentRepresentation:对应 PersistAll<TEvent>(IEnumerable<TEvent>, Action<TEvent>) 传入的一组事件。

注意:虽然 AtomicWrite.Payload 声明为 object 属性,其运行时类型永远是 ImmutableList<IPersistentRepresentation>。这一点在 Persistent.cs 的 AtomicWrite 定义与示例实现 var payload = (IImmutableList<IPersistentRepresentation>)message.Payload;(见 SqliteJournal.cs)中均得到印证。

同一 AtomicWrite 内的全部 Persistent 必须原子写入(all-or-none)。若底层存储不支持多事件原子写,应抛出 NotSupportedException 说明问题,并在插件文档中注明该限制。

失败处理

  • 批次级存储失败或任何写入结果不确定时,必须fault(置失败)整个 Task;
  • 数据存储连接问题必须通过 fault Task 来体现,不能作为逐条写入的拒绝结果;
  • fault 的 Task 不提供逐条写入的结果列表。

处理 AtomicWrite 结果

返回的 Task 需要区分“批次级失败”与“每个 AtomicWrite 的结果”:

  • 只有当 Journal 知道每一个输入 AtomicWrite 的结果时,才允许以成功完成 Task;
  • 全部写入成功:返回 null;
  • 部分/逐条结果:返回与输入一一对应、顺序一致的结果列表。null 条目表示该写已存储、后续回放可见;异常条目表示拒绝整个 AtomicWrite(其任何事件都不得在后续回放中出现);
  • 被拒绝的写属于“已知的逐条结果”,因此本身不会使 Task 失败;批次中的其他 AtomicWrite 可能已被存储——批处理仅为性能,整批不是原子的。

示例:批次含 5 个 AtomicWrite,第 5 个是多事件写且不被存储支持,则 Journal 可存储前 4 个,并以 [null, null, null, null, new NotSupportedException(...)] 成功完成任务。

示例 SQL 与实现(见 SqliteJournal.cs):

-- InsertEventSql
INSERT INTO event_journal (persistence_id, sequence_nr, timestamp,
    is_deleted, manifest, payload, serializer_id)
VALUES (@PersistenceId, @SequenceNr, @Timestamp,
    @IsDeleted, @Manifest, @Payload, @SerializerId);

实现要点:对每个 AtomicWrite 开启独立数据库事务(connection.BeginTransaction())保证原子性;串行化时使用 _serialization.FindSerializerForType(...) 查找负载类型的序列化器,并通过 Akka.Serialization.Serialization.WithTransport(...) 切换序列化上下文(这对本地 IActorRef 的正确序列化至关重要);最后用 Task.Factory.ContinueWhenAll 收集各写任务结果,将 faulted 任务解包为异常条目,返回 IImmutableList<Exception>。

注意:该 SQLite 示例当前将故障的插入任务聚合成逐条拒绝条目,应仅作为逐条结果示例看待;批次级存储失败或结果不确定必须 fault 返回的 Task。

2.4 DeleteMessagesToAsync:批量删除事件

protected abstract Task DeleteMessagesToAsync(
    string persistenceId,
    long toSequenceNr)

参数含义:

  • persistenceId:持久化 Actor 标识;
  • toSequenceNr:要删除的最后一个事件的包含性序号上限。

本调用受熔断器保护。要求异步删除到包含性 toSequenceNr 为止的全部持久化消息,且该操作必须原子完成。

示例 SQL(DeleteBatchSql / HighestSequenceNrSql / UpdateSequenceNrSql)与实现(SqliteJournal.cs):

-- DeleteBatchSql
DELETE FROM event_journal
    WHERE persistence_id = @PersistenceId AND sequence_nr <= @ToSequenceNr;
DELETE FROM journal_metadata
    WHERE persistence_id = @PersistenceId AND sequence_nr <= @ToSequenceNr;

-- UpdateSequenceNrSql
INSERT INTO journal_metadata (persistence_id, sequence_nr)
VALUES (@PersistenceId, @SequenceNr);

实现通过单个数据库事务完成三步:先查当前最高序号(HighestSequenceNrSql)→ 删除事件与元数据(DeleteBatchSql)→ 若 highestSeqNr <= toSequenceNr,则把该序号写入 journal_metadata(UpdateSequenceNrSql),使最高序号得以保留而不回退。

三、Journal 的 HOCON 配置

3.1 最小配置

插件自定义部分只需指定插件 class 的完全限定类型名:

akka.persistence.journal {
  plugin = "akka.persistence.journal.custom-sqlite"
  custom-sqlite {
    # qualified type name of the SQLite persistence journal actor
    class = "Akka.Persistence.Custom.Journal.SqliteJournal, Akka.Persistence.Custom"
  }
}

class 指向的类必须提供无参构造或单个 Akka.Configuration.Config 参数的构造。示例项目的实际配置见 sqlite.conf,还额外暴露了 connection-string、connection-timeout = 30s、auto-initialize = off、plugin-dispatcher 等自定义项,由 JournalSettings(见 Settings.cs)通过 config.GetString("connection-string")、config.GetTimeSpan("connection-timeout")、config.GetBoolean("auto-initialize") 读取。

3.2 默认 Fallback 配置

未在插件自定义段定义的设置将回退到 akka.persistence.journal-plugin-fallback(定义于 persistence.conf):

akka.persistence.journal-plugin-fallback {
  # 提供 journal 插件 API 实现的完全限定类名(必填)
  class = ""

  # 插件 Actor 的调度器
  plugin-dispatcher = "akka.persistence.dispatchers.default-plugin-dispatcher"

  # 消息回放的调度器
  replay-dispatcher = "akka.persistence.dispatchers.default-replay-dispatcher"

  # journal 监督策略;须为 Akka.Actor.SupervisorStrategyConfigurator 的子类
  # 且有无参构造;默认 journal 崩溃后重启
  supervisor-strategy = "Akka.Actor.DefaultSupervisorStrategy"

  # 默认序列化器:作为 manifest 序列化器,
  # 且在没有更具体的绑定时作为 payload 序列化器
  serializer = "json"

  # 已废弃:曾是写入 journal 的持久化消息批的最大条数。
  # 现在该设置无实际作用——PersistentActor 会一次性写入
  # 自上次写入以来累积的全部消息。
  max-message-batch-size = 200

  # 从 Journal 恢复时,相邻事件之间的间隔超过该值则恢复失败。
  # 注意:在回放事件前读取快照同样受此超时影响
  #(尽管它配置在 journal 段)。
  recovery-event-timeout = 30s

  circuit-breaker {
    max-failures = 10
    call-timeout = 10s
    reset-timeout = 30s
  }

  # 回放过滤器:通过检查序号与 writerUuid 检测损坏的事件流
  replay-filter {
    # 检测到无效事件时的处理方式:
    # `repair-by-discard-old`:丢弃来自旧 writer 的事件并记录警告
    # `fail`:使回放失败并记录错误
    # `warn`:记录警告但照常发出事件
    # `off`:完全禁用该功能
    mode = repair-by-discard-old

    # 使用前瞻缓冲区分析事件,此为缓冲区大小(事件条数)
    window-size = 100

    # 记住多少个旧的 writerUuid
    max-old-writers = 10

    # 设为 on 可对每条回放事件输出详细调试日志
    debug = off
  }
}

这些设置在 AsyncWriteJournal.cs 的构造器中实际生效:circuit-breaker 三个参数用于创建 CircuitBreaker(熔断器);replay-filter.mode 被解析为 ReplayFilterMode 枚举,非法值会直接抛出 ConfigurationException,支持值 off | repair-by-discard-old | fail | warn;window-size、max-old-writers、debug 则决定 ReplayFilter 的行为。另外 recovery-event-timeout 在 Eventsourced.Recovery.cs 中被读取,用于控制恢复超时。

3.3 Pre-Start 自动初始化

良好实践是允许插件使用者从空库自动初始化后端存储。为此应支持 auto-initialize 设置。实现方案是:在 PreStart 中异步执行建表(Initialize().PipeTo(Self)),并通过 BecomeStacked(WaitingForInitialization) 切换为等待状态;等待期间stash 所有收到的消息,收到 Status.Success 后 UnbecomeStacked() 并 Stash.UnstashAll(),收到 Status.Failure 则记录错误并 Context.Stop(Self)。完整实现见 SqliteJournal.cs(SqliteJournal 通过 IWithUnboundedStash 获得 IStash)。该模式同样适用于 SnapshotStore。

四、实现 SnapshotStore:继承 SnapshotStore

4.1 LoadAsync:加载快照

Task<SelectedSnapshot> LoadAsync(string persistenceId, SnapshotSelectionCriteria criteria)

参数含义:

  • persistenceId:持久化 Actor 标识;
  • criteria:快照加载选择条件。

本调用受熔断器保护,异步加载一个快照。核心实现 SnapshotStore.cs 中,criteria.Limit(loadSnapshot.ToSequenceNr) 后经熔断器调用 LoadAsync。

示例 SQL 与实现(见 SqliteSnapshotStore.cs):

-- SelectSnapshotSql
SELECT persistence_id, sequence_nr, timestamp, manifest, payload, serializer_id
FROM snapshot
WHERE persistence_id = @PersistenceId
  AND sequence_nr <= @SequenceNr
  AND timestamp <= @Timestamp
ORDER BY sequence_nr DESC
LIMIT 1

表结构(SqliteSnapshotStore.cs):

CREATE TABLE IF NOT EXISTS snapshot (
    persistence_id VARCHAR(255) NOT NULL,
    sequence_nr INTEGER(8) NOT NULL,
    timestamp INTEGER(8) NOT NULL,
    manifest VARCHAR(255) NOT NULL,
    payload BLOB NOT NULL,
    serializer_id INTEGER(4),
    PRIMARY KEY (persistence_id, sequence_nr));

实现要点:以 criteria.MaxSequenceNr 与 criteria.MaxTimeStamp 作为过滤条件、按序号倒序取最新一条;未读到则返回 null;读到后构建 SnapshotMetadata 并反序列化负载,返回 SelectedSnapshot(metadata, snapshot)。

4.2 SaveAsync:保存快照

Task SaveAsync(SnapshotMetadata metadata, object snapshot)

参数含义:

  • metadata:快照元数据;
  • snapshot:要存储的快照对象实例。

本调用受熔断器保护,异步保存快照。核心实现(SnapshotStore.cs)会在 Timestamp == DateTime.MinValue 时自动填充 DateTime.UtcNow。

示例 SQL 与实现(见 SqliteSnapshotStore.cs):

-- InsertSnapshotSql:先更新后插入(upsert),同序号快照被覆盖
UPDATE snapshot
SET timestamp = @Timestamp, manifest = @Manifest,
    payload = @Payload, serializer_id = @SerializerId
WHERE persistence_id = @PersistenceId AND sequence_nr = @SequenceNr;

INSERT OR IGNORE INTO snapshot
    (persistence_id, sequence_nr, timestamp, manifest, payload, serializer_id)
VALUES (@PersistenceId, @SequenceNr, @Timestamp, @Manifest, @Payload, @SerializerId)

实现要点:同样通过 FindSerializerForType + Serialization.WithTransport 完成序列化,并在数据库事务中执行。

4.3 DeleteAsync(按元数据删除)

Task DeleteAsync(SnapshotMetadata metadata);

参数含义:

  • metadata:快照元数据。

本调用受熔断器保护,删除由 metadata 标识的快照。示例实现(SqliteSnapshotStore.cs)有个值得借鉴的细节:当 metadata.Timestamp != DateTime.MinValue 时,在 DeleteSnapshotRangeSql 基础上追加 AND timestamp = @Timestamp 精确匹配;否则使用按序号精确删除的 DeleteSnapshotSql:

-- DeleteSnapshotSql
DELETE FROM snapshot
WHERE persistence_id = @PersistenceId AND sequence_nr = @SequenceNr;

-- DeleteSnapshotRangeSql
DELETE FROM snapshot
WHERE persistence_id = @PersistenceId
  AND sequence_nr <= @SequenceNr
  AND timestamp <= @Timestamp;

4.4 DeleteAsync(按条件批量删除)

Task DeleteAsync(string persistenceId, SnapshotSelectionCriteria criteria);

参数含义:

  • persistenceId:持久化 Actor 标识;
  • criteria:快照删除选择条件。

本调用受熔断器保护,删除所有匹配 criteria 的快照。示例实现(SqliteSnapshotStore.cs)直接使用 DeleteSnapshotRangeSql,参数取自 criteria.MaxSequenceNr 与 criteria.MaxTimeStamp。

五、SnapshotStore 的 HOCON 配置

最小配置(sqlite.conf):

akka.persistence{
  snapshot-store {
    plugin = "akka.persistence.snapshot-store.custom-sqlite"
    custom-sqlite {
      # qualified type name of the SQLite persistence journal actor
      class = "Akka.Persistence.Custom.Snapshot.SqliteSnapshotStore, Akka.Persistence.Custom"
    }
  }
}

默认 fallback 配置(persistence.conf):

akka.persistence.snapshot-store-plugin-fallback {
  # 提供快照存储插件 API 实现的完全限定类名(启用快照存储时必填)
  class = ""

  # 插件 Actor 的调度器
  plugin-dispatcher = "akka.persistence.dispatchers.default-plugin-dispatcher"

  # 快照存储监督策略;默认崩溃后重启
  supervisor-strategy = "Akka.Actor.DefaultSupervisorStrategy"

  # 默认序列化器:作为 manifest 序列化器,且在没有更具体绑定时作为 payload 序列化器
  serializer = "json"

  circuit-breaker {
    max-failures = 5
    call-timeout = 20s
    reset-timeout = 60s
  }

  # 设为 true 时,快照加载失败不影响恢复(会回退为回放全部事件)。
  # 注意:若事件已被删除,设为 true 可能导致恢复出错。
  snapshot-is-optional = false
}

与 Journal 相比,快照存储的熔断器参数更宽松(max-failures = 5、call-timeout = 20s、reset-timeout = 60s),并额外提供 snapshot-is-optional。SnapshotStore 的 Pre-Start 自动初始化与 Journal 完全同模式(见 SqliteSnapshotStore.cs),并同样通过 SnapshotStoreSettings(Settings.cs)读取 connection-string、connection-timeout、auto-initialize。

六、将插件封装为 Akka.NET Extension

要让自定义持久化 Provider 在 Akka.NET 内无缝工作,最后一步是创建一个包装 Journal 与 SnapshotStore 的 Akka.NET Extension。需要实现两个接口:IExtension 与 ExtensionIdProvider<T>。完整示例见 SqlitePersistence.cs。

6.1 实现 IExtension

IExtension 是标记接口,其实现类的实例是用户与自定义扩展交互的入口。两条约定:

约定一:单构造参数。任何实现该接口的类必须提供一个仅接收单个 ExtendedActorSystem 参数的构造函数:

public SqlitePersistence(ExtendedActorSystem system)
{
    var defaultConfig = DefaultConfiguration();
    system.Settings.InjectTopLevelFallback(defaultConfig);

    JournalConfig = system.Settings.Config.GetConfig(JournalConfigPath);
    DefaultJournalConfig = defaultConfig.GetConfig(JournalConfigPath);
    SnapshotConfig = system.Settings.Config.GetConfig(SnapshotConfigPath);
    DefaultSnapshotConfig = defaultConfig.GetConfig(SnapshotConfigPath);
}

这里还演示了如何把内嵌的 sqlite.conf 作为顶层 fallback 配置注入(InjectTopLevelFallback),并通过 ConfigurationFactory.FromResource<SqlitePersistence>("Akka.Persistence.Custom.sqlite.conf") 从嵌入资源加载默认配置。

约定二:静态 Get 方法。强烈推荐提供静态 Get 方法,负责向扩展管理器注册扩展并实例化实例:

public static SqlitePersistence Get(ActorSystem system)
{
    return system.WithExtension<SqlitePersistence, SqlitePersistenceProvider>();
}

6.2 实现 ExtensionIdProvider

ExtensionIdProvider<T> 是负责创建扩展实例的工厂类,只需重写单个方法:

public class SqlitePersistenceProvider : ExtensionIdProvider<SqlitePersistence>
{
    public override SqlitePersistence CreateExtension(ExtendedActorSystem system)
    {
        return new SqlitePersistence(system);
    }
}

七、让持久化插件原生支持 Native AOT

Akka.Persistence 从 HOCON 段的 class 设置构建 Journal 与 SnapshotStore——这依赖反射,而 Native AOT 或裁剪(trimmed)应用无法使用。如果你的插件有 Akka.Hosting 支持,可通过改变 options 类的基类来“选择加入(opt in)”:使用者无需任何改动,照常调用 WithJournal 与 WithSnapshot。以下步骤来自 SQL、Azure、Redis 与 MongoDB 插件的实践。

Step 1:在 Options 类中用类型命名插件

让你的 options 类继承自泛型基类,从而在代码中指名 journal Actor、默认 read journal Provider 与 snapshot store Actor:

public sealed class SqlJournalOptions : JournalOptions<SqlWriteJournal, SqlReadJournalProvider>
{
    // ...原有成员保持不变...
}

public sealed class SqlSnapshotOptions : SnapshotOptions<SqlSnapshotStore>
{
    // ...原有成员保持不变...
}

这是全部改动。WithJournal / WithSnapshot 会注册这些类型,核心按 HOCON class 同样的构造规则构建它们:Actor 为 (Config) 或无参构造,read journal Provider 为 (ExtendedActorSystem, Config)、(ExtendedActorSystem) 或无参构造。你的类仍继承 JournalOptions 与 SnapshotOptions,所以使用者代码无需修改即可编译。泛型基类的实现见 TypedPluginOptions.cs。

  • 无 read journal 的插件继承 JournalOptions<TJournal>;
  • 泛型参数必须是插件 class 所指向的类型:开关关闭时,HOCON class 若指向其他类型会在启动时失败,因此插件的变体(如 GridFS 快照存储)需要携带自身泛型参数的 options。

Step 2:核对 Read Journal 的 Plugin Id

Read Journal 默认注册在 akka.persistence.query.journal.{Identifier}。若位于其他路径,请重写 ReadJournalPluginId:

protected override string ReadJournalPluginId => MongoDbReadJournal.Identifier;

开关关闭时,没有任何机制能通过反射找到 read journal 的 DefaultConfiguration(),因此确保 Hosting 扩展添加 read journal 的默认 HOCON(正如 Akka.Persistence.Sql 用 DefaultQueryConfig 所做)。

Step 3:通过类型化 Builder 方法添加事件适配器

若 Hosting 包添加事件适配器,请在 journal builder 上使用 AddEventAdapter<TAdapter>、AddReadEventAdapter<TAdapter> 或 AddWriteEventAdapter<TAdapter>(见 AkkaPersistenceJournalBuilder.cs)。它们在代码中指名类型,这正是核心所需。

Step 4:让所有入口统一经过 WithJournal 与 WithSnapshot

注册发生在 WithJournal(options, ...) 与 WithSnapshot(options, ...) 内部。跳过它们的入口无法 opt in——Azure 插件曾因此踩坑:其接收 Setup 对象的重载从不调用 WithJournal,导致类型从未注册。确保每个公共入口(包括为用户构建 options 的入口)最终都落到这两个调用之一。

Step 5:排查其他反射点

Spike 中发现了两个典型问题:

  • HOCON 中按类型指名的序列化器:插件默认配置按类型指名的序列化器(如 Redis 快照序列化器)在关闭反射后无法解析,应在 Hosting 扩展中用 WithCustomSerializer 注册,并给出其序列化的类型;
  • 测试中的负载类型:测试消息同样需要序列化器;开关关闭后没有 fallback 序列化器,请为测试负载配置一个。

另外,使用 Props.CreateBy 与 IIndirectActorProducer 创建子 Actor,并避免用 Type.GetType 读取自有类型。

Step 6:关闭开关进行测试

在 Hosting 测试中关闭 Akka.DynamicTypeLoading 特性开关(测试项目内):

<ItemGroup>
  <RuntimeHostConfigurationOption Include="Akka.DynamicTypeLoading" Value="false" />
</ItemGroup>

未 opt in 的插件启动时会以 ConfigurationException 失败,例如:

[akka.persistence.journal.sql.class] [Akka.Persistence.Sql.Journal.SqlWriteJournal, Akka.Persistence.Sql]
is not built in and dynamic type loading is disabled. Use a plugin registered through Akka.Persistence.Hosting
(WithJournal or WithSnapshot, with options derived from JournalOptions<TJournal> or SnapshotOptions<TSnapshotStore>)
or enable the [Akka.DynamicTypeLoading] feature switch.

加入泛型基类后同一批测试应通过。最终检查是发布一个 Native AOT canary 应用——仓库中的 src/aot/Akka.Persistence.AOT.App/Program.cs 正是这样的示范:它以开关关闭方式构建系统,通过 WithJournalAndSnapshot(new CanaryJournalOptions(), new CanarySnapshotOptions(), ...) 注册插件、用 AddWriteEventAdapter 添加适配器、用 WithCustomSerializer 注册序列化器,随后完成持久化、恢复、快照与查询的完整闭环,并断言“未注册类型的 journal 在开关关闭时按设计启动失败”。

关于 Sealed Options 类

若 options 类为 sealed,只有插件作者能 opt in——这是有意的设计:插件类型归属插件作者,使用者无法指定其他类型。在 JIT 上,存在 HOCON class 时仍由它决定,不存在时使用已注册类型。完整图景参见 docs/articles/deployment/native-aot.md。

八、用 TCK 测试套件验证插件兼容性

Akka.Persistence 内置了标准化的技术兼容性套件(Technology Compatibility Kit,TCK),可方便地纳入单元测试,验证自定义 Provider 是否满足基本兼容性要求。做法是:创建一个 XUnit 单元测试项目,引用自定义持久化项目与 Akka.Persistence.TCK 包(仓库内即 src/core/Akka.Persistence.TCK),然后实现以下四个抽象类之一(TCK 基类定义见 JournalSpec.cs、SnapshotStoreSpec.cs、JournalSerializationSpec.cs、SnapshotStoreSerializationSpec.cs):

  • JournalSpec
  • JournalSerializationSpec
  • SnapshotStoreSpec
  • SnapshotStoreSerializationSpec

仓库的 src/examples/Akka.Persistence.Custom.Tests 提供了完整样例:

  • SqliteJournalSpec.cs:继承 JournalSpec,通过 ConfigurationFactory.ParseString 构造带 auto-initialize = on 与内存 SQLite 连接串(Filename=file:memdb-journal-<guid>.db)的规范配置,并在构造中调用 SqlitePersistence.Get(Sys) 注册扩展后执行 Initialize();通过 protected override bool SupportsSerialization => false; 声明不支持序列化场景;
  • SqliteSnapshotStoreSpec.cs:继承 SnapshotStoreSpec,声明 SupportsSerialization => true;
  • SqliteJournalSerializationSpec.cs:继承 JournalSerializationSpec,配置中绑定自定义 event-adapters 与 event-adapter-bindings,并用 [Fact(Skip = "SQLite plugin does not support EventAdapter.Manifest")] 跳过不支持的用例;
  • SqliteSnapshotStoreSerializationSpec.cs 与 SqliteSnapshotStoreSaveSnapshotSpec.cs:分别覆盖序列化与快照保存场景。

测试项目通过 <ProjectReference Include="..\..\core\Akka.Persistence.TCK.Xunit2\Akka.Persistence.TCK.Xunit2.csproj" /> 与自定义插件项目建立引用(见 Akka.Persistence.Custom.Tests.csproj),因此直接 dotnet test 即可运行整套兼容性用例。

结语

编写一个生产可用的 Akka.Persistence 自定义 Provider,本质上是三件事的叠加:正确实现 AsyncWriteJournal 与 SnapshotStore 的抽象方法(尤其吃透 AtomicWrite 原子语义、回放不受熔断与“最高序号永不回退”这两条硬性约束)、通过 HOCON 与 Akka.NET Extension 把它接入 ActorSystem,以及用官方 TCK 验证契约、按 AOT 清单完成 Native AOT 适配。仓库中的 SQLite 示例项目(Journal、SnapshotStore、Extension、TCK 测试一应俱全)是一个可直接对照、复制并替换为任意后端存储的完整模板——从 SQL 到内存数据库,均可无缝迁移到 PostgreSQL、MongoDB、Azure 等目标存储之上。

登录后查看全文
akka.net