9、给应用添加优雅关停功能

在成功实现一个简单的 Web 服务器之后，接下来需要进一步完善其核心功能，使其更贴合实际需求并满足企业级应用场景的要求。例如，需要实现功能丰富的中间件、处理跨域访问、以及支持优雅关停等功能。本节课将深入个绍这些关键功能的实现，帮助打造一个更加健壮、高效、且易于维护的 Web 服务器。

添加优雅关停功能

Web 服务器通常都需要实现优雅关停功能。优雅关停服务器可以带来很多好处，例如提高 API 接口的成功率，减少系统脏数据的出现概率等。本节会详细介绍如何实现优雅关停功能。

优雅关停的必要性

在应用程序的生命周期中，新功能发布、缺陷修复、配置变更等操作都需要重启服务。在服务进程停止时，可能需要执行一些必要的处理工作，例如：

• 正在执行的 HTTP 请求需要等待其完成并返回结果，否则可能会导致请求报错或产生脏数据
• 异步处理任务需要将缓存中的数据处理完成，否则可能会导致数据丢失或不一致:
• 关闭数据库连接，否则数据库连接池可能会保留无效连接，浪费宝贵的连接资源,

为了解决上述问题，建议的做法是给应用添加优雅关停功能，以提高系统的健壮性。

优雅关停的实现思路

实现优雅关停的最佳实践是在服务进程停止前，等待所有任务处理完成后再退出进程。在 Go 应用开发中，可以通过向应用程序发送标准的系统信号来终止服务进程。以下是最常见的三种终止方式：

• CTRL+C : 发送 SIGINT 信号;
• kill <pid> : 向指定进程发送SIGTERM 信号;
• kill -9 <pid> : 向指定进程发送 SIGKILL 信号，强制终止信号。需要注意的是，SIGKILL 信号既不能被应用程序捕获，也不能被阻塞或忽略

提示：日常关闭服务时，应该尽量避免使用kill -9 ，因为此命令会导致应用进程无法执行优雅关停逻辑。

fastgo实现优雅关停功能

如果能够捕获SIGINT和SIGTERM信号，并在捕获后执行一些关停逻辑，就可以实现优雅关停功能。实际上，当前go应用的优雅关停大多都是这么实现的。

Go提供了os/signal包，用于监听并处理接受到的信号。

// 启动一些非阻塞任务，例如：HTTP / gRPC 服务，异步任务处理等逻辑

// 创建一个 os.Signal 类型的 channel，用于接收系统信号
quit := make(chan os.Signal, 1)
// 当执行 kill 命令时（不带参数），默认会发送 syscall.SIGTERM 信号
// 使用 kill -2 命令会发送 syscall.SIGINT 信号（例如按 CTRL+C 触发）
// 使用 kill -9 命令会发送 syscall.SIGKILL 信号，但 SIGKILL 信号无法被捕获，因此无需监听和处理
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
// 阻塞程序，等待从 quit channel 中接收到信号
<-quit

// 执行一些清理工作

// 程序自然退出

上述代码执行优雅关停的流程如下：

1. 启动 HTTP/GRPC 服务或其他异步任务，以非阻塞方式运行。如果服务本身是阻塞方式，可以通过 Go 协程启动;
2. 创建一个 os.Signal 类型的 channel，用于捕获应用程序的关停信号;
3. 调用 signal.Notify函数，设置需要捕获的信号类型，例如 syscall.SIGINT 和syscall.SIGTERM
4. 使用 <-quit 阻塞主程序，等待信号到来;
5. 当系统接收到 SIGINT 或SIGTERM 信号时，会向 quit 通道写入一条 os.Signal 类型的数据;
6. quit 读取到信号后，解除阻塞状态，执行后续清理工作。清理完成后，进程正常退出。清理工作可根据业务逻辑执行不同的操作，例如通过 net/http 包的 Shutdown 方法优雅关闭 HTTP 服务。

在 Go 项目开发中，还可以通过一些 Go 包，例如: fvbock/endless 来实现优雅关停，但更推荐上面的方式，简单，并目不需要引入新包。很多优秀的开源项目，例如 Kubernetes 优雅关停实现思路跟上述思路保持一致。

fastgo 根据以上优雅关停功能实现思路，实现了优雅关停逻辑，代码如下(位于 intemal/apiserver/server.go 文件中):

// Run
//
//	@Description: Run运行应用
//	@receiver s
//	@return error
func (s *Server) Run() error {
	slog.Info(fmt.Sprintf("Read MYSQL host from config %s", s.cfg.MYSQLOptions.Addr))
	slog.Info("Start to listening the incoming requests on http address", "addr", s.cfg.Addr)
	go func() {
		if err := s.srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
			slog.Error(err.Error())
			os.Exit(1)
		}
	}()
	// 创建一个os.Signal 类型的channel，用于接受系统信号
	quit := make(chan os.Signal, 1)
	// 当执行kill命令时（不带参数），默认会发送syscall.SIGTERM信号
	// 使用kill -2 命令会发送syscall.SIGINT信号（例如按ctrl+c触发）
	// 使用kill -9 命令会发送syscall.SIGKILL信号，但SIGKILL信号无法被捕捉，因此无需监听和处理
	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
	// 阻塞程序，等待从quit channel中接受到信号
	<-quit
	slog.Info("Shutting down server ....")
	// 优雅关闭服务
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	// 先关闭依赖的服务，再关闭被依赖的服务
	// 10秒内优雅关闭服务（将未处理完的请求处理完再关闭服务），超过10秒就超时退出
	if err := s.srv.Shutdown(ctx); err != nil {
		slog.Error("Insecure Server forced to shutdown", "err", err)
		return err
	}
	slog.Info("Server exited")
	return nil
}

在上述代码中，quit 收到 SIGINT 和 SIGTERM 信号后，程序会解除阻塞状态，并调用*http.Server类型实例的 Shutdown 方法优雅关停服务器。

通过context.WithTimeout 创建上下文对象ctx，其主要作用是为优雅关闭服务提供超时控制，确保服务在一定时间内完成清理工作。如果超过指定时间(这里是 10 秒)，服务将被强制终止。 ctx 被传递给 s.srv.Shutdown(ctx)方法，用于通知服务相关的协程或其他子任务，当前服务正在关闭，并提供一个超时时间。服务中的任务可以通过监听 ctx.Done() 来检测是否需要终止，从而及时结束任务，避免资源泄漏。

*http.Server 类型的Shutdown 方法的工作流程如下: 首先关闭所有已开启的监听器，然后关闭所有空闲连接，最后等待所有活跃连接进入空闲状态后终止服务。如果传入的ctx 在服务完成终止之前超时，则 Shutdown 方法会返回与 context 相关的错误。否则会返回由关闭服务监听器引发的其他错误。

当Shutdown方法被调用时，Serve、ListenAndServe 以及 ListenAndServeTLS 方法会立即返回 ErrServerClosed 错误。ErrServerClosed 错误被视为服务关闭时的正常行为。因此，如果 ListenAndServe 返回该错误，程序不会打印错误信息。

编译并测试优雅关停功能

(base) dujie@MacBook-Pro fastgo % sh build.sh                                        
gitlab.com/onexstack/fastgo/internal/apiserver
gitlab.com/onexstack/fastgo/cmd/fg-apiserver/app/options
command-line-arguments
(base) dujie@MacBook-Pro fastgo % ./_output/fg-apiserver -c configs/fg-apiserver.yaml
/Users/dujie/.fastgo/fg-apiserver.yaml
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /healthz                  --> gitlab.com/onexstack/fastgo/internal/apiserver.(*Config).NewServer.func2 (5 handlers)
{"time":"2025-04-02T15:08:37.222349+08:00","level":"INFO","msg":"Read MYSQL host from config 127.0.0.1:3306"}
{"time":"2025-04-02T15:08:37.222451+08:00","level":"INFO","msg":"Start to listening the incoming requests on http address","addr":"0.0.0.0:6666"}
^C{"time":"2025-04-02T15:08:45.011961+08:00","level":"INFO","msg":"Shutting down server ...."}
{"time":"2025-04-02T15:08:45.012307+08:00","level":"INFO","msg":"Server exited"}