Go 服务优雅关闭入门：让 HTTP 服务收到信号后稳稳退出

服务退出也需要设计

很多入门 HTTP 服务最后都是这样：

log.Fatal(http.ListenAndServe(":8080", mux))

它能启动服务，但没有认真处理停止过程。你按 Ctrl+C，或者部署平台发送 SIGTERM，进程可能立刻退出，正在处理的请求被中断，日志没来得及刷，后台任务也不知道该停。小练习问题不大，真实服务就不够稳。

Go 的 http.Server 提供了 Shutdown 方法，可以停止接收新连接，并给正在处理的请求一点时间完成。配合 os/signal 和 context.WithTimeout，我们能写出一个清楚的优雅关闭流程。

这篇文章会从最小 HTTP 服务改起，逐步加入信号监听、关闭超时和后台任务退出。

使用 http.Server

先不要直接调用 http.ListenAndServe，而是创建 server：

mux := http.NewServeMux()
mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintln(w, "ok")
})

server := &http.Server{
	Addr:    ":8080",
	Handler: mux,
}

启动：

if err := server.ListenAndServe(); err != nil {
	log.Fatal(err)
}

有了 server 变量，后面就能调用 server.Shutdown(ctx)。

监听退出信号

常见退出信号是 os.Interrupt 和 syscall.SIGTERM。前者通常来自 Ctrl+C，后者常见于容器或进程管理器停止服务。

stop := make(chan os.Signal, 1)
signal.Notify(stop, os.Interrupt, syscall.SIGTERM)

<-stop
log.Println("shutdown signal received")

这段代码会阻塞，直到收到信号。实际服务中，HTTP server 需要同时运行，所以通常放到 goroutine 里启动服务，主 goroutine 等信号。

完整优雅关闭骨架

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/healthz", healthHandler)

	server := &http.Server{
		Addr:    ":8080",
		Handler: mux,
	}

	errCh := make(chan error, 1)
	go func() {
		log.Println("listening on :8080")
		errCh <- server.ListenAndServe()
	}()

	stop := make(chan os.Signal, 1)
	signal.Notify(stop, os.Interrupt, syscall.SIGTERM)

	select {
	case sig := <-stop:
		log.Printf("received signal: %s", sig)
	case err := <-errCh:
		if err != nil && err != http.ErrServerClosed {
			log.Fatalf("server error: %v", err)
		}
	}

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	if err := server.Shutdown(ctx); err != nil {
		log.Printf("graceful shutdown failed: %v", err)
		if err := server.Close(); err != nil {
			log.Printf("force close failed: %v", err)
		}
	}

	log.Println("server stopped")
}

Shutdown 会让 server 停止接收新请求，并等待已有请求结束，直到 context 超时。如果超时还没结束，可以调用 Close 强制关闭。

ListenAndServe 在正常关闭后会返回 http.ErrServerClosed，这不是错误，不应该当成 fatal。

给请求处理留出退出路径

优雅关闭不只是 server 的事，handler 也要尊重请求 context。

func slowHandler(w http.ResponseWriter, r *http.Request) {
	select {
	case <-time.After(3 * time.Second):
		fmt.Fprintln(w, "done")
	case <-r.Context().Done():
		log.Printf("request cancelled: %v", r.Context().Err())
		return
	}
}

如果客户端断开，或者 server 正在关闭，请求 context 会被取消。Handler 里做外部调用、数据库查询、长任务时，也应该把 r.Context() 传下去。

不要在 handler 深处随便使用 context.Background()，否则请求取消信号就断了。正确做法是：

user, err := service.GetUser(r.Context(), id)

这样关闭时，内部调用也有机会停止。

后台任务也要停

如果服务里有定时任务，可以共享一个根 context：

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

go runCleaner(ctx)

任务：

func runCleaner(ctx context.Context) {
	ticker := time.NewTicker(1 * time.Minute)
	defer ticker.Stop()

	for {
		select {
		case <-ticker.C:
			log.Println("clean expired data")
		case <-ctx.Done():
			log.Println("cleaner stopped")
			return
		}
	}
}

收到信号后先 cancel()，再关闭 server：

cancel()

shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
defer shutdownCancel()
server.Shutdown(shutdownCtx)

后台 goroutine 必须有退出路径。否则服务看似停止了 HTTP，但进程可能还挂着，或者任务在关闭过程中继续写数据。

常见问题 FAQ

Q: 为什么 Shutdown 后还有 goroutine 没退出？
A: Shutdown 只关闭 listener 和空闲连接。你自己启动的 goroutine 仍然需要手动退出。确保所有后台任务监听 ctx.Done()。

Q: 第二次信号真的有必要处理吗？
A: 长期运行的服务建议处理。第一次信号做优雅退出，第二次允许强制终止。短生命周期工具可以不需要。

Q: 开发环境 graceful shutdown 有必要吗？
A: 有必要。开发环境的数据库连接、日志 flush 同样需要清理。而且这是验证关闭逻辑是否正确的最佳环境。

常见陷阱

1. 把 http.ErrServerClosed 当错误处理：这是正常关闭信号，不要 fatal。
2. Shutdown 超时太短：几秒可能对大请求不够，按业务最长请求时间合理设置。
3. 信号 handler 没有注册 SIGTERM：容器平台通常发 SIGTERM，不是 SIGINT。
4. 在 handler 深处生成新的 Background context：这让取消链断裂，shutdown 时内部调用无法感知。

对比表

小结

Go HTTP 服务的优雅关闭核心流程是：使用 http.Server，单独 goroutine 启动服务，主 goroutine 监听 SIGINT 和 SIGTERM，收到信号后创建带超时的 context，调用 server.Shutdown(ctx)，必要时再 Close 强制关闭。

同时，handler 和后台任务要尊重 context。请求内部调用传 r.Context()，定时任务监听 ctx.Done()。这样服务停止时，不会粗暴中断所有事情，也不会无限等待。

入门项目也可以从一开始写好关闭逻辑。它不复杂，却能让程序更像真实服务，也能帮助你理解 Go 里 context、signal 和 HTTP server 如何协作。养成在开发环境就测试关闭行为的习惯，避免上线后才发现 goroutine 泄漏或资源未释放的问题。

WebSocket 和 SSE 的关闭处理

如果服务支持 WebSocket 或 SSE，server.Shutdown 只会等 HTTP handler 结束，不会等长连接自然断开。需要额外处理：

type Hub struct {
    clients map[*Client]bool
    mu      sync.Mutex
}

func (h *Hub) CloseAll() {
    h.mu.Lock()
    defer h.mu.Unlock()
    for client := range h.clients {
        client.conn.Close()
    }
}

在 shutdown 流程中：

hub.CloseAll()
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
server.Shutdown(ctx)

数据库连接关闭

db, err := sql.Open("postgres", dsn)
if err != nil {
    log.Fatal(err)
}
defer db.Close()

sql.DB.Close() 会等待所有连接归还。如果 handler 慢，关闭可能耗时较长。

最佳实践总结

1. 使用 http.Server 不要直接用 ListenAndServe。
2. 监听 SIGINT 和 SIGTERM。
3. 处理中的请求加超时控制。
4. 后台 goroutine 必须有退出路径。
5. 资源释放放在可以看到的地方，不要深埋。

优雅关闭不仅是代码层面的技术，也是运维体验的一部分。一个能平稳关闭的服务更容易被信任，也更能适应容器化和自动化部署环境。

HTTP/2 连接的特殊处理

HTTP/2 连接复用程度更高，关闭时需要给已有 stream 更多时间：

server := &http.Server{
    Addr:         ":8080",
    Handler:      mux,
    IdleTimeout:  120 * time.Second,
    ReadTimeout:  5 * time.Second,
    WriteTimeout: 10 * time.Second,
}

IdleTimeout 控制空闲连接存活时间。优雅关闭时应合理设置，避免连接长时间挂起。

Kubernetes 环境中的信号

K8s 停止 Pod 时发送 SIGTERM，grace period 默认为 30 秒。shutdown 流程必须在此时限内完成：

terminationGracePeriodSeconds: 30

如果时间不够，需调长 grace period 或优化关闭逻辑。超过后 K8s 会发送 SIGKILL。

资源释放顺序

推荐的关闭顺序：

1. 停止接收新请求（server.Shutdown）。
2. 通知所有后台 goroutine 退出（cancel context）。
3. 等待正在处理的请求完成。
4. 关闭数据库连接。
5. flush 日志和指标。
6. 退出进程。

这个顺序确保了数据不丢失，资源井井有条地释放。不要跳过任何一步，也不要反向执行。

最后提醒

优雅关闭不是银弹，但它让每个服务的生命周期更可控。在微服务和容器化时代，优雅关闭能力直接影响发布频率和回滚速度。把它当作工程素养的一部分来培养，而不是上线前的临时补丁。

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

• 函数是否处理了所有 error 返回值
• 并发代码是否有明确的退出路径和 WaitGroup
• 用户输入是否经过校验和清洗
• 敏感配置是否通过环境变量或加密存储注入
• 测试是否覆盖了正常路径和至少一个错误路径
• 日志是否包含足够的上下文信息但不泄露敏感数据
• 接口设计是否符合最小接口原则

CI/CD 集成建议

• 每次提交前运行 go fmt ./...
• CI 中运行 go vet ./... 和 golangci-lint run
• 单元测试使用 go test -race ./... 检测数据竞争
• 关键路径的 benchmark 加入回归测试
• 使用 go mod verify 确保依赖完整性

性能调优检查点

• 使用 pprof 分析 CPU 和内存使用
• 关注 benchmark 的 allocs/op，减少高频路径的堆分配
• 检查数据库查询是否使用索引
• 确认外部 HTTP 调用有合理的超时设置
• 缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

1. goroutine 和线程的区别
2. channel 的缓冲和非缓冲用法
3. defer 的执行顺序和与返回值的关系
4. map 的并发不安全性和解决方案
5. interface 的隐式实现和类型断言
6. slice 的底层数组和 append 机制
7. GC 的基本原理和调优参数
8. context 的使用场景和超时控制
9. error 的包装和 errors.Is/errors.As
10. sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

1. 不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
2. 资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
3. 不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
4. 不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
5. 不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
6. 不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

1. 把文中所有示例代码在自己的机器上跑一遍
2. 给示例代码补充错误分支的测试用例
3. 尝试基于本文内容构建一个小型完整项目
4. 在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
5. 订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

• Go 官方网站：https://go.dev/
• Go 标准库文档：https://pkg.go.dev/std
• Go by Example：https://gobyexample.com/
• Effective Go：https://go.dev/doc/effective_go
• Go 常见问题：https://go.dev/doc/faq
• Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

多级 shutdown 超时配置

对于复杂的服务，可能需要配置多级超时。第一级 shutdown 给正在处理的请求 5 秒完成。第二级 shutdown 给长连接或后台任务额外的 10 秒。如果两级都超时了，才执行强制退出。这种分层策略允许不同优先级的资源有不同的关闭时间窗口，避免了"一刀切"导致的提前终止。在 Kubernetes 中，需要保证 terminationGracePeriodSeconds 大于等于所有 shutdown 超时的总和。把这些超时参数统一放在配置文件中，方便不同环境的差异化调整。shutdown 逻辑不应该是固定的硬编码，而应该具备一定的弹性。