高级技巧：@godaddy/terminus自定义错误处理和健康检查响应

高级技巧：@godaddy/terminus自定义错误处理和健康检查响应

【免费下载链接】terminusGraceful shutdown and Kubernetes readiness / liveness checks for any Node.js HTTP applications项目地址: https://gitcode.com/gh_mirrors/te/terminus

在Node.js应用开发中，实现优雅关闭（Graceful Shutdown）和可靠的健康检查是保障服务稳定性的关键环节。@godaddy/terminus作为一款强大的Node.js HTTP应用工具，不仅提供了基础的Kubernetes就绪/存活检查功能，还支持高度可定制的错误处理和健康检查响应机制。本文将分享如何通过简单配置实现专业级的错误处理策略和健康检查响应定制，帮助开发者构建更健壮的生产级应用。

为什么需要自定义健康检查响应？

默认的健康检查通常只返回简单的"OK"状态，但在实际生产环境中，你可能需要：

• 返回详细的服务状态信息（如数据库连接数、缓存命中率）
• 根据不同业务模块返回分级健康状态
• 实现自定义的健康检查逻辑（如依赖服务可用性检测）
• 为监控系统提供结构化的健康数据

通过@godaddy/terminus的健康检查自定义功能，你可以轻松实现上述需求，让健康检查成为系统监控的重要组成部分。

基础健康检查配置示例

在@godaddy/terminus中配置健康检查非常简单，以下是一个基础示例：

const express = require('express'); const terminus = require('@godaddy/terminus'); const app = express(); // 自定义健康检查函数 function onHealthCheck() { // 在这里实现你的健康检查逻辑 // 例如：检查数据库连接、缓存服务等 return Promise.resolve(); } const server = app.listen(3000); terminus(server, { healthChecks: { '/healthcheck': onHealthCheck // 健康检查端点 } });

这段代码在/healthcheck路径上配置了一个基础的健康检查端点，当服务正常时返回200状态码。你可以在各个示例目录中找到类似的实现，如example/mongoose/express.js和example/postgres/index.js。

高级健康检查响应定制

返回自定义状态信息

要返回更详细的健康状态信息，只需在健康检查函数中返回一个包含状态数据的对象：

async function onHealthCheck() { // 检查数据库连接 const dbStatus = await checkDatabaseConnection(); // 检查缓存服务 const cacheStatus = await checkCacheService(); return { status: 'ok', timestamp: new Date().toISOString(), services: { database: dbStatus, cache: cacheStatus, api: 'running' } }; }

这种方式可以为监控系统提供丰富的状态数据，帮助运维人员快速定位问题。

实现分级健康状态

有时你可能需要区分"完全健康"和"部分健康"状态，这可以通过抛出错误来实现：

async function onHealthCheck() { const criticalServices = await checkCriticalServices(); if (!criticalServices.database) { // 关键服务不可用时抛出错误，返回503状态码 throw new Error('Database connection failed'); } return { status: 'degraded', services: { database: 'ok', cache: 'degraded', search: 'unavailable' } }; }

当健康检查函数抛出错误时，terminus会自动返回503状态码，这对于Kubernetes的存活检查非常有用。

错误处理高级配置

@godaddy/terminus提供了多种错误处理钩子，让你能够捕获和处理不同阶段的错误。

onSendFailureDuringShutdown

当服务正在关闭但仍收到请求时，会触发onSendFailureDuringShutdown钩子：

terminus(server, { onSendFailureDuringShutdown: async () => { // 记录关闭期间的请求 logger.warn('Request received during shutdown'); // 可以在这里实现自定义的错误响应逻辑 }, healthChecks: { '/healthcheck': onHealthCheck } });

这个钩子在lib/terminus.js中定义，用于处理关闭期间的请求。

信号处理与优雅关闭

terminus支持多种系统信号的处理，包括SIGTERM、SIGINT和SIGUSR2，你可以通过onSignal和onShutdown钩子实现优雅关闭逻辑：

terminus(server, { signals: ['SIGTERM', 'SIGINT'], onSignal: async () => { // 在关闭前执行清理操作 await closeDatabaseConnections(); await flushCaches(); }, onShutdown: async () => { // 所有连接关闭后执行的操作 console.log('Server gracefully shutdown'); }, healthChecks: { '/healthcheck': onHealthCheck } });

这种配置可以确保服务在收到关闭信号时，能够完成当前请求并清理资源后再退出。你可以在lib/standalone-tests/terminus.onshutdown.sigterm.js等测试文件中找到更多信号处理示例。

实际应用场景示例

数据库连接检查

在example/mysql/index.js中，展示了如何检查MySQL数据库连接：

function onHealthCheck () { return new Promise((resolve, reject) => { connection.query('SELECT 1', (error) => { if (error) { reject(error); } else { resolve(); } }); }); }

多服务器健康检查

在lib/standalone-tests/terminus.multiserver.js中，展示了如何为多个服务器实例配置健康检查：

const server1 = http.createServer((req, res) => res.end('ok')) const server2 = http.createServer((req, res) => res.end('ok')) const server3 = http.createServer((req, res) => res.end('ok')) terminus([server1, server2, server3], { onSignal: () => { console.log('server1:onSignal') }, healthChecks: { '/healthcheck': () => Promise.resolve() } })

最佳实践总结

1. 实现有意义的健康检查：不要只返回"OK"，而是检查关键依赖服务的状态
2. 使用结构化响应：返回JSON格式的健康数据，便于监控系统解析
3. 合理设置超时时间：根据业务需求调整健康检查超时时间
4. 全面的错误处理：利用onSignal和onShutdown钩子确保资源正确释放
5. 测试关闭流程：通过lib/terminus.spec.js中的测试用例了解各种关闭场景

通过本文介绍的自定义错误处理和健康检查响应技巧，你可以充分利用@godaddy/terminus的强大功能，为你的Node.js应用构建更可靠的生命周期管理系统。无论是简单的Express应用还是复杂的微服务架构，这些最佳实践都能帮助你提升系统的稳定性和可维护性。

要开始使用@godaddy/terminus，只需通过npm安装：

npm install @godaddy/terminus

或者克隆仓库进行本地开发：

git clone https://gitcode.com/gh_mirrors/te/terminus

探索example/目录中的各种示例，了解如何将terminus集成到不同类型的Node.js应用中。

【免费下载链接】terminusGraceful shutdown and Kubernetes readiness / liveness checks for any Node.js HTTP applications项目地址: https://gitcode.com/gh_mirrors/te/terminus