终于不用手搓两级缓存了！C#.NET HybridCache 详解：L1 L2、标签失效与防击穿实战

简介很多项目一开始做缓存通常都是这么写的先查 IMemoryCache - 没有再查 Redis - 还没有就查数据库 - 再把结果写回两层缓存刚开始看起来没什么问题。但只要项目一复杂这套逻辑很快就会变得又长又散每个地方都在手写两级缓存本地缓存和 Redis 的过期时间不好统一并发一上来容易缓存击穿对象序列化、反序列化到处都是删除缓存时还得考虑本地层和分布式层一起失效这时候.NET官方给了一个更现代的选择HybridCache一句话先说透HybridCache是.NET官方提供的混合缓存库把进程内缓存和分布式缓存整合成一套统一 API同时内置了缓存旁路、防击穿和序列化能力。这篇文章重点讲这些事HybridCache到底解决了什么问题它和IMemoryCache、IDistributedCache有什么关系为什么很多人会把它看成官方版“两级缓存”GetOrCreateAsync到底好用在哪标签失效、删除缓存、多实例场景应该怎么理解用几个更像真实项目的 demo把常见写法串起来HybridCache到底是什么可以先用最白话的方式理解HybridCache就是官方把“本地缓存 分布式缓存 回源逻辑”这套常见套路统一收成了一层能力。它最常见的结构通常是L1本地内存缓存L2分布式缓存例如 Redis读取时的思路通常是先查 L1 - L1 没有再查 L2 - L2 也没有才执行回源函数 - 再把结果写回 L1 和 L2这也是为什么很多人会把它看成官方版两级缓存方案。为什么会有HybridCache因为老写法虽然能用但现实里会反复踩同一批坑。最典型的几个痛点有这些1. 缓存旁路逻辑重复每个服务都在写先查缓存没有就查数据库再回填缓存代码很容易一份份复制出去。2. 本地缓存和分布式缓存不好统一有的地方只查内存有的地方只查 Redis有的地方先查内存再查 Redis。时间一长缓存访问方式很容易失控。3. 高并发下容易击穿某个热点 key 一旦过期大量请求可能会一起回源数据库。4. 序列化逻辑散落手动用IDistributedCache时很多项目都在自己写JSON 序列化反序列化默认 TTL扩展方法这些东西本来就不该在业务层到处重复。HybridCache和IMemoryCache、IDistributedCache到底是什么关系先把关系讲清楚后面就不容易混。IMemoryCache本地内存缓存只在当前进程内生效速度极快多实例之间不共享IDistributedCache分布式缓存抽象通常接 Redis、SQL Server 这类外部缓存多实例可共享需要处理序列化HybridCache上层统一缓存库默认用MemoryCache做本地层如果项目里配置了IDistributedCache它就会把那一层作为分布式层可以直接这样记HybridCache不是替代IMemoryCache或IDistributedCache的底层存储而是把它们组织成一套更顺手的高层缓存方案。它是不是只有接了 Redis 才有价值不是。这是一个很容易误解的点。即便没有配置分布式缓存HybridCache仍然可以工作依然有本地缓存依然有GetOrCreateAsync依然有缓存击穿保护只不过这时候它更像更高级的本地缓存访问层如果项目里同时配置了 Redis 这类IDistributedCache实现它才会自然升级成本地L1分布式L2先看最基础的注册方式先装包dotnetaddpackage Microsoft.Extensions.Caching.Hybrid在 ASP.NET Core 里注册varbuilderWebApplication.CreateBuilder(args);builder.Services.AddHybridCache();varappbuilder.Build();app.Run();这就是最小接入方式。如果项目里什么都不额外配它会先用本地内存能力工作起来。如果要接 Redis怎么配先装 Redis 包dotnetaddpackage Microsoft.Extensions.Caching.StackExchangeRedis然后这样注册varbuilderWebApplication.CreateBuilder(args);builder.Services.AddStackExchangeRedisCache(options{options.Configurationlocalhost:6379;});builder.Services.AddHybridCache();varappbuilder.Build();app.Run();这一点非常关键HybridCache自己不是 Redis 客户端它会自动使用项目里已经注册好的IDistributedCache作为二级缓存。也就是说Redis 不是单独写进HybridCache配置里的而是通过现有IDistributedCache接入。HybridCache最核心的 API 是什么最核心的通常就是一个GetOrCreateAsync这个方法几乎把最常见的缓存旁路场景全包了。它做的事情可以概括成先按 key 查缓存如果命中直接返回如果没命中执行工厂函数再把结果写回缓存Demo 1最小可用的GetOrCreateAsyncusingMicrosoft.Extensions.Caching.Hybrid;publicsealedclassUserService{privatereadonlyHybridCache_cache;publicUserService(HybridCachecache){_cachecache;}publicasyncTaskUserDtoGetUserAsync(intid,CancellationTokencancellationTokendefault){returnawait_cache.GetOrCreateAsync($user:{id},asynccancel{awaitTask.Delay(100,cancel);returnnewUserDto(id,Tom);},cancellationToken:cancellationToken);}}publicsealedrecordUserDto(intId,stringName);这个例子虽然小但已经把它和传统缓存写法的差别拉开了没有手动Get没有手动判断缓存命中没有手动写回缓存很多场景里直接一个GetOrCreateAsync就够了。它为什么能防缓存击穿这是HybridCache最有价值的点之一。很多缓存问题本质不是“缓存不会用”而是热点 key 一过期大量请求一起去回源。HybridCache内置了同 key 并发合并能力。可以先这样理解同一个 key 同时来了很多请求第一个请求负责真正执行回源函数其他请求等待这个结果也就是说对同一个 key不会让所有并发请求都一起打数据库。这就是很多资料里常说的stampede protection或者single flightDemo 2商品详情缓存的标准写法usingMicrosoft.Extensions.Caching.Hybrid;publicsealedclassProductQueryService{privatereadonlyHybridCache_cache;privatereadonlyProductRepository_repository;publicProductQueryService(HybridCachecache,ProductRepositoryrepository){_cachecache;_repositoryrepository;}publicasyncTaskProductDto?GetByIdAsync(intid,CancellationTokencancellationTokendefault){returnawait_cache.GetOrCreateAsync($product:{id},asynccancelawait_repository.GetByIdAsync(id,cancel),cancellationToken:cancellationToken);}}publicsealedclassProductRepository{publicTaskProductDto?GetByIdAsync(intid,CancellationTokencancellationTokendefault){ProductDto?productid1?newProductDto(1,机械键盘,399m):null;returnTask.FromResult(product);}}publicsealedrecordProductDto(intId,stringName,decimalPrice);这个写法已经非常接近真实项目里的缓存查询服务了。过期策略怎么配HybridCache里最常见的过期配置在HybridCacheEntryOptions最值得先记住的是两个时间ExpirationLocalCacheExpiration可以先用最白话的方式理解Expiration整体缓存项的有效时间更偏向分布式层LocalCacheExpiration本地缓存层的有效时间Demo 3本地层短一点分布式层长一点usingMicrosoft.Extensions.Caching.Hybrid;publicsealedclassProductService{privatereadonlyHybridCache_cache;publicProductService(HybridCachecache){_cachecache;}publicasyncTaskProductDtoGetAsync(intid,CancellationTokencancellationTokendefault){varoptionsnewHybridCacheEntryOptions{ExpirationTimeSpan.FromMinutes(30),LocalCacheExpirationTimeSpan.FromMinutes(5)};returnawait_cache.GetOrCreateAsync($product:{id},asynccancel{awaitTask.Delay(50,cancel);returnnewProductDto(id,机械键盘,399m);},options,cancellationToken:cancellationToken);}}publicsealedrecordProductDto(intId,stringName,decimalPrice);这种配置思路非常常见本地层更短分布式层更长为什么经常这么做因为这样通常能兼顾两件事本地读性能好多实例下旧数据停留时间不会太长全局默认配置怎么配如果很多缓存项都差不多可以在注册时直接配全局默认值。varbuilderWebApplication.CreateBuilder(args);builder.Services.AddHybridCache(options{options.MaximumPayloadBytes1024*1024;options.MaximumKeyLength1024;options.DefaultEntryOptionsnewHybridCacheEntryOptions{ExpirationTimeSpan.FromMinutes(10),LocalCacheExpirationTimeSpan.FromMinutes(5)};});这里几个点比较实用MaximumPayloadBytes限制单个缓存项大小MaximumKeyLength限制 key 最大长度DefaultEntryOptions全局默认过期策略这类默认配置的价值在于避免每个地方都手写 TTL降低超大缓存项把系统拖慢的风险它默认怎么序列化对象如果项目里配置了分布式缓存层那么对象写到二级缓存时就需要序列化。HybridCache默认的处理方式可以先记成这样string和byte[]会被特殊处理其他对象默认走System.Text.Json这就意味着大多数普通对象场景下不需要再像IDistributedCache那样手写一层 JSON 扩展方法这是它非常省事的一点。如果默认序列化不合适怎么办也可以配置自定义序列化器。官方支持从AddHybridCache()链式配置AddSerializerAddSerializerFactory也就是说如果项目有更明确的性能目标比如想换成 protobuf想对某个类型做更细粒度的序列化控制HybridCache也不是只能死用默认 JSON。SetAsync和GetOrCreateAsync怎么选虽然GetOrCreateAsync很强但不是所有场景都适合它。如果已经有明确数据想直接写缓存可以用SetAsync例如后台预热缓存主动刷新热点数据某些事件驱动场景下直接覆盖缓存Demo 4主动写入缓存usingMicrosoft.Extensions.Caching.Hybrid;publicsealedclassProductCacheWriter{privatereadonlyHybridCache_cache;publicProductCacheWriter(HybridCachecache){_cachecache;}publicasyncTaskWarmupAsync(ProductDtoproduct,CancellationTokencancellationTokendefault){await_cache.SetAsync($product:{product.Id},product,options:newHybridCacheEntryOptions{ExpirationTimeSpan.FromMinutes(30),LocalCacheExpirationTimeSpan.FromMinutes(5)},cancellationToken:cancellationToken);}}publicsealedrecordProductDto(intId,stringName,decimalPrice);更新数据时缓存该怎么失效这也是缓存里最容易出问题的部分。最常见、也最稳的一种思路通常还是先更新数据库再删除相关缓存让下一次查询自动重建Demo 5更新后删除缓存usingMicrosoft.Extensions.Caching.Hybrid;publicsealedclassProductCommandService{privatereadonlyHybridCache_cache;privatereadonlyProductRepository_repository;publicProductCommandService(HybridCachecache,ProductRepositoryrepository){_cachecache;_repositoryrepository;}publicasyncTaskUpdateAsync(ProductDtoproduct,CancellationTokencancellationTokendefault){await_repository.UpdateAsync(product,cancellationToken);await_cache.RemoveAsync($product:{product.Id},cancellationToken);}}这个思路为什么常见因为它简单而且通常更不容易把脏数据写回缓存。标签失效是什么为什么它很适合批量清理这是HybridCache相比很多旧缓存写法很有吸引力的一点。可以先把标签理解成给一批缓存项打上逻辑分组。例如商品详情都打上product某个分类商品再打上category:keyboard这样当分类更新时就不需要手动删一堆 key而是可以按标签失效。Demo 6写缓存时带标签usingMicrosoft.Extensions.Caching.Hybrid;publicsealedclassProductQueryService{privatereadonlyHybridCache_cache;publicProductQueryService(HybridCachecache){_cachecache;}publicasyncTaskProductDtoGetAsync(intid,CancellationTokencancellationTokendefault){varoptionsnewHybridCacheEntryOptions{ExpirationTimeSpan.FromMinutes(20),LocalCacheExpirationTimeSpan.FromMinutes(5)};vartagsnew[]{product,$product:{id},category:keyboard};returnawait_cache.GetOrCreateAsync($product:{id},asynccancel{awaitTask.Delay(50,cancel);returnnewProductDto(id,机械键盘,399m);},options,tags,cancellationToken:cancellationToken);}}publicsealedrecordProductDto(intId,stringName,decimalPrice);为什么标签要写成数组第一个product又是什么意思这里的vartagsnew[]{product,$product:{id},category:keyboard};本质上是在给同一条缓存打上多个“逻辑分组标签”。先抓住一个核心点标签不是 key本质上是为了后续按不同维度做失效控制。之所以写成数组是因为一条缓存通常不只属于一个维度。比如一个商品详情缓存同时可能属于商品模块某一个具体商品某一个商品分类所以会需要一次挂多个标签而不是只挂一个。可以把这三个标签拆开看product大类标签$product:{id}单对象标签category:keyboard业务分类标签1.product是大类标签这个标签最适合表达这条缓存属于商品模块它的价值在于后面可以直接按模块整体失效await_cache.RemoveByTagAsync(product,cancellationToken);这句话的效果可以理解成让所有打过product标签的缓存都失效所以第一个product不是特殊关键字只是一个普通标签只不过通常会把它当成“商品模块总标签”来用。2.$product:{id}是单对象标签如果id 12那它就会变成product:12它的意义更像这条缓存属于“商品 12”这个对象维度这样以后如果要按“某一个对象”维度做逻辑失效就会更精确。3.category:keyboard是业务维度标签这个标签最适合表达这条商品缓存同时属于“键盘分类”这样当分类维度发生变化时就可以直接按分类清await_cache.RemoveByTagAsync(category:keyboard,cancellationToken);而不需要自己去维护这一分类下所有商品 key 的清单。标签设计的思路通常可以分成这三层比较常见的设计方式就是模块级标签例如product对象级标签例如product:12业务级标签例如category:keyboard这样做的好处是很直接的想清整个模块可以按模块标签想清某个对象可以按对象标签想清某个业务范围可以按业务标签也就是说标签最值钱的地方不是“多挂几个字符串”而是先把后面的失效维度设计出来。标签不要乱挂维度要能落到真实失效场景标签并不是越多越好。如果一条缓存随手挂一堆没有明确意义的标签后面维护反而会乱。更稳的做法通常是先问自己以后可能按什么维度清缓存是按模块清按对象清还是按分类清哪些维度是真实会发生的失效场景想清这几个问题后再决定挂哪些标签设计会稳很多。Demo 7按标签失效usingMicrosoft.Extensions.Caching.Hybrid;publicsealedclassCategoryCommandService{privatereadonlyHybridCache_cache;publicCategoryCommandService(HybridCachecache){_cachecache;}publicasyncTaskUpdateCategoryAsync(CancellationTokencancellationTokendefault){await_cache.RemoveByTagAsync(category:keyboard,cancellationToken);}}这里有个非常关键的技术事实一定要说清楚RemoveByTagAsync是逻辑失效不是立刻去把所有底层缓存值物理删掉。更准确地说带这些标签的数据后续会被当成缓存未命中处理但底层已有值通常还是按自己的生命周期自然过期这个差别很重要。还有一个多实例下非常容易忽略的点按 key 删除和按标签失效时当前节点和二级分布式缓存会被处理。但其他服务器进程里的本地内存层并不会被主动扫一遍物理清掉。也就是说多实例场景下仍然要理解一个现实本地层本身就是每个节点各有一份这也是为什么前面经常会建议LocalCacheExpiration不要太长Demo 8更接近真实项目的商品服务usingMicrosoft.Extensions.Caching.Hybrid;publicsealedclassProductService{privatereadonlyHybridCache_cache;privatereadonlyProductRepository_repository;publicProductService(HybridCachecache,ProductRepositoryrepository){_cachecache;_repositoryrepository;}publicasyncTaskProductDto?GetByIdAsync(intid,CancellationTokencancellationTokendefault){returnawait_cache.GetOrCreateAsync($product:{id},asynccancelawait_repository.GetByIdAsync(id,cancel),options:newHybridCacheEntryOptions{ExpirationTimeSpan.FromMinutes(30),LocalCacheExpirationTimeSpan.FromMinutes(5)},tags:[product,$product:{id}],cancellationToken:cancellationToken);}publicasyncTaskUpdateAsync(ProductDtoproduct,CancellationTokencancellationTokendefault){await_repository.UpdateAsync(product,cancellationToken);await_cache.RemoveAsync($product:{product.Id},cancellationToken);await_cache.RemoveByTagAsync(product,cancellationToken);}}publicsealedclassProductRepository{publicTaskProductDto?GetByIdAsync(intid,CancellationTokencancellationTokendefault){ProductDto?productid1?newProductDto(1,机械键盘,399m):null;returnTask.FromResult(product);}publicTaskUpdateAsync(ProductDtoproduct,CancellationTokencancellationTokendefault)Task.CompletedTask;}publicsealedrecordProductDto(intId,stringName,decimalPrice);这个例子里几乎已经能看到HybridCache在真实业务里的完整轮廓了查询走GetOrCreateAsync更新后删 key需要时按标签做一批逻辑失效HybridCache、IDistributedCache、CacheManager怎么选真正做选型时先别急着问哪个更火。更该先问的是有没有本地L1加分布式L2的需求是不是多实例部署缓存旁路逻辑是不是已经写得到处都是热点 key 并发回源是不是已经成了现实问题项目更偏官方路线还是历史缓存体系已经很重可以直接按下面这张表看方案更适合什么场景IMemoryCache单机、本地、轻量缓存IDistributedCache多实例共享缓存但不强调两级缓存封装HybridCache官方两级缓存、旁路逻辑统一、防击穿诉求明确CacheManager历史项目、缓存层复杂、策略集中管理需求更重可以直接把边界记成这样只有本地缓存需求优先IMemoryCache只需要跨节点共享缓存优先IDistributedCache已经明确需要两级缓存又不想再手写样板代码优先评估HybridCache历史项目缓存层已经很重还需要更强的集中管理能力再看CacheManager如果项目里已经开始频繁写这种逻辑先查内存 - 没有再查 Redis - 没有再查数据库 - 再写回两层缓存 - 还要自己想怎么防击穿那真正该考虑的就不再只是“Redis 怎么配”而是这套两级缓存样板代码值不值得交给HybridCache这种更高层的官方能力来接管。总结HybridCache的价值不只是“把缓存 API 包得更短”。它真正值钱的地方通常是官方两级缓存方案内置缓存旁路内置并发防击穿默认序列化和更顺手的对象缓存体验更适合现代 ASP.NET Core 项目的缓存写法如果项目已经开始频繁手写“本地缓存 Redis 回源 防击穿”这套逻辑那HybridCache基本就是一个很自然的升级方向。如果只记一句话最值得记的是HybridCache最大的意义不是多一个缓存库而是把两级缓存、回源逻辑和并发保护收成了一套官方统一能力。