ASP.NET Core 输出缓存中间件实战指南:8 个示例带你掌握 OutputCache 从基础到策略化配置

原创2026-10-14 22:16:331,336 阅读
文章标签:示例工程

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 是真正在服务端保存响应内容并按策略复用。

在仓库的示例中,启用输出缓存只需三个步骤:

  1. 注册服务:builder.Services.AddOutputCache();
  2. 挂载中间件:app.UseOutputCache();
  3. 标记端点:在端点后链式调用 .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 个示例,落地输出缓存时可以遵循几条原则:

  1. 先注册 AddOutputCache(),再 UseOutputCache(),最后在端点或策略中声明缓存,三者顺序缺一不可;
  2. 默认值心中有数:60 秒过期、64 MB 响应体上限,特殊需求用 Expire 或策略定制;
  3. 区分缓存维度用 SetVaryByQuery,批量管理用 Tag + EvictByTagAsync,二者配合可实现"细粒度缓存、粗粒度失效";
  4. 基策略定全局规则,命名策略做例外与定制,避免在每个端点重复写配置;
  5. 敏感或个性化响应(如随机数、用户私有数据)务必谨慎缓存,可用基策略条件或 NoCache 策略主动排除。

从最小 API 的单端点缓存,到多租户动态策略,这套由浅入深的示例体系足以覆盖输出缓存的绝大多数生产场景。所有代码均可直接在 output-cache-middleware 目录下按编号运行验证。

登录后查看全文
practical-aspnetcore