传统错误追踪的问题 想象一下：您正在调试一个生产环境中的问题，用户报告了“未找到用户”的错误。您查看错误跟踪仪表盘，发现数百个类似的错误，但它们的 ID 各不相同：
Error ID: a1b2c3d4- “未找到用户 123” Error ID: e5f6g7h8- “未找到用户 456” Error ID: i9j0k1l2- “未找到用户 789” 尽管这些本质上是相同的错误（用户查找失败），但您的监控系统会将它们视为完全不同的问题。这使得以下情况几乎不可能发生：
将相关错误分组以便进行有效分析 准确跟踪错误频率 识别应用程序故障的模式 根据实际影响确定修复的优先级 进入StableError：解决方案 StableError是一个 TypeScript 库，它通过根据错误的语义内容（而不是其可变部分）生成稳定、一致的错误 ID来解决这个确切的问题。
魔法：同样的错误 = 同样的 ID import { createStableError } from 'stable-error';
// These all generate the SAME error ID const error1 = createStableError('User 123 not found', { category: 'validation', metadata: { field: 'email' } });
const error2 = createStableError('User 456 not found', { category: 'validation', metadata: { field: 'email' } });
const error3 = createStableError('USER 789 NOT FOUND', { category: 'validation', metadata: { field: 'email' } });
console.log(error1.id === error2.id); // true console.log(error1.id === error3.id); // true 工作原理：智能消息规范化 StableError 使用复杂的消息规范化来确保语义相同的错误产生相同的 ID：
1.数字规范化 // All of these become "user NUMBER not found" "User 123 not found" "User 456 not found" "User 999999 not found" 2. UUID 规范化 // All of these become "user UUID not found" "User 550e8400-e29b-41d4-a716-446655440000 not found" "User 6ba7b810-9dad-11d1-80b4-00c04fd430c8 not found" 3.时间戳规范化 // All of these become "error at TIMESTAMP" "Error at 2023-01-01T10:00:00Z" "Error at 2023-12-31T23:59:59Z" "Error at 1672531200000" // Unix timestamp 4.大小写和空格规范化 // All of these become "user not found" "User not found" "USER NOT FOUND" " user not found " 智能元数据过滤 并非所有元数据都应影响错误 ID 的生成。StableError 仅考虑表示错误语义的“稳定”元数据键：
包含在 ID 生成中：
type，，，，，，codefieldoperationservicecomponent 忽略（变量数据）：
userId，，，timestampsessionIdrequestId // These generate the SAME ID (userId and timestamp are ignored) createStableError('Error', { metadata: { field: 'email', userId: 123, // Ignored timestamp: '2023-01-01' // Ignored } });
createStableError('Error', {
metadata: {
field: 'email',
userId: 456, // Ignored
timestamp: '2023-12-31' // Ignored
}
});
实际使用示例
- API 错误处理 import { createStableError } from 'stable-error';
async function getUserById(id: string) { try { const user = await database.findUser(id); if (!user) { throw createStableError('User not found', { category: 'validation', statusCode: 404, severity: 'medium', metadata: { field: 'userId', operation: 'user_lookup' } }); } return user; } catch (error) { // Convert any unexpected errors to stable errors if (error instanceof Error && !error.id) { throw createStableError(error, { category: 'database', severity: 'high', metadata: { operation: 'user_lookup' } }); } throw error; } } 2.错误监控集成 // With your favorite error tracking service 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' } });
// Send to your monitoring service errorTracker.captureException(stableError, { tags: { errorId: stableError.id, category: stableError.category, severity: stableError.severity }, extra: stableError.metadata }); } 3.错误聚合仪表板 // Group errors by stable ID for analytics 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; }, {}); 主要特点 ✅稳定的错误 ID 相同的错误消息 + 类别 + 元数据 = 相同的 ID 8 个字符的十六进制 ID，方便参考 ✅全面支持 TypeScript 具有全面接口的完整类型安全性 所有选项和方法的 IntelliSense 支持 ✅灵活输入 适用于字符串消息或现有的错误对象 转换时保留原始堆栈跟踪 ✅丰富的错误信息 类别分类 严重程度（低、中、高、严重） HTTP 状态代码 时间戳 自定义元数据 JSON序列化 const error = createStableError('Test error', { category: 'validation', severity: 'high' });
const json = error.toJSON(); // { // id: "a1b2c3d4", // message: "Test error", // category: "validation", // severity: "high", // timestamp: "2023-01-01T10:00:00Z", // statusCode: 500, // metadata: {}, // stack: "Error: Test error\n at ..." // } 安装和快速启动 npm install stable-error
or
yarn add stable-error
or
bun add stable-error import { createStableError } from 'stable-error';
// Create your first stable error const error = createStableError('Something went wrong', { category: 'api', severity: 'high', metadata: { endpoint: '/users', method: 'GET' } });
console.log(Error ID: ${error.id}); // Always the same for this error type
浏览器和运行时支持
现代浏览器（ES2018+）
Node.js 14+
TypeScript 4.5+
Bun（已全面测试）
结论
StableError 将错误追踪从混乱的局面转变为一个有组织的、可操作的系统。通过为语义相同的错误生成一致的 ID，它能够：
更好的错误分析——了解哪些错误真正重要 更快的调试——将相关问题分组 改进优先级- 关注高频问题 更清晰的仪表板- 不再有来自变量数据的噪音 无论您是构建小型应用程序还是管理大型系统，StableError 都能为您提供有效的错误监控和调试基础。不妨尝试一下，看看它如何彻底改变您的错误跟踪工作流程。查看更多www.mxwd.cc
