Trong quá trình làm backend .NET, chúng tôi nhận ra exception gần như luôn tìm được đường xuất hiện, dù dự án nhỏ hay lớn. Một lỗi ở tầng dữ liệu có thể nổi lên thành lỗi 500 ở tầng API, và nếu không có chỗ xử lý tập trung, cả team lại phải lật log từng nơi. Vì vậy, khi nói đến xử lý lỗi thường gặp trong ASP.NET, middleware gần như luôn là lựa chọn đầu tiên của đội ngũ chúng tôi.
Bài viết này đi qua cách xây dựng middleware xử lý lỗi cho ASP.NET Core, từ nguyên lý hoạt động, vị trí đăng ký, cho tới những tình huống cụ thể mà chúng tôi từng gặp khi triển khai. Bạn sẽ thấy cách tiếp cận này giúp code gọn hơn, log rõ ràng hơn và API trả lỗi nhất quán hơn.
Vì sao middleware phù hợp để xử lý lỗi trong ASP.NET
Cách truyền thống là đặt try/catch ở từng controller hoặc service. Cách này không sai, nhưng code dễ phình to và thiếu đồng nhất. Mỗi lập trình viên trong team có thể bắt lỗi theo một kiểu khác nhau, khiến response gửi về client không còn thống nhất.
Middleware giải quyết vấn đề đó bằng cách chặn lỗi ở một điểm duy nhất trong pipeline. Dù lỗi phát sinh từ controller, service hay tầng truy cập dữ liệu, request vẫn phải đi qua middleware trước khi trả về client. Logic chỉ cần viết một lần và áp dụng cho toàn bộ ứng dụng.
Chúng tôi từng làm một dự án với hơn hai mươi controller, mỗi nơi tự viết catch riêng. Khi khách hàng báo lỗi 500 xuất hiện ngẫu nhiên, việc lần theo log mất gần cả buổi vì mỗi nơi ghi một kiểu. Sau khi chuyển sang middleware tập trung, thời gian debug giảm rõ rệt, vì mọi lỗi đều đi qua một chỗ và được ghi theo cùng một định dạng.
Middleware nằm ở đâu trong pipeline của ASP.NET
ASP.NET xử lý request như một chuỗi middleware nối tiếp. Request đi vào từ đầu, qua từng middleware, tới controller, rồi đi ngược lại để trả response. Hiểu được chiều đi và chiều về là bước đầu tiên để đặt middleware xử lý lỗi đúng chỗ.
Vị trí đăng ký rất quan trọng. Chúng tôi thường đặt middleware xử lý lỗi gần đầu pipeline, ngay sau các middleware ghi log request cơ bản. Lý do là nó phải bọc mọi thứ phía sau thì mới bắt được exception phát sinh trong quá trình xử lý.
Nếu đặt ở cuối pipeline, middleware sẽ không thấy lỗi từ những middleware đứng trước. Đây là sai lầm khá phổ biến ở các bạn mới làm quen với ASP.NET Core, và thường chỉ được phát hiện khi đã có sự cố ngoài production.
Viết middleware xử lý lỗi từ đầu
Tạo class middleware riêng để bắt exception
Cách phổ biến nhất là tạo một class có phương thức InvokeAsync nhận HttpContext và delegate next. Bên trong, bọc lệnh gọi next bằng try/catch. Khi có exception, khối catch sẽ ghi log, rồi tự tạo response lỗi thay vì để lỗi thoát ra ngoài.
Cách viết này cho bạn toàn quyền kiểm soát vòng đời của lỗi. Bạn quyết định status code, thông điệp trả về người dùng, và có đính kèm thông tin debug hay không tùy môi trường đang chạy.
Dùng UseExceptionHandler có sẵn
Nếu không muốn viết middleware từ đầu, ASP.NET Core đã có sẵn UseExceptionHandler. Bạn khai báo một route xử lý lỗi, chẳng hạn /error, rồi viết endpoint trả về response chuẩn hóa. Cách này nhanh và đủ dùng cho dự án không có logic lỗi quá phức tạp.
Đội ngũ chúng tôi thường chuyển sang middleware riêng khi cần phân loại lỗi chi tiết: lỗi validation trả 400, không tìm thấy dữ liệu trả 404, còn lỗi hệ thống mới trả 500. UseExceptionHandler mặc định thường xử lý mọi lỗi như nhau, nên muốn phân loại kỹ bạn phải tùy biến thêm.
Ngoài middleware, nhiều đội hiện nay còn tích hợp trợ lý AI để hỗ trợ debug nhanh hơn. Chúng tôi có ghi lại kinh nghiệm khi đưa AI vào kiến trúc chatbot dành cho đội ngũ developer, nếu bạn quan tâm hướng đi này.
Các lỗi thường gặp và cách middleware xử lý từng loại
Không phải lỗi nào cũng nên xử lý giống nhau. Dưới đây là những loại lỗi chúng tôi gặp nhiều nhất khi vận hành ASP.NET, cùng cách xử lý riêng cho từng loại.
- NullReferenceException: thường xảy ra khi dữ liệu từ database hoặc request body thiếu trường bắt buộc. Ở môi trường development, middleware ghi đầy đủ stack trace; ở production chỉ trả thông báo chung để không lộ cấu trúc code.
- DbUpdateException từ Entity Framework: xuất hiện khi vi phạm ràng buộc dữ liệu, ví dụ trùng khóa chính. Chúng tôi bắt riêng loại này, trả mã 400 kèm thông điệp dễ hiểu, tránh để lỗi SQL gốc lộ ra ngoài.
- Lỗi validation từ model binding khi request thiếu trường hoặc sai định dạng. Middleware gom toàn bộ lỗi thành một danh sách và trả một lần, thay vì báo rời rạc từng field.
- Timeout khi gọi service bên ngoài: middleware ghi rõ endpoint nào bị timeout và trả mã 503, để client hiểu đây là lỗi tạm thời và có thể thử lại.
- Không tìm thấy route hoặc tài nguyên: chuyển về một response 404 thống nhất, thay vì trang lỗi mặc định khó đọc của ASP.NET.
Điểm chung của các trường hợp này là giữ đầy đủ thông tin cho lập trình viên trong log, nhưng chỉ đưa ra ngoài những gì client thực sự cần biết.
Chuẩn hóa response lỗi để frontend dễ xử lý
Khi viết middleware, việc format response phải nhất quán là thứ chúng tôi coi trọng nhất. Frontend và các bên thứ ba gọi API sẽ đỡ vất vả hơn nhiều nếu mọi lỗi đều có cùng cấu trúc JSON, dù là 400 hay 500.
ASP.NET Core có sẵn chuẩn ProblemDetails theo RFC 7807, gồm các trường title, status, detail và instance. Đội ngũ thường mở rộng thêm trường errorCode riêng, để frontend ánh xạ sang thông báo phù hợp cho người dùng cuối, thay vì hiển thị nguyên văn message tiếng Anh từ backend.
Trong một dự án thương mại điện tử chúng tôi từng tham gia, đội frontend liên tục phàn nàn vì mỗi endpoint trả lỗi một kiểu. Sau khi áp dụng middleware chuẩn hóa, số bug liên quan đến xử lý lỗi phía frontend giảm rõ rệt chỉ trong vài tuần.
Ghi log đúng cách để không phải đoán khi sự cố xảy ra
Middleware xử lý lỗi cũng là nơi lý tưởng để ghi log tập trung. Chúng tôi thường tiêm ILogger vào middleware và ghi đủ thông tin: đường dẫn request, phương thức HTTP, thời điểm xảy ra và toàn bộ stack trace.
Một mẹo nhỏ chúng tôi luôn áp dụng là gắn correlation ID cho mỗi request, sinh ra ngay đầu pipeline. Khi có lỗi, log sẽ mang mã này, giúp lần theo hành trình của một request cụ thể, kể cả khi nó đi qua nhiều service.
Khi cần viết lại tài liệu vận hành hay runbook xử lý sự cố cho gọn hơn, chúng tôi từng chia sẻ về cách chọn công cụ AI hỗ trợ biên soạn tài liệu kỹ thuật. Bạn có thể tham khảo thêm để tiết kiệm thời gian viết tài liệu.
Lưu ý khi triển khai middleware ở môi trường production
Một sai lầm phổ biến là để middleware trả nguyên stack trace cho client, kể cả ở production. Điều này vô tình để lộ cấu trúc code, tên bảng database, thậm chí đường dẫn file trên server, tạo cơ hội cho kẻ xấu khai thác.
Chúng tôi luôn kiểm tra biến môi trường trước khi quyết định mức độ chi tiết của response lỗi. Ở development, middleware trả đầy đủ message và stack trace để debug nhanh. Ở production, response chỉ chứa thông điệp chung và một mã tham chiếu, còn chi tiết đầy đủ được ghi vào log nội bộ.
Một lưu ý khác là đừng để chính middleware xử lý lỗi ném ra exception. Chúng tôi từng gặp trường hợp middleware serialize một object có tham chiếu vòng khi ghi log, khiến nó crash và kéo theo cả request. Vì vậy, middleware cần được test kỹ bằng nhiều loại exception giả lập trước khi đưa lên production.
Kinh nghiệm khi triển khai cho hệ thống nhiều microservice
Có một dự án gồm năm microservice viết bằng ASP.NET Core mà đội ngũ chúng tôi từng hỗ trợ tái cấu trúc. Ban đầu mỗi service tự viết middleware riêng, không theo chuẩn chung, khiến việc tổng hợp log qua các service rất khó khăn.
Chúng tôi quyết định đóng gói middleware thành một thư viện NuGet dùng chung. Mỗi service chỉ cần cài package và đăng ký một dòng trong Program.cs là có ngay khả năng bắt lỗi, chuẩn hóa response và ghi log đúng định dạng.
Kết quả là khi có sự cố ở bất kỳ service nào, đội vận hành chỉ cần tra theo correlation ID để thấy toàn bộ hành trình request, không phải hỏi từng team cách họ viết code. Nếu bạn đang cân nhắc tự động hóa nhiều hơn trong hệ thống nội bộ, chúng tôi cũng có bài phân tích về kiến trúc agent trong quản trị nội bộ, khá liên quan đến cách tổ chức các service giao tiếp với nhau.
Xử lý lỗi bằng middleware không phải kỹ thuật quá cao siêu, nhưng quyết định rất nhiều đến trải nghiệm vận hành lâu dài. Chỉ cần đặt đúng middleware ở đầu pipeline, phân loại lỗi rõ ràng và ghi log đầy đủ, bạn đã tiết kiệm được nhiều thời gian debug về sau.
Theo kinh nghiệm của đội ngũ, khoản đầu tư nhỏ để chuẩn hóa xử lý lỗi ngay từ đầu dự án luôn đáng giá hơn nhiều so với việc chắp vá khi hệ thống đã phình to. Hy vọng những chia sẻ trong bài giúp bạn tự tin hơn khi xây middleware cho dự án ASP.NET của mình.


