.NET 9 内置中间件速查表

📌 提示：中间件顺序很重要！本表仅为速查，不是完整顺序规范。

---

🐞 错误处理

名称	作用	Services 注册	app.Use 调用	注意点
Developer Exception Page	开发环境显示详细异常	无	app.UseDeveloperExceptionPage();	仅开发环境使用
Exception Handler	生产环境全局异常处理	无	app.UseExceptionHandler("/Error");	在管道前端配置
Status Code Pages	处理 404/500 等状态码，返回页面或 JSON	无	app.UseStatusCodePages();	常用于调试/友好提示

---

🔒 安全 & 传输

名称	作用	Services 注册	app.Use 调用	注意点
HTTPS Redirection	HTTP 自动跳转到 HTTPS	无	app.UseHttpsRedirection();	建议生产必开
HSTS	添加 Strict-Transport-Security 头	无	app.UseHsts();	仅在 HTTPS 下启用

---

📂 静态文件

名称	作用	Services 注册	app.Use 调用	注意点
Default Files	自动查找 index.html	无	app.UseDefaultFiles();	通常配合 StaticFiles
Static Files	提供 wwwroot 静态文件	无	app.UseStaticFiles();	会短路后续中间件
Directory Browser	目录浏览	services.AddDirectoryBrowser();	app.UseDirectoryBrowser();	谨慎启用（安全风险）

---

🚏 路由 & 终结点

名称	作用	Services 注册	app.Use 调用	注意点
Routing	路由匹配	services.AddRouting();	app.UseRouting();	必须在 Endpoints 前
Endpoints	执行终结点	控制器/Minimal API 注册	app.UseEndpoints(endpoints => { ... });	在 Routing 之后

---

👤 身份认证与授权

名称	作用	Services 注册	app.Use 调用	注意点
Authentication	验证用户身份 (JWT/Cookie 等)	services.AddAuthentication();	app.UseAuthentication();	在 Routing 之后
Authorization	授权访问控制	services.AddAuthorization();	app.UseAuthorization();	在 Authentication 之后

---

🍪 会话 & Cookie

名称	作用	Services 注册	app.Use 调用	注意点
Cookie Policy	控制 Cookie 策略 (SameSite/Consent)	services.Configure<CookiePolicyOptions>(...)	app.UseCookiePolicy();	在写 Cookie 之前
Session	服务器端 Session 存储	services.AddSession();	app.UseSession();	在访问 Session 前调用

---

⚡ 性能优化

名称	作用	Services 注册	app.Use 调用	注意点
Response Compression	响应压缩 (gzip/brotli)	services.AddResponseCompression();	app.UseResponseCompression();	放在写响应前
Response Caching	基于 HTTP 头缓存响应	services.AddResponseCaching();	app.UseResponseCaching();	与压缩顺序要考虑
Output Caching	缓存终结点输出	services.AddOutputCache();	app.UseOutputCache();	新一代缓存

---

🌐 代理 / 反向代理

名称	作用	Services 注册	app.Use 调用	注意点
Forwarded Headers	使用代理头恢复真实 IP/协议	services.Configure<ForwardedHeadersOptions>(...)	app.UseForwardedHeaders();	尽早调用
Host Filtering	Host 白名单过滤	配置 AllowedHosts	自动应用	防主机头攻击
Path Base	设置应用基路径	无	app.UsePathBase("/foo");	适用于子路径托管

---

📊 诊断与健康

名称	作用	Services 注册	app.Use 调用	注意点
Http Logging	记录请求/响应	services.AddHttpLogging();	app.UseHttpLogging();	谨慎生产开启
Health Checks	健康检查端点	services.AddHealthChecks();	app.UseHealthChecks("/health");	K8s/监控探针常用

---

🔌 实时通信

名称	作用	Services 注册	app.Use 调用	注意点
WebSockets	开启 WebSocket 支持	无	app.UseWebSockets();	提前启用
SignalR	高级实时通信	services.AddSignalR();	app.MapHub<ChatHub>("/chat");	需在 Endpoints 中注册

---

🔄 请求改写 / 辅助

名称	作用	Services 注册	app.Use 调用	注意点
URL Rewriter	URL 重写/重定向	services.AddRouting();	app.UseRewriter(new RewriteOptions()...);	常用于迁移/SEO
HttpMethodOverride	允许 POST 覆盖为 PUT/DELETE	services.AddHttpMethodOverride();	app.UseHttpMethodOverride();	表单场景常用
Header Propagation	传播请求头到 HttpClient	services.AddHeaderPropagation();	app.UseHeaderPropagation();	微服务链路追踪

---

🚦 限流 (Rate Limiting)

名称	作用	Services 注册	app.Use 调用	注意点
Rate Limiter	请求速率/并发限制	services.AddRateLimiter(...);	app.UseRateLimiter();	.NET 8+ 内置

---

⚠️ 管道顺序（常见模板）

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

app.UseForwardedHeaders();
app.UseAuthentication();
app.UseAuthorization();

app.UseSession();
app.UseResponseCompression();
app.UseResponseCaching();
app.UseRateLimiter();

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
    endpoints.MapHealthChecks("/health");
});