5分钟上手NewLife.Redis:面向.NET开发者的完整快速入门指南

原创2026-10-23 11:23:591,944 阅读
文章标签:后端缓存抽象数据库客户端消息队列

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 通过延迟队列触发落库,从而削峰平滑写入。下图展示了这一典型流程:

NewLife.Redis流式统计架构:Redis队列与延迟队列配合应用统计落库的流程示意图

管道Pipeline与性能优化:GC分配降低42%~52%

批量操作时,网络往返(RTT)是主要瓶颈。开启自动管道合并即可"攒够一批再发":

rds.AutoPipeline = 100;   // 写操作累积 100 条自动提交管道

在内存层面,团队用 dotMemory 做过专项分析,针对 Redis 客户端的 GC 分配热点(命令执行、类型转换、UTF8 编解码)逐项优化。下图中可以看到 RedisClient 命令执行路径上的分配占比:

dotMemory分析NewLife.Redis客户端的GC内存分配:RedisClient命令执行路径占比

优化后,异步命令路径同样受益,字节数组大量来自 SharedArrayPool 复用而非新建:

dotMemory分析NewLife.Redis异步命令的内存分配:字节缓冲区池化复用效果

优化效果一览(完整数据见 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 仅调试时打开

下一步:项目文档导航

想深入某个方向?这些资料都在仓库里:

按照本文的步骤走一遍,你已经掌握了 NewLife.Redis 的高性能 Redis 客户端连接、缓存操作与消息队列三大核心能力——剩下的,就是把它用到你的项目里了。🎉

登录后查看全文
NewLife.Redis