Sparkdo.Caching 1.0.1

Sparkdo.Caching

Sparkdo 缓存库，提供分布式缓存功能实现。

功能特性

• 分布式缓存接口：提供通用的分布式缓存接口定义
• 默认缓存实现：基于 Microsoft.Extensions.Caching.Distributed 的默认实现
• 多租户支持：支持多租户场景下的缓存隔离
• 工作单元集成：与工作单元集成，支持事务性缓存操作
• 缓存键标准化：提供缓存键标准化机制
• JSON 序列化：基于 UTF-8 JSON 的缓存项序列化
• 异常处理：可配置的缓存异常处理机制
• 与 Sparkdo 框架无缝集成

安装

<PackageReference Include="Sparkdo.Caching" Version="x.x.x" />

核心组件

缓存接口

• IDistributedCache<TCacheItem>: 分布式缓存接口（字符串键）
• IDistributedCache<TCacheItem, TCacheKey>: 分布式缓存接口（泛型键）

缓存实现

• DefaultDistributedCache<TCacheItem>: 默认分布式缓存实现（字符串键）
• DefaultDistributedCache<TCacheItem, TCacheKey>: 默认分布式缓存实现（泛型键）

缓存配置

• SparkdoDistributedCacheOptions: 分布式缓存配置选项
• DistributedCacheKeyNormalizeArgs: 缓存键标准化参数
• IDistributedCacheKeyNormalizer: 缓存键标准化器接口
• DefaultDistributedCacheKeyNormalizer: 默认缓存键标准化器实现

序列化

• IDistributedCacheSerializer: 分布式缓存序列化器接口
• Utf8JsonDistributedCacheSerializer: UTF-8 JSON 缓存序列化器实现

其他组件

• ICacheSupportsMultipleItems: 支持多项操作的缓存接口
• CacheNameAttribute: 缓存名称特性
• UnitOfWorkCacheItem: 工作单元缓存项
• UnitOfWorkCacheItemExtensions: 工作单元缓存项扩展方法

使用示例

基本缓存使用

public class MyService
{
    private readonly IDistributedCache<MyCacheItem> _cache;
    
    public MyService(IDistributedCache<MyCacheItem> cache)
    {
        _cache = cache;
    }
    
    public async Task<MyCacheItem> GetDataAsync(string key)
    {
        // 尝试从缓存获取数据
        var cachedItem = await _cache.GetAsync(key);
        if (cachedItem != null)
        {
            return cachedItem;
        }
        
        // 如果缓存中没有，从数据源获取
        var item = await GetDataFromSourceAsync(key);
        
        // 将数据存入缓存
        await _cache.SetAsync(key, item);
        
        return item;
    }
}

批量缓存操作

public class MyService
{
    private readonly IDistributedCache<MyCacheItem, int> _cache;
    
    public MyService(IDistributedCache<MyCacheItem, int> cache)
    {
        _cache = cache;
    }
    
    public async Task<Dictionary<int, MyCacheItem>> GetBatchDataAsync(int[] keys)
    {
        // 批量获取缓存数据
        var cachedItems = await _cache.GetManyAsync(keys);
        
        var result = new Dictionary<int, MyCacheItem>();
        var missingKeys = new List<int>();
        
        // 分离已缓存和未缓存的数据
        foreach (var item in cachedItems)
        {
            if (item.Value != null)
            {
                result[item.Key] = item.Value;
            }
            else
            {
                missingKeys.Add(item.Key);
            }
        }
        
        // 获取未缓存的数据
        if (missingKeys.Any())
        {
            var missingItems = await GetBatchDataFromSourceAsync(missingKeys);
            
            // 批量设置缓存
            var itemsToCache = missingItems.Select(x => new KeyValuePair<int, MyCacheItem>(x.Key, x.Value));
            await _cache.SetManyAsync(itemsToCache);
            
            // 合并结果
            foreach (var item in missingItems)
            {
                result[item.Key] = item.Value;
            }
        }
        
        return result;
    }
}

缓存配置

// 在模块配置中自定义缓存选项
public override void Configure(IConfigureContext context)
{
    context.Services.Configure<SparkdoDistributedCacheOptions>(options =>
    {
        // 配置全局缓存条目选项
        options.GlobalCacheEntryOptions.AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(1);
        
        // 为特定缓存类型配置选项
        options.ConfigureCache<MyCacheItem>(new DistributedCacheEntryOptions
        {
            SlidingExpiration = TimeSpan.FromMinutes(30)
        });
    });
}

扩展性

该库提供了完整的缓存功能实现，可以通过以下方式扩展：

1. 实现自定义的缓存键标准化器
2. 实现自定义的缓存序列化器
3. 实现自定义的缓存提供者
4. 通过配置选项自定义缓存行为
5. 通过继承和重写默认实现来定制缓存功能

所有公共接口和类都添加了详细的 XML 文档注释，便于开发者理解和使用。