跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

akka-net-best-practices

Critical Akka.NET best practices including EventStream vs DistributedPubSub, supervision strategies, error handling, Props vs DependencyResolver, work distribution patterns, and cluster/local mode abstractions for testability.

Aaronontheweb · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add Aaronontheweb/dotnet-skills --skill akka-net-best-practices

技能说明


name: akka-net-best-practices description: Critical Akka.NET best practices including EventStream vs DistributedPubSub, supervision strategies, error handling, Props vs DependencyResolver, work distribution patterns, and cluster/local mode abstractions for testability. invocable: false

Akka.NET Best Practices

When to Use This Skill

Use this skill when:

  • Designing actor communication patterns
  • Deciding between EventStream and DistributedPubSub
  • Implementing error handling in actors
  • Understanding supervision strategies
  • Choosing between Props patterns and DependencyResolver
  • Designing work distribution across nodes
  • Creating testable actor systems that can run with or without cluster infrastructure
  • Abstracting over Cluster Sharding for local testing scenarios

Reference Files

  • work-distribution-patterns.md: Database queues, Akka.Streams throttling, outbox pattern
  • cluster-local-abstractions.md: GenericChildPerEntityParent, IPubSubMediator, execution mode wiring
  • async-cancellation-patterns.md: Actor-scoped CancellationToken, linked CTS, timeout handling

1. EventStream vs DistributedPubSub

Critical: EventStream is LOCAL ONLY

Context.System.EventStream is local to a single ActorSystem process. It does NOT work across cluster nodes.

// BAD: This only works on a single server
// When you add a second server, subscribers on server 2 won't receive events from server 1
Context.System.EventStream.Subscribe(Self, typeof(PostCreated));
Context.System.EventStream.Publish(new PostCreated(postId, authorId));

When EventStream is appropriate:

  • Logging and diagnostics within a single process
  • Local event bus for truly single-process applications
  • Development/testing scenarios

Use DistributedPubSub for Multi-Node

For events that must reach actors across multiple cluster nodes, use Akka.Cluster.Tools.PublishSubscribe:

using Akka.Cluster.Tools.PublishSubscribe;

public class TimelineUpdatePublisher : ReceiveActor
{
    private readonly IActorRef _mediator;

    public TimelineUpdatePublisher()
    {
        // Get the DistributedPubSub mediator
        _mediator = DistributedPubSub.Get(Context.System).Mediator;

        Receive<PublishTimelineUpdate>(msg =>
        {
            // Publish to a topic - reaches all subscribers across all nodes
            _mediator.Tell(new Publish($"timeline:{msg.UserId}", msg.Update));
        });
    }
}

Akka.Hosting Configuration for DistributedPubSub

builder.WithDistributedPubSub(role: null); // Available on all roles, or specify a role

Topic Design Patterns

PatternTopic FormatUse Case
Per-usertimeline:{userId}Timeline updates, notifications
Per-entitypost:{postId}Post engagement updates
Broadcastsystem:announcementsSystem-wide notifications
Role-basedworkers:rss-pollerWork distribution

2. Supervision Strategies

Key Clarification: Supervision is for CHILDREN

A supervision strategy defined on an actor dictates how that actor supervises its children, NOT how the actor itself is supervised.

public class ParentActor : ReceiveActor
{
    // This strategy applies to children of ParentActor, NOT to ParentActor itself
    protected override SupervisorStrategy SupervisorStrategy()
    {
        return new OneForOneStrategy(
            maxNrOfRetries: 10,
            withinTimeRange: TimeSpan.FromSeconds(30),
            decider: ex => ex switch
            {
                ArithmeticException => Directive.Resume,
                NullReferenceException => Directive.Restart,
                ArgumentException => Directive.Stop,
                _ => Directive.Escalate
            });
    }
}

Default Supervision Strategy

The default OneForOneStrategy already includes rate limiting:

  • 10 restarts within 1 second = actor is permanently stopped
  • This prevents infinite restart loops

You rarely need a custom strategy unless you have specific requirements.

When to Define Custom Supervision

Good reasons:

  • Actor throws exceptions indicating irrecoverable state corruption -> Restart
  • Actor throws exceptions that should NOT cause restart (expected failures) -> Resume
  • Child failures should affect siblings -> Use AllForOneStrategy
  • Need different retry limits than the default

Bad reasons:

  • "Just to be safe" - the default is already safe
  • Don't understand what the actor does - understand it first

3. Error Handling: Supervision vs Try-Catch

When to Use Try-Catch (Most Cases)

Use try-catch when:

  • The failure is expected (network timeout, invalid input, external service down)
  • You know exactly why the exception occurred
  • You can handle it gracefully (retry, return error response, log and continue)
  • Restarting would not help (same error would occur again)
public class RssFeedPollerActor : ReceiveActor
{
    public RssFeedPollerActor()
    {
        ReceiveAsync<PollFeed>(async msg =>
        {
            try
            {
                var feed = await _httpClient.GetStringAsync(msg.FeedUrl);
                var items = ParseFeed(feed);
                // Process items...
            }
            catch (HttpRequestException ex)
            {
                // Expected failure - log and schedule retry
                _log.Warning("Feed {Url} unavailable: {Error}", msg.FeedUrl, ex.Message);
                Context.System.Scheduler.ScheduleTellOnce(
                    TimeSpan.FromMinutes(5), Self, msg, Self);
            }
            catch (XmlException ex)
            {
                // Invalid feed format - log and mark as bad
                _log.Error("Feed {Url} has invalid format: {Error}", msg.FeedUrl, ex.Message);
                Sender.Tell(new
阅读完整来源 ↗