Giới thiệu StableError: Thư viện TypeScript cho theo dõi lỗi hiệu quả
Giới thiệu
Trong quá trình phát triển ứng dụng, việc theo dõi và xử lý lỗi là một phần quan trọng giúp đảm bảo chất lượng sản phẩm. Tuy nhiên, các hệ thống theo dõi lỗi truyền thống thường gặp khó khăn trong việc nhóm và phân tích các lỗi tương tự nhau. Chính vì vậy, thư viện StableError ra đời nhằm giải quyết vấn đề này một cách hiệu quả.
Vấn đề với việc theo dõi lỗi truyền thống
Hãy tưởng tượng bạn đang gỡ lỗi một vấn đề trong sản xuất mà người dùng báo cáo lỗi "Không tìm thấy người dùng". Bạn kiểm tra bảng điều khiển theo dõi lỗi và thấy hàng trăm lỗi tương tự, nhưng chúng có các ID khác nhau:
Error ID: a1b2c3d4- "Người dùng 123 không tìm thấy"Error ID: e5f6g7h8- "Người dùng 456 không tìm thấy"Error ID: i9j0k1l2- "Người dùng 789 không tìm thấy"
Dù những lỗi này về bản chất là giống nhau (lỗi tìm kiếm người dùng), nhưng hệ thống theo dõi của bạn lại coi chúng là các vấn đề hoàn toàn khác nhau. Điều này khiến việc:
- Nhóm các lỗi liên quan để phân tích hiệu quả gặp khó khăn
- Theo dõi tần suất lỗi một cách chính xác
- Xác định mẫu trong các lỗi của ứng dụng
- Ưu tiên sửa chữa dựa trên tác động thực tế
Giới thiệu về StableError: Giải pháp cho vấn đề
StableError là một thư viện TypeScript giúp giải quyết chính xác vấn đề này bằng cách tạo ra các ID lỗi ổn định, nhất quán dựa trên nội dung ngữ nghĩa của lỗi, không phải các phần thay đổi của chúng.
Phép màu: Lỗi giống nhau = ID giống nhau
typescript
import { createStableError } from 'stable-error';
// Tất cả đều tạo ra cùng một ID lỗi
const error1 = createStableError('Người dùng 123 không tìm thấy', {
category: 'validation',
metadata: { field: 'email' }
});
const error2 = createStableError('Người dùng 456 không tìm thấy', {
category: 'validation',
metadata: { field: 'email' }
});
const error3 = createStableError('NGƯỜI DÙNG 789 KHÔNG TÌM THẤY', {
category: 'validation',
metadata: { field: 'email' }
});
console.log(error1.id === error2.id); // true
console.log(error1.id === error3.id); // trueCách thức hoạt động: Chuẩn hóa tin nhắn thông minh
StableError sử dụng công nghệ chuẩn hóa tin nhắn tinh vi để đảm bảo rằng các lỗi ngữ nghĩa giống nhau sẽ tạo ra cùng một ID:
1. Chuẩn hóa số
typescript
// Tất cả đều trở thành "người dùng SỐ không tìm thấy"
"Người dùng 123 không tìm thấy"
"Người dùng 456 không tìm thấy"
"Người dùng 999999 không tìm thấy"2. Chuẩn hóa UUID
typescript
// Tất cả đều trở thành "người dùng UUID không tìm thấy"
"Người dùng 550e8400-e29b-41d4-a716-446655440000 không tìm thấy"
"Người dùng 6ba7b810-9dad-11d1-80b4-00c04fd430c8 không tìm thấy"3. Chuẩn hóa thời gian
typescript
// Tất cả đều trở thành "lỗi tại THỜI GIAN"
"Lỗi tại 2023-01-01T10:00:00Z"
"Lỗi tại 2023-12-31T23:59:59Z"
"Lỗi tại 1672531200000" // Unix timestamp4. Chuẩn hóa ký tự viết hoa và khoảng trắng
typescript
// Tất cả đều trở thành "người dùng không tìm thấy"
"Người dùng không tìm thấy"
"NGƯỜI DÙNG KHÔNG TÌM THẤY"
" người dùng không tìm thấy "Lọc metadata thông minh
Không phải tất cả metadata đều nên ảnh hưởng đến việc tạo ID lỗi. StableError chỉ xem xét các khóa metadata "ổn định" thể hiện ý nghĩa ngữ nghĩa của lỗi:
Được bao gồm trong việc tạo ID:
type,code,field,operation,service,component
Bị bỏ qua (dữ liệu thay đổi):
userId,timestamp,sessionId,requestId
typescript
// Những điều này tạo ra cùng một ID (userId và timestamp bị bỏ qua)
createStableError('Lỗi', {
metadata: {
field: 'email',
userId: 123, // Bị bỏ qua
timestamp: '2023-01-01' // Bị bỏ qua
}
});
createStableError('Lỗi', {
metadata: {
field: 'email',
userId: 456, // Bị bỏ qua
timestamp: '2023-12-31' // Bị bỏ qua
}
});Ví dụ sử dụng trong thực tế
1. Xử lý lỗi API
typescript
import { createStableError } from 'stable-error';
async function getUserById(id: string) {
try {
const user = await database.findUser(id);
if (!user) {
throw createStableError('Người dùng không tìm thấy', {
category: 'validation',
statusCode: 404,
severity: 'medium',
metadata: {
field: 'userId',
operation: 'user_lookup'
}
});
}
return user;
} catch (error) {
// Chuyển đổi bất kỳ lỗi không mong muốn nào thành lỗi ổn định
if (error instanceof Error && !error.id) {
throw createStableError(error, {
category: 'database',
severity: 'high',
metadata: { operation: 'user_lookup' }
});
}
throw error;
}
}2. Tích hợp theo dõi lỗi
typescript
// Với dịch vụ theo dõi lỗi yêu thích của bạn
import { createStableError } from 'stable-error';
function trackError(error: Error, context: any) {
const stableError = createStableError(error, {
category: 'api',
severity: 'high',
metadata: {
service: 'user-service',
component: 'auth-middleware'
}
});
// Gửi đến dịch vụ theo dõi của bạn
errorTracker.captureException(stableError, {
tags: {
errorId: stableError.id,
category: stableError.category,
severity: stableError.severity
},
extra: stableError.metadata
});
}3. Bảng điều khiển tổng hợp lỗi
typescript
// Nhóm lỗi theo ID ổn định cho phân tích
const errorGroups = errors.reduce((groups, error) => {
const stableError = createStableError(error);
const id = stableError.id;
if (!groups[id]) {
groups[id] = {
id,
message: stableError.message,
category: stableError.category,
count: 0,
firstSeen: stableError.timestamp,
lastSeen: stableError.timestamp,
severity: stableError.severity
};
}
groups[id].count++;
groups[id].lastSeen = stableError.timestamp;
return groups;
}, {});Tính năng chính
✅ ID lỗi ổn định
- Thông điệp lỗi giống nhau + loại + metadata = ID giống nhau
- ID 8 ký tự thập phân dễ tham chiếu
✅ Hỗ trợ TypeScript đầy đủ
- Đảm bảo loại đầy đủ với các giao diện toàn diện
- Hỗ trợ IntelliSense cho tất cả các tùy chọn và phương thức
✅ Đầu vào linh hoạt
- Hoạt động với tin nhắn chuỗi hoặc các đối tượng Error hiện có
- Giữ nguyên stack trace gốc khi chuyển đổi
✅ Thông tin lỗi phong phú
- Phân loại theo loại
- Cấp độ nghiêm trọng (thấp, trung bình, cao, nghiêm trọng)
- Mã trạng thái HTTP
- Thời gian
- Metadata tùy chỉnh
✅ Chuẩn hóa JSON
typescript
const error = createStableError('Lỗi kiểm tra', {
category: 'validation',
severity: 'high'
});
const json = error.toJSON();
// {
// id: "a1b2c3d4",
// message: "Lỗi kiểm tra",
// category: "validation",
// severity: "high",
// timestamp: "2023-01-01T10:00:00Z",
// statusCode: 500,
// metadata: {},
// stack: "Error: Lỗi kiểm tra\n at ..."
// }Cài đặt và bắt đầu nhanh
bash
npm install stable-error
# hoặc
yarn add stable-error
# hoặc
bun add stable-error
typescript
import { createStableError } from 'stable-error';
// Tạo lỗi ổn định đầu tiên của bạn
const error = createStableError('Có lỗi xảy ra', {
category: 'api',
severity: 'high',
metadata: { endpoint: '/users', method: 'GET' }
});
console.log(`Error ID: ${error.id}`); // Luôn giống nhau cho loại lỗi nàyHỗ trợ trình duyệt và môi trường
- Trình duyệt hiện đại (ES2018+)
- Node.js 14+
- TypeScript 4.5+
- Bun (đã được kiểm tra hoàn toàn)
Kết luận
StableError biến việc theo dõi lỗi từ một mớ hỗn độn thành một hệ thống có tổ chức, có thể hành động. Bằng cách tạo ra các ID nhất quán cho các lỗi ngữ nghĩa giống nhau, nó cho phép:
- Phân tích lỗi tốt hơn - Xem những lỗi thực sự quan trọng
- Gỡ lỗi nhanh hơn - Nhóm các vấn đề liên quan lại với nhau
- Cải thiện ưu tiên - Tập trung vào các vấn đề có tần suất cao
- Bảng điều khiển sạch hơn - Không còn tiếng ồn từ dữ liệu thay đổi
Cho dù bạn đang xây dựng một ứng dụng nhỏ hay quản lý một hệ thống quy mô lớn, StableError cung cấp nền tảng cho việc theo dõi và gỡ lỗi lỗi hiệu quả. Hãy thử nghiệm và xem cách nó có thể cách mạng hóa quy trình theo dõi lỗi của bạn.
Sẵn sàng để bắt đầu? Hãy xem kho GitHub để biết tài liệu đầy đủ, ví dụ và các cập nhật mới nhất.
StableError là mã nguồn mở và có sẵn theo giấy phép MIT.
