eagle-reserror

Node.js 后端服务统一错误码库，为 EAGLE 平台后端服务提供标准化的异常响应对象。

核心价值：

• 错误码集中管理，避免各服务重复定义
• 标准化的响应结构（http_code + error_code + error_message）
• AA-BB-CCC 编码体系，兼顾机器可读与人可读（UE/SE/TE + 业务域 + 编号）
• 可抛出的异常类 ResErrorException，配合 reserror() 统一处理
• 内置常见第三方库异常映射（MongoDB、MySQL、PostgreSQL、Redis、Kafka、NestJS）
• 用户可注册自定义异常映射，优先级高于内置
• 构建时自动校验 error_code 唯一性
• 零运行时依赖

安装

npm install eagle-reserror

运行时依赖

无。

快速启动

引用错误常量

import { ResError } from 'eagle-reserror';

const err = ResError.AUTH.ACCOUNT_NOT_EXIST;
// → { http_code: 200, error_code: 'UE-AUTH-004', error_message: 'The account is not registered in the system or has been deleted.' }

抛出业务异常

import { ResError, ResErrorException } from 'eagle-reserror';

throw new ResErrorException(ResError.AUTH.ACCOUNT_NOT_EXIST);

统一异常处理

import { reserror, ResErrorException } from 'eagle-reserror';

try {
  // 业务代码...
} catch (e) {
  const errObj = reserror(e);
  ctx.status = errObj.http_code;
  ctx.body = errObj;
}

注册自定义异常映射

import { registerExceptionMap, ResError } from 'eagle-reserror';

registerExceptionMap({
  MyCustomError: ResError.BASE.INVALID_REQUEST,
});

核心概念

错误对象结构

每个错误常量包含三个字段：

| 字段 | 类型 | 说明 | |---|---|---| | http_code | number | HTTP 状态码（UE→200, SE→500, TE→500） | | error_code | string | 错误唯一标识，格式为 AA-BB-CCC | | error_message | string | 英文错误描述 |

error_code 编码规则

AA-BB-CCC 格式：

• AA — 错误来源：UE（用户错误）/ SE（系统错误）/ TE（第三方错误）
• BB — 业务域：COMM（通用）/ AUTH（认证授权）/ USER（用户中心）
• CCC — 具体编号：每个业务域下从 001 递增

http_code 规则

| 错误来源 | http_code | 说明 | |---|---|---| | UE (User Exception) | 200 | 用户请求有误，但服务端正常处理并返回错误信息 | | SE (Server Exception) | 500 | 服务端内部异常 | | TE (Third-party Exception) | 500 | 第三方服务异常 |

业务域

| 领域 | 命名空间 | 说明 | |---|---|---| | 通用/基础 | BASE | 通用错误、系统错误、第三方错误 | | 认证授权 | AUTH | 登录、令牌、权限等认证相关错误 | | 用户中心 | USER | 注册、账户等用户管理相关错误 |

异常处理流程

reserror() 函数按以下优先级处理异常：

1. ResErrorException → 直接返回其 errorData
2. 用户自定义映射（registerExceptionMap 注册）
3. 库内置映射（MongoDB、MySQL、PostgreSQL、Redis、Kafka、NestJS 等）
4. 未命中 → 返回 SE-COMM-001（内部服务错误）

API 总览

• BASE — 通用错误：5 个错误常量（UE-COMM-001, SE-COMM-001, TE-COMM-001~003）
• AUTH — 认证授权错误：21 个错误常量（UE-AUTH-001~021）
• USER — 用户中心错误：3 个错误常量（UE-USER-001~003）
• 错误码对照表：新旧格式完整映射
• 异常响应设计规范：AA-BB-CCC 编码规范
• 第三方库异常映射：内置映射列表与自定义注册

构建 & 发版

npm run build              # 构建 dist/ + 校验 error_code 唯一性
npm run validate           # 仅校验 error_code 唯一性
npm run generate-types     # 生成 types/*.d.ts
npm run release-patch      # 1.3.4 → 1.3.5
npm run release-minor      # 1.3.4 → 1.4.0
npm run release-major      # 1.3.4 → 2.0.0

文档索引

| 文档 | 面向 | 用途 | |---|---|---| | 异常响应设计规范 | 开发者 | 理解 AA-BB-CCC 编码规范 | | 错误码对照表 | 使用者 | 查找错误码定义与解决方案 | | 第三方库异常映射 | 使用者 | 查看内置映射、注册自定义映射 | | PROJECT-GUIDE.md | 开发者 | 项目全貌导读 | | WORKING-STATE.md | AI·Agent | 当前待办与建议 |