ASP.NET Core Web API 入門心得 - Middleware 順序

TLDR

• Middleware 的執行順序至關重要，錯誤的順序會導致功能失效或非預期的行為。
• UseRouting 必須位於 UseRateLimiter 之前（除非僅使用全域 Filter）。
• UseCors 必須放在 UseRouting 之後，且位於 UseAuthentication 與 UseResponseCaching 之前。
• UseStaticFiles 若涉及跨域存取或文化特性，需根據需求調整其與 UseCors 或 UseRequestLocalization 的先後順序。
• UseAuthentication 必須始終位於 UseAuthorization 之前。
• 端點路由（如 MapControllers 或 MapRazorPages）必須放置於管線的最末端。

Middleware 核心功能說明

在 ASP.NET Core 中，Middleware 構成請求處理管線。以下為常見 Middleware 的功能與用途：

• UseDeveloperExceptionPage：回報應用程式執行階段錯誤。
• UseExceptionHandler：攔截管線中後續 Middleware 擲回的例外狀況。
• UseHsts：新增 Strict-Transport-Security 標頭，強制瀏覽器僅使用 HTTPS 連線。
• UseHttpsRedirection：將 HTTP 要求重新導向至 HTTPS。
• UseStaticFiles：處理靜態檔案請求。
• UseRouting：處理路由解析。
• UseAuthentication：驗證使用者身分。
• UseAuthorization：授權使用者存取資源。
• UseSession：處理 Session 狀態。
• UseEndpoints：將端點新增至要求管線。

TIP

UseHsts 與 UseHttpsRedirection 皆用於處理 HTTPS，前者由瀏覽器端執行，後者則由伺服器端程式處理。

Middleware 建議執行順序與注意事項

以下為建議的 Middleware 註冊順序。請注意，部分 Middleware 的順序具有嚴格的相依性：

var app = builder.Build();

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

app.UseHttpsRedirection();

// 什麼情況下會遇到問題：當靜態檔案涉及跨域存取 (CORS)、文化特性 (Localization) 或壓縮快取時。
// 若有跨域需求，UseStaticFiles 必須放在 UseCors 後面；
// 若涉及文化特性，必須放在 UseRequestLocalization 後面；
// 若需快取壓縮檔案，必須放在 UseResponseCompression 和 UseResponseCaching 後面。
app.UseStaticFiles();
app.UseCookiePolicy();

// 什麼情況下會遇到問題：當需要限流 (Rate Limiting) 或路由解析時。
// UseRouting 必須放在 UseRateLimiter 前面。
app.UseRouting();
app.UseRateLimiter();

// 什麼情況下會遇到問題：當需要處理多語言或跨域請求時。
// UseRequestLocalization 必須在任何檢查文化特性的 Middleware 之前。
// UseCors 必須放在 UseRouting 後面，且位於 UseAuthentication 與 UseResponseCaching 之前。
app.UseRequestLocalization();
app.UseCors();

// 什麼情況下會遇到問題：當需要身分驗證與授權時。
// UseAuthentication 必須嚴格放在 UseAuthorization 之前。
app.UseAuthentication();
app.UseAuthorization();

// 什麼情況下會遇到問題：當需要使用 Session 狀態時。
// 必須放在 UseCookiePolicy 後面，且在端點路由 Middleware 之前。
app.UseSession();

// 什麼情況下會遇到問題：當需要效能優化時。
// 若需快取壓縮過的回應，可調整兩者順序。
app.UseResponseCompression();
app.UseResponseCaching();

// 什麼情況下會遇到問題：當請求無法正確導向至 Controller 或 Page 時。
// 所有端點路由相關的 Map 方法必須放在管線的最末端。
app.MapRazorPages();
app.MapDefaultControllerRoute();

app.Run();

異動歷程

• 2024-04-08 初版文件建立。