Phân loại lỗi cho ứng dụng doanh nghiệp: UI và giám sát nhất quán

Vấn đề mà một phân loại lỗi giải quyết trong ứng dụng doanh nghiệp thực tế

Phân loại lỗi là cách chung để đặt tên và nhóm lỗi để mọi người xử lý chúng theo cùng một cách. Thay vì mỗi màn hình và API tự tạo thông báo của riêng họ, bạn định nghĩa một tập nhỏ các category (như validation hay auth) và các quy tắc về cách chúng xuất hiện với người dùng và trong giám sát.

Nếu không có cấu trúc chung đó, cùng một vấn đề xuất hiện dưới nhiều dạng khác nhau. Một trường bắt buộc bị thiếu có thể hiển thị là “Bad Request” trên mobile, “Có lỗi xảy ra” trên web, và một stack trace trong logs. Người dùng không biết phải làm gì tiếp theo, và đội on-call lãng phí thời gian đoán xem đó là lỗi người dùng, tấn công hay sự cố toàn hệ thống.

Mục tiêu là nhất quán: cùng loại lỗi dẫn tới hành vi UI giống nhau và hành vi cảnh báo giống nhau. Vấn đề validation nên chỉ ra chính xác trường bị lỗi. Vấn đề quyền hạn nên chặn hành động và giải thích quyền truy cập còn thiếu. Lỗi phụ thuộc nên đề nghị retry an toàn, trong khi giám sát bật cảnh báo đúng đội chịu trách nhiệm.

Một ví dụ thực tế: một nhân viên bán hàng cố tạo hồ sơ khách hàng nhưng dịch vụ thanh toán đang bị sự cố. Nếu app trả về 500 chung chung, họ sẽ thử lại và có thể tạo trùng sau đó. Với một category rõ ràng là dependency-failure, UI có thể thông báo dịch vụ tạm thời không khả dụng, ngăn gửi trùng, và giám sát có thể đánh thức đúng đội.

Sự thống nhất này quan trọng nhất khi một backend cung cấp cho nhiều client. Nếu API, web app, mobile app và công cụ nội bộ cùng dựa vào các category và mã giống nhau, sự cố sẽ bớt cảm giác ngẫu nhiên.

Mô hình đơn giản: category, code, message, details

Taxonomy dễ quản lý hơn khi bạn tách bốn thứ thường bị trộn lẫn: category (loại vấn đề), code (mã định danh ổn định), message (văn bản cho con người), và details (ngữ cảnh có cấu trúc). HTTP status vẫn quan trọng, nhưng không nên là toàn bộ câu chuyện.

Category trả lời: “UI và giám sát nên hành vi thế nào?” Một 403 có thể là “auth” ở chỗ này, trong khi một 403 khác có thể là “policy” nếu sau này bạn thêm quy tắc. Category nói về hành vi, không phải transport.

Code trả lời: “Chính xác đã xảy ra chuyện gì?” Code nên ổn định và nhàm chán. Nếu bạn đổi tên một nút hoặc refactor dịch vụ, code không nên thay đổi. Dashboard, cảnh báo và script hỗ trợ phụ thuộc vào điều này.

Message trả lời: “Chúng ta nói gì với người dùng?” Quyết định ai là đối tượng của message. Message hướng tới người dùng nên ngắn và lịch sự. Message cho hỗ trợ có thể bao gồm bước tiếp theo. Logs có thể kỹ thuật hơn.

Details trả lời: “Chúng ta cần gì để sửa?” Giữ details có cấu trúc để UI phản ứng được. Với lỗi form, đó có thể là tên trường. Với lỗi phụ thuộc, đó có thể là tên dịch vụ upstream và giá trị retry-after.

Đây là cấu trúc gọn nhiều đội thường dùng:

{
  "category": "validation",
  "code": "CUSTOMER_EMAIL_INVALID",
  "message": "Enter a valid email address.",
  "details": { "field": "email", "rule": "email" }
}

Khi tính năng thay đổi, giữ category nhỏ và ổn định, và thêm code mới thay vì tái sử dụng code cũ. Điều đó giữ cho hành vi UI, xu hướng giám sát và playbook hỗ trợ đáng tin cậy khi sản phẩm phát triển.

Các category cốt lõi: validation, auth, rate limits, dependencies

Hầu hết ứng dụng doanh nghiệp có thể bắt đầu với bốn category xuất hiện khắp nơi. Nếu bạn đặt tên và xử lý chúng giống nhau trên backend, web và mobile, UI sẽ phản ứng nhất quán và giám sát trở nên dễ đọc.

Validation (mong đợi)

Lỗi validation xảy ra khi dữ liệu người dùng hoặc quy tắc nghiệp vụ không thỏa. Đây là chuyện bình thường và nên dễ sửa: trường bắt buộc thiếu, định dạng không hợp lệ, hoặc quy tắc như “discount không vượt quá 20%” hoặc “tổng đơn hàng phải > $0”. UI nên tô chính xác trường hoặc quy tắc, không hiện alert chung chung.

Xác thực và phân quyền (mong đợi)

Lỗi auth thường chia thành hai trường hợp: chưa xác thực (chưa đăng nhập, session hết hạn, token thiếu) và không có quyền (đã đăng nhập nhưng thiếu quyền). Xử lý khác nhau. “Vui lòng đăng nhập lại” phù hợp với trường hợp đầu. Với trường hợp thứ hai, tránh tiết lộ chi tiết nhạy cảm, nhưng vẫn rõ ràng: “Bạn không có quyền duyệt hóa đơn.”

Giới hạn tốc độ (mong đợi, nhưng theo thời gian)

Rate limiting nghĩa là “quá nhiều yêu cầu, thử lại sau.” Nó thường xuất hiện khi import, dashboard bận, hoặc retry lặp lại. Bao gồm gợi ý retry-after (dù chỉ là “chờ 30 giây”), và để UI tự giảm tần suất thay vì đập server.

Lỗi phụ thuộc (thường bất ngờ)

Lỗi phụ thuộc đến từ dịch vụ upstream, timeout, hoặc outage: nhà cung cấp thanh toán, email/SMS, database, hoặc dịch vụ nội bộ. Người dùng không thể sửa mấy thứ này, nên UI nên đề nghị fallback an toàn (lưu nháp, thử sau, liên hệ hỗ trợ).

Sự khác biệt chính là hành vi: lỗi mong đợi là một phần của luồng bình thường và cần phản hồi chính xác; lỗi bất ngờ báo hiệu không ổn định và nên kích hoạt cảnh báo, correlation ID và log cẩn thận.

Bước từng bước: xây taxonomy trong một workshop

Taxonomy nên đủ nhỏ để nhớ, nhưng đủ nghiêm để hai đội đều dán nhãn cùng một vấn đề giống nhau.

1) Giới hạn thời gian và chọn một tập nhỏ

Bắt đầu với workshop 60–90 phút. Liệt kê các lỗi thấy nhiều nhất (input sai, vấn đề đăng nhập, quá nhiều yêu cầu, outage bên thứ ba, bug bất ngờ), rồi gom chúng vào 6–12 category mà mọi người có thể đọc to mà không cần mở tài liệu.

2) Đồng ý một quy ước tên mã ổn định

Chọn mẫu đặt tên dễ đọc trong logs và ticket. Giữ ngắn, tránh số phiên bản, và coi code là cố định khi đã phát hành. Mẫu phổ biến là tiền tố category + slug rõ ràng, ví dụ AUTH_INVALID_TOKEN hoặc DEP_PAYMENT_TIMEOUT.

Trước khi rời phòng, quyết định mọi lỗi phải bao gồm gì: category, code, message an toàn, details có cấu trúc, và trace hoặc request ID.

3) Viết một quy tắc cho category vs code

Các đội thường vướng khi category trở thành nơi chứa mọi thứ. Một quy tắc đơn giản giúp: category trả lời “UI và monitoring nên phản ứng thế nào?”, code trả lời “Chính xác đã xảy ra chuyện gì?”. Nếu hai lỗi cần hành vi UI khác nhau, chúng không nên chia sẻ category.

4) Đặt hành vi UI mặc định theo category

Quyết định người dùng thấy gì theo mặc định. Validation tô trường. Auth dẫn tới sign-in hoặc hiển thị thông báo truy cập. Rate limit hiện “thử lại sau X giây”. Lỗi phụ thuộc hiện màn hình retry điềm tĩnh. Khi có các mặc định này, tính năng mới có thể tuân theo thay vì tạo xử lý riêng lẻ.

5) Thử với kịch bản thực tế

Chạy năm luồng phổ biến (signup, checkout, tìm kiếm, sửa admin, upload file) và dán nhãn mọi thất bại. Nếu nhóm tranh luận, thường bạn cần một quy tắc rõ ràng hơn, không phải thêm hai mươi mã mới.

Lỗi validation: làm cho người dùng có thể hành động

Validation là loại lỗi bạn thường muốn hiển thị ngay. Nó nên dự đoán được: nói người dùng phải sửa gì, và không bao giờ kích hoạt vòng retry.

Validation ở cấp trường và cấp form là hai vấn đề khác nhau. Lỗi cấp trường gán cho một input (email, phone, amount). Lỗi cấp form là về tổ hợp input (ngày bắt đầu phải trước ngày kết thúc) hoặc thiếu tiền đề (chưa chọn phương thức vận chuyển). Phản hồi API nên làm rõ sự khác biệt để UI phản ứng đúng.

Một lỗi quy tắc nghiệp vụ phổ biến là “vượt hạn mức tín dụng”. Người dùng có thể nhập số hợp lệ, nhưng hành động không được phép theo trạng thái tài khoản. Xử lý như lỗi validation cấp form với lý do rõ ràng và gợi ý an toàn, ví dụ “Hạn mức khả dụng của bạn là $500. Giảm số tiền hoặc yêu cầu tăng hạn mức.” Tránh lộ tên nội bộ như tên trường database, mô hình scoring hoặc bước engine.

Phản hồi có thể hành động thường bao gồm một mã ổn định (không chỉ câu tiếng Anh), một message thân thiện với người dùng, con trỏ trường tùy chọn cho lỗi cấp trường, và gợi ý an toàn nhỏ (ví dụ ví dụ định dạng, phạm vi cho phép). Nếu cần tên quy tắc cho kỹ sư, đặt nó trong log, không phải UI.

Log lỗi validation khác với lỗi hệ thống. Ghi đủ ngữ cảnh để debug xu hướng mà không lưu dữ liệu nhạy cảm. Ghi user ID, request ID, tên quy tắc hoặc mã, và trường nào lỗi. Với giá trị, chỉ log những gì cần (thường “có/không” hoặc độ dài) và che dữ liệu nhạy cảm.

Trong UI, tập trung vào sửa, không retry. Tô trường, giữ lại dữ liệu người dùng đã nhập, cuộn tới lỗi đầu tiên và vô hiệu hóa retry tự động. Lỗi validation không phải tạm thời, nên “thử lại” là lãng phí thời gian.

Lỗi xác thực và phân quyền: giữ an ninh và rõ ràng

Lỗi xác thực và phân quyền giống nhau với người dùng, nhưng khác nhau về bảo mật, luồng UI và giám sát. Tách chúng ra giúp hành vi nhất quán trên web, mobile và API.

Unauthenticated nghĩa app không xác minh được ai là người dùng. Nguyên nhân thường là thiếu thông tin đăng nhập, token không hợp lệ, hoặc session hết hạn. Forbidden nghĩa người dùng đã biết danh tính nhưng không được phép thực hiện hành động.

Session hết hạn là trường hợp phổ biến nhất. Nếu bạn hỗ trợ refresh token, thử silent refresh một lần, rồi retry request gốc. Nếu refresh thất bại, trả về lỗi unauthenticated và chuyển người dùng tới sign-in. Tránh vòng lặp: sau một lần refresh, dừng và hiển thị bước tiếp theo rõ ràng.

Hành vi UI nên dự đoán được:

• Unauthenticated: yêu cầu đăng nhập và giữ lại tác vụ người dùng đang làm
• Forbidden: ở nguyên trang và hiển thị thông báo truy cập, kèm hành động an toàn như “yêu cầu quyền”
• Tài khoản bị vô hiệu hoặc bị thu hồi: đăng xuất và hiển thị thông báo ngắn rằng hỗ trợ có thể giúp

Về auditing, log đủ để trả lời “ai cố làm gì và tại sao bị chặn” mà không lộ bí mật. Một bản ghi hữu ích gồm user ID (nếu biết), tenant hoặc workspace, tên hành động, định danh tài nguyên, timestamp, request ID và kết quả kiểm tra chính sách (allowed/denied). Giữ token thô và mật khẩu ngoài logs.

Trong thông điệp cho người dùng, đừng tiết lộ tên vai trò, quy tắc quyền hoặc cấu trúc chính sách nội bộ. “Bạn không có quyền duyệt hóa đơn” an toàn hơn “Chỉ FinanceAdmin mới có quyền duyệt hóa đơn.”

Lỗi giới hạn tốc độ: hành vi dự đoán khi tải cao

Rate limits không phải là bug. Đó là hàng rào an toàn. Xử lý chúng như một category hạng một để UI, logs và cảnh báo phản ứng nhất quán khi traffic tăng vọt.

Rate limit thường xuất hiện dưới vài dạng: theo người dùng (một người click quá nhanh), theo IP (nhiều người dùng qua một mạng văn phòng), hoặc theo API key (một job tích hợp chạy lỗi). Nguyên nhân quan trọng vì cách sửa khác nhau.

Gì nên có trong phản hồi rate-limit tốt

Client cần hai thứ: biết họ bị giới hạn, và khi nào thử lại. Trả về HTTP 429 kèm thời gian chờ rõ ràng (ví dụ Retry-After: 30). Cũng bao gồm mã lỗi ổn định (ví dụ RATE_LIMITED) để dashboard có thể nhóm sự kiện.

Giữ message bình tĩnh và cụ thể. “Quá nhiều yêu cầu” đúng nhưng không giúp. “Vui lòng chờ 30 giây rồi thử lại” đặt kỳ vọng và giảm nhấp lặp.

Phía UI, ngăn retry nhanh. Mẫu đơn giản là vô hiệu hóa hành động trong khoảng chờ, hiển thị đồng hồ đếm ngắn, rồi cho phép một lần retry an toàn khi hết giờ. Tránh ngôn từ khiến người dùng nghĩ dữ liệu đã mất.

Giám sát là nơi các đội thường phản ứng quá mức. Đừng gọi trực tiếp cho ai vì mỗi 429. Theo dõi tỉ lệ và cảnh báo khi có spike bất thường: tăng đột ngột ở một endpoint, tenant hoặc API key là có thể hành động.

Phía backend cũng nên có hành vi dự đoán. Dùng exponential backoff cho retry tự động, và làm cho retry idempotent. Hành động “Tạo hóa đơn” không nên tạo hai hóa đơn nếu request đầu thực sự đã thành công.

Lỗi phụ thuộc: xử lý outage mà không gây hỗn loạn

Lỗi phụ thuộc là thứ người dùng không thể sửa bằng cách nhập đúng. Người dùng làm mọi thứ đúng, nhưng gateway thanh toán timeout, kết nối database rớt, hoặc dịch vụ upstream trả 5xx. Xử lý chúng như một category riêng để UI và giám sát phản ứng dự đoán.

Bắt đầu bằng đặt tên các dạng thất bại phổ biến: timeout, lỗi kết nối (DNS, TLS, refused), và upstream 5xx (bad gateway, service unavailable). Dù bạn không biết nguyên nhân gốc, bạn vẫn có thể ghi lại điều đã xảy ra và phản ứng nhất quán.

Retry hay fail fast

Retry hữu ích với sự cố ngắn, nhưng cũng có thể làm tồi tệ thêm outage. Dùng quy tắc đơn giản để mọi đội đều quyết định giống nhau.

• Retry khi lỗi có khả năng tạm thời: timeout, connection reset, 502/503
• Fail fast với trường hợp người dùng gây ra hoặc vĩnh viễn: 4xx từ dependency, credential sai, resource không tồn tại
• Giới hạn retry (ví dụ 2–3 lần) và thêm backoff nhỏ
• Không bao giờ retry hành động không idempotent trừ khi có idempotency key

Hành vi UI và fallback an toàn

Khi dependency lỗi, nói người dùng có thể làm gì tiếp theo mà không đổ lỗi cho họ: “Sự cố tạm thời. Vui lòng thử lại.” Nếu có fallback an toàn, đề nghị nó. Ví dụ: nếu Stripe sập, cho phép người dùng lưu đơn hàng ở trạng thái “Pending payment” và gửi email xác nhận thay vì mất giỏ hàng.

Cũng bảo vệ người dùng khỏi gửi hai lần. Nếu họ nhấn “Pay” hai lần trong khi phản hồi chậm, hệ thống nên nhận ra. Dùng idempotency key cho luồng tạo và charge, hoặc kiểm tra trạng thái như “order đã được thanh toán” trước khi thực hiện lại.

Với giám sát, log các trường trả lời câu hỏi nhanh: “Dependency nào đang lỗi, và mức độ tệ ra sao?” Ghi tên dependency, endpoint hoặc thao tác, thời lượng, và kết quả cuối cùng (timeout, connect, upstream 5xx). Điều này làm cho cảnh báo và dashboard có ý nghĩa hơn thay vì ồn ào.

Đảm bảo giám sát và UI nhất quán giữa các kênh

Taxonomy chỉ hoạt động khi mọi kênh nói cùng một ngôn ngữ: API, web UI, mobile app và logs. Nếu không, cùng một vấn đề sẽ xuất hiện thành năm thông báo khác nhau, và không ai biết đó là lỗi người dùng hay sự cố thật.

Đối xử với HTTP status như lớp phụ trợ. Chúng hữu ích với proxy và hành vi client cơ bản, nhưng category và code nên mang ý nghĩa chính. Một timeout phụ thuộc vẫn có thể trả 503, nhưng category nói UI nên đề nghị “Thử lại” và giám sát nên báo on-call.

Làm cho mọi API trả về một cấu trúc lỗi tiêu chuẩn, ngay cả khi nguồn gốc khác nhau (database, module auth, API bên thứ ba). Cấu trúc đơn giản như sau giữ cho xử lý UI và dashboard nhất quán:

{
  "category": "dependency",
  "code": "PAYMENTS_TIMEOUT",
  "message": "Payment service is not responding.",
  "details": {"provider": "stripe"},
  "correlation_id": "9f2c2c3a-6a2b-4a0a-9e9d-0b0c0c8b2b10"
}

Correlation ID là cầu nối giữa “người dùng thấy lỗi” và “chúng ta có thể truy vết”. Hiển thị correlation_id trong UI (nút sao chép giúp ích), và luôn log nó phía backend để bạn có thể theo dõi một request qua các dịch vụ.

Đồng ý những gì an toàn để hiển thị ở UI so với chỉ trong logs. Một phân chia thực tế: UI nhận category, một message rõ ràng và bước tiếp theo; logs nhận chi tiết kỹ thuật và ngữ cảnh request; cả hai chia sẻ correlation_id và mã lỗi ổn định.

Danh sách kiểm nhanh cho hệ thống lỗi nhất quán

Sự nhất quán là nhàm chán theo cách tốt nhất: mọi kênh hành vi giống nhau, và giám sát nói thật.

Bắt đầu kiểm tra phía backend, bao gồm job nền và webhook. Nếu bất kỳ trường nào là tùy chọn, người ta sẽ bỏ qua và sự nhất quán vỡ.

• Mỗi lỗi bao gồm category, một mã ổn định, một message an toàn cho người dùng và một trace ID.
• Vấn đề validation là mong đợi, nên không kích hoạt cảnh báo paging.
• Vấn đề auth và permission được theo dõi cho mẫu bảo mật, nhưng không coi như outage.
• Phản hồi rate limit bao gồm gợi ý retry (ví dụ, số giây chờ) và không spam cảnh báo.
• Lỗi phụ thuộc bao gồm tên dependency và chi tiết timeout hoặc status.

Rồi kiểm tra quy tắc UI. Mỗi category nên ánh xạ đến một hành vi màn hình dự đoán để người dùng không phải đoán bước sau: validation tô trường, auth yêu cầu sign-in hoặc hiện thông báo truy cập, rate limit hiển thị chờ bình tĩnh, lỗi phụ thuộc đề nghị retry và fallback khi có thể.

Một test đơn giản là kích hoạt một lỗi từ mỗi category trong môi trường staging và xác minh kết quả giống nhau trên web app, mobile app và admin panel.

Những lỗi thường gặp và bước tiếp theo thực tế

Cách nhanh nhất làm vỡ hệ thống lỗi là xem nó như chuyện phụ. Các đội khác nhau sẽ dùng từ khác nhau, mã khác nhau và hành vi UI khác nhau cho cùng một vấn đề. Công việc taxonomy có giá trị khi nó được giữ nhất quán.

Các mẫu thất bại thường gặp:

• Lộ văn bản exception nội bộ cho người dùng. Nó làm người dùng bối rối và có thể lộ dữ liệu nhạy cảm.
• Gán mọi 4xx là “validation.” Thiếu quyền không giống thiếu trường.
• Tạo mã mới cho mỗi tính năng mà không review. Bạn có thể có 200 mã mà chỉ có 5 ý nghĩa khác nhau.
• Retry sai loại lỗi. Retry lỗi permission hoặc email sai chỉ tạo thêm tiếng ồn.

Ví dụ đơn giản: một nhân viên bán hàng gửi form “Tạo khách hàng” và nhận 403. Nếu UI coi mọi 4xx là validation, nó sẽ tô trường lung tung và yêu cầu “sửa input” thay vì nói họ cần quyền. Giám sát sẽ hiện spike “validation” khi thực ra là vấn đề roles.

Các bước tiếp theo thực tế phù hợp trong một workshop ngắn: viết tài liệu một trang về taxonomy (categories, khi dùng chúng, 5–10 mã điển hình), định nghĩa quy tắc message (người dùng thấy gì vs log chứa gì), thêm cổng review nhẹ cho mã mới, đặt quy tắc retry theo category, rồi triển khai end-to-end (response backend, ánh xạ UI và dashboard giám sát).

Nếu bạn xây với AppMaster (appmaster.io), việc tập trung hóa những quy tắc này ở một chỗ sẽ giúp cùng một category và code hoạt động nhất quán trên backend, web app và native mobile apps.