Thời lượng: 20 phút
Level: Intermediate
Yêu cầu: Đã hoàn thành bài học về Validation.
Mục tiêu bài học
Sau bài học này, bạn sẽ:
- Xây dựng được cấu trúc mã lỗi (Error Codes) khoa học và dễ hiểu.
- Biết cách thiết kế hệ thống Error Registry tập trung.
- Ánh xạ (Map) thành công giữa mã lỗi nghiệp vụ và mã trạng thái HTTP.
Nội dung chính
1. Tại sao cần Error Registry?
Trong các hệ thống lớn, nếu mỗi developer tự đặt tên lỗi (VD: ERR01, NOT_FOUND_USER, USER_MISSING), Client sẽ không thể xử lý logic một cách tự động.
Error Registry là:
- Một "cuốn từ điển" duy nhất chứa toàn bộ mã lỗi của dự án.
- Giúp team Frontend biết chắc chắn mã lỗi nào sẽ trả về trong trường hợp nào.
- Giúp việc dịch (Localization) thông báo lỗi dễ dàng hơn.
2. Cấu trúc mã lỗi chuẩn (Taxonomy)
Một mã lỗi tốt nên mang tính phân cấp: [DOMAIN]_[CATEGORY]_[REASON]
| Phần | Ý nghĩa | Ví dụ |
|---|---|---|
| DOMAIN | Thuộc Service/Module nào | AUTH, ORDER, PAYMENT |
| CATEGORY | Loại lỗi chung | INVALID, NOT_FOUND, EXPIRED |
| REASON | Lý do cụ thể | PASSWORD, ORDER_ID, TOKEN |
Ví dụ:
AUTH_INVALID_CREDENTIALS: Sai tài khoản/mật khẩu.ORDER_NOT_FOUND: Không tìm thấy đơn hàng.PAYMENT_INSUFFICIENT_FUNDS: Số dư không đủ để thanh toán.
3. Thiết kế bảng Error Registry
Hệ thống Design System cần một file (hoặc Database) định nghĩa mã lỗi và Mapping với HTTP Status.
| Error Code | HTTP Status | Tiếng Việt | English |
|---|---|---|---|
VALIDATION_FAILED | 400 | Dữ liệu không hợp lệ | Validation failed |
AUTH_UNAUTHORIZED | 401 | Vui lòng đăng nhập | Unauthorized access |
AUTH_FORBIDDEN | 403 | Không có quyền truy cập | Access denied |
INTERNAL_ERROR | 500 | Lỗi hệ thống | Internal server error |
Nguyên tắc then chốt
"Mã lỗi là dành cho máy, Thông báo lỗi là dành cho người."
Lập trình viên Client sẽ dùng Mã lỗi (AUTH_EXPIRED_TOKEN) để viết code xử lý (VD: tự động logout). Người dùng cuối sẽ nhìn thấy Thông báo lỗi ("Phiên làm việc hết hạn"). Đừng bao giờ mix hai cái này với nhau.
Thực hành
Bài tập 1: Xây dựng Catalog cho Module "Thanh toán"
Bối cảnh: Hệ thống thanh toán của bạn có các lỗi:
- Thẻ hết hạn.
- Sai mã PIN.
- Ngân hàng bảo trì.
- Vượt hạn mức ngày.
Yêu cầu:
- Thiết kế mã lỗi (Error Code) cho 4 trường hợp trên.
- Gán HTTP Status Code phù hợp cho từng mã.
Xem đáp án mẫu
| Error Code | HTTP Status |
|---|---|
PAYMENT_CARD_EXPIRED | 400 |
PAYMENT_INVALID_PIN | 400 |
PAYMENT_BANK_MAINTENANCE | 503 |
PAYMENT_LIMIT_EXCEEDED | 400 |
Tình huống thực tế
Scenario 1: Có quá nhiều mã lỗi giống nhau
Bối cảnh:
Team A tạo mã USER_NOT_FOUND. Team B tạo mã ACCOUNT_MISSING. Cả hai đều muốn ám chỉ việc không tìm thấy tài khoản.
Giải quyết: Đây là lúc vai trò của Governance (Quản trị) phát huy. Design System phải có một file Shared (VD: một npm package chứa các hằng số mã lỗi) hoặc một Repository tập trung. Mọi mã lỗi mới đều phải qua review để đảm bảo không bị trùng lặp ngữ nghĩa.
Câu hỏi phỏng vấn
Senior Level
- Q: Bạn làm thế nào để xử lý Đa ngôn ngữ (i18n) cho lỗi trong Design System?
A:
- Backend chỉ trả về Error Code (
AUTH_FAILED). - Frontend dựa vào Error Code này để tra bảng ngôn ngữ của Client (i18next) và hiển thị thông báo tương ứng.
- Nếu Client không biết mã lỗi này, Backend có thể trả về một field
message(default English) làm fallback.
- Backend chỉ trả về Error Code (
Tóm tắt
Những điều cần nhớ
- Mã lỗi nên có cấu trúc phân cấp (Domain_Category_Reason).
- Centralized Registry là Single Source of Truth cho mã lỗi.
- Mã lỗi cố định, thông báo lỗi có thể thay đổi tùy ngôn ngữ.
Key Takeaways
- Consistency: Chỉ dùng một mã duy nhất cho một ý nghĩa duy nhất trên toàn hệ thống Microservices.
- Machine-readable: Giúp Client viết logic xử lý lỗi tự động thay vì dùng Regex để parse string.
Bước tiếp theo
Trong bài tiếp theo, bạn sẽ học về Lesson 4.3: Global Exception Handling - Cách bắt mọi lỗi phát sinh và đóng gói chúng theo chuẩn một cách tự động.