Cuture.AspNetCore.ResponseCaching 2.0.2-beta-05

Cuture.AspNetCore.ResponseCaching

1. Intro

基于ResourceFilter和ActionFilter实现的asp.net core服务端缓存组件

2. 注意项

• 针对Action的缓存实现，基于Filter，非中间件/AOP实现；
• 命中缓存时直接将内容写入响应流，省略了序列化、反序列化等操作；
• 只会缓存响应内容和ContentType，忽略了其它响应Header；
• 支持基于QueryKey、FormKey、Header、Claim、Model中单个或多个组合的缓存键生成；
• 已实现基于Memory和Redis(StackExchange.Redis)的缓存，可拓展；
• 默认缓存Key生成器会包含请求路径为缓存Key；
• 默认缓存Key是大小写不敏感（强制转换为小写）的；
• Asp.net Core版本要求 - 3.1以上；
• Diagnostics支持；
• 执行流程概览；

3. 如何使用

3.1 安装Nuget包

Install-Package Cuture.AspNetCore.ResponseCaching

3.2 在Startup中配置选项

public void ConfigureServices(IServiceCollection services)
{
    //....Other Settings

    services.AddCaching(options =>
    {
        options.Enable = true;  //是否启用响应缓存
        options.DefaultCacheStoreLocation = CacheStoreLocation.Memory;      //默认缓存数据存储位置 - Memory
        options.DefaultExecutingLockMode = ExecutingLockMode.None;      //默认执行锁定模式 - 不锁定
        options.DefaultStrictMode = CacheKeyStrictMode.Ignore;      //默认缓存Key的严格模式 - 忽略没有的找到的Key
        options.LockedExecutionLocalResultCache = new MemoryCache(new MemoryCacheOptions());    //锁定执行时，响应的本地缓存
        options.MaxCacheableResponseLength = 1024 * 1024;       //默认最大可缓存的响应内容长度
        options.MaxCacheKeyLength = 1024;       //最大缓存Key长度
        options.OnCannotExecutionThroughLock = (cacheKey, filterContext, next) => Task.CompletedTask;     //无法使用锁执行请求时（Semaphore池用尽）的回调
        options.OnExecutionLockTimeoutFallback = (cacheKey, filterContext, next) => Task.CompletedTask;     //执行锁定超时后的处理委托
    });

    //以下为可选配置

    // 锁定执行的相关配置
    services.PostConfigure<ResponseCachingExecutingLockOptions>(options =>
    {
        options.MinimumSemaphoreRetained = 50;  //信号池的最小保留大小
        options.MaximumSemaphorePooled = 1000;  //信号池的最大大小

        options.MinimumExecutingLockRetained = 50;  //执行锁池的最小保留大小
        options.MaximumExecutingLockPooled = 1000;  //执行锁池的最大大小

        options.SemaphoreRecycleInterval = TimeSpan.FromMinutes(4);     //信号池的回收间隔
        options.ExecutingLockRecycleInterval = TimeSpan.FromMinutes(2);     //执行锁池的回收间隔
    });
}

3.3 为Action方法标记ResponseCachingMetadataAttribute与ResponseCacheableAttribute

3.3.1 工作方式概述

• ResponseCachingMetadata为派生自IResponseCachingMetadata的Attribute，用于描述响应缓存的配置等细节；
• ResponseCacheable为内部实现的Attribute，用于使用Endpoint获取对应Action的ResponseCachingMetadata并动态构建Filter；

IResponseCachingMetadata接口及内置的ResponseCachingMetadata列表： | 接口 | 描述内容 | 内置实现 | | --- | --- | --- | |IResponseClaimCachePatternMetadata|创建缓存时依据的 Claim 类型|ResponseCachingAttribute| |IResponseFormCachePatternMetadata|创建缓存时依据的 Form 键|ResponseCachingAttribute| |IResponseHeaderCachePatternMetadata|创建缓存时依据的 Header 键|ResponseCachingAttribute| |IResponseModelCachePatternMetadata|创建缓存时依据的 Model 参数名|ResponseCachingAttribute| |IResponseQueryCachePatternMetadata|创建缓存时依据的 Query 键|ResponseCachingAttribute| |ICacheKeyGeneratorMetadata|用于生成缓存Key的ICacheKeyGenerator实现类型|CacheKeyGeneratorAttribute| |ICacheKeyStrictModeMetadata|缓存键严格模式|ResponseCachingAttribute| |ICacheModelKeyParserMetadata|用于生成Model的缓存Key的IModelKeyParser实现类型|CacheModelKeyParserAttribute| |ICacheModeMetadata|缓存模式|ResponseCachingAttribute| |ICacheStoreLocationMetadata|缓存数据存储位置|ResponseCachingAttribute| |IDumpStreamInitialCapacityMetadata|Dump响应的Stream初始容量|ResponseDumpCapacityAttribute| |IExecutingLockMetadata|Action的执行锁定方式|ExecutingLockAttribute| |IHotDataCacheMetadata|热点数据缓存方式|HotDataCacheAttribute| |IMaxCacheableResponseLengthMetadata|最大可缓存响应长度|ResponseCachingAttribute| |IResponseDurationMetadata|缓存时长|ResponseCachingAttribute|

3.3.2 使用内置的特性

使用[ResponseCaching]标记需要缓存响应的Action，或者使用简便标记[CacheByQuery]、[CacheByForm]、[CacheByHeader]、[CacheByClaim]、[CacheByModel]、[CacheByPath]、[CacheByFullUrl] (这些标记都是继承自ResponseCaching并进行了简单的预设置)；

[ResponseCaching(
                60,  //缓存时长（秒）
                Mode = CacheMode.Custom,   //设置缓存模式 - 自定义缓存Key生成
                VaryByClaims = new[] { "id" },     //依据Claim中的`id`进行构建缓存Key
                VaryByHeaders = new[] { "version" },   //依据Header中的`version`进行构建缓存Key
                VaryByQueryKeys = new[] { "page", "pageSize" },    //依据Query中的`page`和`pageSize`进行构建缓存Key
                VaryByModels = new[] { "input" },  //依据Model中的`input`进行构建缓存Key
                StoreLocation = CacheStoreLocation.Memory,     //设置缓存数据存储位置 - Memory
                StrictMode = CacheKeyStrictMode.Ignore,    //缓存Key的严格模式 - 忽略没有的找到的Key
                MaxCacheableResponseLength = 1024 * 1024      //最大可缓存的响应内容长度
                )]
[CacheKeyGenerator(typeof(CustomCacheKeyGenerator), FilterType.Resource)]    //使用 CustomCacheKeyGenerator 作为缓存key生成器
[CacheModelKeyParser(typeof(CustomModelKeyParser))]    //使用 CustomModelKeyParser 作为model的key解析器
[ExecutingLock(ExecutingLockMode.CacheKeySingle)]    //执行action时锁定执行过程，锁定粒度为每个缓存Key，不允许并行执行
[HotDataCache(50, HotDataCachePolicy.LRU)]    //将热点数据缓存在内存中，淘汰算法为LRU
[ResponseDumpCapacity(1024 * 1024)]    //指定dump响应的stream初始化容量，减少不必要的扩容
public IEnumerable<DataDto> Foo([FromQuery] int page, [FromQuery] int pageSize, [FromBody] RequestDto input)
{
    //...action logic
}

3.3.3 使用自定义特性

1. 自定义Attribue，继承继承ResponseCacheableAttribute（或继承IFilterFactory自行实现构建逻辑）；
2. 自定义Attribue，继承需要设置的IResponseCachingMetadata接口；
3. 使用上述自定义特性标记需要缓存的Action方法；

• 可以使用多个Attribute分别实现IResponseCachingMetadata，也可以将所有的功能在一个Attribute实现；

3.4 使用Redis进行缓存

不配置时将默认使用MemoryCache进行缓存

3.4.1 安装Nuget包

Install-Package Cuture.AspNetCore.ResponseCaching.StackExchange.Redis

3.4.2 配置Redis缓存

public void ConfigureServices(IServiceCollection services)
{
    //....Other Settings

    services.AddCaching()
            .UseRedisResponseCache("redis:6379",    //redis配置字符串
                                   "ResponseCache_"     //缓存前缀
                                  );
}

3.5 拦截器

• 当前只有两个拦截器
  • 缓存存储拦截器：ICacheStoringInterceptor
  • 缓存写入拦截器：IResponseWritingInterceptor
• 拦截器可以有多个；
• 拦截器执行顺序为 全局Service拦截器 → 全局Instance拦截器 → Attribute拦截器；

3.5.1 自定义拦截器

• 继承需要拦截的流程接口即可；

public class IgnoreHelloCacheStoringInterceptor
    : Attribute     //继承Attribute，以进行单个Action的设置
    , ICacheStoringInterceptor      //响应存储拦截器
{
    public async Task<ResponseCacheEntry?> OnCacheStoringAsync(ActionContext actionContext, string key, ResponseCacheEntry entry, OnCacheStoringDelegate<ActionContext> next)
    {
        if (key == "hello")
        {
            return null; //key为hello时，不进行存储，且不进行后续的处理
        }

        return await next(actionContext, key, entry);   //执行后续处理
    }
}

3.5.2 设置全局拦截器

• 全局生效的拦截器

public void ConfigureServices(IServiceCollection services)
{
    //....Other Settings

    services.AddCaching().ConfigureInterceptor(options =>
    {
        //Instance拦截器
        options.AddInterceptor(new CacheHitStampInterceptor("key", "value"));    //添加拦截器 CacheHitStampInterceptor 的实例作为全局拦截器
        
        //Service拦截器
        options.AddServiceInterceptor<CustomInterceptor>();    //从DI中获取 CustomInterceptor 作为全局拦截器
    });
}

3.5.2 设置Action拦截器

• 将拦截器Attribute设置到对应的Action方法即可，此时拦截器只针对当前Action生效

3.5.3 内置的CacheHitStamp缓存处理拦截器

• 此拦截器将会在命中缓存时向响应的HttpHeader中添加指定内容
• 此设置可能因为前置拦截器短路而不执行

配置方法：

public void ConfigureServices(IServiceCollection services)
{
    //....Other Settings

    services.AddCaching().UseCacheHitStampHeader("cached", "1");    //当命中缓存时，响应的Header中将附加`cached: 1`
}

4. 示例

4.1 基于Query缓存

使用query中的page和pageSize缓存

[HttpGet]
[CacheByQuery(60, "page", "pageSize")]
public ResultDto Foo(int page, int pageSize)
{
    //...action logic
}

4.2 基于Form缓存

使用form中的page和pageSize缓存

[HttpGet]
[CacheByForm(60, "page", "pageSize")]
public ResultDto Foo()
{
    int page = int.Parse(Request.Form["page"]);
    int pageSize = int.Parse(Request.Form["pageSize"]);
    //...action logic
}

4.3 基于Model缓存

使用action的参数进行缓存

[HttpPost]
[CacheByModel(60)]
public ResultDto Foo(RequestDto input)
{
    //...action logic
}

public class RequestDto : ICacheKeyable
{
    public int Page { get; set; }

    public int PageSize { get; set; }

    public string AsCacheKey() => $"{Page}_{PageSize}";
}

使用Model缓存会使用以下方式的其中一种生成Key（优先级从上往下）

• 指定ModelKeyParserType
• Model类实现ICacheKeyable接口
• Model类的ToString方法

此时Filter由ResourceFilter转变为ActionFilter

4.4 基于用户缓存

使用用户凭据中的id和query中的page与pageSize组合构建缓存Key

[ResponseCaching(60,
                 Mode = CacheMode.Custom,
                 VaryByClaims = new[] { "id" },
                 VaryByQueryKeys = new[] { "page", "pageSize" })]
public ResultDto Foo(int page, int pageSize)
{
    //...action logic
}

5. 自定义缓存实现

实现IMemoryResponseCache或IDistributedResponseCache接口；并将实现注入asp.net core的DI，替换掉默认实现；

Diagnostics支持

• 部分功能已使用Diagnostic，DiagnosticName为Cuture.AspNetCore.ResponseCaching；

事件列表如下：

使用ILogger打印事件信息

• 已实现简单的Diagnostic订阅并打印，直接启用即可输出日志；
• 使用Diagnostic会对性能有那么一点影响；

1. 配置服务时添加Logger

services.AddCaching()
        .AddDiagnosticDebugLogger() //在Debug模式下使用Logger输出Diagnostic事件信息
        .AddDiagnosticReleaseLogger();  //在Release模式下使用Logger输出Diagnostic事件信息

2. 构建应用时启用Logger

app.EnableResponseCachingDiagnosticLogger();

如上配置后，内部将订阅相关Diagnostic，并将事件信息使用ILogger输出。