Galosys.Foundation.StackExchange.Redis 26.5.20.1

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