# @easyweb/errors 中文文档

规范地址：https://npmcn.com/package/%40easyweb/errors/

版本：1\.1\.0
npm 元数据更新时间：2026-08-14T15:01:45.878Z
中文译文更新时间：2026-11-13T04:19:34.208Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40easyweb/errors
原文对照：https://npmcn.com/package/%40easyweb/errors/?lang=original
项目主页：https://github.com/Alpine-Solusi/easy-web-global#readme
源码仓库：https://github.com/Alpine-Solusi/easy-web-global

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：75.1 kB，90 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- peer 依赖：express ^5\.0\.0
- 首次发布：2026-08-06T02:14:28.833Z
- 最新版本发布：2026-08-14T15:01:45.679Z
- 近 30 天下载量：3410（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

用于 Easyweb 微服务的共享 HTTP 错误分类: 带有机器可读代码的打出错误类, 以及将其序列化的快速错误处理中件

## 安装

```sh
npm install @easyweb/errors
```

也可以使用：`pnpm add @easyweb/errors`、`yarn add @easyweb/errors`、`bun add @easyweb/errors`

## README

# @easyweb/错误

用于 Easyweb 微服务的共享 HTTP 错误分类学: 有机器可读代码的打出错误类, 以及序列化的快递中件.

以前这些班都住在这里 `@easyweb/authentication`他们搬进来了 `@easyweb/authentication@2.0.0` ——错误处理是交叉的,是一项需要的服务 `ConflictError` 不应依赖JWT包来获得.

## 安装

```bash
npm install @easyweb/errors
```

`express@^5` 是一种同伴依赖,属于消费服务.

## 接线

在每个路由器之后, 上载全部和处理器 :

```ts
import { errorHandler, notFoundHandler } from "@easyweb/errors";
import logger from "./lib/logger";

app.use("/auth", authRouter);

app.all(/.*/, notFoundHandler);
app.use(errorHandler({ logger }));
```

通过服务皮诺的例子。 默认是 `console`,它工作但产生无结构的输出,没有服务名称,没有编辑,也没有请求id.

| 选项 | 默认 |  |
| --- | --- | --- |
| `logger` | `console` | 任何东西 `error` 财务报告和审定财务报表 `warn`。 。 。 . |
| `logClientErrors` | `false` | 警告层的日志4xx 关闭因为客户错误不是事件. |
| `includeRequestId` | `true` | 包含 `requestId` 在体内. |
| `fallbackMessage` | `"Something went wrong"` | 未识别错误的正文文本 . |

## 响应形状

```jsonc
{
  "errors": [
    { "message": "Email is already registered", "field": "email", "code": "CONFLICT" }
  ],
  "requestId": "0f4d…"   // omitted when requestContext has not run
}
```

`message` 财务报告和审定财务报表 `field` 并保持不变. `code` 并且是客户唯一应该分行的.. `message` 自由式英语写在掷出地点, 部分已经是印度尼西亚语.

`requestId` 来自 `req.requestId`,设置 `requestContext` 内 `@easyweb/authentication`,与 `x-request-id` 响应头。 它被防御性地读取,所以这个软件包并不依赖于认证软件包.

## 类

| 状态 | 类 | 构造器 |
| --- | --- | --- |
| 400个 | `BadRequestError` | `(message)` |
| 400个 | `RequestValidationError` | `(errors)` ——接受 `{ field, message }` 或者说 `{ msg, path }`每个条目 |
| 401 (中文(简体) ) | `NotAuthorizedError` | `(message = "Not authorized")` |
| 403 (韩语) | `ForbiddenError` | `(message = "Forbidden")` |
| 404 (韩语) | `NotFoundError` | `()` ——无路线路径 |
| 404 (韩语) | `ResourceNotFoundError` | `(resource, id?)` ——域对象 |
| 409个 | `ConflictError` | `(message, field?)` |
| 422个 | `UnprocessableEntityError` | `(message)` |
| 429个 | `TooManyRequestsError` | `(message?, retryAfterSeconds?)` |
| 500个 | `InternalServerError` | `(message = "Something went wrong")` |
| 500个 | `DatabaseConnectionError` | `()` |
| 502 (中文(简体) ) | `BadGatewayError` | `(message?)` |
| 第503条 | `ServiceUnavailableError` | `(message?, retryAfterSeconds?)` |
| 504 (中文(简体) ) | `GatewayTimeoutError` | `(message?)` |

`retryAfterSeconds` 变成一个 `Retry-After` 头曰.

### 挑一个

-   **401对403** ——401意为"我们不知道你是谁";403意为"我们知道,你可能不知道". 为角色失败而返回401会让客户端回合出现无法成功的再校正循环.
-   **400对409** -400人说请求有问题 如果请求是罚款和 _状态_ 冲突( 重复的电子邮件, 已经核实的账户) , 即 409 : 重试相同的请求无济于事 .
-   **400对404** —— 说 `BadRequestError("User not found")` 责怪打电话的人问了一些没有的东西。 使用 `ResourceNotFoundError`。例外:在登录时,“没有这样的用户”是一个 `NotAuthorizedError`,或端点成为账户编号甲骨文.
-   **500对503** 500表示我们的密码破了 暂时减少的依赖性为503个,管弦乐团对两者有不同的对待.

## 处理者的行为

1.  A 类 `CustomError` 连载着它自己的地位和身体.
2.  身体保护者 `SyntaxError` (malform JSON)变成400,而不是500.
3.  一个非`CustomError` 带有数字 `status` 编号 : `statusCode` 内 `[400,599]` 保留它——堆栈中的几个库设置了一个准确的库.
4.  其它的都是500块 `fallbackMessage`。 。 。 .

在第2至4个分支上 `message` 堆叠是 **永远** 序列化:它们可以命名一个表格,一个查询,或者一个秘密. 只信任状态 .

## `isCustomError`

处理器的分支 `isCustomError(err)`没有 `err instanceof CustomError`。 。 。 .

`instanceof` 比较构造器身份, 所以当此软件包的两个复制件在一个过程中存在时, 失败了 `node_modules/@easyweb/authentication/node_modules/`。失败是静默的和完全的:每次错误都停止匹配,变成通用的500,而类型仍然检查,建筑仍然通过.

两项辩护理由: `@easyweb/authentication` 声明此软件包为 **依赖性** 所以npm无法筑巢 `CustomError` 携带一个 `__easywebError` 该品牌 `isCustomError` 掉头 如果您添加了依赖于此软件包, 请基于同样的原因声明为对等方 .

以 :

```bash
npm ls @easyweb/errors    # must show exactly one, deduped at the top level
```

## 出版

```bash
npm run build && npm publish
```

`build` 运行 `clean` 先说 没有它,一个重新命名或被删除的源文件会留下一个孤儿 `dist/` 船在焦油丸中.

## 常见问题

### @easyweb/errors 是什么？

用于 Easyweb 微服务的共享 HTTP 错误分类: 带有机器可读代码的打出错误类, 以及将其序列化的快速错误处理中件

### 如何安装 @easyweb/errors？

在项目目录运行 npm install @easyweb/errors，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：express（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @easyweb/errors 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @easyweb/errors 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @easyweb/errors 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @easyweb/errors 可以商用吗？

@easyweb/errors 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @easyweb/errors 的下载量有多少？

根据 npm 官方下载统计，@easyweb/errors 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,410 次，日均约 114 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @easyweb/errors 还在维护吗？

最新版本 1\.1\.0 发布于 2026/08/14（2 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/08/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。