一个 Go 服务上线前,我会过一遍这张清单

难度 ★★★☆☆ · 前置:runtime/trace:让调度器在你眼前跑一遍 | 一句话结论:这些参数的默认值几乎都是不设防的状态,上线前把该填的填了、该排的顺序排对,比事后翻故障报告便宜得多。

2023 年 6 月我进第一家公司,写的第一批代码就是接口服务,那会儿我对上线这件事的全部理解是能跑通就行。真正开始怕上线,是因为一次半夜的告警,服务没崩,日志里也没有报错,只是响应慢得离谱,最后翻出来是一个没人设超时的连接一直在那里等着。

那次之后我给自己立了个规矩,发版之前把服务从头过一遍,条目一共八件,顺序基本固定,每回照着走,走完心里才踏实。八件是这些:

  1. 四个超时字段都给了非零值
  2. 出站请求的窗台短于调用方的耐心
  3. 优雅退出的顺序从停入口开始
  4. 每个 go func 都能答出自己怎么停
  5. context 走参数,不进结构体
  6. 存活和就绪分成两个探针
  7. 日志带请求 id,指标留一条 goroutine 曲线
  8. panic 在中间件那一层接住

默认值一个都不能用。

四个超时字段,零值的意思是永不超时

Go 的 http.Server 在零值上就是能跑的,这是它最容易骗人的地方。ReadHeaderTimeout、ReadTimeout、WriteTimeout、IdleTimeout 四个字段,不给值就是零,而零在源码里的意思是没有限制(也就是永不超时),谁来连都能一直挂着。第一次读到这段行为我还不信,专门写了一个只监听不回包的 handler 去试,客户端那边一直等着,服务这边那条 goroutine 也一直睡着,两边谁也不着急,也没有任何一方会先放弃。

这中间只要有一个连接是半开的,它占住的就不只是一个 socket,还有背后那条 goroutine 和它引用着的一整片栈,而这一笔账在监控上看不出来,因为连接数没涨、内存也没到阈值,只有 goroutine 数在缓慢地往上顶。

配置结构体里我还会加一条启动断言,四个值只要有任何一个为零就直接起不来。

四个字段各管一段:

字段 管哪一段 零值 我现在的值
ReadHeaderTimeout 只到请求头读完 永不超时 3s
ReadTimeout 整个请求体读完 永不超时 10s
WriteTimeout 从读到最后一个字节到写完响应 永不超时 10s
IdleTimeout 两个 keep-alive 请求之间的空档 退回 ReadTimeout 60s

四个字段里我一开始只给了 ReadTimeout,以为够了,后来才发现它管的是整个请求的读取,连 body 一起算,请求头并没有单独的上限。

ReadHeaderTimeout 是单独拎出来的一条线,因为慢速攻击就卡在发头这一步,一个字节一个字节地挤,头永远发不完。

我之前把它和 ReadTimeout 理解成同一件事,结果是把读头的窗口开得跟整个业务处理一样宽,等于放行了最该拦住的那一类连接。

这个值不设,连接池那边看着是空闲的,服务这边却挂着不撒手,数量一多句柄就见底,而报出来的错误是打开文件失败,跟超时看起来毫无关系。

给它一个短的上限,这类连接根本进不来,连 handler 都读不到。那设成多短算合适?我现在的值是三秒,比一条正常请求该花的时间长,比一个人的耐心短。

读得到头,才谈得上处理。

1
2
3
4
5
6
7
8
9
10
cfg := loadConfig()

srv := &http.Server{
Addr: cfg.Addr,
Handler: mux,
ReadHeaderTimeout: cfg.ReadHeaderTimeout,
ReadTimeout: cfg.ReadTimeout,
WriteTimeout: cfg.WriteTimeout,
IdleTimeout: cfg.IdleTimeout,
}

IdleTimeout 管的是 keep-alive 之间那段没人说话的空档,它跟 ReadTimeout 盯的不是一件事,一个在等下一个请求过来,一个在等当前这个请求读完,互不重叠。这个值还有个容易漏的退路,零值的时候它会自动退回 ReadTimeout 的值,而 ReadTimeout 要是也没给,那两条就一起失效,一条连上来的连接理论上可以挂上一整天。

出站请求的窗台,要比上游的耐心更短

http.Client 的零值同样是个不设防的东西,Timeout 不给就是一直等。我现在的写法是两层的,Client 那一层给一个兜底的总时长,每次调用再套一个 context.WithTimeout,而外面那个 ctx 是从请求里带下来的,带着调用方自己的 deadline。两层不是重复,一层管的是这一次调用最多花多久,另一层管的是调用方走了之后这件事还要不要继续。context 一取消,http 这边会立刻把连接断掉,不会留一条还在跑的流在后台占着 goroutine 和读缓冲(这一点我在排查一次内存缓慢上涨的时候受益过),栈上那一串全是被取消之后还在读的函数,而它们本该在第一次取消的时候就退出。那之后我把所有出站调用都收进一个构造 client 的函数,谁要用谁去拿,不再允许在业务代码里手写 http.Client{}。重试只对幂等的操作做,而且要退避加抖动。为什么非得加抖动?因为所有客户端同时重试,等于替下游排好了一次新的高峰。失败一次马上重打,等于把下游那一秒的抖动放大成好几倍的流量,本来只是慢一下的接口,被自己的重试打进雪崩。重试要有上限。上限不只是次数,还有总时长。几轮退避之后已经过去好几秒,这时候再打一次,调用方那边的超时大概率已经先到了,请求白打一场,还多占了一次下游的配额,而下游那时候本来就在忙。

1
2
3
4
5
6
7
8
9
10
11
12
ctx, cancel := context.WithTimeout(r.Context(), cfg.OutboundTimeout)
defer cancel()

req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)

for i := 0; i < cfg.MaxRetries; i++ {
resp, err = client.Do(req)
if err == nil {
break
}
time.Sleep(backoff(i))
}

优雅退出的顺序,反了就丢请求

退出的开关我用 signal.NotifyContext 挂着,收到 SIGTERM 的时候 ctx 被取消,服务进入收尾。顺序是死的,五步:

  1. 监听先停,srv.Shutdown 把 listener 关掉、把空闲连接关掉,新连接直接拒
  2. 等手上那些正在处理的请求跑完,Shutdown 自己带一个 ctx,那个 ctx 就是等待的上限
  3. 关数据库连接池
  4. 停消息队列的消费者,先停止拉新消息,等在处理的那几条 ack 完再关连接
  5. 进程自己 return,别指望 Shutdown 会替你退出

这一步做完才算收尾。反过来的话,请求还在跑,池子先没了,那些请求全部变成取连接失败,报错看起来像是数据库出了问题,其实是自己关早了,而真正的原因要去翻退出那一段代码才看得出来。发布的时候这两种错的表现完全不一样,前者是重启期间零星几个 502,后者是一片看着像数据库挂了的 500,我宁愿要前面那种。(这段顺序我改过一次,最早写的是先关连接池再 Shutdown,觉得池子空着不好看,写完才反应过来反了。)有个坑我踩过,Shutdown 返回之后进程并不会自己退出,得自己往下走完收尾再 return,不然 main 结束得太早,defer 里的东西还没执行。先停监听,再关池子。消费者那边同理,先停止拉新消息,等在处理的那几条 ack 完再关连接。

反过来先关连接,那几条消息会被重新投递,业务上就是同一个动作做了两次,而这类重复往往要过几天才会从对账里冒出来。

1
2
3
4
5
6
7
8
9
10
11
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()

<-ctx.Done()

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

srv.Shutdown(shutdownCtx)
db.Close()
consumer.Stop()

每个 go func 都得答一句它怎么停

上线前我会在仓库里搜 go func,一条一条看它怎么退。退的方式就那么几种,每一种都有它容易出事的地方:

  • 挂在 context 上,ctx.Done() 一到就 return,这种最省心,前提是调用方真的会取消
  • 靠一个 close(chan) 广播,所有人同时醒来,这种怕的是关两次,或者关的人和发的人是同一个
  • 靠循环条件,而那个条件是一个永远不会被改的变量,这就是泄漏
  • 靠 time.After 之类的定时器,这种最隐蔽,因为它在超时前一直安静地待着

goroutine 泄漏最难受的地方是它不报错,进程活着,内存慢慢涨,pprof 拿到的栈上全是同一个函数堆在那里,一串一模一样的调用链叠了几百层,看不出是谁起的头。

我现在的习惯是,起 goroutine 的地方旁边必须能看到它结束的条件,看不到就先不写,宁可让调用方多等一会儿,也不留一条不知道归谁的协程在后台跑。这条规矩执行起来有点烦,但它挡掉的都是那种要过两三周才会变成告警的问题。写不出退出条件,就是没写完。还有一种是被动的,goroutine 里在等一个 channel,而对面那个生产者已经退了,这个 channel 永远不会被关闭,也就永远不会有人来叫醒它。

这种最难查,因为它看起来干干净净,连阻塞点都是合理的,代码读起来没有任何一处像错的。

没人叫醒它,它就一直等,从上线一直等到进程被杀,日志里一句都不留。

context 走参数,不能进结构体

context.Context 是给一次调用用的,它的生命周期应该跟这次调用一样长。

// 对的写法

存进结构体之后,它就会一直活着,活到结构体被回收为止,创建它的那一刻留下的 deadline 和取消信号全部停在原地。

// 错的写法

存起来的那一刻,取消就失效了。

外面那次请求早就超时返回了,里面这个 ctx 还以为一切正常,下游该断的不肯断,该放的连接不放,超时在这个位置彻底失效。

传参是显式的,每个函数的签名上都能看见它,读代码的人知道这条链上哪里有取消点,也知道哪一层可以提前放弃,接手的人不用再去翻结构体的初始化。

写测试的时候这一点差别更明显,传参的版本可以在用例里换一个带超时的 ctx,存进结构体的那个根本换不动。

也有例外,长生命周期的组件可以在启动时接一个根 ctx,但那是根,不是某次请求的 ctx,两者不能混着传。

1
2
3
4
5
6
7
8
9
10
11
// 错的写法
type Server struct {
ctx context.Context
}

// 对的写法
func (s *Server) Handle(ctx context.Context, req *Request) error {
ctx, cancel := context.WithTimeout(ctx, cfg.HandlerTimeout)
defer cancel()
return s.do(ctx, req)
}

存活和就绪,回答的不是同一个问题

两个接口经常被写成一个,然后被同一个探针打。存活检查回答的是进程还在不在,它挂了就该重启,就绪检查回答的是能不能接流量,它不过就该从负载均衡里摘掉,但不该重启。启动预热没做完的时候,缓存是空的,连接池还没建起来,这个时候就绪必须是红的,否则第一批流量进来就是一片超时,而重启解决不了任何问题,只会让它再红一次。这两件事混在一起,最坏的结果是一个起不来的实例被反复杀掉,日志里只剩下一串重启记录,真正的病因一行都看不到。我现在会把两个接口分开写,红的位置不一样,值班的人看到的处理方式也不一样,一个位置对应重启,另一个位置对应摘流量,看图的那一刻就知道该点哪个按钮。探针的超时要短,比请求超时更短,因为它回答的是一个即时问题。一个探针自己都要等上好几秒,等它给出答案,被问的那个东西可能早就不行了。

该摘流量的时候,别重启。

依赖的健康状态也归到就绪这一侧。

数据库、缓存、下游服务各自一个探针,任何一个红了,就绪跟着红,因为这种状态下接进来的流量只会变成错误。

1
2
3
4
5
6
7
8
9
10
11
mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
})

mux.HandleFunc("/readyz", func(w http.ResponseWriter, r *http.Request) {
if !cache.Warm() || !db.Ping() {
w.WriteHeader(http.StatusServiceUnavailable)
return
}
w.WriteHeader(http.StatusOK)
})

日志带请求 id,指标留一条 goroutine 曲线

标准库从 1.21 起有了 log/slog,结构化日志这件事不用再拉第三方。进中间件时生成一个请求 id 塞进 ctx,后面所有日志都从 logger.With 出来的那个实例打,一条请求的日志就能按 id 串起来,翻的时候不用再靠时间戳去猜哪几行属于同一次调用。级别要能在线调,用一个 atomic 包着的 LevelVar 挂在 handler 上,出事的时候把级别调到 debug,不用重启进程。重启一次就是一次断流,能在线上改的东西不要留给下一次发布,而且重启会把现场一起清掉,正好是排查最需要的那一部分。

这里有件事我吃过亏,日志里只打格式化之后的一句话,中间夹了变量又没带 key,后来想按用户 id 去筛,发现那个 id 混在句子里了。

指标的最小集合我记了五个,请求数、延迟分布、错误数、goroutine 数、堆大小。

前面三个是业务面的,后面两个是运行时的,缺哪一个都会在出事的时候卡住。

泄漏在图上长得非常明显。goroutine 数用 runtime.NumGoroutine 就能拿,堆大小读 runtime.ReadMemStats,或者挂在 expvar 上。

这两个数字平时是一条平线,一旦开始单调往上走,基本就是有人在漏,图比栈好认得多。

GOMAXPROCS 在容器里还有个老问题,默认读的是宿主机的核数,不是 limit。

Go 1.25 起有了容器感知的默认值,之前的版本要自己上 automaxprocs,或者在启动脚本里写明。

核数给大了,上下文切换跟着变多,延迟的分位数会先抖起来。

(Go 1.25 那个容器感知的默认值,我只在自己这一台 Linux 容器里试过,别的 cgroup 版本和 Windows 那边没验证完。)

panic 在中间件那一层接住

一个请求 panic 了,不该带走整个进程,但也不该悄悄没了。中间件里 defer 一个 recover,接住之后记一条带栈的日志,把错误计数加一,然后给客户端回一个 500。recover 只在 defer 里有效,写在普通语句里拿到的是 nil,这一点我在别的地方已经栽过一次。

写得出来才查得出来。

吞掉和崩掉是两种坏,崩掉至少还有栈,吞掉之后你只知道这里少了一个响应,剩下的全靠猜,而猜出来的结论十有八九是错的,还得花时间把猜错的方向一条条排掉。所以那条日志里必须带栈,debug.Stack 就够,别只打一句出错了。接住之后这个连接还能用,但请求已经被毁了,别指望把原来的 handler 再跑一遍,也别在 recover 里写业务补偿,那里已经不是一个正常的状态了。吞掉比崩掉更难查,因为崩掉至少留了一份栈,吞掉之后现场是空的。还有一层,goroutine 里起的 panic 中间件接不到。那些地方得各自兜,兜不住就是整个进程退出。所以前面那条说每个 go func 都要能停,和这条其实是一回事,都指向同一个问题,这个后台任务出事了谁知道,谁来看,谁来收尾。清单的意义是不靠记性。人一到发布那天就容易慌,慌的时候只会想起自己刚踩过的那个坑,剩下的全忘了,而线上出事从来不挑你记着的那个。

把条目写下来,每次照着过一遍,比相信自己的记性好用,也比事后解释为什么漏了要省事,毕竟解释的那半小时本来可以用来修。

1
2
3
4
5
6
7
8
9
10
11
12
func Recover(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if rec := recover(); rec != nil {
logger.Error("panic", "req_id", reqID(r), "err", rec)
metrics.PanicTotal.Inc()
http.Error(w, "internal error", http.StatusInternalServerError)
}
}()
next.ServeHTTP(w, r)
})
}