Xử lý lỗi thường gặp trong ASP.NET hiếm khi nằm đúng chỗ bạn nghĩ tới đầu tiên. Chúng tôi từng mất gần nửa ngày chỉ để tìm ra nguyên nhân, và thủ phạm lại là một dòng đăng ký middleware tưởng chừng vô hại. Chuyện này lặp lại khá nhiều lần, nên chúng tôi muốn ghi lại thành kinh nghiệm để bạn đỡ phải đi vòng.
Một lần thêm middleware xác thực làm cả hệ thống đứng hình
Đội ngũ bên mình từng tiếp nhận một dự án ASP.NET Core chạy ổn định suốt nhiều tháng. Không có sự cố lớn nào. Mọi thứ êm ru cho tới khi cần phục vụ thêm một client mobile mới. Lúc đó, chúng tôi bổ sung middleware xác thực JWT vào pipeline.
Ngay sau khi deploy, toàn bộ endpoint cũ bỗng trả về 401. Request gửi lên vẫn hợp lệ. Token vẫn còn hạn. Vậy mà hệ thống vẫn từ chối. Cảm giác lúc đó khá khó chịu, vì mọi thứ nhìn qua đều đúng.
Chúng tôi soi kỹ cấu hình JWT: issuer, audience, khóa ký. Kiểm tra xong lại kiểm tra thêm lần nữa. Mãi sau mới thấy vấn đề nằm ở chỗ khác hoàn toàn. Middleware mới được đăng ký sai vị trí trong pipeline, đứng trước bước làm việc mà nó cần phục vụ.
Đây là kiểu lỗi mà rất nhiều bạn mới làm quen với ASP.NET Core dễ gặp. Ta thường nghĩ chỉ cần gọi đúng phương thức đăng ký là xong. Thực tế, cách gọi đúng mà đặt sai chỗ vẫn cho ra kết quả sai.
Vì sao thứ tự middleware quyết định mọi thứ
Middleware trong ASP.NET Core chạy theo mô hình pipeline tuần tự. Mỗi request đi qua các bước theo đúng thứ tự bạn đăng ký trong Program.cs. Bước nào đứng trước sẽ xử lý trước, và bước sau chỉ nhận được những gì bước trước để lại.
Vì vậy thứ tự không phải chi tiết phụ. Chỉ cần lệch một bước, luồng xác thực có thể sụp đổ. Thông báo lỗi trả về thường khá chung chung, nên rất khó đoán nguyên nhân thật sự nếu chỉ nhìn bề ngoài.
Lấy một ví dụ cụ thể. Nếu UseAuthorization nằm trước UseAuthentication, hệ thống sẽ kiểm tra quyền khi người dùng chưa hề được nhận diện. Kết quả là người dùng đã đăng nhập đúng vẫn bị chặn. Từ phía client, bạn chỉ thấy một con số 401 khó hiểu.
Các lỗi thường gặp trong ASP.NET liên quan middleware và authentication
Đăng ký sai thứ tự khiến lỗi khó nhận ra
Đây là nguyên nhân phổ biến nhất mà chúng tôi gặp khi debug các dự án vừa thêm middleware xác thực. Về nguyên tắc, UseAuthentication phải đứng trước UseAuthorization. Cả hai cần đứng trước middleware định tuyến tới controller.
Lý do khá rõ ràng. Nếu request tới controller trước khi thông tin người dùng được xác thực đầy đủ, hệ thống coi người dùng là chưa đăng nhập. Bạn nhận về lỗi từ chối truy cập dù token và cấu hình đều đúng. Khi hệ thống có nhiều lớp xử lý, việc hiểu từng tầng phối hợp với nhau càng quan trọng. Nếu muốn hình dung rõ hơn cách sắp xếp các tầng này, bạn có thể tham khảo cách thiết kế API layer để dữ liệu chạy mượt.
Token hết hạn và CORS dễ bị nhầm lẫn
Token hết hạn và CORS chặn request là hai lỗi hay bị nhầm nguyên nhân nhất. Cả hai đều có thể khiến trình duyệt báo lỗi na ná nhau, nên dev dễ mất thời gian đoán sai hướng.
CORS thường hiện thông báo trên console của trình duyệt, không nằm rõ ràng ở tab mạng. Nếu chỉ nhìn mã trạng thái HTTP, bạn rất dễ tưởng nhầm đó là lỗi xác thực. Ngược lại, token hết hạn hay bị bỏ qua vì ta mặc định token vừa cấp vẫn còn hiệu lực. Điều này đặc biệt hay xảy ra khi thời gian sống của token được cấu hình ngắn hơn bạn tưởng.
Dưới đây là các triệu chứng và nguyên nhân mà chúng tôi thường kiểm tra đầu tiên.
| Triệu chứng | Nguyên nhân thường gặp |
|---|---|
| Lỗi 401 dù đã đăng nhập | Middleware xác thực đăng ký sai thứ tự |
| Request bị chặn trên trình duyệt | CORS chưa cho phép domain của client, thông báo nằm ở console |
| Đột nhiên mất quyền truy cập | Token đã hết hạn, client chưa kịp refresh |
Cách khoanh vùng lỗi middleware nhanh hơn khi debug
Thay vì đọc lại toàn bộ pipeline rồi đoán mò, chúng tôi thường bắt đầu bằng cách tạm thời tắt từng middleware một. Nên bắt đầu với middleware vừa mới thêm vào, vì đó thường là thủ phạm.
Sau mỗi lần tắt, chạy lại request và quan sát kết quả. Nếu lỗi biến mất khi bỏ một middleware nào đó, bạn đã có hướng xử lý rõ ràng. Cách này nhanh hơn nhiều so với tin vào thông báo chung chung, vì thông báo đó không phải lúc nào cũng chỉ đúng nguyên nhân gốc.
Ghi log chi tiết tại từng middleware trong giai đoạn debug cũng rất đáng làm. Log cho bạn biết request dừng lại ở bước nào. Nếu chỉ biết request thất bại mà không rõ thất bại ở đâu, bạn sẽ tốn thời gian gấp nhiều lần.
Nếu nhóm đã có quy trình review code trước khi merge, hãy cân nhắc đưa việc kiểm tra thứ tự middleware vào checklist. Bạn cũng nên rà lại top 10 sai lầm thường gặp về backend development khi làm .NET để soát những lỗi hay lặp lại trong quá trình phát triển backend.
Quy trình kiểm tra trước khi thêm middleware mới
Trước khi đưa middleware mới vào, hãy dành vài phút xác nhận vị trí đăng ký có hợp lý với các middleware đang có. Chú ý đặc biệt đến mối quan hệ giữa xác thực, phân quyền và định tuyến. Kiểm tra lại CORS đã cho đúng domain của client chưa, và thời gian sống của token có khớp với nhu cầu thực tế không.
Sau mỗi lần thay đổi pipeline, hãy test lại các endpoint quan trọng. Đội ngũ bên mình thường viết sẵn vài test case xác thực cơ bản: gọi endpoint yêu cầu đăng nhập với token hợp lệ, với token đã hết hạn, và không có token. Chạy lại bộ test này mỗi khi pipeline thay đổi.
Nhờ vậy, hồi quy được phát hiện ngay trong quá trình phát triển, thay vì chờ người dùng báo lỗi mới biết pipeline đã bị ảnh hưởng. Khi đã nắm chắc thứ tự middleware, phân biệt được các lỗi dễ nhầm và có quy trình debug rõ ràng, bạn sẽ xử lý lỗi authentication trong ASP.NET nhanh hơn rất nhiều. Chúc bạn debug suôn sẻ.
