{"id":19992202,"url":"https://github.com/OpenSagas-csharp/servicecomb-pack-csharp","last_synced_at":"2025-05-04T11:30:47.027Z","repository":{"id":97072977,"uuid":"143521755","full_name":"OpenSagas-csharp/servicecomb-pack-csharp","owner":"OpenSagas-csharp","description":"The .NET  omega   agent for Apache incubator-servicecomb-saga https://github.com/apache/servicecomb-pack","archived":true,"fork":false,"pushed_at":"2019-01-07T06:19:22.000Z","size":580,"stargazers_count":152,"open_issues_count":4,"forks_count":43,"subscribers_count":15,"default_branch":"omega_v0.1","last_synced_at":"2024-11-13T04:54:55.201Z","etag":null,"topics":["data-consistency","distributed-transactions","eventually-consistent","netcore","saga"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenSagas-csharp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-08-04T11:05:38.000Z","updated_at":"2024-07-20T00:01:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"8abbee94-a357-4b0f-a8ad-9db2f19eb952","html_url":"https://github.com/OpenSagas-csharp/servicecomb-pack-csharp","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSagas-csharp%2Fservicecomb-pack-csharp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSagas-csharp%2Fservicecomb-pack-csharp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSagas-csharp%2Fservicecomb-pack-csharp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenSagas-csharp%2Fservicecomb-pack-csharp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenSagas-csharp","download_url":"https://codeload.github.com/OpenSagas-csharp/servicecomb-pack-csharp/tar.gz/refs/heads/omega_v0.1","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252329150,"owners_count":21730557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-consistency","distributed-transactions","eventually-consistent","netcore","saga"],"created_at":"2024-11-13T04:52:04.677Z","updated_at":"2025-05-04T11:30:43.933Z","avatar_url":"https://github.com/OpenSagas-csharp.png","language":"C#","funding_links":[],"categories":["C\\#"],"sub_categories":[],"readme":"\n# servicecomb-pack-csharp\n[![Build Status](https://travis-ci.org/OpenSagas-csharp/servicecomb-pack-csharp.svg?branch=omega_v0.1)](https://travis-ci.org/OpenSagas-csharp/servicecomb-pack-csharp)\n\nThe .NET  omega   agent for Apache servicecomb-pack\n\n\n# Saga基本使用指南\n\n## 使用前置条件说明\n\n\u003e 如果还有同学对Saga还不甚了解的同学,可以参考Saga官方中文地址[地址](https://github.com/apache/incubator-servicecomb-saga/blob/master/README_ZH.md),同时可以参考此项目贡献者之一的[WithLin](https://github.com/WithLin)的一篇中文说明文章,该地址如下:[地址](https://www.cnblogs.com/WithLin/p/9556413.html),文章由浅入深的讲述了分布式事务在微服务场景下的重要性,以及Saga对分布式事务的大致实现方式和后续的思考\n\n* **必须** 你需要可用的一个本地或者远程的数据库(mysql或者postpresql)作为Saga持久化分布式事务事件的持久化存储,当然只要官方支持的Database Provider即可,具体idea数据库配置如下图,注意数据库的名字与您真实数据库名一致\n\n![alpha-server-database-setting.png](imgs/alpha-server-database-setting.png)\n\n* **必须** 成功启动alpha-server,导致环境搭建以及部署颇为麻烦,后期官方将会提供image上传docker hub提供给大家使用,启动成功参考下图\n\n![alpha-server.png](imgs/alpha-server.png)\n\n* **可选** 同时saga提供了UI可视化界面,直接idea中启动saga-web即可\n\n* **支持docker-compose**:根目录提供了一个dockercompose文件,只需要在工程的根目录下执行docker-compose up -d 即可，上面的操作可以给感兴趣的调试环境的搭建。\n\n\n\n## 开始玩转分布式事务Saga\n\n克隆当前项目,然后请使用VS2017打开解决方案定位到sample目录,你会看到如下所示的三个实例应用程序,这里app都是基于TargetFramework=netcoreapp2.0的,所以需要相应的启动环境\n\n![sample-app-test.png](imgs/sample-app-test.png)\n\n下面对上图做一个基本介绍,假定现在我们有三个微服务,分别是 Booking-预定服务,Car-订车服务,Hotel-酒店服务,相信大家一看便知,三者的从属关系以及在现实社会中的关联关系,下面我们的分布式事务一致性测试将在这几个app中完成,现在我们分别对项目做一定的初始化工作\n\n```csharp\nservices.AddOmegaCore(option =\u003e\n{\n    // your alpha-server address\n    option.GrpcServerAddress = \"localhost:8080\";\n    // your app identification\n    option.InstanceId = \"Booking123\";\n    // your app name\n    option.ServiceName = \"Booking\";\n});\n```\n\n这里需要对三个项目都做如上所示的基本配置即可,现在一直都配置就绪了,下面开始我们的分布式事务的测试吧...\n\n## 分布式事务场景测试\n\n下面将会针对正常以及异常情况分别测试\n\n### 正常情况测试\n\n\u003e 由 Booking 发起预定汽车和预定酒店的服务,且假设三个服务均可以正常访问的情况,正常启动如下图所示:\n![apps.png](imgs/apps.png)\n\n```csharp\n        [HttpGet, SagaStart] // SagaStart 顾名思义标记为分布式事务开始的地方\n        [Route(\"book1\")]\n        public ActionResult Book()\n        {\n            // init basic httpclient\n            var httpClient = new HttpClient();\n            // mark a reservation of car\n            httpClient.GetAsync(\"http://localhost:5002/api/values\");\n            // book a hotel\n            httpClient.GetAsync(\"http://localhost:5003/api/values\");\n            // your busniess code\n            // for example save the order to your database\n            return Ok(\"ok\");\n        }\n```\n\n请求结果返回\"ok\",结果我们看看数据记录的是什么东西,相信也是大家比较关心的,看懂了数据库也就了解了分布式事务的阶段性事件存储,下面直接上图:\n\n![db-txevents.png](imgs/db-txevents.png)\n\n我们从上图很明显的就能看出来服务的先后关系以及服务之间的依赖关系,同时LocalTxId标记了每个一个过程的唯一ID,其中[type]需要注重说明一下,标记了每个动作了的状态同时也是判断每个微服务是否成功是否需要补偿的重要标准( 特别说明: sample项目中的预定车辆以及预定酒店是模拟操作,具体可以参见各自项目代码 )\n\n### 节点服务异常情况\n\n\u003e 这里我为什么要说节点服务异常呢?相信经历过微服务的同学就知道,错综复杂的服务之间的调用,就会增加耦合以及某个节点服务出现异常导致整个调用连失败的情况,所以基于如此我们下面测试每个阶段所带来的情况分析\n\n```csharp\n        [HttpGet, SagaStart]\n        [Route(\"book1\")]\n        public ActionResult Book1()\n        {\n            // throw new a exception for test\n            throw new DbUpdateException(\"I'm a dbUpdateException\", new Exception());\n            // init basic httpclient\n            var httpClient = new HttpClient();\n            // mark a reservation of car\n            httpClient.GetAsync(\"http://localhost:5002/api/values\").Wait();\n            // book a hotel\n            httpClient.GetAsync(\"http://localhost:5003/api/values\").Wait();\n            return Ok(\"ok\");\n        }\n```\n\n这里只是记录[Book1]本身服务的生命周期,因为还没有请求car和hotel,下面截图也验证我的预期结果:\n\n![test-sagastart-exception](imgs/test-sagastart-exception.png)\n\n#### 测试Car-Service调用异常\n\n\u003e 这里需要特别说明的是,需要 httpClient 等待微服务调用结果,这样car-service出现调用异常,我们的框架才会感知到,才会上报通知事务管理,最后终止或者回滚事务链条\n\nOmega.Sample.Booking -\u003e ValuesController:\n\n```csharp\n        [HttpGet, SagaStart]\n        [Route(\"book2\")]\n        public ActionResult Book2()\n        {\n            // init basic httpclient\n            var httpClient = new HttpClient();\n            // mark a reservation of car , this will be throw a exception from car-service\n            httpClient.GetAsync(\"http://localhost:5002/api/values\").Wait();\n            // book a hotel\n            httpClient.GetAsync(\"http://localhost:5003/api/values\").Wait();\n            return Ok(\"ok\");\n        }\n```\n\nOmega.Sample.Car -\u003e ValuesController :\n\n```csharp\n        [HttpGet]\n        public IEnumerable\u003cstring\u003e Get()\n        {\n            CarBookingService carBookingService = new CarBookingService();\n            var carbook = new CarBooking()\n            {\n                Id = 1,\n                Amount = 1,\n                Name = \"WithLin\"\n            };\n            carBookingService.Order(carbook);\n            return new string[] { \"value1\", \"value2\" };\n        }\n```\n\nOmega.Sample.Car -\u003e CarBookingService:\n\n```csharp\n    public class CarBookingService\n    {\n        private readonly ConcurrentDictionary\u003cint, CarBooking\u003e _bookings = new ConcurrentDictionary\u003cint, CarBooking\u003e();\n\n\n        [Compensable(nameof(CancelCar))]\n        public void Order(CarBooking carBooking)\n        {\n            carBooking.Confirm();\n            _bookings.TryAdd(carBooking.Id, carBooking);\n            // throw new Exception\n            throw new Exception(\"test car serivice error\");\n        }\n\n        void CancelCar(CarBooking booking)\n        {\n            _bookings.TryGetValue(booking.Id, out var carBooking);\n            carBooking?.Cancel();\n        }\n    }\n```\n\n果不其然我们的[Book2]方式直接向我们抛出了异常,上图说明:\n\n![car-service-exception.jpg](imgs/car-service-exception.jpg)\n\n那么再来看看数据是否和我们预期感觉一样讷,相信聪明的小伙伴应该知道套路是什么了:\n\n![CarAbortDatabase.png](imgs/CarAbortDatabase.png)\n\n关于 car-service 的红框状态描述相信大家就很清楚了,历经了开始-\u003e中止-\u003e结束,最后整个 Booking 方式完成\n\n#### 测试Hotel-Service调用异常\n\n\u003e 预期调用 Hotel-Service 异常,但是我们的 car-service 调用成功,这个时候我们需要 car-service 通过补偿的方式撤销调用 car-service 带来的数据或者状态的变化,达到要么全部成功,要么全部失败的结果,实现最终一致性\n\nOmega.Sample.Booking -\u003e ValuesController:\n\n```csharp\n        [HttpGet, SagaStart]\n        [Route(\"book\")]\n        public async Task\u003cActionResult\u003e Book()\n        {\n            // init basic httpclient\n            var httpClient = new HttpClient();\n            // mark a reservation of car\n            await httpClient.GetAsync(\"http://localhost:5002/api/values\");\n            // book a hotel\n            await httpClient.GetAsync(\"http://localhost:5003/api/values\");\n            return Ok(\"ok\");\n        }\n```\n\nOmega.Sample.Car -\u003e ValuesController :\n\n```csharp\n        [HttpGet]\n        public IEnumerable\u003cstring\u003e Get()\n        {\n            CarBookingService carBookingService = new CarBookingService();\n            var carbook = new CarBooking()\n            {\n                Id = 1,\n                Amount = 1,\n                Name = \"WithLin\"\n            };\n            carBookingService.Order(carbook);\n            return new string[] { \"value1\", \"value2\" };\n        }\n```\n\nOmega.Sample.Car -\u003e CarBookingService:\n\n\u003e 这里需要特别说明 [Compensable(nameof(CancelCar))] 此标记是指示补偿或者回滚时的方法,当然它的执行是在事务官发起通知的时候执行,具体参考下图断点命中\n\n```csharp\n    public class CarBookingService\n    {\n        private readonly ConcurrentDictionary\u003cint, CarBooking\u003e _bookings = new ConcurrentDictionary\u003cint, CarBooking\u003e();\n\n\n        [Compensable(nameof(CancelCar))]\n        public void Order(CarBooking carBooking)\n        {\n            carBooking.Confirm();\n            _bookings.TryAdd(carBooking.Id, carBooking);\n            //throw new Exception(\"test car serivice error\");\n        }\n\n        void CancelCar(CarBooking booking)\n        {\n            _bookings.TryGetValue(booking.Id, out var carBooking);\n            carBooking?.Cancel();\n        }\n    }\n```\n\nOmega.Sample.Hotel -\u003e ValuesController :\n\n```csharp\n        [HttpGet]\n        public IEnumerable\u003cstring\u003e Get()\n        {\n            HotelBookingService bookingService = new HotelBookingService();\n            HotelBooking hotelBooking = new HotelBooking()\n            {\n                Id = 1,\n                Amount = 10,\n                Name = \"test\"\n            };\n            bookingService.Order(hotelBooking);\n            return new string[] { \"value1\", \"value2\" };\n        }\n```\n\nOmega.Sample.Hotel -\u003e HotelBookingService:\n\n\u003e 注意这里因为 booking.Amount \u003e 2 将会触发异常导致服务调用错误\n\n```csharp\n        [Compensable(nameof(CancelHotel))]\n        public void Order(HotelBooking booking)\n        {\n            if (booking.Amount \u003e 2)\n            {\n                throw new ArgumentException(\"can not order the rooms large than two\");\n            }\n            booking.Confirm();\n            _bookings.TryAdd(booking.Id, booking);\n        }\n```\n\nCar-Service 补偿方法触发执行命中断点如下图:\n\n![DebugPicture.png](imgs/DebugPicture.png)\n\n数据库事务链条状态图(聪明的你观察到了那个补偿事件的记录了讷):\n\n![HotleAbort-Scenario.png](imgs/HotleAbort-Scenario.png)\n\n#### 测试Booking-Service 最后调用异常\n\n\u003e 这里我们最后再来测试一下,如下情况,也是前面的 car-service hotel-service 调用都没有问题,但是最后 booking-service 提交的出现了未知异常(例如网络抖动.数据库闪断之类),代码我就不贴太多了,展示 booking-service 即可\n\n```csharp\n        [HttpGet, SagaStart]\n        [Route(\"book\")]\n        public async Task\u003cActionResult\u003e Book()\n        {\n            // init basic httpclient\n            var httpClient = new HttpClient();\n            // mark a reservation of car (no exception)\n            await httpClient.GetAsync(\"http://localhost:5002/api/values\");\n            // book a hotel (no exception)\n            await httpClient.GetAsync(\"http://localhost:5003/api/values\");\n            throw new Exception(\"just test unknown exception\");\n            return Ok(\"ok\");\n        }\n```\n\n理所当然的如下图所示:\n\n\u003e 关于 Command 表大致用来存储需要补偿的命令的,相应的alpha-server有定时服务在刷这个表,一直补偿成功为止,来保证最终的分布式事务的一致性\n\n![CarAndCompensate.png](imgs/CarAndCompensate.png)\n\n\u003e 相信你已经注意到了我们的两个预定服务都触发了补偿逻辑(红框所示)\n\n![BookingAbortDatabase.png](imgs/BookingAbortDatabase.png)\n\n#### 如何在服务超时情况维持分布式事务测试\n\n```csharp\n[HttpGet, SagaStart(TimeOut = 3)]\n        [Route(\"book3\")]\n        public ActionResult Book3()\n        {\n            // init basic httpclient\n            var httpClient = new HttpClient();\n            // mark a reservation of car , this will be throw a exception from car-service\n            httpClient.GetAsync(\"http://localhost:5002/api/values\").Wait();\n            // book a hotel\n            httpClient.GetAsync(\"http://localhost:5003/api/values\").Wait();\n            Thread.Sleep(5000);\n            return Ok(\"ok\");\n        }\n```\n\n\u003e 事件表详情\n![timeoutdatabase-txEvent.png](imgs/timeoutdatabase-txEvent.png)\n\u003e 超时表详情\n![timeoutdatabase-txEvent.png](imgs/timeoutdatabase-TxTime.png)\n\u003e 补偿表详情\n![timeoutdatabase-txCompenste.png](imgs/timeoutdatabase-txCompenste.png)\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenSagas-csharp%2Fservicecomb-pack-csharp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOpenSagas-csharp%2Fservicecomb-pack-csharp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenSagas-csharp%2Fservicecomb-pack-csharp/lists"}