Go / 系统课时

把配置日志与优雅退出接入入口

把配置日志与优雅退出接入入口

入口程序需要同时解决三个发布问题:配置不能写死、日志要便于检索、收到终止信号后要给正在处理的请求留出收尾时间。下面把环境变量、flags、slog 和 http.Server.Shutdown 接到一个可直接运行的入口。

学习目标

  • 用“命令行参数 > 环境变量 > 默认值”的优先级读取监听地址与超时。
  • 用 log/slog 输出结构化启动、停止和错误日志。
  • 用 signal.NotifyContext 与 Server.Shutdown 完成有截止时间的优雅退出。

先把配置优先级固定下来

发布程序最容易出现的配置问题是同一参数有多个来源却没有明确优先级。这里约定 flags 最高,其次环境变量,最后才是代码默认值。例如 TASK_API_ADDR=:8081 配合 -addr=:8090 时,最终必须监听 :8090。

建议保留四个参数:监听地址 :8080、ReadHeaderTimeout=5s、IdleTimeout=60s、优雅退出上限 ShutdownTimeout=10s。ReadHeaderTimeout 限制读取请求头的时间,IdleTimeout 控制 keep-alive 空闲连接,而退出超时只约束关停阶段。

把配置、结构化日志和退出流程放进 main

下面示例适用于 Go 1.21+;其中 log/slog 从 Go 1.21 起进入标准库。保存为 main.go。

go
package main

import (
	"context"
	"errors"
	"flag"
	"fmt"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"
)

type config struct {
	addr              string
	readHeaderTimeout time.Duration
	idleTimeout       time.Duration
	shutdownTimeout   time.Duration
}

func firstNonEmpty(values ...string) string {
	for _, value := range values {
		if value != "" {
			return value
		}
	}
	return ""
}

func parseDuration(name, value string) time.Duration {
	d, err := time.ParseDuration(value)
	if err != nil {
		fmt.Fprintf(os.Stderr, "%s must be a Go duration, got %q\n", name, value)
		os.Exit(2)
	}
	return d
}

func loadConfig() config {
	var addrFlag, readHeaderFlag, idleFlag, shutdownFlag string

	// Flags 默认留空,解析后再覆盖环境变量,才能保证优先级正确。
	flag.StringVar(&addrFlag, "addr", "", "HTTP listen address")
	flag.StringVar(&readHeaderFlag, "read-header-timeout", "", "request header timeout")
	flag.StringVar(&idleFlag, "idle-timeout", "", "keep-alive idle timeout")
	flag.StringVar(&shutdownFlag, "shutdown-timeout", "", "graceful shutdown deadline")
	flag.Parse()

	return config{
		addr: firstNonEmpty(
			addrFlag,
			os.Getenv("TASK_API_ADDR"),
			":8080",
		),
		readHeaderTimeout: parseDuration("read-header-timeout", firstNonEmpty(
			readHeaderFlag,
			os.Getenv("TASK_API_READ_HEADER_TIMEOUT"),
			"5s",
		)),
		idleTimeout: parseDuration("idle-timeout", firstNonEmpty(
			idleFlag,
			os.Getenv("TASK_API_IDLE_TIMEOUT"),
			"60s",
		)),
		shutdownTimeout: parseDuration("shutdown-timeout", firstNonEmpty(
			shutdownFlag,
			os.Getenv("TASK_API_SHUTDOWN_TIMEOUT"),
			"10s",
		)),
	}
}

func main() {
	cfg := loadConfig()
	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: slog.LevelInfo,
	}))

	mux := http.NewServeMux()
	mux.HandleFunc("GET /healthz", func(w http.ResponseWriter, r *http.Request) {
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok\n"))
	})

	srv := &http.Server{
		Addr:              cfg.addr,
		Handler:           mux,
		ReadHeaderTimeout: cfg.readHeaderTimeout,
		IdleTimeout:       cfg.idleTimeout,
	}

	// SIGINT 对应 Ctrl+C;SIGTERM 是容器和服务管理器常用的停止信号。
	runCtx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	errCh := make(chan error, 1)
	go func() {
		logger.Info("server starting",
			"addr", cfg.addr,
			"read_header_timeout", cfg.readHeaderTimeout.String(),
			"idle_timeout", cfg.idleTimeout.String(),
		)
		errCh <- srv.ListenAndServe()
	}()

	select {
	case err := <-errCh:
		if err != nil && !errors.Is(err, http.ErrServerClosed) {
			logger.Error("server failed", "error", err)
			os.Exit(1)
		}
		return
	case <-runCtx.Done():
		logger.Info("shutdown signal received")
	}

	// Shutdown 停止接收新连接,并等待活动请求在截止时间前结束。
	shutdownCtx, cancel := context.WithTimeout(context.Background(), cfg.shutdownTimeout)
	defer cancel()

	if err := srv.Shutdown(shutdownCtx); err != nil {
		logger.Error("graceful shutdown failed", "error", err)
		_ = srv.Close()
		os.Exit(1)
	}

	if err := <-errCh; err != nil && !errors.Is(err, http.ErrServerClosed) {
		logger.Error("server stopped with error", "error", err)
		os.Exit(1)
	}
	logger.Info("server stopped")
}

预期结果

text
代码可由 Go 1.21+ 编译;进程启动后监听最终配置地址,并在收到 SIGINT 或 SIGTERM 后进入带截止时间的 Shutdown 流程。

配置加载、服务运行与优雅退出的生命周期

启动并验证配置覆盖

初始化模块后,用环境变量设置地址和请求头超时,再用 flag 把空闲超时覆盖成 45s。下面命令适用于 Bash、zsh 等 POSIX shell。

bash
test -f go.mod || go mod init example.com/taskapi >/dev/null 2>&1
TASK_API_ADDR=:8090 TASK_API_READ_HEADER_TIMEOUT=3s go run . -idle-timeout=45s

预期输出

text
{"time":"<TIME>","level":"INFO","msg":"server starting","addr":":8090","read_header_timeout":"3s","idle_timeout":"45s"}

<TIME> 是运行时生成的时间戳。另开一个终端请求健康检查:

bash
curl -sS -i http://127.0.0.1:8090/healthz

预期输出

text
HTTP/1.1 200 OK
Date: <TIME>
Content-Length: 3
Content-Type: text/plain; charset=utf-8

ok

如果同时设置 TASK_API_ADDR=:8081 与 -addr=:8090,启动日志中的 addr 应为 :8090。如果最终选中的 duration 值写成 fast,程序会在监听端口前以状态码 2 退出并指出参数格式错误。

验证优雅退出而不是直接杀进程

回到运行服务的终端按 Ctrl+C,signal.NotifyContext 会取消运行上下文;随后 Shutdown 停止接受新连接,并等待现有请求结束,最长等待 shutdown-timeout 指定的时间。成功时会看到两条结构化日志。

text
{"time":"<TIME>","level":"INFO","msg":"shutdown signal received"}
{"time":"<TIME>","level":"INFO","msg":"server stopped"}

Shutdown 超时返回错误时,示例调用 Close 强制关闭剩余连接并以非零状态退出。生产程序还应把数据库连接池、消息消费者等资源放在同一退出阶段收尾,但不要先关闭它们再等待 HTTP 请求,否则仍在执行的处理器可能突然失去依赖。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

把配置日志与优雅退出接入入口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通