TJC.Cyclops.Redis 2026.4.14.2

🚀 Cyclops.Redis

📝 项目概述

Cyclops.Redis 是 Cyclops.Framework 中的Redis客户端集成专家，为您的应用程序提供强大而灵活的 Redis 操作封装！ 🎯

我们精心设计的组件支持多种 Redis 部署模式（单实例、哨兵、集群），并封装了缓存、队列、分布式锁、发布订阅等常用功能，简化了 Redis 在 .NET 应用程序中的使用。无论是构建高性能缓存系统，还是实现分布式队列，Cyclops.Redis都能为您提供出色的支持。

✨ 为什么选择 Cyclops.Redis？

• 多种部署模式：支持单实例、哨兵和集群三种部署模式
• 功能丰富：封装了缓存、队列、分布式锁、发布订阅等常用功能
• 易于集成：与.NET依赖注入系统无缝集成
• 高性能：基于StackExchange.Redis实现高效的连接池管理
• 可靠性：提供安全的分布式锁实现和故障处理
• 灵活性：丰富的配置选项，适应不同场景需求

🎯 核心功能模块

🔌 Redis 连接管理

• 多种部署模式：支持单实例（Instance）、哨兵（Sentinel）和集群（Cluster）三种部署模式
• 连接池管理：基于 StackExchange.Redis 实现高效的连接池管理
• 灵活配置：提供丰富的配置选项，支持密码认证、连接超时、重试策略等
• 故障处理：内置连接异常处理和自动重连机制

// 连接管理核心实现位于 RedisClient 类

📦 缓存操作

• 统一接口：实现 IServiceCache 接口，提供标准化的缓存操作
• 自动序列化：自动处理对象的 JSON 序列化与反序列化
• 过期管理：支持设置缓存过期时间和检查过期状态
• 哈希存储：使用 Redis 哈希结构存储缓存数据，便于管理
• 批量操作：支持批量设置和获取缓存

// RedisCache 类提供完整的缓存功能实现

📋 Redis 队列

• 高性能队列：基于 Redis List 实现的高性能分布式队列
• 状态跟踪：支持队列任务的状态管理（未开始、处理中等）
• 异步操作：提供同步和异步的队列操作方法
• 超时管理：支持设置队列数据的过期时间
• 优先级队列：支持基于优先级的队列操作

// RedisQueue<T> 类实现了类型化的队列操作

🔒 分布式锁

• 安全实现：基于 SET NX PX 命令和 Lua 脚本实现的安全分布式锁
• 锁续期：支持锁的续期操作，防止长时间任务执行期间锁过期
• 智能重试：支持配置等待超时和重试间隔
• 安全释放：使用 Lua 脚本确保只有锁的持有者才能释放锁
• 可重入锁：支持可重入锁机制

// RedisDistributedLock 类实现了安全的分布式锁机制

📡 Redis 流（Stream）

• 生产者-消费者：提供 Redis Stream 的生产者和消费者封装
• 消息分组：支持基于消费者组的消息处理
• 持久化：利用 Redis Stream 的持久化特性
• 消息回溯：支持消息的确认和回溯机制
• 消息过滤：支持基于条件的消息过滤

// RedisProducer 和 RedisConsumer 类实现了流操作

📢 发布订阅系统

• 发布-订阅模式：提供 Redis 发布订阅的完整封装
• 多频道支持：支持多频道的发布和订阅
• 键过期监听：提供键过期事件的监听机制
• 消息广播：支持向多个订阅者广播消息

// RedisPublisher 和 RedisSubscriber 类实现了发布订阅功能
// RedisKeyExpireListener 类实现了键过期监听

🛠️ 技术栈

• .NET 8.0：基于最新的 .NET 平台构建，利用最新的.NET特性
• StackExchange.Redis：高性能的 Redis 客户端库，提供高效的连接管理
• JSON 序列化：内置 JSON 序列化支持，自动处理对象序列化
• Lua 脚本：用于实现原子操作（如分布式锁的安全释放）

📦 环境依赖

• .NET 8.0 或更高版本
• Redis 服务器：支持 Redis 3.2 及以上版本（使用流功能需要 Redis 5.0+）
• 支持的平台：Windows、Linux、macOS
• IDE推荐：Visual Studio 2022、Visual Studio Code

🚀 安装与配置

🔍 安装方式

NuGet包管理器

Install-Package TJC.Cyclops.Redis

.NET CLI

dotnet add package TJC.Cyclops.Redis

PackageReference

<PackageReference Include="TJC.Cyclops.Redis" Version="1.0.0" />

⚙️ 配置 Redis 连接

配置文件设置

在应用程序配置文件中添加 Redis 连接配置：

{
  "RedisOptions": {
    "Type": "Instance", // 可选值：Instance, Sentinel, Cluster
    "Masters": "localhost:6379",
    "Slaves": "localhost:6380", // 可选，仅 Instance 模式使用
    "Password": "your_password", // 可选
    "DefaultDatabase": 0,
    "ConnectTimeout": 5000,
    "CommandTimeout": 5000,
    "ConnectRetry": 3,
    "KeepAlive": 60,
    "BusyRetry": 3,
    "BusyRetryWaitMS": 500,
    "AllowAdmin": false,
    "ServiceName": "mymaster" // 可选，仅 Sentinel 模式使用
  }
}

依赖注入配置

在ASP.NET Core应用中，通过依赖注入进行配置：

// 在Program.cs或Startup.cs中
using Cyclops.Redis;

var builder = WebApplication.CreateBuilder(args);

// 读取Redis配置
var redisOptions = new RedisOptions();
builder.Configuration.GetSection("RedisOptions").Bind(redisOptions);

// 添加Cyclops.Redis服务
builder.Services.AddCyclopsRedis(redisOptions);

var app = builder.Build();

// ...

app.Run();

🎯 配置建议

• 连接超时：根据网络环境设置合理的连接超时时间
• 重试策略：配置适当的重试次数和间隔，提高可靠性
• 密码安全：将密码存储在安全的配置管理系统中
• 数据库选择：根据应用需求选择合适的Redis数据库
• 部署模式：根据应用规模选择合适的Redis部署模式

📝 代码示例

📦 基本使用 - 缓存操作

以下示例展示了如何使用 Cyclops.Redis 进行缓存操作：

// 创建缓存实例
var cache = new RedisCache();

// 设置缓存
cache.Set("user:1", new UserInfo { Id = 1, Name = "张三" });

// 获取缓存
var user = cache.Get<UserInfo>("user:1");

// 删除缓存
cache.Del("user:1");

// 检查缓存是否存在
var exists = cache.ContainsKey("user:1");

📋 Redis 队列操作

以下示例展示了如何使用 Cyclops.Redis 进行队列操作：

// 获取 Redis 客户端
var redis = new CyclopsRedis();

// 创建队列实例
var queue = redis.GetRedisQueue<OrderInfo>("order_queue");

// 入队
var order = new OrderInfo { OrderId = "ORD123", Amount = 100.5 };
var queueId = await queue.EnqueueAsync(order);

// 出队
string key;
var dequeuedOrder = await queue.DequeueAsync(out key);

🔒 分布式锁使用

以下示例展示了如何使用 Cyclops.Redis 实现分布式锁：

// 获取 Redis 客户端
var redis = new CyclopsRedis();

// 创建分布式锁
var distributedLock = redis.CreateDistributedLock("lock:order:123", TimeSpan.FromSeconds(30));

// 尝试获取锁，最多等待5秒，每50ms重试一次
if (await distributedLock.AcquireAsync(TimeSpan.FromSeconds(5), TimeSpan.FromMilliseconds(50)))
{
    try
    {
        // 执行需要同步的操作
        Console.WriteLine("获取锁成功，执行操作...");
        await Task.Delay(1000);
    }
    finally
    {
        // 释放锁
        await distributedLock.ReleaseAsync();
    }
}
else
{
    Console.WriteLine("获取锁失败");
}

📢 Redis 发布订阅

以下示例展示了如何使用 Cyclops.Redis 实现发布订阅功能：

// 获取 Redis 客户端
var redis = new CyclopsRedis();

// 创建订阅者
var subscriber = redis.GetSubscriber("notification_channel");

// 订阅消息
await subscriber.SubscribeAsync((channel, message) => {
    Console.WriteLine($"收到消息: {message}");
});

// 创建发布者
var publisher = redis.GetPublisher("notification_channel");

// 发布消息
await publisher.PublishAsync("Hello, Redis Pub/Sub!");

📡 Redis 流操作

以下示例展示了如何使用 Cyclops.Redis 实现流操作：

// 获取 Redis 客户端
var redis = new CyclopsRedis();

// 创建生产者
var producer = redis.GetRedisProducer("order_stream");

// 发送消息
await producer.ProduceAsync(new Dictionary<string, string>() {
    { "orderId", "ORD456" },
    { "amount", "200.0" }
});

// 创建消费者
var consumer = redis.GetRedisConsumer("order_stream", 0, "order_group");

// 消费消息
var messages = await consumer.ConsumeAsync(count: 10);
foreach (var message in messages)
{
    Console.WriteLine($"消费消息: {message.Id} - {message.Data}");
    // 确认消息
    await consumer.AcknowledgeAsync(message.Id);
}

⚡ 高级功能

🔌 多种连接模式

以下示例展示了如何配置不同的Redis连接模式：

// 哨兵模式配置示例
var sentinelOptions = new RedisOptions {
    Type = EnumRedisType.Sentinel,
    Masters = "sentinel1:26379,sentinel2:26379",
    ServiceName = "mymaster"
};

// 集群模式配置示例
var clusterOptions = new RedisOptions {
    Type = EnumRedisType.Cluster,
    Masters = "node1:6379,node2:6379,node3:6379"
};

🔔 键过期监听

以下示例展示了如何使用 Cyclops.Redis 监听键过期事件：

// 获取键过期监听器
var listener = redis.GetKeyExpireListener();

// 订阅键过期事件
await listener.SubscribeAsync((key) => {
    Console.WriteLine($"键过期: {key}");
    // 执行清理或其他操作
});

📦 单例模式使用

以下示例展示了如何使用 Cyclops.Redis 的单例模式：

// 使用单例实例
var cache = RedisCache.Instance;

// 或使用 CyclopsRedis 单例
var redis = CyclopsRedis.Instance;

🚀 性能优化建议

• 合理设置连接池：根据并发量调整连接池大小，避免连接过多或过少
• 优先使用异步操作：使用异步方法提高并发性能，避免阻塞主线程
• 设置合理的过期时间：为缓存数据设置适当的过期时间，避免 Redis 内存无限增长
• 使用管道和事务：批量操作时使用管道或事务，减少网络往返次数
• 统一键命名规范：使用清晰、一致的键命名规范，便于管理和查询
• 优化数据结构：根据数据特点选择合适的 Redis 数据结构
• 监控内存使用：定期监控 Redis 内存使用情况，及时调整策略
• 使用 Redis Cluster：对于大规模应用，考虑使用 Redis Cluster 提高可用性和性能

🔧 故障排查

• 连接问题：检查 Redis 服务器是否运行，网络是否可达，密码是否正确
• 超时问题：调整连接超时和命令超时设置，检查网络延迟
• 内存问题：监控 Redis 内存使用情况，设置合理的 maxmemory 策略
• 分布式锁争用：调整锁的过期时间和重试策略，避免长时间占用锁
• 性能问题：检查 Redis 服务器性能，考虑使用 Redis Cluster 或哨兵模式
• 序列化问题：确保缓存对象可序列化，检查 JSON 序列化配置
• 键冲突：使用唯一的键命名空间，避免键冲突
• 版本兼容性：确保 Redis 服务器版本与使用的功能兼容（如流功能需要 Redis 5.0+）

🤝 贡献者

我们欢迎社区贡献！如果您有任何改进建议或功能需求，欢迎提交PR或Issue。

• yswenli：核心开发者

📋 版本信息

• 当前版本：
• 作者：yswenli
• 描述：企服版框架中Redis客户端集成组件
• 更新频率：定期更新，持续改进

📄 许可证

保留所有权利

🎉 结语

Cyclops.Redis 致力于为您的应用程序提供强大、灵活的 Redis 操作能力。我们相信，通过简化 Redis 的使用复杂性，您可以更专注于业务逻辑的实现，构建出更高效、更可靠的分布式应用。

如果您有任何问题或建议，欢迎与我们联系！让我们一起构建更好的Redis集成解决方案！ 🚀