
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()sebelumUseAuthentication(): 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 menerima401 Unauthorizedatau403 Forbidden.UseStaticFiles()diletakkan terlalu bawah atau selepas fallback auth: Jika aplikasi mewajibkan login secara global (contohnya melalui fallback policy) sebelumUseStaticFiles(), permintaan untuk/css/site.cssatau/favicon.icoakan 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 menggunakanHTTPtempatan. TanpaUseForwardedHeaders()di barisan paling atas,Request.Schemekekalhttp, alamat IP pelanggan dibaca sebagai127.0.0.1(merosakkan rate limiting), dan URL callback OAuth/OpenID gagal kerana tidak sepadan denganhttps://. UseCors()diletakkan di luar julatUseRouting()dan endpoint: Dalam model routing endpoint ASP.NET Core,app.UseCors()mesti berada selepasapp.UseRouting()dan sebelumapp.UseAuthorization()sertaapp.MapControllers(). Jika diletakkan sebelumUseRouting(), 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:
- Jangan ubah
Responseselepasawait next(context)jika respons sudah mula dihantar: Sebaik sahaja endpoint mula menulis ke strim respons,context.Response.HasStartedmenjaditrue. Cuba menambah header atau menukar kod status selepas titik itu akan melemparkanInvalidOperationException. - Jangan baca
Request.Bodysesuka hati: Strim badan permintaan hanya boleh dibaca sekali secara lalai. Jika middleware audit atau logging anda membacaRequest.Bodytanpa memanggilcontext.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.