@abinnovision/nestjs-healthz (英语)

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

安装

yarn add @abinnovision/nestjs-healthz

快速启动

1. 安装模块

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

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

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

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

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()。该类仍需注册为提供者:

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

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

终点

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

状态模式

总体状态为三态:

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

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

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

限速检查执行

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

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

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

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

超时和抛出错误

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

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

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

响应形状

{
  "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()

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

HealthzModule.forRoot();

@HealthAttestor(options)

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

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 并肩作战.

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

HealthCheckOutcome

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

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

许可证

阿帕奇 - 2.0