后端微服务【免费下载链接】akka.netCanonical actor model implementation for .NET with local distributed actors in C# and F#.项目地址https://gitcode.com/gh_mirrors/ak/akka.net点击查看免费下载本文围绕 Akka.Hosting 的核心 APIAkkaConfigurationBuilder展开它通过IServiceCollection.AddAkka接入 .NET 标准的Microsoft.Extensions.Hosting生态让开发者不写一行 HOCON 文本就能完成ActorSystem的配置、启动、依赖注入与优雅停机。读完本文你将掌握WithRemoting/WithClustering/WithActors等构建方法的正确用法、AddHocon/AddSetup/WithActorRefProvider三个高级方法背后的合并与覆盖规则以及ActorRegistry、IRequiredActorTKey如何在 Akka 内外统一提供 actor 引用并能在自己的 ASP.NET Core 或 Host 应用中原样落地。一、AddAkka 入口与完整配置示例AddAkka是IServiceCollection上的扩展方法也是进入 Akka.Hosting 的入口。它会创建一个AkkaConfigurationBuilder由你用它来配置并最终启动ActorSystem。下面给出 AkkaConfigurationBuilder 官方文档 中的完整示例一个启用了远程通信与集群的 Web 应用并顺带演示了ActorRegistry的依赖注入注册using Akka.Hosting; using Akka.Actor; using Akka.Actor.Dsl; using Akka.Cluster.Hosting; using Akka.Remote.Hosting; var builder WebApplication.CreateBuilder(args); builder.Services.AddAkka(MyActorSystem, configurationBuilder { configurationBuilder .WithRemoting(localhost, 8110) .WithClustering(new ClusterOptions(){ Roles new[]{ myRole }, SeedNodes new[]{ Address.Parse(akka.tcp://MyActorSystemlocalhost:8110)}}) .WithActors((system, registry) { var echo system.ActorOf(act { act.ReceiveAny((o, context) { context.Sender.Tell(${context.Self} rcv {o}); }); }, echo); registry.TryRegisterEcho(echo); // register for DI }); }); var app builder.Build(); app.MapGet(/, async (context) { var echo context.RequestServices.GetRequiredServiceActorRegistry().GetEcho(); var body await echo.Askstring(context.TraceIdentifier, context.RequestAborted).ConfigureAwait(false); await context.Response.WriteAsync(body); }); app.Run();这个示例体现了AkkaConfigurationBuilder的四个关键卖点不写 HOCON远程绑定、集群角色、种子节点全部通过强类型 APIWithRemoting、ClusterOptions表达自动执行生命周期最佳实践AddAkka会注册一个后台IHostedServiceAkkaHostedService由它负责按 Akka.NET 的最佳实践运行ActorSystem并管理其生命周期自动绑定 DIActorSystem与 1.5 版本引入的ActorRegistry都被注册进IServiceCollectionAkka 之外的控制器、中间件、SignalR Hub 都能安全地消费它们对子插件开放其他包如文档中提到的Akka.Persistence.SqlServer、集群内的 Sharding 等可以在同一个 builder 上继续追加扩展方法。源码视角AddAkka 到底做了什么查看 AkkaHostingExtensions.cs 中AddAkka的实现可以看到它内部实际做了这些事public static IServiceCollection AddAkka[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] T( this IServiceCollection services, string actorSystemName, ActionAkkaConfigurationBuilder, IServiceProvider builder) where T:AkkaHostedService { var b new AkkaConfigurationBuilder(services, actorSystemName); // add the default Akka.Streams configuration by default - hurts nothing, but // ensures that StreamRefs work correctly out of the box in case users // havent attempted to materialize a stream yet b.AddHocon(ActorMaterializer.DefaultConfig(), HoconAddMode.Append); services.AddSingletonAkkaConfigurationBuilder(sp { builder(b, sp); return b; }); // registers the hosted services and begins execution b.Bind(); // ... services.AddHostedServiceT(); return services; }值得注意的三个细节Akka.Streams 默认配置被自动追加b.AddHocon(ActorMaterializer.DefaultConfig(), HoconAddMode.Append)确保即使你从未手动配置 StreamsStreamRef之类的功能开箱即用builder 本身是单例你的配置委托在IServiceProvider首次解析AkkaConfigurationBuilder时才执行因此可以使用IServiceProvider解析IConfiguration等 DI 服务见AddAkka的重载Maui 场景有专门保护检测到运行在 MAUI 环境时AddAkka会抛出PlatformNotSupportedException提示改用Akka.Hosting.Maui的AddAkkaMaui避免用户踩坑。二、ActorSystem 生命周期启动、注册与停机启动顺序先建 System再跑 starter最后跑 startup taskAkkaConfigurationBuilder内部把用户配置分成两组回调执行时机不同。从 AkkaConfigurationBuilder.cs 的StartAsync可以看到internal async TaskActorSystem StartAsync(ActorSystem sys) { if (_complete) return sys; _complete true; /* * Start Actors */ var registry ActorRegistry.For(sys); foreach (var starter in _actorStarters) { await starter(sys, registry).ConfigureAwait(false); } foreach (var startupTask in _startupTasks) { await startupTask(sys, registry).ConfigureAwait(false); } return sys; }即ActorSystem创建完成后先按注册顺序执行所有WithActors传入的 actor starter再执行所有AddStartup传入的一次性初始化任务。_complete标志保证整套启动流程只执行一次。ActorSystem 是如何被创建的ActorSystem实例的组装逻辑位于AkkaConfigurationBuilder内部的ActorSystemFactoryAkkaConfigurationBuilder.cs。其拼装顺序是若未提供LoggerFactorySetup则从 DI 容器解析ILoggerFactory并自动附加让 Akka 日志走Microsoft.Extensions.Logging管道创建DependencyResolverSetupDI 桥接与BootstrapSetup后者携带你通过AddHocon累积的全部 HOCON 配置如果显式设置了ActorRefProviderWithActorRefProvider则附加到BootstrapSetup依次And(...)合并你通过AddSetup添加的其他Setup若有WithCustomSerializer注册的序列化器则生成SerializationSetup合并进去若有WithExtensions注册的扩展则合并进ExtensionsSetup以IExtensionId实例而非akka.extensions类型名的方式传入最终ActorSystem.Create(config.ActorSystemName, actorSystemSetup)创建系统。停机CoordinatedShutdown 兜底托管服务 AkkaHostedService.cs 负责把宿主生命周期和 Akka 生命周期绑在一起StartAsync中从 DI 解析ActorSystem提前抓取CoordinatedShutdown引用然后调用ConfigurationBuilder.StartAsync同时挂了一个TerminationHook——一旦ActorSystem先于宿主终止例如集群 membership 变化触发的退出会把Environment.ExitCode置为-1并调用HostApplicationLifetime.StopApplication()StopAsync中执行完整的CoordinatedShutdown.Run(CoordinatedShutdown.ClrExitReason.Instance)即 Akka.NET 标准的协调停机流程而不是直接Terminate系统。这就是文档所说自动在幕后执行 Akka.NET 应用生命周期最佳实践的具体含义。三、ActorRegistry 与 IRequiredActor Akka 内外的统一 DI文档示例里registry.TryRegisterEcho(echo)一行代码就打通了 Akka 与 .NET 生态的边界。这套机制由两类 API 组成详见 依赖注入文档ActorRegistry一个以Type为键、IActorRef为值的线程安全注册表设计用途是存放那些需要被 Akka 内外共同访问的顶层 actor如入口路由、ShardRegion、ClusterSingleton。它同时是一个 Akka.NET 扩展Extension也可以通过ActorRegistry.For(system)从系统直接获取IRequiredActorTKey在任意被 DI 的类控制器、Hub、IHostedService构造函数里声明它框架就会从ActorRegistry中解析出键为TKey的 actor 引用注入进来。在 AkkaConfigurationBuilder.cs 的Bind()方法中可以看到这些类型是如何被注册进 DI 容器的internal void Bind() { // register as singleton - not interested in supporting multi-Sys use cases ServiceCollection.AddSingleton(ActorSystemFactory()); ServiceCollection.AddSingletonActorRegistry(sp { return ActorRegistry.For(sp.GetRequiredServiceActorSystem()); }); ServiceCollection.AddSingletonIActorRegistry(sp { return sp.GetRequiredServiceActorRegistry(); }); ServiceCollection.AddSingletonIReadOnlyActorRegistry(sp { return sp.GetRequiredServiceActorRegistry(); }); ServiceCollection.AddSingleton(typeof(IRequiredActor), typeof(RequiredActor)); // Automatically register all Akka.NET health checks with the HealthCheckServiceOptions ServiceCollection.AddOptionsHealthCheckServiceOptions() // creates an OptionsBuilder .PostConfigureAkkaConfigurationBuilder((opts, akka) { foreach (var reg in akka.HealthChecks.Select(h h.Value.ToHealthCheckRegistration())) opts.Registrations.Add(reg); }); }由此确认了几个实现事实ActorSystem按单例注册注释明确说明不支持多 System 场景ActorRegistry/IActorRegistry/IReadOnlyActorRegistry三个接口都指向同一个实例开闭泛型IRequiredActor全局映射到RequiredActor实现你通过WithHealthCheck注册的 Akka 健康检查会被自动合并进 ASP.NET Core 的HealthCheckServiceOptions。RequiredActorTActor的取值逻辑ActorRegistry.cs分三步先查缓存 → 同步查注册表快速路径→ 若仍未注册则抛出带有明确指引的MissingActorRegistryEntryException提示你在IHostedService构造函数中改用GetAsync等待 actor 就绪因为 Akka 服务与其他 hosted service 是并行启动的。注册 API 一览ActorRegistryActorRegistry.cs提供的常用方法方法说明RegisterTKey(actor, overwrite false)强制注册重复键且不允许覆盖时抛DuplicateActorRegistryExceptionTryRegisterTKey(actor, overwrite false)尝试注册失败返回false而不抛异常TryGetTKey(out actor)未命中时actor为ActorRefs.NobodyGetTKey()未注册时抛MissingActorRegistryEntryExceptionGetAsyncTKey(ct)若 actor 尚未注册等待其注册完成可被CancellationToken取消一个可直接运行的更简洁变体见 SimpleDemo 示例它通过WithShardRegion把Echo类型的ShardRegion注册进 registry然后在 ASP.NET Core 端点里直接把IRequiredActorEcho作为参数注入省去了手动GetRequiredServiceActorRegistry().GetEcho()builder.Services.AddAkka(MyActorSystem, configurationBuilder { configurationBuilder .WithRemoting(hostname: localhost, port: 8110) .WithClustering(new ClusterOptions{SeedNodes new []{ akka.tcp://MyActorSystemlocalhost:8110, }}) .WithShardRegionEcho( typeName: myRegion, entityPropsFactory: (_, _, resolver) { return s resolver.PropsEchoActor(s); }, messageExtractor: Extractor, shardOptions: new ShardOptions()); }); app.MapGet(/, async (HttpContext context, IRequiredActorEcho echoActor) { var echo echoActor.ActorRef; var body await echo.Askstring(context.TraceIdentifier, context.RequestAborted) .ConfigureAwait(false); await context.Response.WriteAsync(body); });注意该示例的entityPropsFactory第三个参数是IDependencyResolver实体 actorEchoActor构造函数依赖IReplyGenerator通过 Akka.DependencyInjection 的 resolver 从 DI 容器自动构造这正是WithActors带 resolver 重载存在的意义。四、插件式组合Remoting、Clustering 与持久化文档的第二个示例展示了AkkaConfigurationBuilder对子插件开放的设计意图——多个With*方法在同一个 builder 上串联每个插件包贡献自己的扩展方法builder.Services.AddAkka(MyActorSystem, configurationBuilder { configurationBuilder .WithRemoting(localhost, 8110) .WithClustering(new ClusterOptions() { Roles new[] { myRole }, SeedNodes new[] { Address.Parse(akka.tcp://MyActorSystemlocalhost:8110) } }) .WithSqlServerPersistence(builder.Configuration.GetConnectionString(sqlServerLocal)) .WithShardRegionUserActionsEntity(userActions, s UserActionsEntity.Props(s), new UserMessageExtractor(), new ShardOptions(){ StateStoreMode StateStoreMode.DData, Role myRole}) .WithActors((system, registry) { var userActionsShard registry.GetUserActionsEntity(); var indexer system.ActorOf(Props.Create(() new Indexer(userActionsShard)), index); registry.TryRegisterIndex(indexer); // register for DI }); })其中WithSqlServerPersistence来自文档提到的Akka.Persistence.SqlServer包该包不在本仓库中此处按文档描述引用WithRemoting、WithClustering、WithShardRegion则分别来自本仓库的Akka.Remote.Hosting与Akka.Cluster.Hosting。WithRemoting 的参数与默认值WithRemoting 扩展 有三种重载public static AkkaConfigurationBuilder WithRemoting( this AkkaConfigurationBuilder builder, string? hostname null, // 默认 0.0.0.0 int? port null, // 默认 2552 string? publicHostname null, // 主机名别名场景下对外通告的主机名 int? publicPort null) // 端口别名场景下对外通告的端口另有ActionRemoteOptions委托重载和直接传RemoteOptions实例的重载。从源码可以看到一个重要的保护逻辑WithRemoting末尾只有当 builder 尚未设置 provider或当前 provider 是 Local 时才把 provider 设为ProviderSelection.Remote如果已经显式是Cluster、Remote或Custom则不做任何修改no-op。WithClusteringAkkaClusterHostingExtensions.cs同理——它把 provider 设为ProviderSelection.Cluster.Instance且当ClusterOptions.ClusterReadyCheck为true时会自动附加集群就绪健康检查。也就是说provider 的最终取值取决于你显式的WithActorRefProvider调用与各With*插件的协作顺序而不是简单的后调用覆盖前调用。这直接引出下一节的WithActorRefProvider。五、其他高级方法AddHocon、AddSetup 与 WithActorRefProvider官方文档 在WithActors之外明确列出了三个面向高级场景的方法下面结合源码逐一展开。1. AddHocon合并 HOCON 或 IConfigurationAddHocon有两种形态AkkaHostingExtensions.cs// 形态一直接合并 Akka.NET 的 Config 对象 public static AkkaConfigurationBuilder AddHocon(this AkkaConfigurationBuilder builder, Config hocon, HoconAddMode addMode) // 形态二把 Microsoft.Extensions.Configuration 的 IConfiguration 节转换为 HOCON public static AkkaConfigurationBuilder AddHocon( this AkkaConfigurationBuilder builder, IConfiguration configuration, HoconAddMode addMode, bool normalizeKeys true)addMode是 HoconAddMode 枚举三种取值在 AddHoconConfiguration 中的实际语义是模式实现效果HoconAddMode.Appendconfig.WithFallback(add)新 HOCON 作为回退追加到末尾已有值优先插件默认该模式保证不破坏用户配置HoconAddMode.Prependadd.WithFallback(config)新 HOCON 置顶覆盖已有值但不删除原值后续调用可再覆盖更早的调用HoconAddMode.Replace与 Prepend 相同表达式但语义标记为破坏性源码注释警告插件开发者永远不要直接对用户调用该模式应让用户自己选择关于IConfiguration转换形态的规则Microsoft.Extensions.Configuration 集成文档 有完整说明要点是HOCON 键名区分大小写而IConfiguration默认不区分默认情况下normalizeKeys true所有键会被自动转小写键中的.会被当作 HOCON 对象分隔符除非用双引号包裹环境变量 provider 中__转.、_转-全整数的键会被解析为数组需要保留键大小写的边缘场景如序列化绑定System.Object可传normalizeKeys: false此时所有键必须按 HOCON 兼容的写法书写。转换后的等价示例来自该文档{ akka: { cluster: { roles: [ front-end, back-end ], min-nr-of-members: 3, log-info: true } } }配合环境变量AKKA__CLUSTER__SEED_NODES__0、AKKA__CLUSTER__SEED_NODES__1等价于akka { cluster { roles: [ front-end, back-end ] min-nr-of-members: 3 log-info: true seed-nodes: [ akka.tcp//mySystemlocalhost:4055, akka.tcp//mySystemlocalhost:4056 ] } }使用方式var host new HostBuilder() .ConfigureHostConfiguration(builder { builder.AddJsonFile(appsettings.json).AddEnvironmentVariables(); }) .ConfigureServices((context, services) { services.AddAkka(mySystem, (builder, provider) { var akkaConfig context.Configuration.GetSection(akka); builder.AddHocon(akkaConfig, HoconAddMode.Prepend); }); });除AddHocon外还有直接读文件的AddHoconFile(hoconFilePath, addMode)以及两个内置单键快捷方法WithActorAskTimeout(timeout)写入akka.actor.ask-timeout与WithStrictSerialization(enabled)写入akka.actor.serialization-settings.allow-unregistered-types off/on要求 Akka.NET 1.5.66用于禁止未注册类型回退到默认序列化器。2. AddSetup向启动管道注入 Setup 对象AddSetup允许你加入任意 Akka.NETSetup对象如BootstrapSetup、ServiceProviderSetup。AddSetup 实现 有两个特殊处理internal AkkaConfigurationBuilder AddSetup(Setup setup) { if (_complete) return this; // we will recreate our own BootstrapSetup later - just extract the parts for now. if (setup is BootstrapSetup bootstrapSetup) { if (bootstrapSetup.Config.HasValue) Configuration Configuration.HasValue ? Configuration.FlatSelectConfig(c bootstrapSetup.Config.Value.WithFallback(c)) : bootstrapSetup.Config; ActorRefProvider bootstrapSetup.ActorRefProvider; return this; } // dont apply the diSetup if (setup is DependencyResolverSetup) { return this; } Setups.Add(setup); return this; }即如果你传入BootstrapSetupbuilder 只抽取其中的Config和ActorRefProvider合并进自己的状态真正的BootstrapSetup由框架在创建ActorSystem时重建——这样可以避免用户配置的 provider 与WithRemoting/WithClustering设置的 provider 冲突。DependencyResolverSetup会被直接忽略因为框架自己会创建 DI 桥接DependencyResolverSetup.Create(sp)。其余Setup如SerializationSetup、ExtensionsSetup则按原样追加进最终启动管道。3. WithActorRefProvider显式指定 ActorRefProviderpublic static AkkaConfigurationBuilder WithActorRefProvider(this AkkaConfigurationBuilder builder, ProviderSelection providerSelection)该方法把 builder 的ActorRefProvider属性OptionProviderSelection设置为指定值。典型用途是文档中给出的场景在一个本应默认走ActorRefProvider.Cluster的测试宿主中强制ActorRefProvider.Local。从 ActorSystemFactory 可以看到只有当config.ActorRefProvider.HasValue为真时provider 才会被附加到BootstrapSetup上否则完全交给 HOCON 中akka.actor.provider配置项决定。这也解释了为什么WithRemoting/WithClustering内部都要先检查已有 provider 再决定是否设置——显式调用过的WithActorRefProvider拥有最终决定权。六、源码中还能看到的其他构建方法除文档列出的方法外从 AkkaConfigurationBuilder.cs 与 AkkaHostingExtensions.cs 的源码结构看builder 的公开 API 面还包括WithActors的四种重载ActionActorSystem, IActorRegistry、带IDependencyResolver的三参重载actor 实体可从 DI 容器构造依赖、返回Task的ActorStarter与ActorStarterWithResolver委托。非异步的Action形式会被包装成Task.CompletedTask形式统一入队AddStartup注册在所有 actor 都实例化之后执行一次的应用初始化任务如向顶层 actor 发送首条消息、执行迁移逻辑同样有同步与StartupTask委托两种重载WithCustomSerializer(identifier, boundTypes, factory)以编程方式注册自定义序列化器及其类型绑定最终在创建系统时汇总为SerializationSetup源码WithExtensions(Type[])/WithExtensionT()注册在ActorSystem启动时自动创建并启动的扩展如分布式发布订阅、集群指标。注意泛型版本WithExtensionT()标注了[DynamicallyAccessedMembers]是为 Native AOT 裁剪友好的写法而Type数组版本带[RequiresUnreferencedCode]WithHealthCheck系列支持传AkkaHealthCheckRegistration、DI 解析的IAkkaHealthCheck类型、或纯函数FuncActorSystem, ActorRegistry, CancellationToken, TaskHealthCheckResultWithActorSystemLivenessCheck提供开箱即用的存活检查默认失败状态Unhealthy默认标签akka、liveness。如前所述这些检查会被Bind()自动注册进HealthCheckServiceOptions直接对 ASP.NET Core 的/health端点可见WithSerializationV2(enabled true)打开/关闭akka.actor.serialization-v2开关让已有 V2 版本的内置序列化器接管旧绑定源码注释明确提示——只有当集群中所有节点都能读取 V2 格式时才应打开且你自己注册的绑定HOCON 或WithCustomSerializer仍然优先。这些方法在 API 文档中均有中文注释式的英文 XML doc 说明可按需查阅对应文件。七、实践要点与常见陷阱结合文档与源码给出几条落地建议WithActors只执行一次_complete标志使所有注册方法在系统启动后调用会直接短路返回starter 也不会重跑。需要启动后做一次性动作请用AddStartup顶层 actor 才进 registryActorRegistry的 XML 注释明确提醒——如果你把系统里每个 actor 都注册进 registry那你一定用错了。它是为入口路由、ShardRegion、ClusterSingleton 这类跨 Akka/非 Akka 边界共享的引用设计的IHostedService中取 actor 用GetAsyncIRequiredActorT.ActorRef属性在 actor 尚未注册时会抛异常附带指引信息而GetAsync会挂起等待注册完成。原因在 RequiredActor 的注释 中写明Akka 本身作为另一个 hosted service 是异步启动的与其他 service 并行插件间 provider 协商有固定规则WithRemoting/WithClustering不会覆盖你显式设置的ProviderSelection.Cluster/Remote/Custom/Local写测试宿主时用WithActorRefProvider(ProviderSelection.Local)即可锁定本地模式健康检查是免费附赠的只要注册了WithActorSystemLivenessCheck或自定义WithHealthCheck配合IHealthChecksBuilder即可暴露给负载均衡器/编排系统做存活探测。总结AkkaConfigurationBuilder是 Akka.Hosting 将 Akka.NET 接入Microsoft.Extensions.Hosting的核心抽象AddAkka完成注册与托管AkkaHostingExtensions.csbuilder 累积配置HOCON、Setup、序列化器、扩展、actor starterBind()把ActorSystem/ActorRegistry/IRequiredActor与健康检查注入 DI 容器AkkaConfigurationBuilder.csAkkaHostedService负责启动协调与CoordinatedShutdown停机AkkaHostedService.cs。对于AddHocon、AddSetup、WithActorRefProvider三个高级方法源码给出了明确的合并语义与保护逻辑可以作为自己编写 Akka.Hosting 插件时的参照模板。配套阅读Microsoft.Extensions.Configuration 集成 与 Akka.NET 内外的依赖注入。赞分享后端微服务【免费下载链接】akka.netCanonical actor model implementation for .NET with local distributed actors in C# and F#.项目地址https://gitcode.com/gh_mirrors/ak/akka.net点击查看免费下载相关推荐Akka.NET 依赖注入实战指南从 Akka.DependencyInjection 到 Actor 生命周期管理Akka.NET 依赖注入实战指南从 Akka.DependencyInjection 到 Actor 生命周期管理 本文围绕 Akka.NET 官方推荐的依后端微服务Akka.NET 部署到 Azure Cloud ServiceWorker Role 宿主模式与 ActorSystem 生命周期管理Akka.NET 部署到 Azure Cloud ServiceWorker Role 宿主模式与 ActorSystem 生命周期管理 本文讲解如何将 Ak后端微服务Pkl依赖注入配置对象生命周期管理Pkl依赖注入配置对象生命周期管理 在现代应用开发中配置管理往往面临对象依赖复杂、生命周期混乱的问题。Pkl配置即代码语言通过其独特的依赖注入Depe编程语言语言运行时创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考