NewLife.Redis
High performance redis client, support NETCore/. NET4. 0/. NET4. 5. It is specially optimized for big data and message queue. The average daily consumption of online single application is 10 billion. 高性能Redis客户端，支持.NETCore/.NET4.0/.NET4.5，为大数据与消息队列而特别优化，线上单应用日均100亿调用量
Install / Use
/learn @NewLifeX/NewLife.RedisREADME
NewLife.Redis - 高性能 Redis 客户端组件
[English]
NewLife.Redis 是新生命团队打造的高性能 / 高吞吐 / 易集成的 .NET Redis 客户端组件。自 2017 年起在多个千万 / 百亿级数据与高并发生产平台稳定运行，经受日均 80+ 亿次命令调用考验。
📖 完整文档：需求文档 | 架构文档 | 竞品分析 | Garnet 兼容性
目录
- NewLife.Redis - 高性能 Redis 客户端组件
产品介绍
NewLife.Redis 为 .NET 开发者提供对 Redis 全生命周期的访问能力：
- 协议完整：实现 RESP2 协议，覆盖 Redis 2.8 ～ 7.x 全版本主流命令，支持 String / List / Hash / Set / Sorted Set / Stream / Geo / HyperLogLog 所有数据结构。
- 消息队列：内置简单队列、可靠队列（RPOPLPUSH + Ack 语义）、延迟队列、Stream 多消费组队列，开箱即用，无需重复造轮子。
- 集群高可用：支持 Standalone / 主从复制 / Sentinel 哨兵 / Cluster 原生集群，自动故障切换。
- 云厂商适配：针对阿里云 KVStore / 腾讯云 Redis / 华为云 DCS 提供专项配置说明与适配，覆盖代理模式、ACL 认证、SSL 加密、特殊认证格式等差异。
- 兼容实现：自动识别 Microsoft Garnet、kvrocks 等 Redis 兼容实现，功能不支持时优雅降级并提供明确替代方案。
- 宽框架支持：一个包覆盖 .NET Framework 4.5 ～ .NET 10+，适配工控、政务、IoT 等遗留场景。
核心特性
- 经大规模生产验证：200+ Redis 实例，日峰值 1 亿+ 业务对象写入 / 80+ 亿命令调用
- 低延迟：单次 Get/Set 往返 200～600µs（含网络）
- 高吞吐：内置连接池（最大 100,000 并发）+ 高效同步 RESP 协议解析 + 可选自动管道合并
- 自动重试与多地址故障切换：Server 支持逗号分隔多节点，网络异常快速切换，默认 10 秒屏蔽窗口
- 丰富高级结构：List / Hash / Set / SortedSet / Stack / Geo / HyperLogLog / Stream
- 多种消息队列范式：简单 / 可靠 / 延迟 / Stream / 多消费组
- 可插拔编码器：默认 JSON，可扩展二进制序列化
- APM 追踪：支持
ITracer链路追踪 +PerfCounter性能计数器 - 强命名 + 多目标框架：net45 / net461 / netstandard2.0 / netstandard2.1 / (扩展包含 netcoreapp3.1 → net10)
- 零外部重量级依赖，充分复用 NewLife 生态（日志、配置、序列化、安全）
Redis 协议与版本支持
RESP 协议支持
| 协议 | 状态 | 说明 | |------|------|------| | RESP2 | ✅ 完整支持 | 简单字符串 / 错误 / 整数 / 批量字符串 / 数组 | | RESP3 | 🔄 规划中 | Map / Set / Double 类型，需 HELLO 握手协商 |
Redis 版本特性支持
| Redis 版本 | 主要特性 | 状态 | |-----------|---------|------| | 2.8 | 基础命令、SCAN、HyperLogLog、Pub/Sub | ✅ 完整支持 | | 3.0 | Cluster 原生集群、CRC16 分片路由 | ✅ 完整支持 | | 3.2 | GEO 地理信息 | ✅ 完整支持 | | 4.0 | UNLINK 异步删除、MODULE | 🔄 部分支持 | | 5.0 | Stream 数据结构（XADD/XREAD/XGROUP/XACK 全套）| ✅ 完整支持 | | 6.0 | ACL 访问控制、TLS/SSL、LMOVE、RESET | ✅ 完整支持 | | 6.2 | COPY、GETDEL、GETEX、GEOSEARCH | ✅ 主要命令支持 | | 7.0 | Functions（FCALL）、LMPOP/ZMPOP、分片 Pub/Sub | 🔄 规划中 | | 7.2 | SSUBSCRIBE / SPUBLISH | 🔄 规划中 |
架构与模块划分
┌─────────────────────────────────────────────────────────────────┐
│ 应用层 │
│ ASP.NET Core / Console / WinForms / IoT / Worker Service │
└──────────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────────▼──────────────────────────────────┐
│ 扩展集成层 (NewLife.Redis.Extensions) │
│ IDistributedCache · IDataProtection · AddRedisCaching DI │
└──────────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────────▼──────────────────────────────────┐
│ 高级功能层 (FullRedis) │
│ RedisList<T> · RedisHash<T> · RedisSet<T> · RedisSortedSet<T> │
│ RedisStack<T> · RedisGeo · HyperLogLog · PrefixedRedis │
│ RedisQueue<T> · RedisReliableQueue<T> · RedisDelayQueue<T> │
│ RedisStream<T> · PubSub · RedisEventBus │
│ RedisCluster · RedisSentinel · RedisReplication │
└──────────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────────▼──────────────────────────────────┐
│ 核心客户端层 (Redis) │
│ 连接池 ObjectPool<RedisClient>（Min=10, Max=100000） │
│ 多节点切换 · Pipeline 管理 · 编码器 · 配置解析 │
└──────────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────────▼──────────────────────────────────┐
│ 协议通信层 (RedisClient) │
│ TCP/TLS 连接 · RESP2 编解码 · ArrayPool<byte> 缓冲区 │
└──────────────────────────────┬──────────────────────────────────┘
│ TCP/TLS
┌──────────────────────────────▼──────────────────────────────────┐
│ Redis Server / Garnet / kvrocks / 阿里云 / 腾讯云 / 华为云 │
└─────────────────────────────────────────────────────────────────┘
关键类说明：
| 类 | 职责 |
|----|------|
| Redis | 核心客户端：连接池、多节点切换、Pipeline、配置管理 |
| FullRedis | 增强客户端：集群路由、键前缀、数据结构工厂方法 |
| RedisClient | RESP 协议单元：TCP 连接、命令编解码（内部，池化管理）|
| RedisList<T> 等 | 泛型数据结构封装，统一编码策略 |
| RedisReliableQueue<T> | 可靠消息队列（RPOPLPUSH + Ack 确认）|
| RedisStream<T> | Stream 流队列（Redis 5.0+，消费组模式）|
| IPacketEncoder | 可插拔编解码策略 |
安装与快速开始
# 稳定版
dotnet add package NewLife.Redis
# ASP.NET Core 扩展
dotnet add package NewLife.Redis.Extensions
# 开发版（含预发布）
dotnet add package NewLife.Redis --prerelease
推荐单例，线程安全，全程复用：
using NewLife.Caching;
using NewLife.Log;
XTrace.UseConsole();
var rds = new FullRedis("127.0.0.1:6379", "password", 0)
{
Log = XTrace.Log, // 可选：组件日志
AutoPipeline = 100, // 可选：命令数达到 100 自动提交管道
};
// 写入对象（自动 JSON 序列化）
rds.Set("user:1", new { Name = "Alice", Age = 30 }, expire: 3600);
// 读取（自动反序列化）
var name = rds.Get<String>("user:1");
Console.WriteLine(name);
连接字符串模式（推荐配置中心）：
var rds = FullRedis.Create("server=127.0.0.1:6379;password=pass;db=0;timeout=3000");
基础用法
// 写入 / 读取
rds.Set("k1", 123, expire: 600);
var v = rds.Get<Int32>("k1");
// 仅在不存在时写入
var ok = rds.Add("k2", "init");
// 替换并返回旧值
var old = rds.Replace("k2", "new");
// 计数器
rds.Increment("counter", 1);
rds.Decrement("counter", 2);
// 过期管理
rds.SetExpire("k1", TimeSpan.FromMinutes(10));
var ttl = rds.GetExpire("k1");
// 批量读写
rds.SetAll(new Dictionary<String, Object> { ["a"] = 1, ["b"] = 2 }, expire: 300);
var dict = rds.GetAll<Int32>(["a", "b"]);
// 键前缀（PrefixedRedis）
var scoped = rds.GetPrefixed("myapp:");
scoped.Set("user", "Alice"); // 实际 key 为 myapp:user
数据结构操作
List（列表）
var list = rds.GetList<String>("queue:demo");
list.Add("job1");
list.Add("job2");
var first = list[0];
var popped = list.RightPop();
Hash（哈希）
var hash = rds.GetDictionary<String>("user:1001");
hash["Name"] = "Alice";
hash["Email"] = "alice@example.com";
var name = hash["Name"];
var all = hash.GetAll();
Set（集合）/ SortedSet（有序集合）
var set = rds.GetSet<String>("tags");
set.Add("redis");
set.Add("cache");
var contains = set.Contains("redis");
var zset = rds.GetSortedSet<String>("leaderboard");
zset.Add("Player1", 100.0);
zset.Add("Player2", 95.5);
var top3 = zset.GetByRank(0, 2);
Stack（栈）
var stack = rds.GetStack<String>("undo:ops");
stack.Push("op1");
stack.Push("op2");
var last = stack.Pop(); // "op2"
Geo（地理信息）
var geo = rds.GetGeo("locations");
geo.Add("Beijing", 116.4074, 39.9042);
geo.Add("Shanghai", 121.4737, 31.2304);
var dist = geo.GetDistance("Beijing", "Shanghai", "km");
var nearby = geo.Search("Beijing", 500, "km");
HyperLogLog（基数统计）
var hll = rds.GetHyperLogLog("uv:today");
hll.Add("user1", "user2", "user3");
var count = hll.Count; // 近似基数
hll.Merge("uv:yesterday");
注意：基础
Redis实例仅支持 KV 操作，高级集合请使用FullRedis。
管道 Pipeline 与自动合并
Pipeline 可显著降低网络往返（RTT），提升批量操作吞吐：
// 显式管道
rds.StartPipeline();
for (var i = 0; i < 1000; i++) rds.Set($"p:{i}", i);
var results = rds.StopPipeline(true);
自动模式（推荐生产使用）：
rds.AutoPipeline = 100; // 写操作达到 100 条自动提交
rds.FullPipeline = true; // 读写操作均进入管道（吞吐优先场景）
消息队列
简单队列
var queue = rds.GetQueue<OrderMsg>("orders");
// 生产者
queue.Add(new OrderMsg { OrderId = "12345", Amount = 99.9m });
// 消费者（阻塞等待，timeout=0 永久阻塞）
var msg = queue.TakeOne(timeout: 30);
可靠队列（至少一次语义）
var queue = rds.GetReliableQueue<OrderMsg>("orders");
// 生产
queue.Add(new OrderMsg { OrderId = "12345" });
// 消费 + 确认
var msg = queue.TakeOne(timeout: 30);
if (msg != null)
{
// 处理消息...
queue.Acknowledge(msg); // 确认消费，从 Ack 队列移除
}
// 若进程崩溃未确认，60s 后消息自动回滚到主队列
延迟队列
var delay = rds.GetDelayQueue<OrderMsg>("orders:delay");
// 60 秒后可被消费
delay.Add(new OrderMsg { OrderId =
