当前位置：首页 > news >正文

从入门到精通：Terminus健康检查API全解析

news 2026/7/19 13:56:31

从入门到精通：Terminus健康检查API全解析

【免费下载链接】terminusTerminus module for Nest framework (node.js) :robot:项目地址: https://gitcode.com/gh_mirrors/terminus3/terminus

Terminus是Nest框架的健康检查模块，为Node.js应用提供全面的健康状态监控能力。通过简单配置即可实现多种健康检查功能，帮助开发者实时掌握应用运行状态，及时发现并解决问题。

为什么选择Terminus健康检查？

在现代应用开发中，健康检查是保障系统稳定性的关键环节。Terminus作为Nest官方推荐的健康检查解决方案，具有以下核心优势：

开箱即用：提供多种预设健康检查器，无需从零开发
灵活扩展：支持自定义健康检查逻辑，满足特定业务需求
Nest生态集成：与Nest框架深度融合，保持一致的开发体验
全面监控：覆盖数据库、内存、磁盘、HTTP服务等多种检查类型

快速上手：Terminus基础配置

安装与导入

首先通过npm安装Terminus模块：

npm install @nestjs/terminus

然后在应用模块中导入TerminusModule：

import { Module } from '@nestjs/common'; import { TerminusModule } from '@nestjs/terminus'; @Module({ imports: [TerminusModule] }) export class AppModule {}

创建健康检查控制器

创建健康检查控制器来定义健康检查端点：

// src/health/health.controller.ts import { Controller, Get } from '@nestjs/common'; import { HealthCheckService, HttpHealthIndicator, HealthCheck } from '@nestjs/terminus'; @Controller('health') export class HealthController { constructor( private health: HealthCheckService, private http: HttpHealthIndicator, ) {} @Get() @HealthCheck() check() { return this.health.check([ () => this.http.pingCheck('nestjs-docs', 'https://docs.nestjs.com'), ]); } }

启动应用后，访问http://localhost:3000/health即可查看健康检查结果。

核心健康检查类型详解

1. HTTP服务检查

通过HttpHealthIndicator可以监控外部HTTP服务的可用性：

this.http.pingCheck('api-service', 'https://api.example.com/health')

支持配置超时时间和状态码验证，确保依赖服务正常运行。

2. 数据库健康检查

Terminus提供多种数据库检查器，轻松监控数据库连接状态：

TypeORM检查：typeormHealthIndicator.pingCheck('database')
Mongoose检查：mongooseHealthIndicator.pingCheck('mongodb')
Sequelize检查：sequelizeHealthIndicator.pingCheck('mysql')
Prisma检查：prismaHealthIndicator.pingCheck('prisma')

配置示例可参考样本项目中的005-typeorm-app和008-multi-database-mongoose-app。

3. 内存与磁盘检查

监控系统资源使用情况，防止资源耗尽：

// 内存检查 this.memoryHealthIndicator.checkHeap('memory_heap', 150 * 1024 * 1024); // 磁盘检查 this.diskHealthIndicator.checkStorage('storage', { path: '/', thresholdPercent: 0.9 });

相关实现可查看memory.health.ts和disk.health.ts。

4. 微服务健康检查

支持gRPC、RMQ等微服务健康状态监控：

this.microserviceHealthIndicator.pingCheck('grpc-service', { transport: Transport.GRPC, options: { package: 'health', protoPath: join(__dirname, './protos/health.proto'), url: 'localhost:5005', }, });

详细示例可参考004-grpc-app项目。

高级功能与最佳实践

动态配置

使用Terminus.forRootAsync实现动态配置：

TerminusModule.forRootAsync({ useFactory: () => ({ endpoints: [ { url: '/health', healthIndicators: [ async () => this.http.pingCheck('nestjs-docs', 'https://docs.nestjs.com'), ], }, ], }), })

错误处理与日志

Terminus提供完善的错误处理机制，可通过配置自定义错误日志：

{ errorLogStyle: 'json', // 或 'pretty' logger: new MyCustomLogger() }

相关实现可查看error-logger目录下的代码。

健康检查缓存

合理配置缓存策略，减轻系统负担：

@HealthCheck({ cacheDuration: 3000 }) // 缓存3秒 check() { // 健康检查逻辑 }

常见问题与解决方案

健康检查端点无法访问

确保在控制器中正确使用@HealthCheck()装饰器，并检查路由是否被正确注册。

数据库检查失败

验证数据库连接配置是否正确，确保应用有权限访问数据库服务。相关错误处理可参考errors目录下的错误定义。

自定义健康检查

创建自定义健康检查器：

import { HealthIndicator, HealthIndicatorResult } from '@nestjs/terminus'; export class CustomHealthIndicator extends HealthIndicator { async check(key: string): Promise<HealthIndicatorResult> { const isHealthy = await this.someCheck(); return this.getStatus(key, isHealthy); } }