Galosys.Foundation.FusionCache 26.5.15.1

Galosys.Foundation.FusionCache

成熟度: 🟡 可用 — 功能完整，测试或文档可能不完善

FusionCache 集成模块，为 .NET 应用提供高性能、高可用的分布式缓存解决方案，支持故障安全、背板同步和多级缓存策略。

功能概览

1. 多级缓存

• 内存缓存（L1）
• 分布式缓存（L2，Redis）
• 自动缓存降级
• 缓存穿透保护

2. 故障安全机制

• FailSafe 故障转移
• 节流控制
• 最大故障安全时间
• 自动降级到内存缓存

3. 背板同步

• Redis 背板支持
• 多实例缓存同步
• 实时缓存失效通知

4. 序列化支持

• System.Text.Json 序列化
• 自定义序列化器支持
• 高性能序列化

安装

<PackageReference Include="Galosys.Foundation.FusionCache" Version="x.x.x" />

使用

注册服务

// 在 Startup.cs 或 Program.cs 中注册
services.AddFusionCache();

配置选项

services.AddFusionCache()
    .WithDefaultEntryOptions(opt =>
    {
        // 默认缓存持续时间
        opt.Duration = TimeSpan.FromMinutes(2);
        
        // 启用故障安全
        opt.IsFailSafeEnabled = true;
        
        // 故障安全节流时间
        opt.FailSafeThrottleDuration = TimeSpan.FromHours(2);
        
        // 最大故障安全时间
        opt.FailSafeMaxDuration = TimeSpan.FromMinutes(1);
    })
    .WithSerializer(new FusionCacheSystemTextJsonSerializer())
    .WithDistributedCache(sp => new RedisCache(new RedisCacheOptions 
    { 
        Configuration = connectionString 
    }))
    .WithBackplane(sp => new RedisBackplane(new RedisBackplaneOptions 
    { 
        Configuration = connectionString 
    }));

使用缓存

// 注入 IFusionCache
public class ProductService
{
    private readonly IFusionCache _cache;

    public ProductService(IFusionCache cache)
    {
        _cache = cache;
    }

    public async Task<Product> GetProductAsync(int id)
    {
        return await _cache.GetOrSetAsync<Product>(
            $"product:{id}",
            async ct => await LoadProductFromDbAsync(id, ct),
            options => options.SetDuration(TimeSpan.FromMinutes(10))
        );
    }

    public async Task UpdateProductAsync(Product product)
    {
        await SaveProductToDbAsync(product);
        await _cache.RemoveAsync($"product:{product.Id}");
    }
}

批量操作

// 批量获取
var products = await _cache.GetOrSetAllAsync<Product>(
    productIds.Select(id => $"product:{id}"),
    async (ids, ct) => await LoadProductsFromDbAsync(ids, ct),
    options => options.SetDuration(TimeSpan.FromMinutes(5))
);

// 批量移除
await _cache.RemoveAllAsync(
    productIds.Select(id => $"product:{id}")
);

自定义选项

// 使用自定义选项
var product = await _cache.GetOrSetAsync<Product>(
    $"product:{id}",
    async ct => await LoadProductFromDbAsync(id, ct),
    new FusionCacheEntryOptions
    {
        Duration = TimeSpan.FromMinutes(10),
        IsFailSafeEnabled = true,
        FailSafeMaxDuration = TimeSpan.FromHours(1),
        FailSafeThrottleDuration = TimeSpan.FromMinutes(5),
        FactorySoftTimeout = TimeSpan.FromMilliseconds(100),
        FactoryHardTimeout = TimeSpan.FromMilliseconds(500)
    }
);

核心类

配置说明

连接字符串配置

在 appsettings.json 中配置 Redis 连接字符串：

{
  "ConnectionStrings": {
    "Redis": "localhost:6379,password=your_password,defaultDatabase=0"
  }
}

缓存选项说明

故障安全机制

1. 正常流程: 查询缓存 → 缓存命中 → 返回结果
2. 缓存失效: 查询缓存 → 缓存过期 → 执行工厂方法 → 更新缓存 → 返回结果
3. 故障安全: 查询缓存 → 缓存连接失败 → 返回过期数据 → 异步恢复缓存

依赖项

• microsoft.extensions.caching.stackexchangeredis
• ziggycreatures.fusioncache.backplane.stackexchangeredis
• ziggycreatures.fusioncache.serialization.systemtextjson
• Galosys.Foundation.Core

目录结构

Galosys.Foundation.FusionCache/
├── FusionCacheModule.cs
├── Galosys.Foundation.FusionCache.csproj
└── README.md

最佳实践

1. 缓存键命名

// 推荐使用冒号分隔的层级结构
var cacheKey = $"product:{id}";
var userCacheKey = $"user:{userId}:profile";
var listCacheKey = $"products:category:{categoryId}:page:{page}";

2. 缓存时间策略

// 热点数据：短时间缓存
options.SetDuration(TimeSpan.FromMinutes(5));

// 配置数据：长时间缓存
options.SetDuration(TimeSpan.FromHours(1));

// 静态数据：超长时间缓存
options.SetDuration(TimeSpan.FromDays(1));

3. 故障安全配置

// 关键业务：启用故障安全
options.IsFailSafeEnabled = true;
options.FailSafeMaxDuration = TimeSpan.FromHours(1);

// 非关键业务：禁用故障安全
options.IsFailSafeEnabled = false;

4. 序列化优化

// 使用 System.Text.Json（推荐）
options.Serializer = new FusionCacheSystemTextJsonSerializer();

// 自定义序列化选项
var jsonOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = false
};
options.Serializer = new FusionCacheSystemTextJsonSerializer(jsonOptions);

监控与调试

启用日志

services.AddLogging(builder =>
{
    builder.AddConsole();
    builder.SetMinimumLevel(LogLevel.Information);
});

性能指标

• 缓存命中率
• 缓存响应时间
• 故障安全触发次数
• 背板同步延迟

注意事项

1. Redis 连接: 确保 Redis 服务器配置正确，网络可达
2. 内存占用: 合理设置缓存时间，避免内存溢出
3. 序列化: 大对象序列化可能影响性能，考虑使用压缩
4. 并发控制: 高并发场景建议调整故障安全参数
5. 版本兼容: 确保 FusionCache 版本与项目依赖兼容

示例项目

参考 samples/Dev.API 项目中的 FusionCache 集成示例。