BugFree.CSRedisCore.Extension 1.0.250817.1009

BugFree.CSRedisCore.Extension

基于 CSRedisCore 的强类型扩展，提供 List/Hash/Set/SortedSet/GEO 的便捷包装，以及多种 Redis 队列（简单队列、可靠队列、延迟队列、Stream 消费组）。

特性

• 强类型集合包装：List、Hash、Set、SortedSet
• GEO 常用操作封装：Add/GeoPos/Dist/GeoHash/Radius/RadiusByMember
• 队列套件：
  • 简单队列 RedisQueue（List，无 ACK）
  • 可靠队列 RedisReliableQueue（main+processing，ACK/NACK）
  • 延迟队列 RedisDelayQueue（ZSet 到期 + processing，ACK/NACK）
  • Stream 队列 RedisStream（消费组，ACK）
• 统一的序列化/反序列化（System.Text.Json；string 原样存储）
• 多目标框架：net5.0 / 6.0 / 7.0 / 8.0 / 9.0

依赖：

• CSRedisCore 3.8.804

安装

• 作为项目引用使用（推荐本仓库内同时开发）：
  • 在你的 .csproj 中添加 ProjectReference 指向本项目输出
• 或打包成 NuGet 后在你的项目中引用

说明：包名/发布源视你的实际发布而定，这里不固定给出公共源地址。

快速开始

1) 初始化 CSRedisClient

using CSRedis;
var redis = new CSRedisClient("127.0.0.1:6379,password=,defaultDatabase=0,poolsize=50,ssl=false,writeBuffer=10240");

2) 集合包装（List/Hash/Set/SortedSet）

using BugFree.CSRedisCore.Extension;
using BugFree.CSRedisCore.Extension.Collection;

// List
var list = redis.GetList<string>("demo:list");
list.Add("a");
list.Add("b");
var first = list[0];

// Hash
var dict = redis.GetDictionary<int>("demo:hash");
dict["age"] = 18;
var hasAge = dict.ContainsKey("age");

// Set
var set = redis.GetSet<string>("demo:set");
set.Add("x");
var exists = set.Contains("x");

// SortedSet
var zset = redis.GetSortedSet<string>("demo:zset");
zset.Add("alice", 100);
zset.Add(new[]{"bob","carl"}, 80);
var score = zset.GetScore("alice");

注意：RedisList.Contains/IndexOf 为避免 O(N) 长扫描，当元素数量 > 1000 会抛出不支持异常。

3) GEO 封装

var geo = redis.GetGeo<string>("demo:geo");
// 添加点（member, lng, lat）
geo.Add("A", 116.397128m, 39.916527m);
geo.Add("B", 121.473701m, 31.230416m);

// 距离（单位：m/km/ft/mi）
var dist = geo.Dist("A", "B", CSRedis.GeoUnit.km);

// 位置与哈希
var pos = geo.GeoPos("A", "B"); // (lng, lat)?[] 与入参顺序一一对应
var hash = geo.GeoHash("A", "B");

// 半径查询：按坐标或按成员
var members1 = geo.Radius(116.40m, 39.91m, 5m, CSRedis.GeoUnit.km, count: 10, asc: true);
var members2 = geo.RadiusByMember("A", 5m, CSRedis.GeoUnit.km, count: 10, asc: true);

4) 队列套件

所有队列都在命名空间 BugFree.CSRedisCore.Extension 下，统一提供：

• Add(params T[] values) 入队
• TryDequeue(out MessageContext<T>? msg, TimeSpan? blockTimeout = null, CancellationToken cancel = default) 出队
• ConsumeAsync(Func<MessageContext<T>, CancellationToken, Task<bool>> handler, ConsumptionOptions? options = null) 简单消费循环

using BugFree.CSRedisCore.Extension;

// 简单队列（无 ACK）
var q = redis.GetQueue<string>("demo:q");
q.Add("job1", "job2");
if (q.TryDequeue(out var msg))
{
	Console.WriteLine(msg!.Value);
}

// 可靠队列（ACK/NACK）
var rq = redis.GetReliableQueue<string>("demo:rq");
rq.Add("job");
if (rq.TryDequeue(out var m))
{
	try
	{
		// 处理...
		rq.Ack(m!);
	}
	catch
	{
		rq.Nack(m!, requeue: true);
	}
}

// 延迟队列（ZSet 到期 + processing）
var dq = redis.GetDelayQueue<string>("demo:dq", defaultDelay: TimeSpan.FromSeconds(3));
dq.Add("later");
// 3s 后到期可取到
if (dq.TryDequeue(out var dmsg, TimeSpan.FromSeconds(5)))
{
	// 处理成功
	dq.Ack(dmsg!);
}

// Stream 消费组队列
var sq = redis.GetStream<string>("demo:stream", group: "g1", consumer: "c1");
// 入队：使用 类内 Add（字段名固定为 value）
sq.Add("s1");
// 消费：TryDequeue + Ack
if (sq.TryDequeue(out var smsg, TimeSpan.FromSeconds(1)))
{
	// 处理...
	sq.Ack(smsg!);
}

提示：ConsumeAsync 提供了最简消费循环；可靠/延迟/Stream 模式下返回 true 通常表示处理成功（将 Ack），异常或 false 则 Nack 或忽略。

注意事项

• 序列化：非 string 类型使用 System.Text.Json；string 按原文存储。
• 可空/性能：部分方法（如 List.Contains/IndexOf）为避免 O(N) 大扫描设置了保护阈值。
• GEO 返回：半径查询返回成员数组（string[]），GeoPos 返回与入参顺序一一对应的经纬度。
• 版本兼容：多目标框架（net5–net9）；具体以 csproj 为准。

许可证与交流

• 许可证：见仓库 LICENSE
• 反馈与建议：ligengrong@hotmail.com