HTTP handler 中 panic 会导致连接静默关闭，需用 recover 中间件捕获并返回 HTTP 错误；handler 不返回 error，业务错误须显式调用 http.Error() 并 return；启动错误、context 超时等也需分层处理。
HTTP handler 里 panic 会导致连接被静默关闭
Go 的 http.ServeMux 和 http.Server 默认不会 recover handler 中的 panic，一旦 panic 发生，当前请求协程会终止，客户端可能收到空响应或连接重置（ERR_EMPTY_RESPONSE），而服务端日志里甚至不显示错误——这是最常被忽略的“黑盒失败”。
必须手动包装 handler，用 recover() 捕获 panic 并转为 HTTP 错误响应：
func recoverMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
http.Error(w, "Internal Server Error", http.StatusInternalServerError)
log.Printf("PANIC in %s %s: %v", r.Method, r.URL.Path, err)
}
}()
next.ServeHTTP(w, r)
})
}
- 不要只在单个 handler 函数里写
defer recover()，应统一中间件处理 -
http.Error()是安全的，它会检查w是否已写 header，避免http: multiple response.WriteHeader calls - 别把
err直接返回给客户端（尤其含敏感路径/变量名），生产环境需脱敏
Handler 返回 error 不等于 HTTP 错误响应
Go 标准库的 http.Handler 接口方法签名是 ServeHTTP(http.ResponseWriter, *http.Request)，它本身不返回 error。你写的业务逻辑中产生的 error（比如数据库查询失败、JSON 解析错误）必须由你自己决定如何响应。
常见错误做法：if err != nil { return err } —— 这行代码根本不会生效，因为函数签名没定义返回值。
正确做法是显式调用 http.Error() 或手动写状态码+body：
func userHandler(w http.ResponseWriter, r *http.Request) {
id := chi.URLParam(r, "id")
user, err := db.FindUserByID(id)
if err != nil {
http.Error(w, "User not found", http.StatusNotFound)
return // 必须 return，否则后续代码仍会执行
}
json.NewEncoder(w).Encode(user)
}
- 每次写
http.Error()后必须紧跟return，否则可能触发多次 write - 不要用
w.WriteHeader()单独设状态码后忘了写 body，某些客户端（如 curl）会卡住等待响应体 - 对不同错误类型返回合适状态码：
http.StatusBadRequest（参数解析失败）、http.StatusUnauthorized（鉴权失败）等
net/http.Server 的 ListenAndServe 错误要主动处理
http.ListenAndServe() 和 srv.ListenAndServe() 在端口被占用、证书缺失、TLS 配置错误时会返回 error，但这个 error 不来自 handler，而是服务器启动阶段的问题。
如果不检查，程序会直接退出，且无明确提示：
srv := &http.Server{
Address: ":8080",
Handler: recoverMiddleware(r),
}
log.Println("Starting server on :8080")
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
log.Fatalf("Server failed: %v", err)
}
-
http.ErrServerClosed是正常关机返回的 error，需排除，否则日志里总报“failed” - 监听
:http或:https端口失败时，错误信息通常是listen tcp :80: bind: permission denied，需检查权限或换高位端口 - 使用
http.ListenAndServeTLS时，若证书路径错或格式非法，错误是open cert.pem: no such file or directory或tls: failed to find any PEM data in certificate input
Context 超时和
取消也得进 error 处理链
取消也得进 error 处理链handler 中用了 ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)，但若下游调用（如 RPC、DB 查询）因超时返回 context.DeadlineExceeded，你不做判断，就可能把空数据或部分结果返回给前端。
应该把 context error 显式映射为 HTTP 状态码：
ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
defer cancel()
user, err := db.FindUserWithContext(ctx, id)
if err != nil {
if errors.Is(err, context.DeadlineExceeded) {
http.Error(w, "Request timeout", http.StatusGatewayTimeout)
return
}
if errors.Is(err, context.Canceled) {
http.Error(w, "Request canceled", http.StatusRequestTimeout)
return
}
http.Error(w, "Internal error", http.StatusInternalServerError)
return
}
-
errors.Is(err, context.DeadlineExceeded)比err == context.DeadlineExceeded更健壮，能处理 wrapped error -
http.StatusRequestTimeout（408）适用于客户端主动断开；http.StatusGatewayTimeout（504）更适合作为后端超时响应 - 别在 defer 里调用 cancel 后还继续用 ctx，cancel 后再 select ctx.Done() 会立即返回
if err != nil 只会让代码越来越难维护。
