Orleans：基于 Virtual Actor Model 构建可扩展分布式应用的 .NET 框架实战指南

Orleans基于 Virtual Actor Model 构建可扩展分布式应用的 .NET 框架实战指南【免费下载链接】orleansCloud Native application framework for .NET项目地址: https://gitcode.com/gh_mirrors/or/orleansOrleans 是一个跨平台、面向 .NET 的云原生应用框架它把单机开发中熟悉的对象、接口、async/await、try/catch等概念扩展到多服务器环境帮助开发者以接近单机编程的体验构建弹性、可扩展的云服务。本文以本仓库 README.md 为主线结合 samples/HelloWorld 等示例与 src 下的源码实现系统讲解 Grain 编程模型、Silo 运行时架构、核心特性持久化、事务、流、定时器与提醒、灵活放置、版本化与异构集群等以及从零构建与运行 Orleans 应用的完整路径。读完本文你将掌握Grain 接口与实现的定义规范、IGrainFactory获取与调用 Grain 的机制、UseOrleans/UseLocalhostClustering宿主配置方法、Grain 生命周期与放置策略的原理以及各核心特性在源码中的落点能够直接动手编写并运行自己的第一个 Orleans 应用。Orleans 是什么把“分布式”藏进编程模型Orleans 是微软研究院Microsoft Research创建并开源的框架其核心贡献是提出了Virtual Actor Model虚拟 Actor 模型作为构建云时代分布式系统的新方法。它带来的核心收益在于编程模型本身驯服了高度并行分布式系统固有的复杂性同时不限制能力、也不给开发者强加繁重约束——这也是它常被称为 “Distributed .NET” 的原因。规模弹性从单台本地服务器到云中全局分布的高可用应用Orleans 都能平滑覆盖。开发体验开发者把注意力放在业务逻辑上由运行时处理消息路由、故障转移、激活管理等问题。技术基础基于 .NET 生态运行于 Windows、Linux、macOS兼容 .NET Standard 2.0 及以上可在 .NET Framework 或 .NET Core 上运行。本仓库根目录 README.md 即项目权威入口仓库主体源码位于 src官方示例位于 samples测试代码位于 test。Grains一切应用的基础构件什么是 Grain在任何 Orleans 应用中最基本的构建单元是grain。Grain 是由**用户定义的标识identity、行为behavior与状态state**构成的实体稳定的标识Grain 的标识是用户定义的键key这使得 Grain 无论是否已加载进内存都始终可被调用。强类型契约Grain 可被其他 Grain 或外部客户端如 Web 前端通过强类型的通信接口contracts调用。实现类每个 Grain 都是实现了这些接口之一的类的实例。Grain 可以拥有易失性volatile和/或持久化persistent状态状态可存放于任意存储系统。由于状态随 Grain 分区系统天然获得自动扩展能力也简化了故障恢复。Grain 激活期间状态驻留内存从而获得更低的延迟与更小的存储负载。架构与生命周期示意可参见仓库根目录下的 grain_formulation.svgGrain 由稳定标识、行为、状态组成与 managed_lifecycle.svgGrain 的受管生命周期。Grain 的受管生命周期激活/停用由运行时负责Grain 的实例化由 Orleans 运行时按需自动完成一段时间未使用的 Grain 会被自动从内存移除以释放资源。这一切之所以可行正源于其稳定标识——调用方无需关心 Grain 当前位于哪台服务器、是否已被加载。运行时统一负责 Grain 的激活/停用activation/deactivation与放置/定位placement/locating因此开发者可以像“所有 Grain 永远驻留内存”那样编写代码。从源码看这一抽象的基础定义在 src/Orleans.Core.Abstractions/Core/Grain.cs所有 Grain 实现类继承的抽象基类Grain实现了IGrainBase与IAddressable通过GrainContext暴露运行时上下文、通过GrainFactory访问其他 Grain。Grain 的标识GrainId、激活标识ActivationId、接口类型等 ID 类型定义集中在 src/Orleans.Core.Abstractions/IDs。稳定标识 状态性 受管生命周期三者共同构成了基于 Orleans 构建的系统“可扩展、高性能、可靠”的核心因素——且这一切都无需开发者编写复杂的分布式系统代码。键类型如何标识一个 Grain 实例Grain 接口通过继承特定的“带键标记接口”来声明自己用什么类型的键标识实例定义见 src/Orleans.Core.Abstractions/Core/IGrain.cs标记接口键类型典型场景IGrainWithGuidKeyGuid全局唯一标识如订单、会话IGrainWithIntegerKeylong自增/数值 ID如用户编号IGrainWithStringKeystring可读键如设备序列号、租户名实战示例用 Grain 建模 IoT 云后端考虑一个物联网IoT系统的云后端它需要处理海量设备上报数据、过滤聚合、并向设备下发命令。在 Orleans 中很自然的建模方式是每台设备对应一个 Grain成为物理设备的“数字孪生”digital twin。这些 Grain 将最新设备数据保存在内存中使查询与处理无需直接与物理设备通信通过观察设备的时间序列数据流Grain 还能检测到“测量值超过阈值”等条件变化并触发动作。一个简单的温控器可以这样建模。首先定义设备上报侧接口public interface IThermostat : IGrainWithStringKey { TaskListCommand OnUpdate(ThermostatStatus update); }来自 Web 前端的温控器事件通过调用OnUpdate方法发送到其 Grain该方法可选地返回一条命令给设备var thermostat client.GetGrainIThermostat(id); return await thermostat.OnUpdate(update);同一个温控器 Grain 还可以实现另一个供控制系统交互的接口public interface IThermostatControl : IGrainWithStringKey { TaskThermostatStatus GetStatus(); Task UpdateConfiguration(ThermostatConfiguration config); }这两个接口IThermostat与IThermostatControl由同一个实现类实现public class ThermostatGrain : Grain, IThermostat, IThermostatControl { private ThermostatStatus _status; private ListCommand _commands; public TaskListCommand OnUpdate(ThermostatStatus status) { _status status; var result _commands; _commands new ListCommand(); return Task.FromResult(result); } public TaskThermostatStatus GetStatus() Task.FromResult(_status); public Task UpdateConfiguration(ThermostatConfiguration config) { _commands.Add(new ConfigUpdateCommand(config)); return Task.CompletedTask; } }注意上面的ThermostatGrain并未持久化状态。关于带持久化的完整示例可参考仓库 samples 中的持久化相关示例如 samples/BankAccount账户转账、samples/JournaledTodoList事件溯源待办列表等。Orleans 运行时Silo 与集群Orleans 运行时负责实现上述编程模型。运行时的主要组件是silo负责托管 Grain。通常一组 silo 组成**集群cluster**运行以获得可扩展性与容错能力集群中 silo 相互协调分发工作负载、检测并恢复故障。运行时让集群内托管的 Grain 彼此通信仿佛处于同一进程。除核心编程模型外silo 还为 Grain 提供一系列运行时服务定时器timers、提醒reminders即持久化定时器、持久化persistence、事务transactions、流streams等。Web 前端等外部客户端使用客户端库调用集群中的 Grain该库自动管理网络通信为简化部署客户端也可与 silo 共置co-hosted于同一进程。从 HelloWorld 示例理解完整运行链路仓库中的 samples/HelloWorld 是官方最小可运行示例完整展示了“定义接口 → 实现 Grain → 配置宿主 → 获取引用并调用”的全流程代码可在 Program.cs、IHelloGrain.cs、HelloGrain.cs 中查看。① 定义 Grain 接口IHelloGrain.cspublic interface IHelloGrain : IGrainWithStringKey { ValueTaskstring SayHello(string greeting); }继承IGrainWithStringKey即表明该接口是 Grain 接口且实例以字符串键标识。② 实现 Grain 类HelloGrain.cspublic sealed class HelloGrain : Grain, IHelloGrain { public ValueTaskstring SayHello(string greeting) ValueTask.FromResult($Hello, {greeting}!); }继承Grain基类即标识其为 Grain 实现参考 src/Orleans.Core.Abstractions/Core/Grain.cs。③ 配置宿主并运行Program.cs// Configure the host using var host new HostBuilder() .UseOrleans(builder builder.UseLocalhostClustering()) .Build(); // Start the host await host.StartAsync(); // Get the grain factory var grainFactory host.Services.GetRequiredServiceIGrainFactory(); // Get a reference to the HelloGrain grain with the key friend var friend grainFactory.GetGrainIHelloGrain(friend); // Call the grain and print the result to the console var result await friend.SayHello(Good morning!); Console.WriteLine($\n\n{result}\n\n); Console.WriteLine(Orleans is running.\nPress Enter to terminate...); Console.ReadLine(); Console.WriteLine(Orleans is stopping...); await host.StopAsync();关键点解读UseOrleans(...)是 Orleans 的宿主接入扩展方法UseLocalhostClustering()配置本地单机集群用于开发与测试场景。IGrainFactory从依赖注入容器中获取其扩展方法定义在 src/Orleans.Core.Abstractions/Core/IGrainFactory.cs 附近通过GetGrainT(key)拿到的是 Grain 的引用GrainReference见 src/Orleans.Core.Abstractions/Core/Grain.cs 中的GrainReference属性首次调用时运行时才会真正激活对应实例。调用friend.SayHello(Good morning!)后控制台输出Hello, Good morning!!。此时运行时已经自动实例化了键为friend的HelloGrain开发者无需管理其生命周期——按需激活、空闲停用。工程文件 HelloWorld.csproj 显示该示例通过Microsoft.Orleans.Server包引入完整的服务端silo能力并配合Microsoft.Extensions.Hosting使用 .NET 通用主机。构建与运行示例在仓库 samples/HelloWorld 目录下执行dotnet run即可看到Hello, Good morning!!输出。更多示例的构建脚本可参考 samples/Build-Samples.ps1 与各示例目录下的run.cmd/run.sh。核心特性纵览以下是 Orleans 提供的核心服务与能力仓库根目录 README.md 的 Features 一节有权威概述源码落点均在 src 对应项目。持久化PersistenceOrleans 提供简单的持久化模型在请求处理前确保状态可用并维持一致性。要点一个 Grain 可以有多个命名的持久化数据对象例如用户资料叫profile、库存叫inventory且可存放于不同存储系统资料在数据库 A、库存在数据库 B。Grain 运行期间状态保存在内存读请求无需访问存储。状态更新时调用state.WriteStateAsync()将后备存储同步更新以保证持久性与一致性。相关实现分布于 src/Orleans.Persistence.Memory内存存储、src/Azure/Orleans.Persistence.AzureStorage、src/Azure/Orleans.Persistence.Cosmos、src/AWS/Orleans.Persistence.DynamoDB、src/Google/Orleans.Persistence.Firestore 等。分布式 ACID 事务Transactions在简单持久化模型之上Grain 还可拥有事务状态。多个 Grain 可以共同参与 ACID 事务无论其状态最终存储在哪里。Orleans 的事务是分布式且去中心化的——没有中心事务管理器或协调器并提供可串行化隔离serializable isolation。相关实现位于 src/Orleans.Transactions 及各存储后端如 src/Azure/Orleans.Transactions.AzureStorage、src/AWS/Orleans.Transactions.DynamoDB测试见 test/Transactions。流Streams流帮助开发者近实时地处理序列化数据项。关键特性托管式流无需在使用前显式创建或注册发布者/订阅者可以自由解耦。可靠Grain 可保存检查点cursor并在激活时或之后任意时刻回滚到已保存的检查点。批量投递支持向消费者批量投递消息提升效率与恢复性能。后端多样由 Azure Event Hubs、Amazon Kinesis 等队列服务支撑任意数量的流可多路复用multiplex到较少队列上处理这些队列的职责在集群内均匀平衡。实现见 src/Orleans.Streaming以及各适配器项目如 src/Azure/Orleans.Streaming.EventHubs、src/AWS/Orleans.Streaming.Kinesis、src/AWS/Orleans.Streaming.SQS、src/Orleans.Streaming.NATS。示例可参考 samples/Streaming。定时器与提醒Timers Reminders提醒Reminders是面向 Grain 的持久化调度机制即使 Grain 当前未激活也能确保未来某个时刻执行某个动作。定时器Timers是提醒的非持久化对应物适用于高频、不需要可靠性的场景。定时器 API 的基类实现可参见 src/Orleans.Core.Abstractions/Core/Grain.cs 中的RegisterTimer/RegisterGrainTimer提醒相关实现位于 src/Orleans.Reminders 及各存储后端如 src/Azure/Orleans.Reminders.AzureStorage。灵活的 Grain 放置Flexible Grain Placement当 Grain 被激活时运行时决定在哪台 silo 上激活它这就是放置placement。Orleans 的放置过程完全可配置开箱即用的策略随机random、偏好本地prefer-local、基于负载load-based等。也支持配置自定义放置逻辑从而完全自由地决定 Grain 创建位置例如放到靠近其依赖资源或其他通信 Grain 的服务器上。实现位于 src/Orleans.Core/Placement 与 src/Orleans.Runtime/Placement测试见 test/Orleans.Placement.Tests。Grain 版本化与异构集群Grain Versioning Heterogeneous Clusters应用代码会不断演进而安全地升级有状态的生产系统颇具挑战。Orleans 的支持方式Grain 接口可可选地加版本号。集群维护一份映射哪些 silo 上部署了哪些 Grain 实现、以及这些实现的版本。运行时结合放置策略在路由调用时利用版本信息做放置决策。这既支持版本化 Grain 的安全更新也支持异构集群——不同 silo 可拥有不同的 Grain 实现集合。相关实现见 src/Orleans.Core.Abstractions/Versions 与 src/Orleans.Runtime/Versions。弹性扩展与容错Elastic Scalability Fault ToleranceOrleans 天然支持弹性扩展silo 加入集群即可接受新的激活silo 离开集群缩容或宕机时其上激活的 Grain 会按需在其他 silo 上重新激活集群可缩容到单 silo弹性扩展的同一套性质同时带来容错集群自动检测并快速从故障中恢复。随处运行Run Anywhere只要 .NET Core 或 .NET Framework 受支持Orleans 就能运行Linux、Windows、macOS可部署到 Kubernetes、虚拟机或物理机、本地或云端以及 Azure Container Apps、Azure App Service、Azure Kubernetes Service 等 PaaS 服务。仓库 samples/Deployment 下提供了 Azure App Service 与 Azure Container Apps 的部署示例。无状态工作器Stateless Workers无状态工作器是特殊标记的 Grain不关联任何状态可同时在多个 silo 上激活从而为无状态函数带来更高并行度。相关实现可参考 src/Orleans.Core/Placement 中的放置策略。Grain 调用过滤器Grain Call Filters适用于多个 Grain 的公共逻辑可以表达为拦截器interceptor/ Grain 调用过滤器。Orleans 同时支持入站与出站调用过滤器常见用途包括授权、日志与遥测、错误处理。接口定义见 src/Orleans.Core.Abstractions/Core/IGrainCallFilter.cs 与 src/Orleans.Core.Abstractions/Core/IGrainCallContext.cs。请求上下文Request Context元数据及其他信息可以借助请求上下文沿一系列请求传递典型用途是承载分布式追踪信息或任意用户自定义值。从源码构建 Orleans 与使用官方制品构建解决方案面向贡献者构建、测试与使用本地源码项目的前置要求参见仓库根目录 CONTRIBUTING.md。直接构建整个解决方案dotnet build Orleans.slnx -bl在 Windows 上Build.cmd还会打包解决方案并把包输出到Artifacts/Configuration。官方制品渠道稳定版最新稳定、生产级质量的发布版本通过 NuGet 分发。夜间版Nightly builds发布到专门的 NuGet 源通过全部功能测试但不如稳定版/预发布版测试充分。在项目中使用夜间版包有两种方式方式一修改 .csproj 增加 RestoreSourcesItemGroup RestoreSources $(RestoreSources); https://pkgs.dev.azure.com/dnceng/public/_packaging/orleans-nightly/nuget/v3/index.json /RestoreSources /ItemGroup方式二在解决方案目录创建NuGet.config?xml version1.0 encodingutf-8? configuration packageSources clear / add keyorleans-nightly valuehttps://pkgs.dev.azure.com/dnceng/public/_packaging/orleans-nightly/nuget/v3/index.json / add keynuget valuehttps://api.nuget.org/v3/index.json / /packageSources /configuration配套模板与更多示例项目模板位于 templates/Microsoft.Orleans.Templates可快速生成新应用骨架。仓库 samples 汇集了从 Hello World、银行账户转账到事件溯源待办列表、实时聊天、股票行情、TicTacToe、GPS 追踪等各类场景示例是学习各特性的第一手材料。基于本仓库源码的 API 文档入口位于 docs/index.md可结合具体模块的 src 源码与 test 测试代码交叉验证行为细节。结语Orleans 通过 Virtual Actor Model 把分布式系统的复杂性收敛到运行时内部Grain 的稳定标识、状态性与受管生命周期让应用天然具备可扩展性、性能与可靠性Silo 集群提供了弹性伸缩、故障恢复与丰富的运行时服务持久化、事务、流、提醒、灵活放置、版本化等。无论是 IoT 数字孪生、实时消息类应用还是事务密集型业务系统你都可以从本文的 Grain 建模方法与 Hello World 运行链路出发结合 samples 中的真实示例快速把 Orleans 应用到自己的分布式项目中。【免费下载链接】orleansCloud Native application framework for .NET项目地址: https://gitcode.com/gh_mirrors/or/orleans创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考