用 Akka.Hosting 构建实体 Actor…

在 Akka.NET 中构建领域实体 Actor，并让同一套代码在本地单元测试（无集群）与生产集群分片模式下都能运行。

适用场景

解决思路

1. 定义 AkkaExecutionMode 枚举（LocalTest / Clustered）来控制 Actor 的配置方式：LocalTest 为纯本地 Actor 系统，无 remoting、无集群，用 GenericChildPerEntityParent 代替 ShardRegion；Clustered 为完整集群并使用 ShardRegion。
2. 实现 GenericChildPerEntityParent：一个继承 ReceiveActor 的通用父 Actor，通过静态 CreateProps(IMessageExtractor extractor, Func<string, Props> propsFactory) 创建；在 ReceiveAny 中用 extractor.EntityId(message) 取实体 ID，若为 null 则忽略，否则用 Context.Child(entityId).GetOrElse(() => Context.ActorOf(_propsFactory(entityId), entityId)) 获取或创建子 Actor，并 Forward(_extractor.EntityMessage(message))。
3. 编写消息提取器：继承 Akka.Cluster.Sharding 的 HashCodeMessageExtractor（默认分片数如 40），重写 EntityId(object message)，用 switch 匹配实现了 IWithOrderId 等接口的消息并返回其强类型 ID 的字符串形式，其他返回 null；同时定义 IWithOrderId 接口和强类型 ID（如 readonly record struct OrderId(Guid Value)）。

适用边界 · 注意事项

• 不适用于非 Akka.NET / 非 Akka.Hosting 的 Actor 框架或消息系统。
• 当实体集合无界或实体是短生命周期（会话、草稿、购物车、订单等）时，不要设置 RememberEntities = true。
• 不要把 scoped 服务（如 DbContext、IOrderRepository）直接注入到长生命周期 Actor 的构造函数中，否则 DbContext 会长期存活并变得陈旧。

经验正文