Galosys.Foundation.FreeRedis 26.5.20.1

Galosys.Foundation.FreeRedis

成熟度: 🟢 稳定 — 生产可用，活跃维护

简介

Galosys.Foundation.FreeRedis 基于 FreeRedis 提供 IRedisConnection 和 RedisTemplate 的完整实现，支持集群、哨兵、分布式锁、幂等性、Pub/Sub、消息队列、缓存管理等场景。

特性

• IRedisConnection 实现 — 完整实现 9 大命令组（Key、String、Hash、List、Set、SortedSet、Geo、Stream、Script）
• IPipeline 实现 — 基于 FreeRedis Pipeline 的批量命令执行
• 重试策略 — ResilientRedisConnection 装饰器，指数退避 + 随机抖动自动重试
• 消息队列 — 支持 SendAsync/Handle 延迟队列模式（基于 Redis Stream）
• Pub/Sub — FreeRedisMessageListenerContainer 托管服务，自动管理订阅生命周期
• 分布式锁 — FreeRedisDistributedLock 实现，Lua 原子脚本 + 看门狗自动续期
• 幂等性保证 — FreeRedisDistributedIdempotence 实现，原子标记 + 结果缓存
• 分布式缓存 — 集成 IDistributedCache + RedisCacheManager 命名缓存管理
• 健康检查 — RedisHealthCheck 自动注册，PING 延迟监测
• 连接日志 — RedisConnectionLogger 自动记录连接事件

安装

dotnet add package Galosys.Foundation.FreeRedis

配置

最小化配置（向后兼容）

从 appsettings.json 的 ConnectionStrings:Redis 读取：

{
  "ConnectionStrings": {
    "Redis": "localhost:6379,abortConnect=false"                    // 单节点连接字符串
  }
}

完整配置（推荐）

使用结构化配置节，支持哨兵、密码、超时、重试等完整参数：

{
  "Redis": {
    "Connection": {
      "ConnectionString": "localhost:6379,abortConnect=false",      // 连接字符串（支持集群逗号分隔）
      "ServiceName": "mymaster",                                    // Sentinel 主服务名（哨兵模式必填）
      "Password": "",                                               // 认证密码（留空表示无密码）
      "ConnectTimeout": 5000,                                       // 连接超时（毫秒）
      "SyncTimeout": 5000,                                          // 同步操作超时（毫秒）
      "AsyncTimeout": 10000,                                        // 异步操作超时（毫秒）
      "AbortOnConnectFail": false,                                  // 连接失败时不中止启动
      "ConnectRetry": 3,                                            // 初始连接重试次数
      "KeepAlive": 60,                                              // TCP KeepAlive 间隔（秒）
      "Retry": {
        "MaxRetries": 3,                                            // 命令级最大重试次数
        "InitialDelayMs": 200,                                      // 首次重试延迟（毫秒）
        "MaxDelayMs": 3000,                                         // 最大重试延迟（毫秒）
        "EnableJitter": true                                        // 启用随机抖动避免惊群
      }
    }
  }
}

配置优先级：Redis:Connection 节 > ConnectionStrings:Redis（向后兼容）

快速开始

注册服务

// 最小化注册 — 自动读取配置并注册所有服务
services.AddRedisClient();

使用 RedisTemplate

public class OrderService
{
    private readonly RedisTemplate _redis;

    public OrderService(RedisTemplate redis)
    {
        _redis = redis;
    }

    public async Task CreateOrderAsync(Order order)
    {
        // Value 操作
        await _redis.OpsForValue().SetAsync($"order:{order.OrderNo}", order, TimeSpan.FromMinutes(30));

        // Hash 操作
        await _redis.OpsForHash().PutAsync($"order:detail:{order.OrderNo}", "status", "Created");

        // 通用操作
        await _redis.ExpireAsync($"order:{order.OrderNo}", TimeSpan.FromHours(24));
    }
}

使用 IRedisConnection（底层操作）

public class RawRedisService
{
    private readonly IRedisConnection _connection;

    public RawRedisService(IRedisConnection connection)
    {
        _connection = connection;
    }

    public async Task<byte[]> GetRawAsync(string key)
    {
        return await _connection.StringGetAsync(Encoding.UTF8.GetBytes(key));
    }
}

分布式锁

基于 Lua 原子脚本实现，支持 await using 自动释放和看门狗自动续期：

public class PaymentService(IDistributedLock @lock)
{
    public async Task PayAsync(string orderNo)
    {
        // await using 自动释放，renewalInterval 启用看门狗自动续期
        await using var handle = await @lock.TryAcquireAsync(
            $"lock:pay:{orderNo}",
            expiry: TimeSpan.FromSeconds(30),            // 锁过期时间
            waitTimeout: TimeSpan.FromSeconds(5),         // 等待获取锁的超时
            renewalInterval: TimeSpan.FromSeconds(10));   // 看门狗续期间隔

        if (!handle.IsAcquired)
            throw new BusinessException("获取锁失败");

        // 业务逻辑...
    }
}

旧版 TryAcquireAsync(key, expiry) + ReleaseAsync(key) 已标记 [Obsolete]，请迁移至 IDistributedLockHandle 模式。

幂等性

基于 Redis 原子操作实现请求幂等性保证，支持结果缓存：

public class OrderService(IDistributedIdempotence idempotence)
{
    public async Task<OrderResult> CreateOrderAsync(string requestId, Order order)
    {
        // 原子标记为处理中，防止重复执行
        if (!await idempotence.TryMarkProcessingAsync(requestId, TimeSpan.FromMinutes(10)))
        {
            // 已有请求在处理，尝试获取缓存结果
            var cached = await idempotence.GetCachedResultAsync(requestId);
            if (cached != null) return JsonSerializer.Deserialize<OrderResult>(cached);
            throw new BusinessException("请求正在处理中");
        }

        try
        {
            var result = await DoCreateOrderAsync(order);
            // 成功后缓存结果
            await idempotence.MarkSuccessAsync(requestId, JsonSerializer.Serialize(result), TimeSpan.FromHours(24));
            return result;
        }
        catch
        {
            // 失败时清理状态，允许重试
            await idempotence.ClearStateAsync(requestId);
            throw;
        }
    }
}

Pub/Sub 消息

基于 IRedisMessageListenerContainer 实现发布/订阅，自动作为 BackgroundService 管理订阅生命周期。

发布消息

await redisTemplate.ConvertAndSendAsync("order.events", new OrderEvent { OrderNo = "001" });

订阅消息

// 实现 IMessageListener 接口
public class OrderEventListener : IMessageListener
{
    public async Task OnMessageAsync(RedisMessage message)
    {
        Console.WriteLine($"Channel={message.Channel}, Body={Encoding.UTF8.GetString(message.Body)}");
    }
}

// 注册监听器（IRedisMessageListenerContainer 由 DI 自动注册为 HostedService）
var container = serviceProvider.GetRequiredService<IRedisMessageListenerContainer>();
container.AddMessageListener(new OrderEventListener(), "order.events");

消息队列（Stream）

基于 Redis Stream 的消息队列，支持延迟投递：

// 发送消息（支持延迟投递）
public class OrderCreatedMessage : IMessage
{
    public string OrderNo { get; set; }
    public decimal Amount { get; set; }
}

var template = serviceProvider.GetRequiredService<RedisTemplate>();
// 延迟 30 秒投递
await ((FreeRedisTemplate)template).SendAsync("order.created", new OrderCreatedMessage
{
    OrderNo = "ORDER001",
    Amount = 100.0
}, delaySeconds: 30);

// 处理消息
template.Handle<OrderCreatedMessage>(async msg =>
{
    Console.WriteLine($"处理订单: {msg.OrderNo}");
    return true;
}, "order.created");

Stream 重构说明

Handle 方法已重构：

• 接受 CancellationToken 参数，支持优雅关闭
• 不再使用静态 CancellationTokenSource，由调用方控制生命周期
• 修复延迟队列 Lua 脚本，确保 ZRANGEBYSCORE → XADD → ZREM 原子转移
• 修复 fieldValues 索引越界问题

CacheManager 缓存管理

对标 Spring CacheManager 的命名缓存管理器：

// 注册（在 AddRedisClient 之后）
services.AddRedisCacheManager();

// 使用 Builder 自定义配置
services.AddRedisCacheManager(config =>
{
    config.EntryTtl = TimeSpan.FromHours(1);          // 默认过期时间
    config.KeyPrefix = "myapp:";                       // Key 前缀
    config.DisableCachingNullValues = false;           // 是否禁用缓存 null 值
});

var manager = serviceProvider.GetRequiredService<RedisCacheManager>();
var cache = manager.GetCache("orders");                // 获取或创建命名缓存
await cache.PutAsync("order:001", orderData, TimeSpan.FromHours(1));
var data = await cache.GetAsync<Order>("order:001");
await cache.EvictAsync("order:001");                   // 逐出指定 key
await cache.ClearAsync();                              // 清空缓存

重试策略

ResilientRedisConnection 装饰器自动包装所有 Redis 操作，提供透明重试：

• 指数退避 — 延迟按 InitialDelayMs × 2^(attempt-1) 递增，不超过 MaxDelayMs
• 随机抖动 — 在退避延迟基础上叠加随机偏移，避免惊群效应
• 可重试异常 — TimeoutException 及名称包含 Connection / Timeout 的异常
• 配置驱动 — 通过 Redis:Connection:Retry 节配置，默认 3 次重试

IRedisConnection 实际注册为 ResilientRedisConnection(FreeRedisConnection)，调用方无感知。

健康检查

RedisHealthCheck 由 AddRedisClient() 自动注册，无需额外配置：

• 执行 SET → GET → DEL 操作测量延迟
• 延迟 < 100ms → Healthy
• 延迟 >= 100ms → Degraded
• 连接失败 → Unhealthy

通过 ASP.NET Core 健康检查端点访问：

app.MapHealthChecks("/health");

Pipeline 批量操作

await _redis.ExecuteInPipelineAsync(pipe =>
{
    pipe.SetString("key1"u8.ToArray(), "value1"u8.ToArray());
    pipe.SetString("key2"u8.ToArray(), "value2"u8.ToArray());
    pipe.SetHash("hash1"u8.ToArray(), "field1"u8.ToArray(), "val"u8.ToArray());
});

核心类

DI 注册详情

AddRedisClient() 注册以下服务：

可选注册（需显式调用）：

依赖

• Galosys.Foundation.Redis（抽象层）
• Galosys.Foundation.Core
• FreeRedis
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.Logging.Abstractions