# @dotcom-reliability-kit/errors 中文文档

规范地址：https://npmcn.com/package/%40dotcom-reliability-kit/errors/

版本：5\.1\.0
npm 元数据更新时间：2026-08-19T16:08:44.434Z
中文译文更新时间：2026-11-12T22:44:58.052Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dotcom-reliability-kit/errors
原文对照：https://npmcn.com/package/%40dotcom-reliability-kit/errors/?lang=original
项目主页：https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/errors#readme
源码仓库：https://github.com/Financial-Times/dotcom-reliability-kit

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

- 包体积（解压后）：43.8 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.12 \|\| ^24 \|\| ^26
- 运行依赖：1 个
- 首次发布：2022-05-04T13:19:12.493Z
- 最新版本发布：2026-08-19T16:08:44.182Z
- 近 30 天下载量：3590（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 6 个）

## 中文简介

一组错误类,帮助您在任何情况下丢出最合适的错误

## 安装

```sh
npm install @dotcom-reliability-kit/errors
```

也可以使用：`pnpm add @dotcom-reliability-kit/errors`、`yarn add @dotcom-reliability-kit/errors`、`bun add @dotcom-reliability-kit/errors`

## README

# @dotcom - 可靠性- kit/错误

一组错误类,帮助您在任何情况下抛出最合适的错误, 并识别何时知道错误对未知 。 此模块是 [FT.com 可靠性工具包](https://github.com/Financial-Times/dotcom-reliability-kit#readme)。 。 。 .

-   [使用量](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-usage)
    -   [`OperationalError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-operationalerror)
        -   [`.id`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-operationalerrorid)
        -   [`.relatesToSystems`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-operationalerrorrelatestosystems)
        -   [`.cause`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-operationalerrorcause)
        -   [`.isErrorMarkedAsOperational`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-operationalerroriserrormarkedasoperational)
    -   [`HttpError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-httperror)
        -   [为什么要用这个 `http-errors`? 吗?](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-why-use-this-over-http-errors)
    -   [`DataStoreError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-datastoreerror)
    -   [`UpstreamServiceError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-upstreamserviceerror)
    -   [`UserInputError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-userinputerror)
    -   [`BaseError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-baseerror)
-   [移动](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-migrating)
-   [捐款](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-contributing)
-   [许可证](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-license)

## 使用量

安装 `@dotcom-reliability-kit/errors` 作为依附关系:

```bash
npm install --save @dotcom-reliability-kit/errors
```

在代码中包含 :

```js
import { OperationalError } from '@dotcom-reliability-kit/errors';
```

> \[TIP\] 如果您使用此软件包并带有 TypeScript , 我们建议您使用以下设置: `tsconfig.json` 避免类型错误的文件 :
> 
> ```json
> {
>     "esModuleInterop": true,
>     "module": "nodenext",
>     "moduleResolution": "nodenext"
> }
> ```

此模块会导出不同的错误类别, 这些类别的工作不同 。 所有东西都可以以与上例相同的方式被导入.

### `OperationalError`

这个 `OperationalError` 类是大多数其他出错类型的基础类。 此上下文"操作"意为"我们理解这个出错的原因",所以通过使用这个出错类型,帮助你的团队在抛出一个出乎意料的出错时理解.

[Joyent 处理文件错误](https://web.archive.org/web/20220223020910/https://www.joyent.com/node-js/production/design/errors) 对操作错误有一个很好的解释.

总是最好使用更具体的错误,例如. [`UpstreamServiceError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-upstreamserviceerror),如果存在适合你需要的。 因此,审查这里的文档 找到最合适的错误.

`OperationalError` 可以像普通错误一样工作, 需要消息 :

```js
throw new OperationalError('example message');
```

也可以用数据对象构建操作错误。 这个接受一个 `code` 属性,对于正在发生的错误类型,必须设置为指针,以及 `message` 包含可读信件的属性 :

```js
throw new OperationalError({
    message: 'example message',
    code: 'EXAMPLE_CODE'
});
```

出错代码常态化为大写,字母数字,并下划线限制. 错误属性可以像其他属性一样访问 :

```js
error.message // example message
error.code // EXAMPLE_CODE
```

也可以将这两种构建错误的方法结合起来,既传递信息,又传递附加选项. 这适用于所有错误类型:

```js
throw new OperationalError('example message', {
    code: 'EXAMPLE_CODE'
});
```

您也可以将额外属性传递到错误对象中,这些属性将被收集并存储在 `data` 错误属性 :

```js
const error = new OperationalError({
    message: 'example message',
    code: 'EXAMPLE_CODE',
    article: 'd92acacb-ac53-4505-aa88-eae4b42de994'
});

error.data.article // d92acacb-ac53-4505-aa88-eae4b42de994
```

#### `OperationalError.id`

这个 `id` 操作错误的属性存储一个用于向最终用户显示该错误的唯一标识符。 此错误ID必须符合 [错误 ID 规格](https://github.com/Financial-Times/spec-error-id#readme) 否则将默认为 `EI000`。 。 。 .

> \[TIP\] 如果您不确定, 请使用对系统有意义的内部错误代码, 匹配以下正则表达式 : `^EI[0-9]{3}$`。欲了解更多关于预期格式和注册的用户信息 [错误 ID 规格](https://github.com/Financial-Times/spec-error-id#readme)。您也可以通过 [错误编号软件包](https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/error-id#readme)。 。 。 .

#### `OperationalError.relatesToSystems`

这个 `relatesToSystems` 操作错误的属性存储列表 [FT系统](https://biz-ops.in.ft.com/list/Systems) 与你抛出的错误有关.

这一阵列可包括:

-   返回 HTTP 错误状态代码的依赖性
-   未提供预期数据的数据存储

#### `OperationalError.cause`

这个 `cause` 操作出错的属性存储根因子出错实例,例如已捕获的出错 `try`编号 :`catch` 块。 它允许操作错误包含由根因子错误所捕获的诊断信息.

#### `OperationalError.isErrorMarkedAsOperational()`

您也可以使用 `isErrorMarkedAsOperational` 方法。 它接受任何类型的错误对象并将返回 `true` 如果错误有真伪 `isOperational` 财产和 `false` 否则:

```js
OperationalError.isErrorMarkedAsOperational(new OperationalError('example message')); // true
OperationalError.isErrorMarkedAsOperational(new Error('example message')); // false
```

### `HttpError`

这个 `HttpError` 类扩展 `OperationalError` 并代表 HTTP 错误状态。 它可以和普通错误一样工作,等待消息. 在这种情况下,它将代表一个HTTP `500`数字 :

```js
throw new HttpError('example message');
```

您也可以用数据对象构建 HTTP 错误 。 这个接受一个 `statusCode` 属性,它是一个有效的 HTTP 状态代码,以及您可以在其中设置的所有属性 [`OperationalError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-operationalerror)数字 :

```js
throw new HttpError({
    message: 'your thing was not found',
    statusCode: 404
});
```

单用状态代码创建 HTTP 错误也是可能的,它会默认信件到相应的 HTTP 状态消息:

```js
throw new HttpError(404);
```

错误属性可以像其他属性一样访问 :

```js
error.message // your thing was not found
error.statusCode // 404
error.status // 404
error.statusMessage // Not Found
error.code // HTTP_404
```

#### 为什么要用这个 `http-errors`? 吗?

使用这个错误而不是优秀的 [网页错误](https://github.com/jshttp/http-errors#readme) 库就是我们延伸 `OperationalError` 默认。 这意味着你所抛出的所有HTTP出错被我们工具的其余部分视为"已知出错". 我们还定了一个 `code` 默认的属性导致监控仪表板的代码减少 `code` 财务报告和审定财务报表 `statusCode` 属性,以确定出错的类型.

### `DataStoreError`

这个 `DataStoreError` 类扩展 `OperationalError` 并代表在访问数据存储时发生的错误,例如:MongoDB、PostgreSQL或Redis。 它具有操作错误的所有特性,你可以仅用一个信息构建:

```js
throw new DataStoreError('Could not connect to Redis');
```

也可以用数据对象构建数据存储错误。 您可以使用定义于 [`OperationalError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-operationalerror)数字 :

```js
throw new DataStoreError({
    code: 'REDIS_CONNECTION_FAILED',
    message: 'Could not connect to Redis',
});
```

### `UpstreamServiceError`

这个 `UpstreamServiceError` 类扩展 `HttpError` 并代表连接上游服务时发生的错误,例如FT或第三方API。 它具有操作和HTTP出错的所有特性,你可以仅用一个消息来构建:

```js
throw new UpstreamServiceError('Content could not be fetched');
```

HTTP 状态代码默认为 a [502 (中文(简体) )](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502)。这表明,在连接上游服务时,您的系统收到了无法为最终用户服务的答复.

也可以用数据对象构建上游服务错误。 您可以使用定义于 [`HttpError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-httperror) 财务报告和审定财务报表 [`OperationalError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-operationalerror)数字 :

```js
throw new UpstreamServiceError({
    code: 'CONTENT_PIPELINE_FAILED',
    message: 'Content could not be fetched, the content pipeline is responding with a 503 status',
    statusCode: 503,
    relatesToSystems: ['cp-content-pipeline-graphql']
});
```

### `UserInputError`

这个 `UserInputError` 类扩展 `HttpError` 并代表基于无效用户输入的错误,例如,它们将一个错误的电子邮件地址输入到表格中。 它具有操作和HTTP出错的所有特性,但默认为 `400` 状态代码。 您可以仅用一个消息构建 :

```js
throw new UserInputError('An invalid email address was input');
```

也可以用数据对象构建用户输入错误。 您可以使用定义于 [`HttpError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-httperror) 财务报告和审定财务报表 [`OperationalError`](https://npmcn.com/package/%40dotcom-reliability-kit/errors/#readme-operationalerror)数字 :

```js
throw new UserInputError({
    code: 'REGISTRATION_INFO_INVALID',
    message: 'An invalid email address was input'
});
```

### `BaseError`

我们的指南开始谈论 [操作 vs 程序员出错](https://npmcn.com/package/docs/getting-started/throwing-errors.md#types-of-error)。这个库中的其他错误提供了操作错误,但它们都扩展了一个名为 `BaseError`本课提供了一些便利 `OperationalError` 但标记为非操作性:

```js
const error = new BaseError('This is an error');
error.isOperational === false; // true;
```

这使得您可以使用库代码中的"可靠性 Kit"出错,在那里丢出操作错误是不合理的. 这个 `id`, (中文(简体) ), `code`, (中文(简体) ), `message`,以及 `cause` 属性的工作方式与 `OperationalError`数字 :

```js
throw new BaseError({
    message: 'example message',
    code: 'EXAMPLE_CODE',
    cause: new TypeError('example cause')
});
```

## 移动

咨询 [移徙指南](https://npmcn.com/package/%40dotcom-reliability-kit/errors/docs/migration.md) 如果你想要迁移到这个软件包的后期主要版本.

## 捐款

见 [可靠性工具包中心贡献指南](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/docs/contributing.md)。 。 。 .

## 许可证

凭 [麻省理工学院](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/LICENSE) 执照.  
版权:"2022","金融时报"有限公司.

## 常见问题

### @dotcom-reliability-kit/errors 是什么？

一组错误类,帮助您在任何情况下丢出最合适的错误

### 如何安装 @dotcom-reliability-kit/errors？

在项目目录运行 npm install @dotcom-reliability-kit/errors，或使用 pnpm add / yarn add / bun add。

### @dotcom-reliability-kit/errors 支持 TypeScript 吗？

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

### @dotcom-reliability-kit/errors 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dotcom-reliability-kit/errors 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.12 \|\| ^24 \|\| ^26。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dotcom-reliability-kit/errors 可以商用吗？

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

### @dotcom-reliability-kit/errors 的下载量有多少？

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

### @dotcom-reliability-kit/errors 还在维护吗？

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