BugFree.Cache 1.2.2026.613-beta1618

BugFree.Cache

介绍

BugFree.Cache 是一个基于 Microsoft HybridCache 的高级混合缓存库，在 HybridCache 基础上增加了 Fail-Safe（故障容错）、EagerRefresh（提前刷新）和 Factory Timeout（超时控制）等生产级缓存弹性能力。参考 FusionCache 的核心设计，为 .NET 应用提供可靠的缓存解决方案。

特性

• 混合缓存架构：支持 L1（本地内存）+ L2（Redis 分布式）的混合缓存模式
• Fail-Safe 故障容错：当数据源失败时返回已过期的旧值，避免故障传播到上游
• EagerRefresh 提前刷新：在缓存项即将过期时后台提前刷新，提升用户体验
• Factory 超时控制：软/硬超时控制，防止慢工厂方法阻塞请求
• 基于 NewLife.Redis：使用高性能的 NewLife.Redis 作为 Redis 客户端
• 多目标框架：支持 .NET 8.0 和 .NET 10.0
• Fluent API：提供流畅的配置接口，易于使用

软件架构

┌─────────────────────────────────────────────────────────┐
│                    应用程序层                              │
├─────────────────────────────────────────────────────────┤
│               BugFreeHybridCache                         │
│  ┌─────────────┬─────────────┬─────────────┐            │
│  │ Fail-Safe   │EagerRefresh │  Timeout    │            │
│  │ 故障容错    │  提前刷新   │ 超时控制    │            │
│  └─────────────┴─────────────┴─────────────┘            │
├─────────────────────────────────────────────────────────┤
│              Microsoft HybridCache                       │
│  ┌─────────────────┐  ┌─────────────────┐               │
│  │ L1 本地缓存     │  │ L2 分布式缓存   │               │
│  │ (MemoryCache)   │  │ (Redis)         │               │
│  └─────────────────┘  └─────────────────┘               │
├─────────────────────────────────────────────────────────┤
│           NewLife.Redis (IDistributedCache)              │
└─────────────────────────────────────────────────────────┘

安装教程

1. 通过 NuGet 安装 BugFree.Cache 包：

dotnet add package BugFree.Cache

2. 或者在项目文件中添加包引用：

<PackageReference Include="BugFree.Cache" Version="*" />

使用说明

基本使用

// 在 Program.cs 中注册服务
services.AddBugFreeHybridCache();

// 在控制器或服务中使用
public class MyService
{
    private readonly BugFreeHybridCache _cache;
    
    public MyService(BugFreeHybridCache cache)
    {
        _cache = cache;
    }
    
    public async Task<User> GetUserAsync(int userId)
    {
        return await _cache.GetOrSetAsync(
            $"user:{userId}",
            async ct => await _userRepository.GetByIdAsync(userId, ct),
            opts => opts.SetDuration(TimeSpan.FromMinutes(10))
        );
    }
}

高级配置

services.AddBugFreeHybridCache(
    bfOptions: options =>
    {
        options.DefaultEntryOptions.Duration = TimeSpan.FromMinutes(5);
        options.DefaultEntryOptions.IsFailSafeEnabled = true;
        options.DefaultEntryOptions.FailSafeMaxDuration = TimeSpan.FromHours(1);
    },
    hcOptions: options =>
    {
        options.DefaultEntryOptions.Duration = TimeSpan.FromMinutes(5);
    },
    rdsOptions: options =>
    {
        options.Server = "localhost:6379";
        options.Database = 0;
    }
);

Fail-Safe 使用示例

// 启用 Fail-Safe，当数据源失败时返回过期旧值
var result = await _cache.GetOrSetAsync(
    "critical-data",
    async ct => await GetCriticalDataFromDatabaseAsync(ct),
    opts => opts.SetDuration(TimeSpan.FromMinutes(5))
                 .SetFailSafe(true, TimeSpan.FromHours(1))
);

EagerRefresh 使用示例

// 在缓存过期前 80% 时间后台提前刷新
var result = await _cache.GetOrSetAsync(
    "frequently-accessed-data",
    async ct => await ExpensiveDataOperationAsync(ct),
    opts => opts.SetDuration(TimeSpan.FromMinutes(10))
                 .SetEagerRefresh(0.8)
);

Factory 超时控制

// 设置软超时 2 秒，硬超时 5 秒
var result = await _cache.GetOrSetAsync(
    "data-with-timeout",
    async ct => await SlowDataOperationAsync(ct),
    opts => opts.SetDuration(TimeSpan.FromMinutes(5))
                 .SetFactoryTimeouts(
                     TimeSpan.FromSeconds(2),
                     TimeSpan.FromSeconds(5))
);

配置选项

BugFreeCacheEntryOptions

BugFreeHybridCacheOptions

参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

许可证

本项目使用 MIT 许可证，详见 LICENSE 文件。