# @abinnovision/nestjs-healthz 中文文档

规范地址：https://npmcn.com/package/%40abinnovision/nestjs-healthz/

版本：0\.2\.0
npm 元数据更新时间：2026-10-11T23:11:28.212Z
中文译文更新时间：2026-11-08T01:31:16.946Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40abinnovision/nestjs-healthz
原文对照：https://npmcn.com/package/%40abinnovision/nestjs-healthz/?lang=original
项目主页：https://github.com/abinnovision/nestjs-commons#readme
源码仓库：https://github.com/abinnovision/nestjs-commons

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

- 包体积（解压后）：53.8 kB，31 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@nestjs/core ^11\.0\.0 \|\| ^12\.0\.0，@nestjs/common ^11\.0\.0 \|\| ^12\.0\.0
- 首次发布：2026-05-13T16:46:39.972Z
- 最新版本发布：2026-10-11T23:11:27.866Z
- 近 30 天下载量：1935（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

NestJS的自挂健康检查模块,具有跨模块的验证发现,每个测试者缓存,以及Kubernetes-style/liverz和/readyz端点.

## 安装

```sh
npm install @abinnovision/nestjs-healthz
```

也可以使用：`pnpm add @abinnovision/nestjs-healthz`、`yarn add @abinnovision/nestjs-healthz`、`bun add @abinnovision/nestjs-healthz`

## README

# @abinnovision/nestjs-healthz (英语)

[![npm](https://img.shields.io/npm/v/@abinnovision/nestjs-healthz?style=flat-square)](https://www.npmjs.com/package/@abinnovision/nestjs-healthz)

NestJS自载健康检查模块. Kubernetes 风格的山 `/livez`, (中文(简体) ), `/readyz`,以及 `/healthz` 端点,并发现在整个应用程序上装饰的健康证明人——没有中央注册,没有每个模块的接线.

## 安装

```bash
yarn add @abinnovision/nestjs-healthz
```

## 快速启动

### 1\. 安装模块

```typescript
import { HealthzModule } from "@abinnovision/nestjs-healthz";

@Module({
  imports: [DatabaseModule, HealthzModule.forRoot()],
})
export class AppModule {}
```

`HealthzModule.forRoot()` 是全球性的——每个装入 应用图被扫描给验证人.

### 2\. 宣布单元内具有依赖性的证明人

```typescript
import {
  HealthAttestor,
  type HealthCheckOutcome,
} from "@abinnovision/nestjs-healthz";

@HealthAttestor({ name: "database", critical: true })
export class DatabaseAttestor implements HealthAttestor {
  public constructor(private readonly db: DatabaseService) {}

  public async check(): Promise<HealthCheckOutcome> {
    await this.db.query("SELECT 1");
    return { status: "ok" };
  }
}
```

`@HealthAttestor()` 应用 `@Injectable()` 内部——同样的方式 `@Controller()` 财务报告和审定财务报表 `@Resolver()` 做,所以不需要同时写 `@Injectable()`。该类仍需注册为提供者:

```typescript
@Module({
  providers: [DatabaseService, DatabaseAttestor],
})
export class DatabaseModule {}
```

就是这样. `/healthz`, (中文(简体) ), `/readyz`,以及 `/livez` 现场直播.

## 终点

| 路径 | 行为 | 使用大小写 |
| --- | --- | --- |
| `GET /livez` | 回返 `200 { status, timestamp }`运行 **没有** 证相. | Kubernetes活性探测器——"过程是活的". |
| `GET /readyz` | 运行每个发现的验证人并返回总计状态. | Kubernetes准备探测器——"准备交通". |
| `GET /healthz` | 别名 `/readyz`。 。 。 . | 冠名"应用健康吗?". |

`/livez` 故意不做证明 这样下游会很慢 依赖无法触发吊舱重启 。 只电线 `/readyz` (或 `/healthz`准备检查大门的交通.

## 状态模式

总体状态为三态:

| 合计 | HTTP 密码 | 触发 |
| --- | --- | --- |
| `"ok"` | 200个 | 所有证明人均已报告 `ok`。 。 。 . |
| `"degraded"` | 200个 | 仅 **非临界** 证明人失败 . |
| `"down"` | 第503条 | 至少有一名证明人 `critical: true` (默认)失败 . |

每个证明人都声明这是否至关重要:

```typescript
@HealthAttestor({ name: "queue-depth", critical: false })
```

非关键证明人仍然被报告,但他们的失败没有 把车开走.

## 限速检查执行

每个证明人可以宣布实际的间隔 处决。 默认没有费率限制——每个请求运行 每张支票.

```typescript
@HealthAttestor({
  name: "redis",
  minIntervalMs: 10_000,
})
```

先前的成果——包括以往的成果 `down` 成果——是 用于满足内部请求 `minIntervalMs` 最后一个 执行。 间隔后下一个请求触发 a 新检查.

这主要是防止 探险交通淹没 基础子系统. `/readyz` 通常通过活性调查 控制器、负载平衡器和仪表板平行;无 `minIntervalMs`错误的客户端可以将它变成稳定 流经 `SELECT 1` 查询您的数据库。 约束是 进程——本地——每个复制品执行自己的费率.

## 超时和抛出错误

`check()` 以每测试者超时(默认为2000毫秒)为界。 A 类 超时检查报告为 `{ "status": "down" }`. 例外情况 抛出 `check()` 被困在跑道内,产生同样的 结果——没有任何例外能够逃脱控制器.

基本错误消息通过 NestJS 日志登录 操作员诊断,但故意 **没有** 列入 探测器响应, 因此操作不当的子系统不能泄露内部错误 文本给卷曲者 `/readyz`。 。 。 .

```typescript
@HealthAttestor({ name: "slow-api", timeoutMs: 5000 })
```

## 响应形状

```json
{
  "status": "ok",
  "checks": [
    {
      "name": "database",
      "status": "ok",
      "durationMs": 12
    },
    {
      "name": "redis",
      "status": "down",
      "durationMs": 2003
    }
  ],
  "timestamp": "2026-05-13T12:34:56.000Z"
}
```

HTTP 状态代码为 `503` 当总计状态为 `"down"` 财务报告和审定财务报表 `200` 否则.

## API 参考

### `HealthzModule.forRoot()`

在全球注册模块并挂载三个终点。 带 今天没有参数; 保留为任何条目的条目 未来模块配置 .

```typescript
HealthzModule.forRoot();
```

### `@HealthAttestor(options)`

把班级标作健康证明人. 班级必须执行 `check()` 返回时 `HealthCheckOutcome` (同声或同声. 内部适用 `@Injectable()`。 。 。 .

```typescript
interface HealthAttestorOptions {
  name: string;
  critical?: boolean; // default true
  minIntervalMs?: number; // when set, check runs at most once per interval
  timeoutMs?: number; // default 2000
}
```

### `HealthAttestor` (互动)

每个证明人必须履行的合同。 与 装饰器函数 — TypeScript 的单独值和类型命名空间 让 `@HealthAttestor(...)` 财务报告和审定财务报表 `implements HealthAttestor` 并肩作战.

```typescript
interface HealthAttestor {
  check(): Promise<HealthCheckOutcome> | HealthCheckOutcome;
}
```

### `HealthCheckOutcome`

```typescript
interface HealthCheckOutcome {
  status: "ok" | "down";
  details?: Record<string, string>;
}
```

`details` 浮出水面 `checks[].details` 在答复中—— 用于小型安全到推介诊断(例如:. `{ "lag_seconds": "12" }`) (中文(简体) ). 值仅限于字符串,所以 响应是可预测的,没有呼叫者可以不慎发布 无约束对象或敏感字段.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @abinnovision/nestjs-healthz 是什么？

NestJS的自挂健康检查模块,具有跨模块的验证发现,每个测试者缓存,以及Kubernetes-style/liverz和/readyz端点\.

### 如何安装 @abinnovision/nestjs-healthz？

在项目目录运行 npm install @abinnovision/nestjs-healthz，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@nestjs/core（^11\.0\.0 \|\| ^12\.0\.0）、@nestjs/common（^11\.0\.0 \|\| ^12\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @abinnovision/nestjs-healthz 支持 TypeScript 吗？

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

### @abinnovision/nestjs-healthz 支持 ESM 还是 CommonJS？

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

### @abinnovision/nestjs-healthz 可以商用吗？

@abinnovision/nestjs-healthz 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @abinnovision/nestjs-healthz 的下载量有多少？

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

### @abinnovision/nestjs-healthz 还在维护吗？

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