doc: 添加文档

2024-01-25 15:39:50 +08:00
parent 19d8912680
commit 8e85a233a9
2 changed files with 342 additions and 0 deletions
--- a/Yi.Doc.Md/02.框架功能模块教程/15.缓存.md
+++ b/Yi.Doc.Md/02.框架功能模块教程/15.缓存.md
@@ -0,0 +1,156 @@
+## 简介
+缓存的概念，相信大家都很了解了。主要目的是为了提高系统运行效率，减少服务器压力。由于硬盘的访问速度远远小于内存的速度，
+
+- 对于需要频繁访问的数据，我们可以使用缓存。
+- 对于需要时间过期功能的数据，我们可以使用缓存。
+
+> 缓存中尽量不要存放重要数据，它和硬盘的区别在于，强制中断之后，缓存的数据将会被清空难以找回。
+
+
+框架的缓存模块是基于面向对象的。如果接触过其他缓存框架，可能在第一次接触框架的这种方式，会有一定的不适应，但是对于复杂类型、复杂key的情况，面向对象化的方式，边界会更加清晰。
+## 使用方式
+使用 `IDistributedCache`进行管理缓存，包括
+- 缓存读取
+- 缓存覆盖
+- 缓存删除
+- 缓存写入
+
+支持时间过期及批量操作
+
+### IDistributedCache<TCacheItem>简单类型
+如果你的缓存的key只是一个固定的字符串，那么直接可以通过依赖注入进行`IDistributedCache<TCacheItem>`接口即可，TCacheItem就是你定义存储下来的缓存对象
+例如：
+``` cs
+//定义存储模型
+ public class BookCacheItem
+    {
+        public string Name { get; set; }
+
+        public float Price { get; set; }
+    }
+
+//进行获取或者添加
+  public class BookService : ITransientDependency
+    {
+        private readonly IDistributedCache<BookCacheItem> _cache;
+
+        public BookService(IDistributedCache<BookCacheItem> cache)
+        {
+            _cache = cache;
+        }
+
+        public async Task<BookCacheItem> GetAsync(Guid bookId)
+        {
+            return await _cache.GetOrAddAsync(
+                bookId.ToString(), //缓存键
+                async () => await GetBookFromDatabaseAsync(bookId),
+                () => new DistributedCacheEntryOptions
+                {
+                    AbsoluteExpiration = DateTimeOffset.Now.AddHours(1)
+                }
+            );
+        }
+
+        private Task<BookCacheItem> GetBookFromDatabaseAsync(Guid bookId)
+        {
+            //TODO: 从数据库获取数据
+        }
+    }
+
+```
+
+### IDistributedCache<TCacheItem, TCacheKey>简单key
+同时，推荐使用`IDistributedCache<TCacheItem, TCacheKey>`接口，把key和value同时都当作对象去标识，更加符合面向对象的特征
+
+这里TCacheKey可以为简单类型Guid
+
+``` cs
+
+[CacheName("Books")]
+    public class BookCacheItem
+    {
+        public string Name { get; set; }
+
+        public float Price { get; set; }
+    }
+
+
+    public class BookService : ITransientDependency
+    {
+        private readonly IDistributedCache<BookCacheItem, Guid> _cache;
+
+        public BookService(IDistributedCache<BookCacheItem, Guid> cache)
+        {
+            _cache = cache;
+        }
+
+        public async Task<BookCacheItem> GetAsync(Guid bookId)
+        {
+            return await _cache.GetOrAddAsync(
+                bookId, //Guid类型作为缓存键
+                async () => await GetBookFromDatabaseAsync(bookId),
+                () => new DistributedCacheEntryOptions
+                {
+                    AbsoluteExpiration = DateTimeOffset.Now.AddHours(1)
+                }
+            );
+        }
+        private Task<BookCacheItem> GetBookFromDatabaseAsync(Guid bookId)
+        {
+            //TODO: 从数据库获取数据
+        }
+    }
+
+```
+
+### 复杂类型的缓存键
+如果TCacheKey为复杂类型，可以重写key的ToString方法即可
+``` cs
+public class UserInOrganizationCacheKey
+{
+    public Guid UserId { get; set; }
+ 
+    public Guid OrganizationId { get; set; }
+
+    //构建缓存key
+    public override string ToString()
+    {
+        return $"{UserId}_{OrganizationId}";
+    }
+}
+
+public class BookService : ITransientDependency
+{
+    private readonly IDistributedCache<UserCacheItem, UserInOrganizationCacheKey> _cache;
+
+    public BookService(
+        IDistributedCache<UserCacheItem, UserInOrganizationCacheKey> cache)
+    {
+        _cache = cache;
+    }
+    
+    ...
+}
+```
+
+## 配置
+AbpDistributedCacheOptions 是配置缓存的主要Option类.
+
+示例：为应用程序设置缓存键前缀
+
+``` cs
+Configure<AbpDistributedCacheOptions>(options =>
+{
+    options.KeyPrefix = "MyApp1";
+});
+
+```
+
+## 其他缓存实现
+默认使用的缓存实现是基于`MemoryCache`本地缓存实现的
+
+同时还支持其他的实现：
+[Redis支持](https://docs.abp.io/zh-Hans/abp/latest/Redis-Cache)
+
+由于模块化，只需要在对应的模块中添加依赖即可，不需要修改任何其他代码。
+
--- a/Yi.Doc.Md/02.框架功能模块教程/16.事件总线.md
+++ b/Yi.Doc.Md/02.框架功能模块教程/16.事件总线.md
@@ -0,0 +1,186 @@
+## 本地事件总线
+本地事件总线允许服务发布和订阅进程内事件. 这意味着如果两个服务(发布者和订阅者)在同一个进程中运行,那么它是合适的.
+
+### 发布事件
+以下介绍了两种发布本地事件的方法.
+
+ILocalEventBus
+可以注入 ILocalEventBus 并且使用发布本地事件.
+
+示例: 产品的存货数量发生变化时发布本地事件
+``` cs
+using System;
+using System.Threading.Tasks;
+using Volo.Abp.DependencyInjection;
+using Volo.Abp.EventBus.Local;
+
+namespace AbpDemo
+{
+    public class MyService : ITransientDependency
+    {
+        private readonly ILocalEventBus _localEventBus;
+
+        public MyService(ILocalEventBus localEventBus)
+        {
+            _localEventBus = localEventBus;
+        }
+        
+        public virtual async Task ChangeStockCountAsync(Guid productId, int newCount)
+        {
+            //TODO: IMPLEMENT YOUR LOGIC...
+            
+            //PUBLISH THE EVENT
+            await _localEventBus.PublishAsync(
+                new StockCountChangedEvent
+                {
+                    ProductId = productId,
+                    NewCount = newCount
+                }
+            );
+        }
+    }
+}
+```
+PublishAsync 方法需要一个参数:事件对象,它负责保持与事件相关的数据,是一个简单的普通类:
+``` cs
+using System;
+
+namespace AbpDemo
+{
+    public class StockCountChangedEvent
+    {
+        public Guid ProductId { get; set; }
+        
+        public int NewCount { get; set; }
+    }
+}
+```
+即使你不需要传输任何数据也需要创建一个类(在这种情况下为空类).
+### 订阅事件
+一个服务可以实现 ILocalEventHandler<TEvent> 来处理事件.
+
+示例: 处理上面定义的StockCountChangedEvent
+``` cs
+using System.Threading.Tasks;
+using Volo.Abp.DependencyInjection;
+using Volo.Abp.EventBus;
+
+namespace AbpDemo
+{
+    public class MyHandler
+        : ILocalEventHandler<StockCountChangedEvent>,
+          ITransientDependency
+    {
+        public async Task HandleEventAsync(StockCountChangedEvent eventData)
+        {
+            //TODO: your code that does somthing on the event
+        }
+    }
+}
+```
+这就是全部,MyHandler 由ABP框架自动发现,并在发生 StockCountChangedEvent 事件时调用 HandleEventAsync.
+
+事件可以由0个或多个处理程序订阅.
+一个事件处理程序可以订阅多个事件,但是需要为每个事件实现 ILocalEventHandler<TEvent> 接口.
+
+> 事件处理程序类必须注册到依赖注入(DI),示例中使用了 ITransientDependency. 参阅依赖注入文档了解更多选项.
+
+### 事务和异常行为
+当一个事件发布,订阅的事件处理程序将立即执行.所以;
+
+如果处理程序抛出一个异常,它会影响发布该事件的代码. 这意味着它在 PublishAsync 调用上获得异常. 因此如果你想隐藏错误,在事件处理程序中使用try-catch. *如果在一个工作单元范围内执行的事件发布的代码,该事件处理程序也由工作单元覆盖. 这意味着,如果你的UOW是事务和处理程序抛出一个异常,事务会回滚.
+
+## 分布式事件总线
+分布式事件总线系统提供了一个可以被任何提供程序实现的抽象. 有四种开箱即用的提供程序:
+
+- LocalDistributedEventBus 是默认实现,实现作为进程内工作的分布式事件总线. 是的!如果没有配置真正的分布式提供程序,默认实现的工作方式与本地事件总线一样.
+- RabbitMqDistributedEventBus 通过RabbitMQ实现分布式事件总线
+- KafkaDistributedEventBus 通过Kafka实现分布式事件总线
+- RebusDistributedEventBus 通过Rebus实现分布式事件总线
+- 
+使用本地事件总线作为默认具有一些重要的优点. 最重要的是:它允许你编写与分布式体系结构兼容的代码. 您现在可以编写一个整体应用程序,以后可以拆分成微服务. 最好通过分布式事件而不是本地事件在边界上下文之间(或在应用程序模块之间)进行通信.
+
+### 发布事件
+IDistributedEventBus
+可以注入 IDistributedEventBus 并且使用发布分布式事件.
+
+示例: 产品的存货数量发生变化时发布分布式事件
+``` cs
+using System;
+using System.Threading.Tasks;
+using Volo.Abp.DependencyInjection;
+using Volo.Abp.EventBus.Distributed;
+
+namespace AbpDemo
+{
+    public class MyService : ITransientDependency
+    {
+        private readonly IDistributedEventBus _distributedEventBus;
+
+        public MyService(IDistributedEventBus distributedEventBus)
+        {
+            _distributedEventBus = distributedEventBus;
+        }
+        
+        public virtual async Task ChangeStockCountAsync(Guid productId, int newCount)
+        {
+            await _distributedEventBus.PublishAsync(
+                new StockCountChangedEto
+                {
+                    ProductId = productId,
+                    NewCount = newCount
+                }
+            );
+        }
+    }
+}
+```
+PublishAsync 方法需要一个参数:事件对象,它负责保持与事件相关的数据,是一个简单的普通类:
+``` cs
+using System;
+
+namespace AbpDemo
+{
+    [EventName("MyApp.Product.StockChange")]
+    public class StockCountChangedEto
+    {
+        public Guid ProductId { get; set; }
+        
+        public int NewCount { get; set; }
+    }
+}
+```
+即使你不需要传输任何数据也需要创建一个类(在这种情况下为空类).
+
+> Eto 是我们按照约定使用的Event Transfer Objects(事件传输对象)的后缀. s虽然这不是必需的,但我们发现识别这样的事件类很有用(就像应用层上的DTO 一样).
+
+### 订阅事件
+一个服务可以实现 IDistributedEventHandler<TEvent> 来处理事件.
+
+示例: 处理上面定义的StockCountChangedEto
+``` cs
+using System.Threading.Tasks;
+using Volo.Abp.DependencyInjection;
+using Volo.Abp.EventBus.Distributed;
+
+namespace AbpDemo
+{
+    public class MyHandler
+        : IDistributedEventHandler<StockCountChangedEto>,
+          ITransientDependency
+    {
+        public async Task HandleEventAsync(StockCountChangedEto eventData)
+        {
+            var productId = eventData.ProductId;
+        }
+    }
+}
+```
+这就是全部.
+
+MyHandler 由ABP框架自动发现,并在发生 StockCountChangedEto 事件时调用 HandleEventAsync.
+如果你使用的是分布式消息代理,比如RabbitMQ,ABP会自动订阅消息代理上的事件,获取消息执行处理程序.
+如果事件处理程序成功执行(没有抛出任何异常),它将向消息代理发送确认(ACK).
+你可以在处理程序注入任何服务来执行所需的逻辑. 一个事件处理程序可以订阅多个事件,但是需要为每个事件实现 IDistributedEventHandler<TEvent> 接口.
+
+事件处理程序类必须注册到依赖注入(DI),示例中使用了 ITransientDependency. 参阅DI文档了解更多选项.