推荐用中间件或封装响应函数统一返回错误JSON，定义ErrorResponse结构体和writeError函数，区分业务错误（4xx）与系统错误（5xx），通过AppError接口规范状态码，用recoverMiddleware安全捕获panic，第三方框架如Gin/Echo的错误传播机制比原生net/http更隐蔽。
Go HTTP handler里怎么统一返回错误JSON
直接在每个 http.HandlerFunc 里写 json.NewEncoder(w).Encode() 容易重复且难维护。推荐用中间件或封装响应函数，把错误转成标准结构体再写入响应。
常见错误是直接调用 w.WriteHeader() 后又写 body，但没检查是否已写过 header —— Go 的 http.ResponseWriter 不会报错，但前端可能收不到状态码或解析失败。
- 定义统一错误结构：
type ErrorResponse struct { Code int `json:"code"` Message string `json:"message"` } - 封装响应函数：
func writeError(w http.ResponseWriter, status int, msg string) { w.Header().Set("Content-Type", "application/json") w.WriteHeader(status) json.NewEncoder(w).Encode(ErrorResponse{Code: status, Message: msg}) } - 注意：
WriteHeader()必须在任何Write()或json.Encoder.Encode()之前调用，否则会被忽略
如何区分业务错误和系统错误并设置不同HTTP状态码
业务错误（如参数缺失、资源不存在）应返回 4xx 状态码；系统错误（如数据库连接失败、panic）应返回 5xx。混用会导致前端无法合理重试或提示用户。
Go 没有内置的「错误分类」机制，得靠约定或包装。别用字符串匹配错误信息来判断类型 —— 不稳定且难测试。
立即学习“go语言免费学习笔记（深入）”；
- 定义错误接口：
type AppError interface { error; StatusCode() int } - 实现具体错误：
var ErrNotFound = &appError{msg: "not found", code: http.StatusNotFound} - handler 中：遇到
AppError就用err.StatusCode()，其他错误一律用http.StatusInternalServerError - 避免在中间件里对所有错误都返回 500 —— 会掩盖本该是 400 的请求校验失败
panic 怎么安全捕获并转成 API 错误响应
HTTP handler 中 panic 会导致整个 goroutine 崩溃，不处理就会返回空响应或连接中断。必须用 recover() 拦截，但不能在任意位置乱用。
最稳妥的做法是只在顶层 handler wrapper 里 recover，而不是每个业务函数里都加 defer —— 否则嵌套太多，逻辑混乱。
- 写一个中间件：
func recoverMiddleware(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { defer func() { if err := recover(); err != nil { writeError(w, http.StatusInternalServerError, "internal server error") } }() next.ServeHTTP(w, r) }) } - 注意：recover 只捕获当前 goroutine 的 panic，且必须在 defer 中直接调用
recover()，不能包在另一个函数里 - 不要把 panic 当作控制流用（比如代替 if 判断），这会让错误路径不可预测
第三方库如 echo/gin 的错误处理和原生 net/http 有什么关键差异
echo 和 gin 提供了 c.AbortWithStatusJSON() 或 c.Error() 这类方法，看起来更简洁，但底层仍是封装了 WriteHeader() + Encode()。真正差异在于错误传播方式。
gin 的 c.Error() 只是把错误存到上下文，不自动终止执行；而 echo 的 return err 会触发默认错误处理器 —— 这个行为容易被忽略，导致后续代码仍运行。
- gin 中：必须显式
c.Abort()或return，否则即使调用了c.Error()，后续 handler 仍会执行 - echo 中：
return c.JSON(400, ...)是常规写法，但若用return errors.New("xxx")，需确保已注册HTTPErrorHandler函数 - 原生
net/http没有上下文错误存储机制，所有错误都要手动传递或返回，反而更透明、更可控
复杂点在于：跨中间件传递错误时，框架抽象层可能隐藏了状态写入时机，调试时得看它是否已调用 WriteHeader —— 否则自己再写就报 http: multiple response.WriteHeader calls。
