graterm - Golang 实现应用程序顺序/并发优雅终止插件库

graterm 是一个提供有序优雅终止（Graceful Termination）功能的 Go 语言库，可以帮助应用程序在收到终止信号时按顺序或并发地执行清理操作。

⚡ 功能描述

该库提供流畅的方法来注册有序的应用程序终止钩子（hooks），并阻塞主 goroutine 直到注册的 os.Signal 出现。

具有相同 Order 的终止钩子将并发执行。可以为每个注册的终止钩子设置单独的超时时间，也可以为整个应用程序设置全局终止超时。

🎯 特性

• 仅依赖标准 Go 库（测试除外）
• 与组件无关（可适配任何第三方技术）
• 干净且经过测试的代码：100% 测试覆盖率，包括 goroutine 泄漏测试
• 丰富的示例集

⚙️ 使用方法

安装

go get -u github.com/skovtunenko/graterm

导入

import (
    "github.com/skovtunenko/graterm"
)

基础示例

package main

import (
    "context"
    "log"
    "syscall"
    "time"

    "github.com/skovtunenko/graterm"
)

func main() {
    // 定义终止顺序
    const (
        HTTPServerTerminationOrder graterm.Order = 1
        MessagingTerminationOrder  graterm.Order = 1
        DBTerminationOrder         graterm.Order = 2
    )

    // 创建 Terminator 实例
    terminator, appCtx := graterm.NewWithSignals(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    terminator.SetLogger(log.Default()) // 可选步骤

    // 注册 HTTP Server 终止钩子
    terminator.WithOrder(HTTPServerTerminationOrder).
        WithName("HTTP Server"). // 设置名称是可选的，只有在提供 logger 实例时才有用
        Register(1*time.Second, func(ctx context.Context) {
            log.Println("terminating HTTP Server...")
            defer log.Println("...HTTP Server terminated")
        })

    // 注册无名称的 Messaging 终止钩子
    terminator.WithOrder(MessagingTerminationOrder).
        Register(1*time.Second, func(ctx context.Context) {
            log.Println("terminating Messaging...")
            defer log.Println("...Messaging terminated")
        })

    // 注册 Database 终止钩子
    terminator.WithOrder(DBTerminationOrder).
        WithName("DB"). // 设置名称是可选的，只有在提供 logger 实例时才有用
        Register(1*time.Second, func(ctx context.Context) {
            log.Println("terminating DB...")
            defer log.Println("...DB terminated")

            const sleepTime = 3 * time.Second
            select {
            case <-time.After(sleepTime):
                log.Printf("DB termination sleep time %v is over\n", sleepTime)
            case <-ctx.Done():
                log.Printf("DB termination Context is Done because of: %+v\n", ctx.Err())
            }
        })

    // 等待 os.Signal 出现，然后以最多 20 秒的超时时间终止应用程序
    if err := terminator.Wait(appCtx, 20 * time.Second); err != nil {
        log.Printf("graceful termination period was timed out: %+v", err)
    }
}

与 HTTP 服务器集成示例

package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "net/http"
    "syscall"
    "time"

    "github.com/skovtunenko/graterm"
)

func main() {
    // 定义 HTTP Server 终止顺序
    const HTTPServerTerminationOrder graterm.Order = 1

    // 创建 Terminator 实例
    terminator, appCtx := graterm.NewWithSignals(context.Background(), syscall.SIGINT, syscall.SIGTERM)
    terminator.SetLogger(log.Default()) // 可选步骤

    // 创建 HTTP Server 并添加一个简单的处理程序
    httpServer := &http.Server{
        Addr:              ":8080",
        Handler:           http.DefaultServeMux,
    }
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintf(w, "hello, world!")
    })

    // 在单独的 goroutine 中启动 HTTP 服务器
    go func() { 
        if err := httpServer.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            log.Printf("terminated HTTP Server: %+v\n", err)
        }
    }()

    // 注册 HTTP Server 终止钩子
    terminator.WithOrder(HTTPServerTerminationOrder).
        WithName("HTTPServer"). // 设置名称是可选的，只有在提供 logger 实例时才有用
        Register(10*time.Second, func(ctx context.Context) {
            if err := httpServer.Shutdown(ctx); err != nil {
                log.Printf("shutdown HTTP Server: %+v\n", err)
            }
        })

    // 等待 os.Signal 出现，然后以最多 30 秒的超时时间终止应用程序
    if err := terminator.Wait(appCtx, 30*time.Second); err != nil {
        log.Printf("graceful termination period is timed out: %+v\n", err)
    }
}

测试

运行单元测试：

make test

运行代码质量检查：

make code-quality

许可证

MIT 许可证

作者

• Sergiy Kovtunenko
• Oleksandr Halushchak

graterm 提供了一种简单而强大的方式来实现 Go 应用程序的优雅终止功能，确保资源能够按正确的顺序释放，同时提供灵活的配置选项来满足不同场景的需求。