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 会返回上下文超时错误。

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")
}预期输出
<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,随后强制关闭连接并以非零状态退出。
用环境变量启动并验证
可以先把监听地址改为高位端口,再从另一个终端访问健康检查接口。配置项集中在环境变量后,容器编排或进程管理器只需要注入值,不必修改二进制。
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 .预期输出
<TIME> http server starting addr=:9090随后请求 http://localhost:9090/healthz 应得到 HTTP 200 与正文 ok。按 Ctrl+C 后,进程不再接受新连接,并在在途请求完成或宽限期耗尽后退出。
生产配置要避免的两个误区
不要把 WriteTimeout 设置得短于合法长请求的处理上限,否则正常响应也可能被服务器中断;也不要把停机宽限期设成无限等待,否则发布或节点回收可能永远卡住。对于流式响应、WebSocket 或显式接管连接的场景,还需要单独设计连接生命周期,不能只依赖普通 HTTP 请求的 Shutdown 等待机制。
这套基线把配置解析、启动失败、信号处理和停机结果放在同一个可观测路径里:服务正常关闭应是可识别的成功事件,而不是依赖“进程消失了”来猜测是否安全退出。