后端微服务【免费下载链接】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 1.5 的托管模型中ActorSystem通过Microsoft.Extensions.Hosting的宿主体系创建而 Akka.NET 本身消费的是 HOCON 格式的Config对象。Akka.Hosting提供的AddHocon扩展方法负责在两者之间架起桥梁它能把IConfiguration来自appsettings.json、环境变量等任意 provider转换为 HOCON并合入正在构建的ActorSystem配置。读完本文你将掌握AddHocon的完整用法、键名规范化与环境变量转换规则、大小写敏感场景如 serialization binding的处理方式并能结合 ConfigurationHoconAdapter 源码理解每一处转换行为的实现依据。背景为什么需要 IConfiguration 到 HOCON 的适配器Akka.NET 的核心配置语言是 HOCONHierarchical Object Config Notation。在经典的Akka.Configuration世界里配置来自.hocon/.config文件与ConfigurationFactory。而在 Akka.HostingAkkaConfigurationBuilder API 文档引入之后ActorSystem的创建被纳入标准的IServiceCollection/IHostBuilder流程用户的应用配置天然落在IConfiguration上appsettings.json、环境变量、User Secrets 等。AddHocon 就是这两套配置体系的适配点public static AkkaConfigurationBuilder AddHocon( this AkkaConfigurationBuilder builder, IConfiguration configuration, HoconAddMode addMode, bool normalizeKeys true) { return builder.AddHoconConfiguration(configuration.ToHocon(normalizeKeys), addMode); }从源码签名可以看到三个参数configuration任意IConfiguration或其某个 section通常用context.Configuration.GetSection(akka)取出akka节点addModeHoconAddMode枚举决定新 HOCON 与已有配置的合并方向下一节详述normalizeKeys默认true表示对所有键名做小写化等规范化设为false时不做任何规范化用于必须保留大小写的边缘场景。核心转换规则默认规范化模式使用normalizeKeys true默认时适配器遵循以下规则。这些规则既是文档约定也可以直接在 ConfigurationHoconAdapter 源码中找到对应实现与IConfiguration不同HOCON 的键名区分大小写IConfiguration键中的.句点除非被双引号包裹否则一律视为 HOCON 对象键的层级分隔符IConfiguration不支持 HOCON 的“对象组合”object composition如果你在多个 providerJSON、环境变量等中声明了同一个键只有最后声明的那个生效——这是IConfiguration自身的覆盖语义发生在适配之前针对环境变量 provider__双下划线会被转换为.句点_单下划线会被转换为-短横线如果一个对象的所有子键都是可解析为整数的键则整个对象会被解析为数组。第 2 条中的引号语义由 SplitDottedPathHonouringQuotes 实现它在按.切分路径时会跳过双引号内部的句点从而让Key.With.Dots这样的键保持为单个键名。第 4 条的__→.转换其实由Microsoft.Extensions.Configuration的环境变量 provider 先完成适配器再做剩余处理ExpandKey 中的注释明确写道__ are already converted to : by the environment configuration provider随后对键执行ToLowerInvariant()与Replace(_, -)。完整示例appsettings.json 环境变量appsettings.json{ Logging: { LogLevel: { Default: Information, Microsoft.AspNetCore: Warning } }, AllowedHosts: *, akka: { cluster: { roles: [ front-end, back-end ], min-nr-of-members: 3, log-info: true } } }环境变量AKKA__ACTOR__TELEMETRY__ENABLEtrue AKKA__CLUSTER__SEED_NODES__0akka.tcp//mySystemlocalhost:4055 AKKA__CLUSTER__SEED_NODES__1akka.tcp//mySystemlocalhost:4056 AKKA__CLUSTER__SEED_NODE_TIMEOUT00:00:05注意seed-nodes配置中使用了可解析为整数的键__0、__1因此seed-nodes会被解析为数组。上述环境变量最终被解析为如下 HOCONakka { actor { telemetry.enabled: on } cluster { seed-nodes: [ akka.tcp//mySystemlocalhost:4055, akka.tcp//mySystemlocalhost:4056 ] seed-node-timeout: 5s } }对应示例代码——appsettings.json与环境变量两个来源的组合结果都会进入最终的 HOCON/* Both appsettings.json and environment variables are combined into HOCON configuration: akka { actor.telemetry.enabled: on cluster { roles: [ front-end, back-end ] seed-nodes: [ akka.tcp//mySystemlocalhost:4055, akka.tcp//mySystemlocalhost:4056 ] min-nr-of-members: 3 seed-node-timeout: 5s log-info: true } } */ var host new HostBuilder() .ConfigureHostConfiguration(builder { // Setup IConfiguration to load from appsettings.json and // environment variables builder .AddJsonFile(appsettings.json) .AddEnvironmentVariables(); }) .ConfigureServices((context, services) { services.AddAkka(mySystem, (builder, provider) { // convert IConfiguration to HOCON var akkaConfig context.Configuration.GetSection(akka); builder.AddHocon(akkaConfig, HoconAddMode.Prepend); }); });几点源码层面的印证布尔值JSON 中的true/false会被适配器反向转换为 HOCON 的on/off见 ToHoconElement 中的True on, False off分支数组IsArray 的判断条件是“所有子键都能int.TryParse”命中后按数字键排序构建HoconArray所以即使环境变量中__22先于__1注册数组顺序仍是 0、1、22 对应的逻辑顺序AddAkka入口AddAkka会先向 builder 追加一份ActorMaterializer.DefaultConfig()Append 模式保证 StreamRefs 开箱可用随后才执行你传入的builder委托因此你的AddHocon(..., Prepend)位于它之前优先级更高见 AddAkka 实现。HoconAddMode新配置与已有配置的合并方向HoconAddMode定义在 AkkaConfigurationBuilder.cs三个取值通过 HOCON 的WithFallback机制实现不同方向的合并见 AddHoconConfiguration模式语义实现Append把新 HOCON 追加到末尾作为 fallback已有值优先config.WithFallback(add)Prepend把新 HOCON 放到最前覆盖已有值但不删除add.WithFallback(config)Replace用新 HOCON 替换当前所有 HOCON破坏性操作写插件时不应强制用户采用add.WithFallback(config)实践中当你想把IConfiguration作为最高优先级覆盖reference.conf与之前追加的 HOCON 时选择Prepend如上例如果你只是补充默认值、希望用户显式配置能够覆盖你的插件默认值则选择Append。这也解释了仓库中各托管扩展的写法——例如WithActorAskTimeout、WithStrictSerialization等单键扩展统一使用Prepend见 AkkaHostingExtensions。大小写敏感场景normalizeKeys falseIConfiguration适配器的高级用法——normalizeKeys: false——专门用于需要保留 HOCON 键名大小写的边缘场景最典型的例子就是声明 serialization binding绑定键是 .NET 类型名天然大小写敏感。启用该模式后所有键都不再被规范化你必须以 HOCON 兼容的方式书写全部键。appsettings.json{ Logging: { LogLevel: { Default: Information, Microsoft.AspNetCore: Warning } }, AllowedHosts: *, akka: { \Key.With.Dots\: Key Value, cluster: { roles: [ front-end, back-end ], min-nr-of-members: 3, log-info: true } } }注意Key.With.Dots必须放在转义的双引号内——这是 HOCON 保留属性名中.句点的要求。环境变量PS C:/ [Environment]::SetEnvironmentVariable(akka__actor__telemetry__enabled, true) PS C:/ [Environment]::SetEnvironmentVariable(akka__actor__serialization_bindings__System.Object, hyperion) PS C:/ [Environment]::SetEnvironmentVariable(akka__cluster__seed_nodes__0, akka.tcp//mySystemlocalhost:4055) PS C:/ [Environment]::SetEnvironmentVariable(akka__cluster__seed_nodes__1, akka.tcp//mySystemlocalhost:4056) PS C:/ [Environment]::SetEnvironmentVariable(akka__cluster__seed_node_timeout, 00:00:05)需要注意两点所有环境变量名都是小写的唯独System.Object需要保留类型名的大小写通过环境变量设置 serialization binding 时必须使用.句点而不是__双下划线这在某些 shell 脚本中可能引发问题且没有绕开方式。示例代码——注意AddHocon的最后一个方法参数为false/* Both appsettings.json and environment variables are combined into HOCON configuration: akka { Key.With.Dots: Key Value actor { telemetry.enabled: on serialization-bindings { System.Object hyperion } } cluster { roles: [ front-end, back-end ] seed-nodes: [ akka.tcp//mySystemlocalhost:4055, akka.tcp//mySystemlocalhost:4056 ] min-nr-of-members: 3 seed-node-timeout: 5s log-info: true } } */ var host new HostBuilder() .ConfigureHostConfiguration(builder { // Setup IConfiguration to load from appsettings.json and // environment variables builder .AddJsonFile(appsettings.json) .AddEnvironmentVariables(); }) .ConfigureServices((context, services) { services.AddAkka(mySystem, (builder, provider) { // convert IConfiguration to HOCON var akkaConfig context.Configuration.GetSection(akka); // Note the last method argument is set to false builder.AddHocon(akkaConfig, HoconAddMode.Prepend, false); }); });测试用例对适配行为的验证ConfigurationHoconAdapterTest 是验证该适配器行为的权威来源几个关键断言值得了解因为它们直接界定了适配器的实际行为边界规范化模式EnvironmentVariableTestAKKA__TEST_VALUE_1__A被归一化为akka.test-value-1.a用原大写路径akka.TEST-VALUE-1.A读取则为null__22/__1乱序注册的数组仍按 0、1、22 排序输出非规范化模式EnvironmentVariableCaseSensitiveTestakka.actor.serialization_bindings2__System.Object的绑定键保留为System.Object而不是被小写化这正是设置序列化绑定的前提JSON 中引号键的两种行为非规范化模式下System.Int32键名原样保留NonNormalizedJsonQuotedKeyTest规范化模式下同一键会变成system.int32NormalizedJsonQuotedKeyTest——再次说明需要保留类型名大小绑定时必须用normalizeKeys false点号键展开EncodedKeyTesttest2.b.c这类扁平键会被展开为嵌套 HOCON 路径双下划线边缘情况Issue #631 相关用例以__开头的环境变量如__MISE_SESSION会让 MS.Extensions.Configuration 产生空键适配器会为它创建临时键名__因此可通过__.mise-session路径访问而不会抛异常。实操注意事项小结键命名习惯默认模式下所有键会被小写化且_换成-。如果你的配置键包含大写字母或需要保持System.Object这类类型名务必改用AddHocon(config, HoconAddMode.Prepend, false)并以 HOCON 兼容方式书写全部键多 provider 覆盖IConfiguration同键只保留最后声明的 provider 的值不存在 HOCON 式合并。JSON 与环境变量的“组合”效果来自不同键路径而不是同一键的叠加数组的写法环境变量中用__0、__1… 整数后缀构成数组JSON 中直接写 JSON 数组即可适配器会识别。数组元素按数字键排序优先级选择应用级覆盖用Prepend插件/扩展默认值用AppendReplace是破坏性操作、不要在库代码中强制值转义把任意字符串值写入 HOCON 时可参考仓库内的 string.ToHocon() 工具方法——它会处理反斜杠、引号、控制字符的转义并对含特殊字符的值加双引号ConnectionStringShouldConvertToHoconProperly 验证了含;、\的连接串可以安全往返。相关文档与源码The AkkaConfigurationBuilder API ——AddAkka与AkkaConfigurationBuilder的完整 API 说明Dependency Injection —— 与配置同属 Hosting 主题的组合式 APIHOCON 配置参考 —— HOCON 语言本身适配器实现ConfigurationHoconAdapter.csAddHocon扩展方法AkkaHostingExtensions.cs行为验证测试ConfigurationHoconAdapterTest.cs可运行示例Akka.Hosting.SimpleDemo/Program.cs 与 appsettings.json赞分享后端微服务【免费下载链接】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配置指南HOCON与程序化配置详解Akka.NET配置指南HOCON与程序化配置详解 概述 Akka.NET作为一款强大的分布式Actor模型框架其配置系统是框架灵活性的重要体现。本文将深入后端微服务Akka.NET 配置完全指南HOCON 与 Setup 编程式配置实战Akka.NET 配置完全指南HOCON 与 Setup 编程式配置实战 Akka.NET 的配置体系由两条路径构成以 HOCON https://link后端微服务Akka.NET TestKit 配置详解从默认 HOCON 到虚拟化 TestSchedulerAkka.NET TestKit 配置详解从默认 HOCON 到虚拟化 TestScheduler Akka.NET 的 Akka.TestKit 包内置了一后端微服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考