5分钟上手NewLife.Redis:面向.NET开发者的完整快速入门指南
5分钟上手NewLife.Redis:面向.NET开发者的完整快速入门指南
NewLife.Redis 是一款面向 .NET 平台的高性能 Redis 客户端组件,支持 .NET Core 到 .NET Framework 4.0/4.5 的宽框架覆盖,并为大数据与消息队列场景做了深度优化——线上单应用日均调用量达 100 亿次。本文将带你用 5 分钟完成它的安装、连接、缓存操作与消息队列入门。
为什么选择 NewLife.Redis?📌
在开始之前,先花 30 秒了解这款 Redis 客户端的核心卖点:
| 特性 | 说明 |
|---|---|
| 🚀 高吞吐 | 内置连接池(最高支持 100,000 并发)+ 自动管道合并,批量写入可达约 180 万 ops/s |
| 🏗 宽框架支持 | 一个包覆盖 .NET Framework 4.5 ~ .NET 10+,工控、政务等遗留系统也能用 |
| 📨 内置消息队列 | 简单队列、可靠队列、延迟队列、Stream 多消费组,开箱即用 |
| 🛡 集群高可用 | 支持 Standalone / 主从 / Sentinel / Cluster,网络异常自动切换 |
| ☁️ 云厂商适配 | 针对阿里云 KVStore、腾讯云 Redis、华为云 DCS 提供专项配置说明 |
| 🧠 低 GC 压力 | 针对内存分配深度优化,GC 收集压力显著降低(后文有数据) |
💡 自 2017 年起,NewLife.Redis 已在多个千万 / 百亿级数据平台稳定运行,经受日均 80+ 亿次命令调用的考验。
30秒安装:Redis客户端包
打开终端,在项目目录执行一条命令即可:
dotnet add package NewLife.Redis
如果使用的是 ASP.NET Core 项目,建议再装一个扩展包,可以直接注入分布式缓存:
dotnet add package NewLife.Redis.Extensions
第一次连接:创建Redis客户端
创建客户端只有两种主流写法,推荐单例复用(内部自带连接池,不要频繁 new):
// 方式一:构造参数
var rds = new FullRedis("127.0.0.1:6379", "password", 0);
// 方式二:连接字符串(推荐放配置中心)
var rds = FullRedis.Create("server=127.0.0.1:6379;password=pass;db=0;timeout=3000");
⚠️ 注意区分两个类:基础
Redis实例只做 KV 操作;FullRedis是增强版,额外提供列表、哈希、队列等所有高级工厂方法(如GetList<T>、GetQueue<T>),日常开发请优先使用FullRedis。其定义位于 FullRedis.cs。
最常用的缓存操作:写对象、读对象、计数器
NewLife.Redis 内置 JSON 序列化,C# 对象可以直接存、直接取,不用手写编解码:
// 写入对象(自动 JSON 序列化),1 小时后过期
rds.Set("user:1", new { Name = "Alice", Age = 30 }, expire: 3600);
// 读取并自动反序列化
var v = rds.Get<Int32>("counter");
// 计数器
rds.Increment("counter", 1);
// 仅当 key 不存在时写入(可当简单锁用)
var ok = rds.Add("lock:1", "init");
生产环境建议用键前缀隔离命名空间,避免多应用互相干扰:
var scoped = rds.GetPrefixed("myapp:");
scoped.Set("user", "Alice"); // 实际写入的 key 是 myapp:user
List、Hash、Set、SortedSet 等数据结构也都有对应的泛型封装(FullRedis.cs),用法与集合类几乎一致,这里不再展开。
内置Redis消息队列:不用重复造轮子
这是 NewLife.Redis 相比其他客户端最大的差异化能力之一。四种队列通过工厂方法一行创建:
| 队列类型 | 工厂方法 | 语义保障 |
|---|---|---|
| 简单队列 | rds.GetQueue<T>() |
至多一次,适合可丢弃的普通任务 |
| 可靠队列 | rds.GetReliableQueue<T>() |
至少一次(弹出 + Ack 确认) |
| 延迟队列 | rds.GetDelayQueue<T>() |
按指定延迟时间投递 |
| Stream 流队列 | rds.GetStream<T>() |
Redis 5.0+,支持多消费组 |
可靠队列的消费确认流程长这样(基于 RPOPLPUSH + Ack 语义):
var queue = rds.GetReliableQueue<OrderMsg>("orders");
queue.Add(new OrderMsg { OrderId = "12345" }); // 生产
var msg = queue.TakeOne(timeout: 30); // 消费
if (msg != null)
{
// 处理消息……
queue.Acknowledge(msg); // 确认;若进程崩溃未确认,60s 后自动回滚到主队列
}
完整的队列玩法示例(内存队列、普通、可靠、延迟、Stream、多消费组)可以参考示例工程 Samples/QueueDemo/Program.cs。
在实际业务中,延迟队列 + Hash 统计常常组合成"流式统计"架构:数据先到 Redis 聚合,超时的 Key 通过延迟队列触发落库,从而削峰平滑写入。下图展示了这一典型流程:
管道Pipeline与性能优化:GC分配降低42%~52%
批量操作时,网络往返(RTT)是主要瓶颈。开启自动管道合并即可"攒够一批再发":
rds.AutoPipeline = 100; // 写操作累积 100 条自动提交管道
在内存层面,团队用 dotMemory 做过专项分析,针对 Redis 客户端的 GC 分配热点(命令执行、类型转换、UTF8 编解码)逐项优化。下图中可以看到 RedisClient 命令执行路径上的分配占比:
优化后,异步命令路径同样受益,字节数组大量来自 SharedArrayPool 复用而非新建:
优化效果一览(完整数据见 Doc/Benchmark/Redis核心操作性能测试.md):
| 指标 | 优化前 | 优化后 |
|---|---|---|
| 单次命令延迟 | ~45µs(含网络往返) | 稳定 44~47µs |
| Execute 单次分配 | 208~528 B | 降低 42%~52% |
| 10 万次 SET 总分配 | 36.62 MB | 28.23 MB(-22.9%) |
| 10 万次 GET 总分配 | 23.65 MB | 15.26 MB(-35.5%) |
| GC Gen0 回收次数 | 基线 | 整体降低 33%~50% |
新手必看的配置速查表
| 配置项 | 默认值 | 说明 |
|---|---|---|
AutoPipeline |
0(关闭) | 管道合并阈值,批量写场景建议设为 100 |
ShieldingTime |
10 秒 | 不可用节点的屏蔽窗口,避免反复重试坏节点 |
Retry |
3 | 网络异常重试次数 |
AutoDetect |
false | 自动识别 Cluster/Sentinel 模式;⚠️ 公有云代理模式请保持 false |
SslProtocol |
无 | 生产 / 公有云建议开启 TLS 加密传输 |
多地址高可用只需逗号分隔,故障自动切换:
var rds = new FullRedis("10.0.0.1:6379,10.0.0.2:6379", "pass", 0);
新手最佳实践清单 ✅
- 单例复用:
FullRedis内部有连接池,全局共用一个实例即可 - Key 设计:用
:分层,如user:1001:profile;生产环境开启键前缀隔离 - 批量优先:能
GetAll/SetAll就不要循环单键;写多场景开启AutoPipeline - 控制 Value 大小:建议 1~2KB,大对象拆分或用 Hash 分字段存储
- 可靠消费:生产场景优先用
GetReliableQueue<T>(),避免消息丢失 - 监控:生产启用
Counter性能计数器;ClientLog仅调试时打开
下一步:项目文档导航
想深入某个方向?这些资料都在仓库里:
- 需求与架构:Doc/需求文档.md、Doc/架构文档.md
- 竞品对比(vs StackExchange.Redis 等):Doc/竞品分析.md
- Garnet 兼容服务器适配说明:Doc/Garnet兼容性.md
- 性能测试原始报告:Doc/Benchmark/Redis核心操作性能测试.md
- 可运行的示例工程:Samples/Benchmark/BasicBenchmark.cs、Samples/WebDemo/Program.cs
- 单元测试参考:XUnitTest/BasicTest.cs、XUnitTest/Queues/QueueTests.cs
按照本文的步骤走一遍,你已经掌握了 NewLife.Redis 的高性能 Redis 客户端连接、缓存操作与消息队列三大核心能力——剩下的,就是把它用到你的项目里了。🎉


