ASP.NET Core 输出缓存中间件实战指南:8 个示例带你掌握 OutputCache 从基础到策略化配置
ASP.NET Core 输出缓存中间件实战指南:8 个示例带你掌握 OutputCache 从基础到策略化配置
导读
输出缓存(Output Cache)是 ASP.NET Core 内置的响应缓存中间件,它允许你把 HTTP 响应整体缓存起来,从而显著降低重复请求对服务器资源的消耗。本文基于 practical-aspnetcore 仓库中 output-cache-middleware 的 8 个循序渐进示例,完整覆盖输出缓存的注册、启用、按查询字符串区分缓存、按标签批量失效、全局基策略、命名策略覆盖等核心能力,并延伸到 .NET 11 中新增的 IOutputCachePolicyProvider 动态策略机制。读完本文,你将能够根据业务场景为最小 API 精准配置输出缓存,并能用几行代码完成缓存的管理与失效。
输出缓存中间件核心概念速览
输出缓存中间件(OutputCacheMiddleware)运行在请求管道中,负责三件事:判断某个请求是否允许读取缓存(AllowCacheLookup)、是否允许写入缓存(AllowCacheStorage),以及决定缓存键如何生成(CacheVaryByRules)。与旧式 ResponseCache 特性只写响应头不同,Output Cache 是真正在服务端保存响应内容并按策略复用。
在仓库的示例中,启用输出缓存只需三个步骤:
- 注册服务:
builder.Services.AddOutputCache(); - 挂载中间件:
app.UseOutputCache(); - 标记端点:在端点后链式调用
.CacheOutput(),或通过AddOutputCache(options => ...)配置全局/命名策略。
所有示例均基于最小 API 的 WebApplication 构建(TargetFramework 为 net10.0,见 output-cache-1.csproj),运行方式为进入对应目录后执行 dotnet run。
示例一:最小配置开启端点级缓存
output-cache-1 演示了输出缓存最基础的用法,Program.cs 中关键代码:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOutputCache();
var app = builder.Build();
app.MapGet("/", () => /* 首页 HTML */);
app.UseOutputCache();
app.MapGet("/now", () => DateTime.UtcNow.ToString());
app.MapGet("/cached-now", () => DateTime.UtcNow.ToString()).CacheOutput();
app.Run();
对比两个端点:/now 每次请求都返回最新时间,而 /cached-now 因为调用了 .CacheOutput(),在缓存有效期内重复请求会直接命中缓存,返回同一个时间戳。
默认参数值得特别注意(官方 OutputCacheOptions 默认值):
- 默认缓存过期时间为 1 分钟(60 秒);
- 默认可缓存的响应体大小上限为 64 MB。
这些默认值决定了不写任何参数时缓存的行为边界,也是后续所有示例"默认 60 秒"说法的来源。
示例二:按一个或多个查询字符串区分缓存
output-cache-2 演示了"同一条 URL、不同参数各缓存一份"的场景,其页面提供了 ?version=1、?version=2 以及 ?version=1&culture=en、?version=1&culture=ar 等多个链接。实现方式是在 .CacheOutput() 里调用 SetVaryByQuery:
app.MapGet("/cached-now", () => DateTime.UtcNow.ToString())
.CacheOutput(p => p.SetVaryByQuery("version", "culture"));
要点:
SetVaryByQuery接受一个或多个参数名,可以传多个;- 只有被列入的参数参与缓存键计算。上例中
version和culture任一不同都会生成独立的缓存条目,所以/cached-now?version=1&culture=en与/cached-now?version=1&culture=ar会各缓存一份; - 反之,未被列出的查询参数变化不会产生新缓存。
这非常适合"同一接口按语言、分页、版本号等维度输出不同内容"的场景。
示例三:给缓存打标签,并按标签批量失效
output-cache-3 解决了一个实际问题:缓存过期时间未到,但数据已经变化,如何主动让缓存失效?答案是标签(Tag)。示例中 /cached-now-tagged 端点被打了 datetime 标签,而 /clear 端点负责按标签清除缓存:
app.MapGet("/cached-now-tagged", () => DateTime.UtcNow.ToString())
.CacheOutput(p => p.Tag("datetime"));
app.MapGet("/clear", async (IOutputCacheStore cache) =>
{
await cache.EvictByTagAsync("datetime", CancellationToken.None);
return Results.Ok(new { message = "Cached value purged." });
});
关键 API 说明:
p.Tag("datetime"):给该端点的缓存条目附加标签,多个标签可以多次调用;IOutputCacheStore.EvictByTagAsync(tag, cancellationToken):通过依赖注入直接获取缓存存储,按标签一次性清除所有相关条目;- 示例中
/cached-now(无标签)不会受/clear影响,只有打了datetime标签的条目被清空——标签实现了按业务维度批量管理缓存的能力,例如"所有商品相关缓存打product标签,商品更新时一键清除"。
示例四:全局基策略——为所有端点开启缓存
output-cache-4 不再逐个端点调用 .CacheOutput(),而是通过 AddBasePolicy 注册基策略(Base Policy),让缓存对全部端点生效:
builder.Services.AddOutputCache(options =>
{
options.AddBasePolicy(builder => builder.With(c => true));
});
With(c => true) 表示对任意请求都允许缓存,因此示例中的 /now 和 /random(用 RandomNumberGenerator.GetInt32 生成的随机数)都会被缓存——注意随机数端点被缓存后,刷新页面会看到数值不变,这正是全局策略生效的直接证据。
两点提醒:
- 基策略面向所有请求,应确保被缓存的内容确实"可缓存"(如公开、变化不频繁的数据);
- 缓存时长沿用默认 60 秒。
示例五:基策略配合 HttpContext 按条件缓存
output-cache-5 展示了基策略与 HttpContext 的结合——只有带 cache 查询参数的请求才进入缓存:
options.AddBasePolicy(builder => builder.With(c =>
c.HttpContext.Request.QueryString.Value?.Contains("cache") ?? false));
页面中 /now 不缓存,而 /now?cache 会被缓存。这里的委托参数 c 是 OutputCachePolicyBuilder,其 HttpContext 属性直接暴露当前请求上下文,因此可以读取 QueryString、Path、Header 等任意请求信息来编写判定条件。这种方式非常适合"默认不缓存、显式要求才缓存"的控制粒度。
示例六:按 URL 段前缀条件缓存
output-cache-6 换了一种条件——按路径段开头匹配:
options.AddBasePolicy(builder => builder.With(c =>
c.HttpContext.Request.Path.StartsWithSegments("/cached")));
页面验证逻辑一目了然:
/cached/now→ 命中StartsWithSegments("/cached"),被缓存;/time/cached/now→ 路径不以/cached开头,不被缓存。
StartsWithSegments 是 PathString 提供的段级匹配方法,它按路径段而非字符串前缀比较,避免出现 /cached-other 这类误匹配。适合"某组路由统一走缓存"的架构。
示例七:命名策略覆盖全局基策略
output-cache-7 引入命名策略(Named Policy),并验证了关键规则:端点上的特定策略优先于全局基策略。
builder.Services.AddOutputCache(options =>
{
options.AddBasePolicy(builder => builder.With(c =>
c.HttpContext.Request.Path.StartsWithSegments("/cached")));
options.AddPolicy("NoCache", o => o.NoCache());
});
app.MapGet("/cached/now", () => DateTime.UtcNow.ToString());
app.MapGet("/cached/now-nope", () => DateTime.UtcNow.ToString()).CacheOutput("NoCache");
行为对比:
/cached/now:没有显式策略,应用基策略,被缓存;/cached/now-nope:虽然路径也以/cached开头,但通过.CacheOutput("NoCache")显式指定了NoCache策略,不缓存。
AddPolicy 的第一个参数即策略名称,CacheOutput("策略名") 在端点级别引用它。这一机制让"全局默认缓存 + 少数端点豁免/定制"的组合成为可能。
示例八:策略级自定义过期时间
output-cache-8 演示了如何摆脱默认 60 秒,为特定端点设置 10 分钟过期时间:
builder.Services.AddOutputCache(options =>
{
options.AddBasePolicy(builder => builder.With(c =>
c.HttpContext.Request.Path.StartsWithSegments("/cached")));
options.AddPolicy("10Minutes", o => o.Expire(TimeSpan.FromMinutes(10)));
});
app.MapGet("/cached/now", () => DateTime.UtcNow.ToString());
app.MapGet("/cached/now-nope", () => DateTime.UtcNow.ToString()).CacheOutput("10Minutes");
这里 o.Expire(TimeSpan.FromMinutes(10)) 直接指定缓存生命周期。与示例七结合可以看出策略设计模式:基策略负责"哪些请求可缓存"的默认规则,命名策略负责"缓存多久、怎么变、打什么标签"等细粒度定制,二者通过 CacheOutput("策略名") 精确组合,可读性和可维护性都很好。
进阶延伸:.NET 11 的动态策略提供器
在 .NET 11 中,输出缓存新增了 IOutputCachePolicyProvider 接口,支持动态选择策略——例如从配置或数据库加载策略、按租户应用不同规则。仓库中的 output-cache-policy-provider 示例展示了完整用法:
public interface IOutputCachePolicyProvider
{
IReadOnlyList<IOutputCachePolicy> GetBasePolicies();
ValueTask<IOutputCachePolicy?> GetPolicyAsync(string policyName);
}
示例通过注册自定义提供器,实现按 X-Tenant 请求头区分缓存键(多租户场景下每个租户拥有独立缓存副本):
builder.Services.AddSingleton<IOutputCachePolicyProvider, TenantPolicyProvider>();
// ...
public sealed class TenantVaryPolicy : IOutputCachePolicy
{
public ValueTask CacheRequestAsync(OutputCacheContext context, CancellationToken cancellationToken)
{
context.CacheVaryByRules.HeaderNames = "X-Tenant";
context.AllowCacheLookup = true;
context.AllowCacheStorage = true;
return ValueTask.CompletedTask;
}
// ServeFromCacheAsync / ServeResponseAsync ...
}
验证方式(示例 Readme 提供):
curl -H "X-Tenant: a" http://localhost:5000/
curl -H "X-Tenant: b" http://localhost:5000/
同一个租户的两次请求返回相同时间戳(命中缓存),不同租户各得各的缓存副本。这为生产环境下的动态、多租户缓存策略提供了官方扩展点。
结语:输出缓存的最佳实践要点
综合仓库 8 个示例,落地输出缓存时可以遵循几条原则:
- 先注册
AddOutputCache(),再UseOutputCache(),最后在端点或策略中声明缓存,三者顺序缺一不可; - 默认值心中有数:60 秒过期、64 MB 响应体上限,特殊需求用
Expire或策略定制; - 区分缓存维度用
SetVaryByQuery,批量管理用Tag+EvictByTagAsync,二者配合可实现"细粒度缓存、粗粒度失效"; - 基策略定全局规则,命名策略做例外与定制,避免在每个端点重复写配置;
- 敏感或个性化响应(如随机数、用户私有数据)务必谨慎缓存,可用基策略条件或
NoCache策略主动排除。
从最小 API 的单端点缓存,到多租户动态策略,这套由浅入深的示例体系足以覆盖输出缓存的绝大多数生产场景。所有代码均可直接在 output-cache-middleware 目录下按编号运行验证。