Galosys.Foundation.StackExchange.Redis 26.7.20.2

Galosys.Foundation.StackExchange.Redis

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

简介

Galosys.Foundation.StackExchange.Redis 基于 StackExchange.Redis 提供完整的 IRedisConnection 实现，包括分布式缓存、分布式锁、幂等性控制、Pub/Sub 消息、自动重试和健康检查，适用于 ASP.NET Core 项目。

特性

• IRedisConnection 实现 — 完整实现 9 大命令组（Key、String、Hash、List、Set、SortedSet、Geo、Stream、Script）
• Pipeline 支持 — 批量命令管道执行
• 分布式缓存 — 集成 StackExchangeRedisCache（IDistributedCache）
• 分布式锁 — Lua 原子脚本 + 看门狗自动续期
• 幂等性控制 — 请求去重、结果缓存、状态管理
• Pub/Sub 消息 — 发布订阅、托管监听容器
• 自动重试 — 指数退避 + 随机抖动装饰器
• 健康检查 — PING 探测，自动注册
• 连接日志 — 连接断开/恢复事件自动记录
• ConnectionMultiplexer 管理 — 自动创建和管理连接

安装

dotnet add package Galosys.Foundation.StackExchange.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,                                             // 保持活跃间隔（秒）
      "Retry": {
        "MaxRetries": 3,                                           // 命令失败最大重试次数
        "InitialDelayMs": 200,                                     // 首次重试延迟（毫秒）
        "MaxDelayMs": 3000,                                        // 最大重试延迟（毫秒）
        "EnableJitter": true                                       // 启用随机抖动，防止惊群
      }
    }
  }
}

配置优先级：Redis:Connection > ConnectionStrings:Redis，向后兼容旧配置格式。

快速开始

注册服务

// 最小化配置 — 从 IConfiguration 读取
services.AddStackExchangeRedis(Configuration);

使用 RedisTemplate

public class CacheService
{
    private readonly RedisTemplate _redis;

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

    public async Task SetOrderAsync(string orderNo, Order order)
    {
        await _redis.OpsForValue().SetAsync($"order:{orderNo}", order, TimeSpan.FromMinutes(30));
    }

    public async Task<Order> GetOrderAsync(string orderNo)
    {
        return await _redis.OpsForValue().GetAsync<Order>($"order:{orderNo}");
    }

    public async Task<bool> DeleteOrderAsync(string orderNo)
    {
        return await _redis.DeleteAsync($"order:{orderNo}");
    }
}

使用 IRedisConnection（底层操作）

public class RawRedisService
{
    private readonly IRedisConnection _connection;

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

    public async Task SetRawAsync(string key, byte[] value)
    {
        await _connection.StringSetAsync(Encoding.UTF8.GetBytes(key), value);
    }
}

使用 IDistributedCache

public class DistributedCacheService
{
    private readonly IDistributedCache _cache;

    public DistributedCacheService(IDistributedCache cache)
    {
        _cache = cache;
    }

    public async Task SetAsync(string key, string value)
    {
        await _cache.SetStringAsync(key, value, new DistributedCacheEntryOptions
        {
            AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(30)
        });
    }
}

各数据结构操作

// Hash
await _redis.OpsForHash().PutAsync("user:001", "name", "张三");
await _redis.OpsForHash().PutAsync("user:001", "profile", new { Age = 25 });
var name = await _redis.OpsForHash().GetAsync<string>("user:001", "name");

// List
await _redis.OpsForList().RightPushAsync("task:queue", new TaskItem { Id = 1 });
var task = await _redis.OpsForList().LeftPopAsync<TaskItem>("task:queue");

// Set
await _redis.OpsForSet().AddAsync("tags:product:001", "电子产品", "手机");
var tags = await _redis.OpsForSet().MembersAsync<string>("tags:product:001");

// SortedSet
await _redis.OpsForZSet().AddAsync("leaderboard", "player:001", 9500);
var top10 = await _redis.OpsForZSet().ReverseRangeAsync<string>("leaderboard", 0, 9);

// Geo
await _redis.OpsForGeo().AddAsync("locations", 116.397, 39.908, "北京天安门");
var nearby = await _redis.OpsForGeo().RadiusAsync("locations", 116.397, 39.908, 10, GeoUnit.Kilometers);

// Stream
var msgId = await _redis.OpsForStream().AddAsync("events", new Dictionary<string, string> { ["type"] = "order" });
await _redis.OpsForStream().CreateConsumerGroupAsync("events", "my-group");
var messages = await _redis.OpsForStream().ReadGroupAsync("events", "my-group", "consumer-1", count: 10);

分布式锁

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

public class PaymentService(IDistributedLock @lock)
{
    public async Task PayAsync(string orderNo)
    {
        // 尝试获取锁，支持等待超时和自动续期
        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("获取锁失败");

        // 业务逻辑...
    }
}

幂等性控制

防止重复请求，自动缓存成功结果：

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 消息

发布消息

// 使用 RedisTemplate 发布
await redisTemplate.ConvertAndSendAsync("order.events", new OrderEvent { OrderNo = "001" });

订阅消息

// 实现消息监听器
public class OrderEventListener : IMessageListener
{
    public async Task OnMessageAsync(RedisMessage message)
    {
        Console.WriteLine($"Channel={message.Channel}");
    }
}

// 注册监听器
var container = serviceProvider.GetRequiredService<IRedisMessageListenerContainer>();
container.AddMessageListener(new OrderEventListener(), "order.events");

重试策略

通过 ResilientRedisConnection 装饰器自动为所有 Redis 命令提供重试能力：

• 指数退避 — 每次重试延迟翻倍：InitialDelayMs × 2^(attempt-1)
• 随机抖动 — 在延迟基础上叠加随机值，防止惊群效应
• 可重试异常 — TimeoutException、连接异常等自动重试
• 透明代理 — IRedisConnection 接口不变，业务代码无需修改

配置项参见上方 Retry 节点。

健康检查

注册服务后自动注册基于 PING 的健康检查：

services.AddStackExchangeRedis(Configuration);

// 自动注册，无需额外配置
builder.Services.AddHealthChecks()
    .AddCheck<RedisHealthCheck>("redis");

核心类

DI 注册详情

AddStackExchangeRedis(IConfiguration) 注册以下服务：

与 FreeRedis 实现的差异

依赖

• Galosys.Foundation.Redis（抽象层）
• Galosys.Foundation.Core
• StackExchange.Redis
• Microsoft.Extensions.Caching.StackExchangeRedis
• Microsoft.Extensions.Configuration
• Microsoft.Extensions.DependencyInjection