Golang健康检查插件库health使用指南

health是一个轻量级、可扩展的Golang健康检查库，可以帮助你构建服务健康检查系统。下面我将详细介绍其使用方法。

基本使用

首先安装health库：

go get github.com/alexliesenfeld/health

简单示例

package main

import (
	"fmt"
	"net/http"
	"time"
	
	"github.com/alexliesenfeld/health"
)

func main() {
	// 创建健康检查器
	checker := health.NewChecker(
		// 设置检查超时时间
		health.WithTimeout(10*time.Second),
		
		// 添加自定义检查项
		health.WithCheck(health.Check{
			Name: "some-check",
			Check: func() error {
				// 这里实现你的检查逻辑
				// 返回nil表示健康，返回error表示不健康
				return nil
			},
		}),
	)
	
	// 创建HTTP健康检查端点
	http.Handle("/health", health.NewHandler(checker))
	
	// 启动HTTP服务器
	fmt.Println("Server started at :8080")
	http.ListenAndServe(":8080", nil)
}

核心功能

1. 内置检查器

health提供了一些内置检查器：

checker := health.NewChecker(
	// 内存使用检查
	health.WithSystemMemoryCheck(0.9), // 内存使用超过90%报错
	
	// 磁盘空间检查
	health.WithSystemDiskCheck("/", 0.9), // 根目录使用超过90%报错
	
	// Goroutine数量检查
	health.WithSystemGoroutineCountCheck(1000), // 超过1000个goroutine报错
)

2. 自定义检查项

checker := health.NewChecker(
	health.WithCheck(health.Check{
		Name: "database",
		Check: func() error {
			// 实现数据库连接检查
			db, err := sql.Open("mysql", "user:password@/dbname")
			if err != nil {
				return err
			}
			return db.Ping()
		},
		Timeout: 5 * time.Second, // 单独设置超时
		CacheDuration: 10 * time.Second, // 缓存检查结果10秒
	}),
)

3. 周期性检查

checker := health.NewChecker(
	health.WithPeriodicCheck(15*time.Second, 5*time.Second, health.Check{
		Name: "external-service",
		Check: func() error {
			// 检查外部服务
			resp, err := http.Get("https://api.example.com/status")
			if err != nil {
				return err
			}
			defer resp.Body.Close()
			if resp.StatusCode != http.StatusOK {
				return fmt.Errorf("unexpected status code: %d", resp.StatusCode)
			}
			return nil
		},
	}),
)

高级功能

1. 自定义响应格式

http.Handle("/health", health.NewHandler(
	health.WithChecker(checker),
	health.WithResultWriter(&health.JSONResultWriter{
		PrettyPrint: true,
	}),
))

2. 添加元数据

checker := health.NewChecker(
	health.WithComponent(health.Component{
		Name:    "my-service",
		Version: "1.0.0",
	}),
	health.WithCustomDetails("environment", "production"),
)

3. 状态聚合

checker := health.NewChecker(
	health.WithStatusListener(func(ctx context.Context, state health.CheckerState) {
		// 当健康状态变化时触发
		if state.Status == health.StatusDown {
			log.Printf("Service is down! Details: %v", state.Details)
		}
	}),
)

完整示例

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"
	
	"github.com/alexliesenfeld/health"
)

func main() {
	// 创建健康检查器
	checker := health.NewChecker(
		// 基本配置
		health.WithTimeout(10*time.Second),
		health.WithComponent(health.Component{
			Name:    "order-service",
			Version: "1.2.0",
		}),
		
		// 系统资源检查
		health.WithSystemMemoryCheck(0.8),
		health.WithSystemDiskCheck("/", 0.9),
		
		// 自定义检查项
		health.WithCheck(health.Check{
			Name: "database",
			Check: func() error {
				// 模拟数据库检查
				time.Sleep(100 * time.Millisecond)
				return nil
			},
		}),
		
		// 周期性检查外部服务
		health.WithPeriodicCheck(30*time.Second, 5*time.Second, health.Check{
			Name: "payment-gateway",
			Check: func() error {
				// 模拟外部服务检查
				time.Sleep(200 * time.Millisecond)
				return nil
			},
		}),
		
		// 状态监听
		health.WithStatusListener(func(ctx context.Context, state health.CheckerState) {
			fmt.Printf("Health status changed to: %s\n", state.Status)
		}),
	)
	
	// 创建HTTP健康检查端点
	http.Handle("/health", health.NewHandler(checker))
	
	// 启动服务器
	fmt.Println("Server started at :8080")
	if err := http.ListenAndServe(":8080", nil); err != nil {
		panic(err)
	}
}

扩展建议

1. 集成到现有框架：可以轻松集成到Gin、Echo等Web框架中
2. 自定义检查器：实现health.Checkable接口创建可复用的检查器
3. 监控集成：将健康状态变化发送到Prometheus、Datadog等监控系统
4. 优雅停机：在健康检查失败时触发优雅停机流程

health库设计简洁但功能强大，非常适合微服务架构中的健康检查需求。通过合理配置检查项和阈值，可以全面监控服务的健康状况。