
Dalam banyak projek API yang dibina tergesa-gesa, pengendalian ralat selalunya terjatuh ke dalam salah satu daripada dua tabiat buruk ini. Sama ada pelayan memulangkan halaman ralat 500 lengkap dengan stack trace C#, nama pelayan pangkalan data, dan rentetan SQL kepada pengguna awam—yang merupakan kebocoran maklumat keselamatan—ataupun ia cuma memulangkan teks generik "An error occurred" untuk semua jenis kegagalan.
Kedua-duanya menyusahkan semua pihak. Pengguna tidak tahu apa yang perlu dibetulkan pada borang mereka, pembangun frontend terpaksa meneka format respons yang berubah-ubah antara satu endpoint dengan endpoint lain, dan pasukan sokongan pula tiada nombor rujukan untuk menyemak log pelayan apabila pelanggan mengadu “sistem tak boleh tekan hantar”.
Ralat API yang baik perlu memenuhi dua keperluan serentak: cukup berstruktur untuk membantu antaramuka UI memaparkan panduan yang jelas, dan cukup ketat agar tidak mendedahkan butiran dalaman pelayan di persekitaran produksi.
Gunakan piawaian ProblemDetails dalam ASP.NET Core
ASP.NET Core sudah menyokong format piawai Problem Details (application/problem+json, RFC 9457) secara terbina tanpa perlu memasang pustaka pihak ketiga yang berat. Anda hanya perlu mengaktifkannya dalam Program.cs bersama perisian tengah pengendalian pengecualian:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails(options =>
{
options.CustomizeProblemDetails = context =>
{
context.ProblemDetails.Extensions["traceId"] = context.HttpContext.TraceIdentifier;
};
});
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler();
}
app.UseStatusCodePages();
Dengan konfigurasi ringkas ini, walaupun ralat 404 Not Found atau 500 Internal Server Error berlaku di luar jangkaan, ASP.NET Core tetap memulangkan objek JSON yang seragam dan bukannya halaman HTML kosong atau stack trace mentah:
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Email": ["Format alamat e-mel tidak sah."],
"NoTelefon": ["Sila masukkan nombor telefon Malaysia yang sah."]
},
"traceId": "00-8f3c2a1b4d9e7c22a1b04e91f3d8a2c1-01"
}
Jika anda mahu memetakan pengecualian perniagaan sendiri—seperti NotFoundException atau ConflictException—tanpa menulis blok try/catch yang sama berulang kali dalam setiap Controller atau Minimal API, gunakan antara muka IExceptionHandler yang tersedia sejak .NET 8:
public sealed class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
{
public async ValueTask<bool> TryHandleAsync(
HttpContext httpContext,
Exception exception,
CancellationToken cancellationToken)
{
logger.LogError(exception, "Ralat tidak dijangka. TraceId: {TraceId}", httpContext.TraceIdentifier);
var (status, title) = exception switch
{
KeyNotFoundException => (StatusCodes.Status404NotFound, "Rekod yang diminta tidak ditemui."),
UnauthorizedAccessException => (StatusCodes.Status403Forbidden, "Anda tidak mempunyai kebenaran untuk tindakan ini."),
_ => (StatusCodes.Status500InternalServerError, "Ralat sistem berlaku. Sila cuba sebentar lagi.")
};
httpContext.Response.StatusCode = status;
await httpContext.Response.WriteAsJsonAsync(new ProblemDetails
{
Status = status,
Title = title,
Extensions = { ["traceId"] = httpContext.TraceIdentifier }
}, cancellationToken);
return true;
}
}
Jangan lupa daftarkannya dengan builder.Services.AddExceptionHandler<GlobalExceptionHandler>(); sebelum app.Build().
Bagaimana UI frontend memanfaatkan struktur ini
Apabila format ralat sentiasa konsisten, pasukan frontend (sama ada menggunakan React, Vue, Blazor, atau JavaScript biasa) tidak perlu lagi menulis logik tekaan untuk membaca mesej ralat. Medan errors boleh terus dipadankan dengan nama input pada borang supaya pengguna nampak amaran tepat di bawah kotak Email atau NoTelefon yang silap.
Untuk ralat 500 pula, traceId menjadi jambatan paling berguna antara pengguna dan pembangun. Antaramuka web boleh memaparkan mesej sopan seperti “Sistem menghadapi gangguan sementara. Jika masalah berterusan, kongsi kod rujukan 00-8f3c... kepada pasukan sokongan.” Di sebelah backend, pembangun cuma perlu cari kod traceId tersebut dalam fail log atau Application Insights untuk melihat keseluruhan stack trace sebenar dengan selamat.
Uji aliran gagal pada borang sebenar, bukan sekadar Postman
Menguji laluan berjaya (200 OK) dalam Swagger atau Postman memang mudah, tetapi kualiti API selalunya terserlah ketika berlaku kegagalan. Buka aplikasi anda melalui pelayar di telefon pintar, cuba hantar borang dengan medan wajib yang kosong, nombor invois pendua, atau rekod yang sudah dipadamkan.
Perhatikan dua perkara penting semasa ujian tersebut: pertama, pastikan data yang sudah penat ditaip oleh pengguna dalam medan lain tidak terpadam apabila pelayan memulangkan status 400 atau 422. Kedua, semak tab Network dalam DevTools untuk mengesahkan tiada nama jadual SQL Server, laluan fail pelayan (C:\inetpub\... atau /var/www/...), atau kunci konfigurasi yang terlepas keluar ke respons JSON. Apabila ralat diuruskan dengan kemas sejak awal, pengguna berasa lebih yakin dan proses nyahpepijat di produksi juga menjadi jauh lebih tenang.