Xử lý lỗi trong ASP.NET Core: đừng để API trả stack trace cho người lạ
Một bạn bên đối tác tích hợp gửi request thiếu một field, và nhận về một response 500 dài cả trang: nguyên stack trace, tên namespace, đường dẫn file trên server, và trong message của SqlException có luôn tên bảng lẫn tên server database. Bạn ấy chụp màn hình gửi lại, kèm một câu rất lịch sự: "Bên mình thấy hơi nhiều thông tin".
Nguyên nhân hoá ra đơn giản tới ngại: server mới dựng để biến môi trường ASPNETCORE_ENVIRONMENT=Development. Bài này là checklist mình chạy qua trước khi cho một API lên prod, mỗi mục kèm một ví dụ ngắn.
1. Prod không chạy ở môi trường Development
Với WebApplication, ở môi trường Development, ASP.NET Core tự bật trang lỗi chi tiết cho developer: stack trace, header, cookie, mọi thứ. Tiện lúc dev, thảm hoạ khi lên prod.
Kiểm tra biến ASPNETCORE_ENVIRONMENT (hoặc DOTNET_ENVIRONMENT) trên mọi môi trường chạy thật: server, container, pipeline deploy. Không đặt gì thì mặc định là Production, an toàn. Đặt sai thành Development thì như vụ trên.
2. Một chỗ duy nhất xử lý mọi exception
Từ .NET 8 có IExceptionHandler, gom việc bắt exception chưa xử lý về một nơi:
public class GlobalExceptionHandler(
ILogger<GlobalExceptionHandler> logger,
IProblemDetailsService problemDetails) : IExceptionHandler
{
public async ValueTask<bool> TryHandleAsync(
HttpContext context, Exception exception, CancellationToken ct)
{
// Chi tiết lỗi ghi vào log phía server, không gửi cho client
logger.LogError(exception, "Lỗi chưa xử lý tại {Path}", context.Request.Path);
context.Response.StatusCode = StatusCodes.Status500InternalServerError;
return await problemDetails.TryWriteAsync(new ProblemDetailsContext
{
HttpContext = context,
Exception = exception,
ProblemDetails =
{
Title = "Có lỗi xảy ra, vui lòng thử lại sau.",
Status = StatusCodes.Status500InternalServerError
}
});
}
}
// Program.cs
builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
app.UseExceptionHandler();
Response lỗi giờ theo chuẩn Problem Details (RFC 9457), client nào cũng parse được, và có sẵn field traceId. Client chỉ thấy "có lỗi" kèm một mã, còn chi tiết nằm trong log phía server, tìm theo đúng mã đó. Cách dùng traceId để lần theo một request mình viết kỹ ở bài về logging.
3. Lỗi nghiệp vụ không phải lỗi 500
Đơn không tồn tại không phải lỗi hệ thống. Hết hàng cũng không. Trả 500 cho mấy trường hợp này làm client tưởng server hỏng và retry, làm dashboard báo động giả, làm log đầy những thứ không cần ai xem.
Mình dùng mã lỗi theo đúng nghĩa:
400: request sai định dạng, thiếu field.404: không tìm thấy, hoặc không có quyền xem (lý do trả 404 thay vì 403 mình có viết ở bài bảo mật API cuối series).409: xung đột, ví dụ dữ liệu vừa bị người khác sửa.422: request đúng định dạng nhưng vi phạm luật nghiệp vụ, ví dụ đặt số lượng vượt tồn kho.
Trường hợp đã biết trước thì trả thẳng, không cần ném exception:
if (order is null)
return TypedResults.Problem("Không tìm thấy đơn hàng.", statusCode: StatusCodes.Status404NotFound);
if (order.Status == OrderStatus.Shipped)
return TypedResults.Problem("Đơn đã giao, không huỷ được nữa.", statusCode: StatusCodes.Status422UnprocessableEntity);
Nếu project đã có sẵn một bộ exception nghiệp vụ, đừng đập đi viết lại: map chúng sang mã lỗi ngay trong GlobalExceptionHandler, kiểu OrderNotFoundException thành 404, ConcurrencyConflictException thành 409. Chỉ cần đảm bảo những exception "không ai lường trước" mới rơi xuống 500.
4. Không nuốt exception
try
{
await _payment.ChargeAsync(order, ct);
}
catch (Exception)
{
// "Để lỗi không văng ra ngoài"
}
Đoạn này không xử lý lỗi, nó giấu lỗi. Thanh toán thất bại, code chạy tiếp như chưa có gì, đơn được đánh dấu đã thanh toán. Lỗi thật sẽ hiện ra ở một chỗ khác, vài ngày sau, dưới một hình dạng chẳng liên quan gì tới đoạn này.
Quy tắc của mình: chỉ catch exception mà mình biết xử lý thế nào ngay tại chỗ (retry, fallback, đổi sang một lỗi nghiệp vụ có nghĩa), và catch đúng loại exception đó. Còn lại để nó bay lên GlobalExceptionHandler, nơi nó được log đầy đủ.
5. Validate ở biên
Request đi vào là chỗ chặn dữ liệu sai rẻ nhất. Với controller có [ApiController], ASP.NET Core tự trả 400 kèm danh sách lỗi theo từng field khi model không hợp lệ:
public record CreateOrderRequest(
[Required] string ProductCode,
[Range(1, 100)] int Quantity,
[EmailAddress] string? ContactEmail);
Client nhận về một ValidationProblemDetails kiểu "errors": { "Quantity": ["The field Quantity must be between 1 and 100."] }, đủ để hiển thị lỗi ngay cạnh ô nhập. Minimal API thì từ .NET 10 mới có validation dựng sẵn (builder.Services.AddValidation()); bản cũ hơn mình dùng FluentValidation qua một endpoint filter.
Validation ở biên chỉ kiểm tra hình dạng của dữ liệu. Luật nghiệp vụ như "còn đủ hàng không", "voucher còn hạn không" vẫn nằm trong service, và vẫn cần constraint ở database làm chốt cuối.
6. Message lỗi không kể chuyện nội bộ
Đừng trả ex.Message về cho client. Message của SqlException có tên bảng, tên constraint. Message của exception khi đọc file có đường dẫn thư mục trên server. Mỗi mảnh đều là thông tin cho người muốn tấn công.
Client nhận một câu chung chung kèm traceId. Chi tiết nằm trong log, nơi chỉ người có quyền mới đọc được.
Thử ngay: gửi vài request cố tình sai vào API trên môi trường staging. Body rỗng, sai kiểu dữ liệu, id không tồn tại. Đọc kỹ từng response: có cái nào trả 500 trong khi đáng lẽ là 400 hay 404 không, có cái nào lộ stack trace hay tên bảng không. Rồi search catch (Exception) trong solution và đọc từng chỗ.
Bài sau là logging trong ASP.NET Core: lỗi trên prod mà không lần ra request nào, nối tiếp đúng chỗ bài này dừng: lỗi đã được log, giờ làm sao tìm ra nó. Bạn đang quy ước mã lỗi cho API thế nào? Comment cho mình biết với.
P.S. Mấy cái catch rỗng thường nằm im trong code cũ nhiều năm. Để lôi chúng ra, mình chạy skill code-quality-auditor trong PrimeKit, bộ skill mình tự làm, ở chế độ quét cả codebase. Skill tập trung vào bug, lỗi hồi quy và độ tin cậy, và mỗi phát hiện phải kèm bằng chứng trong code chứ không nói chung chung. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:code-quality-auditor trong Claude Code. Nó tìm ra chỗ đáng ngờ, còn chỗ nào thật sự nên bắt exception thì vẫn là bạn quyết.
All Rights Reserved