akka-best-practices_skill

Overview

This skill captures critical Akka.NET best practices for building reliable, testable actor systems. It focuses on choosing the right pub/sub mechanism, supervision and error-handling patterns, Props vs DependencyResolver trade-offs, robust work-distribution approaches, and techniques to make cluster features testable locally. The guidance is pragmatic and oriented toward real production scenarios.

How this skill works

The content explains when to use Context.System.EventStream versus DistributedPubSub, how supervision strategies apply to children, and when to handle exceptions inside actors versus letting supervision restart them. It outlines Props usage and when to inject IServiceProvider via DependencyResolver. It also presents scalable work distribution patterns (database-driven queues, Akka.Streams throttling) and approaches to abstract cluster sharding for local tests.

When to use it

• Use EventStream only for single-process logging, diagnostics, or dev/testing scenarios.
• Use DistributedPubSub when events must be delivered across multiple cluster nodes.
• Handle expected, recoverable errors with try-catch inside actors; let unknown/state-corrupt errors bubble for supervision.
• Prefer Props.Create for simple actors; use DependencyResolver when you need scoped DI or IRequiredActor<T>.
• Use database-driven queues or Akka.Streams to avoid thundering-herd problems when polling many jobs.
• Abstract cluster features so the same logic runs in both cluster and local test mode.

Best practices

• Remember supervision directives apply to children of the actor declaring the strategy, not to the actor itself.
• Don’t swallow unknown exceptions—handle known, expected failures and let unexpected ones trigger supervision.
• Prefer cluster sharding over remote-deployment; remote deployment is rarely needed.
• Use FOR UPDATE SKIP LOCKED in the DB to claim batches and naturally distribute work across nodes.
• Throttle and limit concurrency with Akka.Streams to control local resource usage and avoid spikes.

Example use cases

• Publish per-user timeline updates with DistributedPubSub topic format like timeline:{userId} across all nodes.
• Make an RSS-polling fleet safe by having workers claim batches from a DB and mark progress, avoiding simultaneous requests.
• Write an OrderProcessor actor that uses DependencyResolver to create a scoped DbContext for each message.
• Let an actor restart on unknown state-corrupt exceptions while using try-catch for transient HttpRequestException retries.
• Run the same sharding logic locally by replacing Cluster Sharding with a lightweight in-process abstraction for unit tests.