Rajah aliran aplikasi pada skrin pembangun

Dalam fail Program.cs projek ASP.NET Core, deretan panggilan app.Use... selalunya kelihatan seperti senarai tetapan biasa. Ramai pembangun menyangka asalkan semua servis dan middleware sudah dipanggil, aplikasi akan berjalan dengan betul.

Hakikatnya, middleware dalam ASP.NET Core membentuk satu saluran paip (pipeline) dua hala. Setiap request masuk mengikut susunan dari atas ke bawah, dan apabila sampai ke hujung atau dihentikan awal (short-circuit), response akan berpatah balik dari bawah ke atas melalui middleware yang sama. Jika susunan ini berubah walaupun satu baris, endpoint yang berjalan elok semalam boleh tiba-tiba memulangkan 404, 401, atau halaman login yang berulang tanpa henti.

Aliran paip dalam Program.cs

Bayangkan struktur tipikal untuk aplikasi web atau API yang diletakkan di belakang reverse proxy seperti Nginx atau Cloudflare Tunnel:

var app = builder.Build();

// 1. Baca header proxy dahulu sebelum middleware lain menilai IP atau scheme
app.UseForwardedHeaders();

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

app.UseHttpsRedirection();

// 2. Fail statik (CSS, JS, gambar) dilayan awal tanpa perlu lalu auth atau routing berat
app.UseStaticFiles();

app.UseRouting();

app.UseCors("AllowFrontend");

// 3. Authentication mesti sentiasa mendahului Authorization
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();
app.MapRazorPages();

app.Run();

Setiap kedudukan dalam kod di atas ada sebab teknikal yang jelas, dan rujukan rasmi dokumentasi middleware ASP.NET Core juga menekankan susunan ini untuk komponen terbina dalam.

Kesilapan susunan yang kerap berlaku di produksi

Sepanjang menyelenggara projek ASP.NET Core, ada beberapa pepijat klasik yang hampir semuanya berpunca daripada salah susunan middleware:

  • UseAuthorization() sebelum UseAuthentication(): Jika ini berlaku, middleware kebenaran cuba menilai polisi ([Authorize]) sebelum identiti pengguna (HttpContext.User) sempat dibina daripada cookie atau token JWT. Akibatnya, pengguna yang sudah log masuk dengan token sah tetap menerima 401 Unauthorized atau 403 Forbidden.
  • UseStaticFiles() diletakkan terlalu bawah atau selepas fallback auth: Jika aplikasi mewajibkan login secara global (contohnya melalui fallback policy) sebelum UseStaticFiles(), permintaan untuk /css/site.css atau /favicon.ico akan disekat dan dialihkan ke halaman /Account/Login. Halaman login itu sendiri akhirnya tampil tanpa gaya CSS.
  • Lupa UseForwardedHeaders() di awal paip: Apabila aplikasi ASP.NET Core berjalan dalam container Docker atau sebagai systemd service di belakang Nginx/Cloudflare, sambungan antara proxy dengan Kestrel selalunya menggunakan HTTP tempatan. Tanpa UseForwardedHeaders() di barisan paling atas, Request.Scheme kekal http, alamat IP pelanggan dibaca sebagai 127.0.0.1 (merosakkan rate limiting), dan URL callback OAuth/OpenID gagal kerana tidak sepadan dengan https://.
  • UseCors() diletakkan di luar julat UseRouting() dan endpoint: Dalam model routing endpoint ASP.NET Core, app.UseCors() mesti berada selepas app.UseRouting() dan sebelum app.UseAuthorization() serta app.MapControllers(). Jika diletakkan sebelum UseRouting(), polisi CORS mengikut endpoint tidak dapat dikuatkuasakan dengan betul.

Berhati-hati apabila menulis middleware sendiri

Apabila anda menulis middleware tersuai menggunakan app.Use(...) atau kelas berasingan dengan InvokeAsync(HttpContext context), ada dua peraturan praktikal yang wajib dijaga:

  1. Jangan ubah Response selepas await next(context) jika respons sudah mula dihantar: Sebaik sahaja endpoint mula menulis ke strim respons, context.Response.HasStarted menjadi true. Cuba menambah header atau menukar kod status selepas titik itu akan melemparkan InvalidOperationException.
  2. Jangan baca Request.Body sesuka hati: Strim badan permintaan hanya boleh dibaca sekali secara lalai. Jika middleware audit atau logging anda membaca Request.Body tanpa memanggil context.Request.EnableBuffering() dan menetapkan semula kedudukan strim (context.Request.Body.Position = 0), controller di bawah akan menerima payload kosong atau model binding gagal.

Cara paling cepat untuk mengesan masalah middleware bukan dengan meneka-neka nama method, tetapi dengan melukis perjalanan satu request sebenar di atas kertas: masuk dari IP mana, melalui fail statik atau tidak, di mana identiti dibaca, dan di mana keizinan disemak. Sebelum menggabungkan kod baharu ke produksi, uji sekurang-kurangnya tiga laluan asas — laluan berjaya dengan pengguna sah, laluan tanpa izin, dan permintaan fail statik — supaya paip aplikasi kekal terjamin.