HTTP错误响应需显式终止处理流程，调用http.Error后必须return；自定义JSON错误应手动设置状态码并编码；统一错误封装比分散判断更可靠；404/500不可依赖默认机制，须主动控制；错误体需脱敏，日志须含trace ID。
HTTP错误响应必须显式写入，http.Error不是唯一选择
Go 的 http.ServeHTTP 接口不会自动终止请求处理流程。即使你调用 http.Error，后续代码仍会继续执行，可能造成重复写入 ResponseWriter 并触发 http: multiple response.WriteHeader calls 错误。
正确做法是：在调用 http.Error 后立即 return，或使用更可控的结构封装错误返回逻辑。
-
http.Error本质只是调用w.WriteHeader(status)+w.Write([]byte(msg))，适合简单场景 - 需要自定义 JSON 错误体（如
{"error": "not found"}）时，应手动调用w.WriteHeader+json.NewEncoder(w).Encode(...) - 避免在中间件或 handler 中忘记
return，尤其在 if-else 分支里
自定义错误类型配合 http.Handler 实现统一错误拦截
把业务错误转为可识别的类型，再通过包装器统一捕获，比每个 handler 都写 if err != nil 更可靠。
type AppError struct {
Code int
Msg string
}
func (e *AppError) Error() string { return e.Msg }
func errorWrapper(h http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
defer func() {
if r := recover(); r != nil {
http.Error(w, "internal error", http.StatusInternalServerError)
}
}()
if err := h(w, r); err != nil {
var appErr *AppError
if errors.As(err, &appErr) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(appErr.Code)
json.NewEncoder(w).Encode(map[string]string{"error": appErr.Msg})
} else {
http.Error(w, "server error", http.StatusInternalServerError)
}
}
}
}
注意：errors.As 要求错误链中存在该类型；若用 fmt.Errorf("wrap: %w", err) 包装原始 *AppError，依然能匹配成功。
立即学习“go语言免费学习笔记（深入）”；
404 和 500 错误不能只靠 http.NotFound 和 panic 捕获
http.NotFound 只是调用 http.Error(w, "404 page not found", 404)，它不阻止路由继续匹配——如果你用的是自定义多层路由（比如自己实现的 map[string]func），必须主动判断路径是否存在并提前返回。
- 标准
http.ServeMux会在无匹配时调用http.NotFound，但第三方路由器（如gorilla/mux、chi）行为不同，需查文档确认默认 404 处理方式 - 500 错误不应依赖 panic 恢复：panic 是异常信号，不是错误控制流；大量 panic 会影响性能，且无法区分真实崩溃和预期错误
- 推荐对关键业务逻辑做显式错误检查，仅将不可恢复的底层故障（如数据库连接丢失）视为 500
客户端看到的错误体格式要和服务端日志联动
返回给前端的 JSON 错误消息（如 {"error": "invalid token"}）不该暴露堆栈或内部字段，但服务端日志里必须保留完整上下文，否则排查困难。
建议结构：
- handler 中：记录带 trace ID、参数、错误详情的 structured log（用
zap或zerolog） - 同时构造精简的用户友好错误体，例如
map[string]string{"error": "authentication failed"} - 避免在错误体中返回
err.Error()原始字符串，尤其是来自数据库或外部 API 的报错（含敏感路径、SQL 片段等）
真正容易被忽略的是 trace ID 的透传：它必须从入口请求头（如 X-Request-ID）读取，并贯穿整个错误链，否则日志无法关联。
