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