开发与测试
akka-hosting-actor-patterns
Patterns for building entity actors with Akka.Hosting - GenericChildPerEntityParent, message extractors, cluster sharding abstraction, akka-reminders, and ITimeProvider. Supports both local testing and clustered production modes.
Aaronontheweb · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add Aaronontheweb/dotnet-skills --skill akka-hosting-actor-patterns技能说明
name: akka-hosting-actor-patterns description: Patterns for building entity actors with Akka.Hosting - GenericChildPerEntityParent, message extractors, cluster sharding abstraction, akka-reminders, and ITimeProvider. Supports both local testing and clustered production modes. invocable: false
Akka.Hosting Actor Patterns
When to Use This Skill
Use this skill when:
- Building entity actors that represent domain objects (users, orders, invoices, etc.)
- Need actors that work in both unit tests (no clustering) and production (cluster sharding)
- Setting up scheduled tasks with akka-reminders
- Registering actors with Akka.Hosting extension methods
- Creating reusable actor configuration patterns
Core Principles
- Execution Mode Abstraction - Same actor code runs locally (tests) or clustered (production)
- GenericChildPerEntityParent for Local - Mimics sharding semantics without cluster overhead
- Message Extractors for Routing - Reuse Akka.Cluster.Sharding's IMessageExtractor interface
- Akka.Hosting Extension Methods - Fluent configuration that composes well
- ITimeProvider for Testability - Use ActorSystem.Scheduler instead of DateTime.Now
Execution Modes
Define an enum to control actor behavior:
/// <summary>
/// Determines how Akka.NET should be configured
/// </summary>
public enum AkkaExecutionMode
{
/// <summary>
/// Pure local actor system - no remoting, no clustering.
/// Use GenericChildPerEntityParent instead of ShardRegion.
/// Ideal for unit tests and simple scenarios.
/// </summary>
LocalTest,
/// <summary>
/// Full clustering with ShardRegion.
/// Use for integration testing and production.
/// </summary>
Clustered
}
GenericChildPerEntityParent
A lightweight parent actor that routes messages to child entities, mimicking cluster sharding semantics without requiring a cluster:
using Akka.Actor;
using Akka.Cluster.Sharding;
/// <summary>
/// A generic "child per entity" parent actor.
/// </summary>
/// <remarks>
/// Reuses Akka.Cluster.Sharding's IMessageExtractor for consistent routing.
/// Ideal for unit tests where clustering overhead is unnecessary.
/// </remarks>
public sealed class GenericChildPerEntityParent : ReceiveActor
{
public static Props CreateProps(
IMessageExtractor extractor,
Func<string, Props> propsFactory)
{
return Props.Create(() =>
new GenericChildPerEntityParent(extractor, propsFactory));
}
private readonly IMessageExtractor _extractor;
private readonly Func<string, Props> _propsFactory;
public GenericChildPerEntityParent(
IMessageExtractor extractor,
Func<string, Props> propsFactory)
{
_extractor = extractor;
_propsFactory = propsFactory;
ReceiveAny(message =>
{
var entityId = _extractor.EntityId(message);
if (entityId is null) return;
// Get existing child or create new one
Context.Child(entityId)
.GetOrElse(() => Context.ActorOf(_propsFactory(entityId), entityId))
.Forward(_extractor.EntityMessage(message));
});
}
}
Message Extractors
Create extractors that implement IMessageExtractor from Akka.Cluster.Sharding:
using Akka.Cluster.Sharding;
/// <summary>
/// Routes messages to entity actors based on a strongly-typed ID.
/// </summary>
public sealed class OrderMessageExtractor : HashCodeMessageExtractor
{
public const int DefaultShardCount = 40;
public OrderMessageExtractor(int maxNumberOfShards = DefaultShardCount)
: base(maxNumberOfShards)
{
}
public override string? EntityId(object message)
{
return message switch
{
IWithOrderId msg => msg.OrderId.Value.ToString(),
_ => null
};
}
}
// Define an interface for messages that target a specific entity
public interface IWithOrderId
{
OrderId OrderId { get; }
}
// Use strongly-typed IDs
public readonly record struct OrderId(Guid Value)
{
public static OrderId New() => new(Guid.NewGuid());
public override string ToString() => Value.ToString();
}
Akka.Hosting Extension Methods
Create extension methods that abstract the execution mode:
using Akka.Cluster.Hosting;
using Akka.Cluster.Sharding;
using Akka.Hosting;
public static class OrderActorHostingExtensions
{
/// <summary>
/// Adds OrderActor with support for both local and clustered modes.
/// </summary>
public static AkkaConfigurationBuilder WithOrderActor(
this AkkaConfigurationBuilder builder,
AkkaExecutionMode executionMode = AkkaExecutionMode.Clustered,
string? clusterRole = null)
{
if (executionMode == AkkaExecutionMode.LocalTest)
{
// Non-clustered mode: Use GenericChildPerEntityParent
builder.WithActors((system, registry, resolver) =>
{
var parent = system.ActorOf(
GenericChildPerEntityParent.CreateProps(
new OrderMessageExtractor(),
entityId => resolver.Props<OrderActor>(entityId)),
"orders");
registry.Register<OrderActor>(parent);
});
}
else
{
// Clustered mode: Use ShardRegion
builder.WithShardRegion<OrderActor>(
"orders",
(system, registry, resolver) =>
entityId => resolver.Props<OrderActor>(entityId),
new OrderMessageExtractor(),
new ShardOptions
{
StateStoreMode = StateStoreMode.DData,
Role = clusterRole
});
}
return builder;
}
}
Composing Multiple Actors
Create a convenience method that registers all domain actors:
阅读完整来源 ↗