Go / 系统课时

配置生产启动与停机

配置生产启动与停机

生产 HTTP 服务不能只调用 http.ListenAndServe 就结束:需要集中管理监听地址、读写超时和环境参数,并在收到退出信号后停止接收新请求、等待在途请求完成。本文用一个可运行程序串起启动失败、优雅停机和停机超时日志,形成可直接部署的最小基线。

学习目标

  • 使用环境变量集中配置监听地址和 HTTP 各阶段超时
  • 用 signal.NotifyContext 与 Server.Shutdown 建立可控的优雅停机流程
  • 区分正常关闭、启动失败和停机超时,并为三种结果留下明确日志

先定义生产配置边界

生产配置至少应覆盖监听地址、ReadHeaderTimeout、ReadTimeout、WriteTimeout、IdleTimeout 与停机宽限期。超时不是越短越好:读写超时必须大于业务允许的正常处理时间,而停机宽限期应覆盖绝大多数在途请求,但仍有明确上限。

下面的程序使用环境变量覆盖默认值;所有持续时间都采用 Go 的 time.ParseDuration 格式,例如 2s、500ms。解析失败直接终止启动,避免服务带着模糊配置继续运行。

组装服务器与优雅停机

Serve 应放到独立 goroutine 中运行,主 goroutine 负责等待 SIGINT 或 SIGTERM。收到信号后调用 Shutdown(ctx):服务器先关闭监听器,不再接收新连接,再等待活跃请求返回;若宽限期耗尽,Shutdown 会返回上下文超时错误。

生产 HTTP 服务从启动到优雅停机的生命周期

go
package main

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

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

func envDuration(key string, fallback time.Duration) time.Duration {
	raw := os.Getenv(key)
	if raw == "" {
		return fallback
	}
	d, err := time.ParseDuration(raw)
	if err != nil {
		log.Fatalf("invalid %s=%q: %v", key, raw, err)
	}
	return d
}

func loadConfig() config {
	addr := os.Getenv("HTTP_ADDR")
	if addr == "" {
		addr = ":8080"
	}
	return config{
		addr:              addr,
		readHeaderTimeout: envDuration("HTTP_READ_HEADER_TIMEOUT", 2*time.Second),
		readTimeout:       envDuration("HTTP_READ_TIMEOUT", 10*time.Second),
		writeTimeout:      envDuration("HTTP_WRITE_TIMEOUT", 15*time.Second),
		idleTimeout:       envDuration("HTTP_IDLE_TIMEOUT", 60*time.Second),
		shutdownTimeout:   envDuration("HTTP_SHUTDOWN_TIMEOUT", 10*time.Second),
	}
}

func main() {
	cfg := loadConfig()

	mux := http.NewServeMux()
	mux.HandleFunc("/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,
		ReadTimeout:       cfg.readTimeout,
		WriteTimeout:      cfg.writeTimeout,
		IdleTimeout:       cfg.idleTimeout,
	}

	errCh := make(chan error, 1)
	go func() {
		log.Printf("http server starting addr=%s", cfg.addr)
		errCh <- srv.ListenAndServe()
	}()

	sigCtx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
	defer stop()

	select {
	case err := <-errCh:
		if !errors.Is(err, http.ErrServerClosed) {
			log.Fatalf("http server start/run failed: %v", err)
		}
		return
	case <-sigCtx.Done():
		log.Printf("shutdown signal received")
	}

	shutdownCtx, cancel := context.WithTimeout(context.Background(), cfg.shutdownTimeout)
	defer cancel()

	if err := srv.Shutdown(shutdownCtx); err != nil {
		log.Printf("http server shutdown failed: %v", err)
		_ = srv.Close()
		os.Exit(1)
	}
	log.Printf("http server shutdown complete")
}

预期输出

text
<TIME> http server starting addr=:8080
<TIME> shutdown signal received
<TIME> http server shutdown complete

日志时间前缀由标准库生成,实际值会不同。若端口已被占用,程序会记录 http server start/run failed 并退出;若在 HTTP_SHUTDOWN_TIMEOUT 内仍有请求未结束,则记录 http server shutdown failed: context deadline exceeded,随后强制关闭连接并以非零状态退出。

用环境变量启动并验证

可以先把监听地址改为高位端口,再从另一个终端访问健康检查接口。配置项集中在环境变量后,容器编排或进程管理器只需要注入值,不必修改二进制。

bash
HTTP_ADDR=:9090 HTTP_READ_HEADER_TIMEOUT=2s HTTP_READ_TIMEOUT=10s HTTP_WRITE_TIMEOUT=15s HTTP_IDLE_TIMEOUT=60s HTTP_SHUTDOWN_TIMEOUT=10s go run .

预期输出

text
<TIME> http server starting addr=:9090

随后请求 http://localhost:9090/healthz 应得到 HTTP 200 与正文 ok。按 Ctrl+C 后,进程不再接受新连接,并在在途请求完成或宽限期耗尽后退出。

生产配置要避免的两个误区

不要把 WriteTimeout 设置得短于合法长请求的处理上限,否则正常响应也可能被服务器中断;也不要把停机宽限期设成无限等待,否则发布或节点回收可能永远卡住。对于流式响应、WebSocket 或显式接管连接的场景,还需要单独设计连接生命周期,不能只依赖普通 HTTP 请求的 Shutdown 等待机制。

这套基线把配置解析、启动失败、信号处理和停机结果放在同一个可观测路径里:服务正常关闭应是可识别的成功事件,而不是依赖“进程消失了”来猜测是否安全退出。

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

目录与阅读设置

阅读设置

17

记录一个想法

配置生产启动与停机

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

登录哪都通