👁 Image
SAEA.RedisSocket 26.4.23.1

SAEA.RedisSocket - 高性能 Redis 客户端 🚀

👁 NuGet version
👁 License

| 中文版

基于 SAEA.Sockets IOCP 技术的高性能 Redis 客户端，支持 Redis Cluster 集群、Stream、分布式锁等完整功能。

快速导航 🧭

30秒快速开始 ⚡

最快上手方式，只需3步即可操作 Redis：

Step 1: 安装 NuGet 包

dotnet add package SAEA.RedisSocket

Step 2: 连接 Redis（仅需3行代码）

using SAEA.RedisSocket;

var client = new RedisClient("server=127.0.0.1:6379;passwords=123456");
client.Connect();

Step 3: 基础数据操作

var db = client.GetDataBase();

// String 操作
db.Set("name", "SAEA");
var value = db.Get("name"); // 输出: SAEA

// Hash 操作
db.HSet("user:1", "name", "张三");
var name = db.HGet("user:1", "name"); // 输出: 张三

就这么简单！ 🎉 你已经可以开始使用高性能 Redis 客户端了。

核心特性 🎯

架构设计 📐

组件架构图

┌─────────────────────────────────────────────────────────────┐
│ SAEA.RedisSocket 架构 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ RedisClient │ │RedisProducer │ │RedisConsumer │ │
│ │ (客户端) │ │ (生产者) │ │ (消费者) │ │
│ └──────┬───────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ RedisDataBase (数据库操作) │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │
│ │ │ String │ │ Hash │ │ List │ │ Set │ │ │
│ │ └────────┘ └────────┘ └────────┘ └────────┘ │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │
│ │ │ ZSet │ │ GEO │ │ Lock │ │ │
│ │ └────────┘ └────────┘ └────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ RedisConnection (连接管理) │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 单机模式 │ │ Cluster │ │ │
│ │ │ Standalone │ │ 集群模式 │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ SAEA.Sockets (IOCP 通信层) │ │
│ │ ┌────────────┐ ┌────────────┐ │ │
│ │ │ BufferPool │ │ Session │ │ │
│ │ │ 内存池 │ │ 会话管理 │ │ │
│ │ └────────────┘ └────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘

Redis Cluster 工作流程

客户端请求流程:

客户端 ──► RedisClient.Connect()
 │
 ▼
 ┌─────────────────┐
 │ 发送 INFO 命令 │
 │ 检测集群模式 │
 └────────┬────────┘
 │
 ┌────────▼────────┐
 │ IsCluster ? │
 └────────┬────────┘
 │
 ┌─────────┴─────────┐
 │ │
 ▼ ▼
┌──────────────┐ ┌──────────────┐
│ 单机模式 │ │ Cluster模式 │
│ 直连服务器 │ │ 获取槽位表 │
└──────────────┘ └──────┬───────┘
 │
 ▼
 ┌─────────────────┐
 │ 操作 Key │
 │ 计算 Slot │
 └────────┬────────┘
 │
 ▼
 ┌─────────────────┐
 │ 路由到正确节点 │
 │ MOVED/ASK 重定向│
 └────────┬────────┘
 │
 ▼
 返回结果

数据操作流程

命令执行流程:

应用层 ──► db.Set("key", "value")
 │
 ▼
 ┌─────────────────┐
 │ 构建 RESP 协议 │
 │ *3\r\n$3\r\n │
 │ SET\r\n... │
 └────────┬────────┘
 │
 ▼
 ┌─────────────────┐
 │ 发送到 Redis │
 │ (IOCP 异步) │
 └────────┬────────┘
 │
 ▼
 ┌─────────────────┐
 │ 接收响应 │
 │ 解析 RESP │
 └────────┬────────┘
 │
 ▼
 返回结果

应用场景 💡

✅ 适合使用 SAEA.RedisSocket 的场景

场景详细说明

🎮 游戏服务器排行榜

// 使用 ZSet 实现实时排行榜
var db = client.GetDataBase();
db.ZAdd("game:rank", "player1", 1000);
db.ZAdd("game:rank", "player2", 1500);

// 获取 Top 10
var top10 = db.ZRangeWithScores("game:rank", 0, 9);

🛒 秒杀场景分布式锁

var db = client.GetDataBase();
var lockKey = "seckill:product:lock";
var lockValue = Guid.NewGuid().ToString();

if (db.Lock(lockKey, lockValue, 30))
{
 try
 {
 // 扣减库存
 var stock = int.Parse(db.Get("stock"));
 if (stock > 0)
 {
 db.Decrement("stock");
 }
 }
 finally
 {
 db.Unlock(lockKey, lockValue);
 }
}

📡 消息推送 Pub/Sub

var db = client.GetDataBase();

// 订阅频道
db.Subscribe("news", (channel, message) => 
{
 Console.WriteLine($"收到推送: {message}");
});

// 发布消息
db.Publish("news", "新品上架通知");

❌ 不适合的场景

性能对比 📊

与其他 .NET Redis 客户端对比

性能测试数据

💡 测试环境: Intel i7-10700, 32GB RAM, Redis 7.0, .NET 7.0

IOCP 优势说明

传统同步模型:
线程1 ──► 阻塞等待 ──► 响应 ──► 处理
线程2 ──► 阻塞等待 ──► 响应 ──► 处理
线程3 ──► 阻塞等待 ──► 响应 ──► 处理
 (每连接一线程，资源消耗大)

IOCP 异步模型:
单个线程 ──► 发起请求 ──► 继续处理
 ──► 发起请求 ──► 继续处理
 ──► 发起请求 ──► 继续处理
 ▼
 完成端口通知 ──► 处理响应
 (单线程处理多连接，高效利用 CPU)

常见问题 ❓

Q1: 如何选择单机模式还是集群模式？

A: SAEA.RedisSocket 会自动检测，无需手动切换：

var client = new RedisClient("server=127.0.0.1:6379");
client.Connect();

if (client.IsCluster)
{
 Console.WriteLine("集群模式，自动处理 MOVED/ASK 重定向");
}
else
{
 Console.WriteLine("单机模式");
}

集群模式下，框架自动处理：

• 槽位计算与路由
• MOVED 永久重定向
• ASK 临时重定向

Q2: 分布式锁如何保证安全？

A: SAEA.RedisSocket 的分布式锁基于 SETNX 实现，包含以下安全机制：

var db = client.GetDataBase();

// 获取锁（原子操作）
var acquired = db.Lock("resource", "unique_value", 30);

// 释放锁（Lua 脚本保证原子性）
db.Unlock("resource", "unique_value");

安全机制：

• 唯一值标识，防止误解锁
• 超时自动释放，避免死锁
• Lua 脚本保证释放原子性

Q3: 如何处理大量 Key 的遍历？

A: 使用 SCAN 命令安全遍历，避免 KEYS 阻塞：

var db = client.GetDataBase();

// 安全遍历所有 Key
var cursor = 0L;
do
{
 var result = db.Scan(cursor, "user:*", 100);
 cursor = result.Cursor;
 foreach (var key in result.Keys)
 {
 Console.WriteLine(key);
 }
} while (cursor != 0);

Q4: Pipeline 和普通操作有什么区别？

A: Pipeline 将多个命令合并发送，减少网络往返：

// 普通操作：3次网络往返
db.Set("k1", "v1"); // 往返1
db.Set("k2", "v2"); // 往返2
db.Get("k1"); // 往返3

// Pipeline：1次网络往返
var batch = db.CreatedBatch();
batch.Set("k1", "v1");
batch.Set("k2", "v2");
batch.Get("k1");
var results = batch.Execute(); // 只需1次往返

Q5: 如何配置连接超时和重试？

A: 通过连接字符串配置：

var client = new RedisClient(
 "server=127.0.0.1:6379;" +
 "passwords=123456;" +
 "actionTimeout=5000" // 操作超时5秒
);

框架内置自动重连机制，连接断开后自动重试。

Q6: Redis Stream 消费失败如何处理？

A: 使用消费组实现可靠消费：

var consumer = client.GetRedisGroupConsumer(
 "mystream", 
 "mygroup", 
 "consumer1"
);

consumer.Subscribe((messages) => 
{
 foreach (var msg in messages)
 {
 try
 {
 // 处理消息
 ProcessMessage(msg);
 // 成功后自动 ACK
 }
 catch (Exception ex)
 {
 // 处理失败，消息保留在 Pending 列表
 // 可通过 XPENDING 查看未确认消息
 }
 }
});

Q7: 如何监控 Redis 连接状态？

A: 使用内置属性和事件：

var client = new RedisClient("server=127.0.0.1:6379");
client.Connect();

// 检查连接状态
Console.WriteLine($"已连接: {client.IsConnected}");
Console.WriteLine($"集群模式: {client.IsCluster}");

// 获取服务器信息
var info = client.Info();
Console.WriteLine(info);

核心类 🔧

使用示例 📝

连接 Redis

using SAEA.RedisSocket;

// 方式1：连接字符串
var client = new RedisClient("server=127.0.0.1:6379;passwords=123456");

// 方式2：RedisConfig 对象
var config = new RedisConfig("127.0.0.1:6379", "123456", 6000);
var client = new RedisClient(config);

// 方式3：直接参数
var client = new RedisClient("127.0.0.1:6379", "123456", 6000);

// 连接
client.Connect();

// 检查连接状态
Console.WriteLine($"已连接: {client.IsConnected}");
Console.WriteLine($"是否集群: {client.IsCluster}");

String 操作

using SAEA.RedisSocket;

var client = new RedisClient("server=127.0.0.1:6379");
client.Connect();

var db = client.GetDataBase();

// 设置值
db.Set("key", "value");
db.Set("key", "value", 3600); // 设置过期时间（秒）

// 获取值
var value = db.Get("key");

// 批量设置/获取
db.MSet(new Dictionary<string, string> { ["k1"] = "v1", ["k2"] = "v2" });
var values = db.MGet("k1", "k2");

// 自增/自减
db.Increment("counter");
db.IncrementBy("counter", 10);
db.Decrement("counter");

Hash 操作

var db = client.GetDataBase();

// 设置 Hash 字段
db.HSet("user:1", "name", "张三");
db.HSet("user:1", "age", "25");

// 获取 Hash 字段
var name = db.HGet("user:1", "name");

// 批量设置/获取
db.HMSet("user:1", new Dictionary<string, string> { ["name"] = "张三", ["age"] = "25" });
var all = db.HMGet("user:1", "name", "age");
var allFields = db.HGetAll("user:1");

// 字段数量
var count = db.HLen("user:1");

// 删除字段
db.HDel("user:1", "age");

// Hash 字段自增
db.HIncrementBy("user:1", "score", 10);

List 操作

var db = client.GetDataBase();

// 推入元素
db.LPush("list", "item1");
db.RPush("list", "item2");

// 弹出元素
var leftItem = db.LPop("list");
var rightItem = db.RPop("list");

// 获取列表长度
var length = db.LLen("list");

// 获取范围元素
var items = db.LRang("list", 0, -1); // 获取所有

// 获取指定位置元素
var item = db.LIndex("list", 0);

// 阻塞弹出
var popped = db.BLPop("list", 10); // 等待10秒

Set 操作

var db = client.GetDataBase();

// 添加成员
db.SAdd("set", "member1");
db.SAdd("set", "member2");

// 检查成员是否存在
var exists = db.SExists("set", "member1");

// 获取所有成员
var members = db.SMemebers("set");

// 移除成员
db.SRemove("set", "member1");

// 集合操作
var inter = db.SInter("set1", "set2"); // 交集
var union = db.SUnion("set1", "set2"); // 并集
var diff = db.SDiff("set1", "set2"); // 差集

ZSet 操作

var db = client.GetDataBase();

// 添加成员（带分数）
db.ZAdd("zset", "member1", 100);
db.ZAdd("zset", "member2", 200);

// 获取分数
var score = db.ZScore("zset", "member1");

// 获取排名
var rank = db.ZRank("zset", "member1");

// 获取范围成员
var members = db.ZRange("zset", 0, -1);
var membersWithScore = db.ZRangeWithScores("zset", 0, -1);

// 增加分数
db.ZIncrBy("zset", 50, "member1");

Key 操作

var db = client.GetDataBase();

// 删除键
db.Del("key");

// 检查键是否存在
var exists = db.Exists("key");

// 设置过期时间
db.Expire("key", 3600);
db.ExpireAt("key", DateTime.Now.AddHours(1));

// 获取剩余生存时间
var ttl = db.Ttl("key");

// 查找匹配的键
var keys = db.Keys("user:*");

// 重命名
db.Rename("oldkey", "newkey");

分布式锁

using SAEA.RedisSocket;

var client = new RedisClient("server=127.0.0.1:6379");
client.Connect();

// 获取锁
var lockKey = "resource_lock";
var lockValue = Guid.NewGuid().ToString();
var acquired = client.GetDataBase().Lock(lockKey, lockValue, 30);

if (acquired)
{
 try
 {
 // 执行业务逻辑
 Console.WriteLine("锁已获取，执行操作...");
 }
 finally
 {
 // 释放锁
 client.GetDataBase().Unlock(lockKey, lockValue);
 }
}

Pub/Sub 发布订阅

using SAEA.RedisSocket;

var client = new RedisClient("server=127.0.0.1:6379");
client.Connect();

// 发布消息
client.GetDataBase().Publish("channel", "Hello Subscribers!");

// 订阅消息
client.GetDataBase().Subscribe("channel", (channel, message) => 
{
 Console.WriteLine($"收到消息 [{channel}]: {message}");
});

Redis Stream

using SAEA.RedisSocket;

var client = new RedisClient("server=127.0.0.1:6379");
client.Connect();

// 生产者
var producer = client.GetRedisProducer("mystream");
producer.Publish(new Dictionary<string, string> { ["field"] = "value" });

// 消费者
var consumer = client.GetRedisConsumer("mystream", "consumer1");
consumer.Subscribe((messages) => 
{
 foreach (var msg in messages)
 {
 Console.WriteLine($"消息ID: {msg.Id}, 数据: {msg.Data}");
 }
});

// 组消费者（支持负载均衡）
var groupConsumer = client.GetRedisGroupConsumer("mystream", "mygroup", "consumer1");
groupConsumer.Subscribe((messages) => 
{
 // 处理消息后自动 ACK
});

批量操作 (Pipeline)

using SAEA.RedisSocket;

var client = new RedisClient("server=127.0.0.1:6379");
client.Connect();

var batch = client.GetDataBase().CreatedBatch();

// 批量添加命令
batch.Set("key1", "value1");
batch.Set("key2", "value2");
batch.Get("key1");

// 执行批量操作
var results = batch.Execute();

Redis Cluster 支持

using SAEA.RedisSocket;

// 连接集群节点
var client = new RedisClient("server=192.168.1.1:6379;passwords=123456");
client.Connect();

// 自动检测集群
if (client.IsCluster)
{
 Console.WriteLine("当前为 Redis Cluster 模式");
 
 // 获取集群信息
 var clusterInfo = client.ClusterInfoStr();
 
 // 自动重定向处理（MOVED/ASK）
 // 无需手动处理，框架自动完成
}

// 集群管理操作
client.AddSlots(new int[] { 0, 1, 2, 3 });
client.DelSlots(new int[] { 0, 1 });
client.ClusterNodes();

连接字符串格式

server=127.0.0.1:6379;passwords=your_password;actionTimeout=6000

依赖项

相关项目

• WebRedisManager - 基于 SAEA.RedisSocket 的 Redis 管理工具

更多资源

• GitHub 仓库
• NuGet 包
• 作者博客

许可证

Apache License 2.0