Go WebSocket 升级前响应写入失败的处理顺序

Go WebSocket 接口最容易混乱的地方，是把“升级前的 HTTP 错误响应”和“升级后的 WebSocket 连接错误”写在同一条分支里。更稳妥的顺序是：先完成鉴权、方法和请求头检查；检查失败时只写一次普通 HTTP 响应并立即返回；只有这些条件满足后，才调用 Upgrader.Upgrade。一旦升级函数返回错误，就记录错误并结束处理，不要再补写第二个 HTTP 响应。

官方地址：https://pkg.go.dev/net/http

WebSocket 库文档：https://pkg.go.dev/github.com/gorilla/websocket

升级前的失败属于 HTTP 层，应用负责写出状态码和简短正文；升级函数内部已经开始处理握手失败时，应用只负责记录并返回。不要用重复的 http.Error 覆盖已经写出的响应，也不要把 http.Hijacker 当成 HTTP/2 下必然存在的能力。

先把普通响应和连接转换分开

一个清晰的服务端处理器可以看成三块：请求校验、升级前响应、连接转换。校验失败时，ResponseWriter 仍然属于 HTTP 响应对象，状态码和正文由当前 Handler 负责；升级成功后，底层连接已经转交给 WebSocket 连接对象，继续调用 w.Write 或 w.WriteHeader 就是错误的边界穿越。

升级前失败只写一次 HTTP 响应

升级前的错误分支要尽量短：先准备内容类型，再写状态码和正文，最后检查正文写入返回值。WriteHeader 本身没有错误返回值，所以真正能观察到网络写失败的位置通常是随后写正文的调用。客户端已经断开时，日志里记录写入错误即可，不要为了“补一条错误”再次写响应。

package main

import (
    "io"
    "log"
    "net/http"
)

// writeHandshakeError 只处理尚未升级的普通 HTTP 错误响应。
func writeHandshakeError(w http.ResponseWriter, status int, message string) {
    // 头部必须在第一次写状态码前设置，避免响应类型被隐式确定。
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    w.WriteHeader(status)

    // WriteHeader 没有错误返回值，正文写入才是这里需要记录的网络错误点。
    if _, err := io.WriteString(w, message+"\n"); err != nil {
        log.Printf("write websocket handshake error response: %v", err)
    }
}

func handler(w http.ResponseWriter, r *http.Request) {
    // 在握手前完成业务条件检查，失败后只写一次 HTTP 响应。
    if r.Method != http.MethodGet {
        writeHandshakeError(w, http.StatusMethodNotAllowed, "websocket requires GET")
        return
    }
    if r.Header.Get("Upgrade") == "" {
        writeHandshakeError(w, http.StatusBadRequest, "missing Upgrade header")
        return
    }

    // 只有普通 HTTP 条件满足后，才把 ResponseWriter 交给升级器。
    // 这里省略具体 upgrader 配置，真实代码应继续检查 Upgrade 的返回错误。
}

这个顺序的价值在于把“写响应失败”和“握手失败”分成两个可观察事件。校验分支已经调用过 WriteHeader 后，应立刻返回；否则后续升级代码可能在同一个请求上继续改变响应状态，日志就会出现重复写头或状态码与真实原因不一致。

让 Upgrader 统一处理握手失败

以 gorilla/websocket 为例，Upgrader.Upgrade 会检查 WebSocket 请求头、Origin 和连接能力；文档说明升级失败时它会向客户端回复 HTTP 错误。因此调用方的失败分支应保持为“记录并返回”，而不是把返回错误再包装成第二个 http.Error。

var upgrader = websocket.Upgrader{
    // 生产环境应根据站点来源做明确校验，不要无条件放开 Origin。
    CheckOrigin: func(r *http.Request) bool {
        return r.Header.Get("Origin") == "https://app.example.com"
    },
}

func websocketHandler(w http.ResponseWriter, r *http.Request) {
    // Upgrade 内部负责握手失败的 HTTP 响应，调用方只记录并结束。
    conn, err := upgrader.Upgrade(w, r, nil)
    if err != nil {
        log.Printf("websocket upgrade failed: %v", err)
        return
    }
    defer conn.Close()

    // 成功后使用 WebSocket 连接对象，不再使用 ResponseWriter 写消息。
    if err := conn.WriteMessage(websocket.TextMessage, []byte("ready")); err != nil {
        log.Printf("write websocket message: %v", err)
        return
    }
}

如果使用的库版本或中间件包装器改变了升级实现，仍然遵守同一个边界：升级器返回错误时不重复写；拿到连接后只操作连接对象。这样即使底层网络写入失败，也能从“握手失败”和“消息写失败”两个阶段分别定位。

http.Hijacker 不是所有请求都能用

标准库文档说明，默认的 HTTP/1.x 服务端响应对象支持 http.Hijacker，但 HTTP/2 有意不支持它；响应包装器也可能没有把这个能力透传出来。自定义升级代码如果直接断言 http.Hijacker，需要把“不支持”当成明确的能力错误，而不是继续写一半握手数据。

如果项目有多层中间件，优先让包装器保留原始响应对象的能力，或使用 http.NewResponseController 处理标准库提供的可控操作。不要在 Handler 返回后继续调用 Hijack，也不要把一个已经升级的连接重新当作 HTTP 响应写入。

排障时只核对三个信号

1. 升级前失败：确认状态码只写一次，正文写入错误是否被记录，Handler 是否立即返回。
2. 升级函数失败：确认是否重复调用了 http.Error，以及请求是否被中间件提前写入响应。
3. 升级成功后失败：确认日志来自 WebSocket 连接写入，而不是原始 ResponseWriter。

常见问题

升级失败后还需要调用 http.Error 吗？

对会自行回复握手错误的升级器，通常不需要。升级器已经处理了 HTTP 错误，调用方记录错误并返回即可；只有在使用自定义升级器且明确约定由调用方写响应时，才由调用方负责那一次响应。

为什么断言到 http.Hijacker 仍然升级失败？

接口存在只代表响应对象暴露了 Hijack 方法，不代表请求头、Origin、协议版本或底层连接都满足 WebSocket 握手条件。先区分能力检查失败、请求校验失败和网络写入失败，再处理对应分支。

归纳起来，Go WebSocket 的失败处理顺序就是：升级前由 Handler 负责一次普通 HTTP 响应；升级器负责一次握手失败响应；升级成功后只使用连接对象。把三种状态分开，响应重复写入和错误归因混乱的问题就会明显减少。