AI 时代重新学 Go(十一):一个 HTTP 请求在 Go 服务里经历了什么

写 Go Web 服务久了，很容易把入口简化成一句话：

http.ListenAndServe(":8080", nil)

或者在 Gin、Kratos、Chi 这些框架里写一个 handler，就觉得请求自然会进来、自然会返回。

但线上很多问题都卡在这条“自然”的路径上：慢请求为什么把连接占住了？客户端断开后数据库查询为什么还在跑？服务重启时为什么有些请求直接断了？读超时、写超时、优雅关闭到底管哪一段？

所以这一篇不先聊框架，先把一个 HTTP 请求在 Go 服务里的生命周期捋清楚。

最小的服务长这样：

package mainimport (    "errors"    "log"    "net/http")func main() {    mux := http.NewServeMux()    mux.HandleFunc("/ping",func(w http.ResponseWriter, r *http.Request) {        _, _ = w.Write([]byte("pong"))    })    if err := http.ListenAndServe(":8080", mux); err != nil && !errors.Is(err, http.ErrServerClosed) {        log.Fatal(err)    }}

ListenAndServe 做了两件事：

1. 1. 监听 TCP 地址，比如 :8080
2. 2. 调用 Server.Serve 处理进入的连接

Go 官方对 Server.Serve^[1] 的描述很直接：它会在 listener 上接收连接，并为每个连接创建服务 goroutine；这些 goroutine 读取请求，再调用 Server.Handler 生成响应。

画成一条线大概是这样：

  客户端    │    │  TCP connect    ▼  Listener.Accept    │    │  得到 net.Conn    ▼  每条连接一个服务 goroutine    │    │  读取请求行、Header、Body    ▼  调用 Handler.ServeHTTP    │    │  写 Header 和 Body    ▼  响应返回 / 连接复用 / 连接关闭

这里有个容易说错的点：不要简单说“每个请求一个 goroutine”。

对 HTTP/1.1 keep-alive 来说，一个 TCP 连接可以连续处理多个请求。Go 文档保证的是 Serve 会给每条连接创建服务 goroutine，连接里的请求再由它读取并交给 handler。HTTP/2 内部还有 stream 的调度，不要拿 HTTP/1.1 的连接模型硬套过去。平时写业务 handler 时你可以把每次 ServeHTTP 当成一次请求的边界，但排查连接、超时、优雅关闭时，脑子里要有“连接”和“请求”两层。

http.Server 才是服务的配置中心

很多 demo 用 http.ListenAndServe，生产代码最好直接写 http.Server：

srv := &http.Server{    Addr:              ":8080",    Handler:           mux,    ReadHeaderTimeout: 5 * time.Second,    ReadTimeout:       30 * time.Second,    WriteTimeout:      30 * time.Second,    IdleTimeout:       60 * time.Second,    MaxHeaderBytes:    1 << 20,}if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {    log.Fatal(err)}

这些字段不是摆设。

ReadHeaderTimeout

ReadHeaderTimeout 限制“读完请求头”的时间。

它主要防慢连接攻击。比如客户端连上来以后，一个字节一个字节地发 header，迟迟不把请求头发完。如果没有限制，服务端就会一直占着这个连接等。

这个值我一般会先配上，比直接配一个很激进的 ReadTimeout 更稳。

ReadTimeout

ReadTimeout 限制读取整个请求的时间，包括 header 和 body。

如果你的服务会接收大文件上传，不能随便把这个值设得太短。因为它不理解业务，不知道哪个接口应该允许慢一点、哪个接口应该立刻拒掉。Go 官方文档也提醒过，多数场景会更偏向先用 ReadHeaderTimeout，再由 handler 自己决定 body 怎么读、读多久。

WriteTimeout

WriteTimeout 限制写响应的时间。

它从读完请求头之后开始算。handler 里计算太久、下游太慢、客户端读取响应太慢，都可能撞到这个边界。

但它不是业务超时的替代品。比如你调用第三方 API，还是要用 context.WithTimeout 控制那次调用，不要指望最后写响应时才发现超时。

IdleTimeout

IdleTimeout 限制 keep-alive 连接在两个请求之间能空闲多久。

请求处理完以后，连接不一定马上关闭。HTTP/1.1 默认可以复用连接。客户端可能过一会儿再发下一个请求。IdleTimeout 管的就是这段“等下一个请求”的时间。

这几个 timeout 可以这样理解：

  建连   │   ├─ 读 Header ─────────────── ReadHeaderTimeout   │   ├─ 读 Header + Body ──────── ReadTimeout   │   ├─ Handler 执行 + 写响应 ─── WriteTimeout   │   └─ 请求结束后等下一次请求 ── IdleTimeout

Handler 是真正的业务入口

Go 的 handler 接口就一个方法：

type Handler interface {    ServeHTTP(http.ResponseWriter, *http.Request)}

http.HandlerFunc 只是一个适配器，让普通函数满足这个接口：

func hello(w http.ResponseWriter, r *http.Request) {    _, _ = w.Write([]byte("hello"))}mux.Handle("/hello", http.HandlerFunc(hello))

框架做了很多路由、参数绑定、中间件、错误封装，但最底层还是回到这个接口。理解这一点以后，中间件也不神秘了：它就是接收一个 handler，返回一个新的 handler。

func logging(next http.Handler) http.Handler {    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {        start := time.Now()        next.ServeHTTP(w, r)        log.Printf("%s %s %s", r.Method, r.URL.Path, time.Since(start))    })}

多个中间件就是一层层包起来：

handler := logging(auth(mux))srv := &http.Server{    Addr:    ":8080",    Handler: handler,}

请求进来后的调用顺序：

  logging    │    ▼  auth    │    ▼  mux    │    ▼  具体业务 handler

所以中间件里有两个原则：

1. 1. 能在调用 next.ServeHTTP 前拒绝的，就直接返回
2. 2. 调了 next.ServeHTTP 之后，不要再假装自己还能安全改响应

ResponseWriter 不是一个随便改的 buffer。底层可能已经把 header 或 body 写给客户端了。想记录状态码，应该包一层 writer，在 WriteHeader 里记下来，而不是请求结束后再凭空改。

Request Context 是请求的生命线

前面第六篇已经聊过 Context。放到 HTTP 服务里，r.Context() 就是每个请求自带的生命周期信号。

Go 官方 Request.Context^[2] 文档里说得很清楚：对服务端收到的请求，客户端连接关闭、HTTP/2 请求被取消，或者 ServeHTTP 返回时，这个 context 会被取消。

业务代码里最常见的错误是：handler 里拿到了请求 context，但往下游调用时没传。

func handleUser(w http.ResponseWriter, r *http.Request) {    ctx := r.Context()    user, err := queryUser(ctx, r.PathValue("id"))    if err != nil {        http.Error(w, err.Error(), http.StatusBadGateway)        return    }    if err := json.NewEncoder(w).Encode(user); err != nil {        log.Printf("write response: %v", err)    }}func queryUser(ctx context.Context, id string) (User, error) {    row := db.QueryRowContext(ctx, `        SELECT id, name        FROM users        WHERE id = ?    `, id)    var u User    if err := row.Scan(&u.ID, &u.Name); err != nil {        return User{}, err    }    return u, nil}

客户端都断了，数据库查询还在跑，通常就是这里断链了。

调第三方 API 也一样：

func callAPI(ctx context.Context, endpoint string) ([]byte, error) {    req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)    if err != nil {        return nil, err    }    resp, err := http.DefaultClient.Do(req)    if err != nil {        return nil, err    }    defer resp.Body.Close()    if resp.StatusCode < 200 || resp.StatusCode >= 300 {        return nil, fmt.Errorf("api status %d", resp.StatusCode)    }    return io.ReadAll(resp.Body)}

这里没有 panic，也没有“先忽略 err”。网络、数据库、客户端断开，都是正常世界的一部分。正常错误就正常返回。

Handler 返回以后，请求就结束了

ServeHTTP 返回是一个明确边界。

官方 Handler^[3] 文档里有一句话很关键：ServeHTTP 返回表示请求已经结束；返回后继续使用 ResponseWriter 或继续读取 Request.Body 都不是有效用法。

这类代码就很危险：

func bad(w http.ResponseWriter, r *http.Request) {    gofunc() {        time.Sleep(time.Second)        _, _ = w.Write([]byte("late write"))    }()    w.WriteHeader(http.StatusAccepted)}

handler 返回后，后台 goroutine 还拿着 w 写响应。它可能写不出去，也可能和连接复用撞在一起。想做异步任务，应该把任务数据投递到队列里，不要把请求对象和响应 writer 带出 handler 生命周期。

如果你确实要做流式响应，那就让 handler 自己在生命周期内持续写，并监听 context：

func stream(w http.ResponseWriter, r *http.Request) {    ctx := r.Context()    ticker := time.NewTicker(time.Second)    defer ticker.Stop()    flusher, ok := w.(http.Flusher)    if !ok {        http.Error(w, "streaming unsupported", http.StatusInternalServerError)        return    }    for {        select {        case <-ctx.Done():            return        case t := <-ticker.C:            if _, err := fmt.Fprintf(w, "data: %s\n\n", t.Format(time.RFC3339)); err != nil {                return            }            flusher.Flush()        }    }}

优雅关闭不是 close 一下端口

服务发布、机器重启、容器滚动更新时，你希望发生的是：

1. 1. 不再接收新连接
2. 2. 已经空闲的连接关掉
3. 3. 正在处理的请求给一点时间跑完
4. 4. 超过时间还没结束，再退出

这就是 Server.Shutdown 要做的事。官方 Shutdown^[4] 文档的核心语义是：先关闭 listener，再关闭 idle 连接，然后等待活跃连接变成 idle；如果传入的 context 超时，就返回 context 的错误。

一个比较完整的写法：

func main() {    mux := http.NewServeMux()    mux.HandleFunc("/ping",func(w http.ResponseWriter, r *http.Request) {        _, _ = w.Write([]byte("pong"))    })    srv := &http.Server{        Addr:              ":8080",        Handler:           mux,        ReadHeaderTimeout: 5 * time.Second,        ReadTimeout:       30 * time.Second,        WriteTimeout:      30 * time.Second,        IdleTimeout:       60 * time.Second,    }    serverErr := make(chan error, 1)    gofunc() {        err := srv.ListenAndServe()        if err != nil && !errors.Is(err, http.ErrServerClosed) {            serverErr <- err            return        }        serverErr <- nil    }()    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)    defer stop()    select {    case err := <-serverErr:        if err != nil {            log.Fatal(err)        }    case <-ctx.Done():        shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)        defer cancel()        if err := srv.Shutdown(shutdownCtx); err != nil {            log.Printf("shutdown: %v", err)        }        if err := <-serverErr; err != nil {            log.Fatal(err)        }    }}

这里有两个细节：

第一，ListenAndServe 在 Shutdown 后会返回 http.ErrServerClosed，这不是异常事故，别把它当 fatal。

第二，调用 Shutdown 后主 goroutine 不能立刻退出。文档也提醒了：ListenAndServe 会很快返回，你要等 Shutdown 自己返回，程序才算真的完成收尾。

还有一个边界：WebSocket 这种 hijacked connection 不归 Shutdown 自动等待。你要自己通知这些长连接退出，比如用 RegisterOnShutdown 做广播。

把这条线记住

一个请求在 Go HTTP 服务里，大致走完这条线：

  TCP accept    │    ▼  connection goroutine    │    ▼  read request with timeout    │    ▼  Handler / middleware chain    │    ▼  request context controls downstream work    │    ▼  write response    │    ▼  keep-alive idle / close    │    ▼  graceful shutdown waits for active work

理解这条线以后，很多线上问题就不再是“框架怎么了”。

慢连接，先看 header/body timeout。

客户端断开后任务还在跑，先看 context 有没有一路传下去。

发布时请求被硬断，先看是不是只关了进程，没有走 Shutdown。

handler 返回后还想写响应，那是生命周期已经越界。

但知道生命周期还不够。下一篇该聊测试了：HTTP handler、中间件、context 取消、超时和并发代码，不能只靠手点接口证明没问题。

引用链接

[1] `Server.Serve`: https://pkg.go.dev/net/http#Server.Serve[2] `Request.Context`: https://pkg.go.dev/net/http#Request.Context[3] `Handler`: https://pkg.go.dev/net/http#Handler[4] `Shutdown`: https://pkg.go.dev/net/http#Server.Shutdown