Golang Web项目如何处理错误返回_统一错误处理方案_技术教程

Go HTTP handler 中 panic 默认导致500且响应不可控，须用recover中间件拦截并统一转为结构化错误响应；应定义带状态码的AppError类型、统一响应包装器Respond，并区分HTTP状态码与业务code。

Go HTTP handler 中 panic 会直接 500，必须拦截

默认情况下，http.ServeMux 或 http.Handler 函数里一旦 panic，Go 的 http.Server 会打印堆栈并返回状态码 500，但响应体不可控、无业务上下文、不记录日志。这不是“错误处理”，是服务裸奔。

正确做法是在中间件中 recover，并转换为结构化错误响应：

func Recovery(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			if err := recover(); err != nil {
				log.Printf("panic recovered: %v", err)
				http.Error(w, "Internal Server Error", http.StatusInternalServerError)
			}
		}()
		next.ServeHTTP(w, r)
	})
}

必须放在所有业务 handler 外层（比如 http.ListenAndServe(":8080", Recovery(r))）
仅捕获 panic，不处理 return errors.New(...) 这类显式错误
不要在 recover 里直接写 JSON 响应——此时可能已部分写入 header，应统一走错误响应构造逻辑

自定义 error 类型 + Status Code 绑定

Go 原生 error 接口不携带 HTTP 状态码，硬编码 http.StatusBadRequest 到每个 handler 里极易遗漏或错配。推荐定义可嵌入状态码的错误类型：

type AppError struct {
	Code    int
	Message string
	Err     error // 底层原始错误（用于日志/调试）
}

func (e *AppError) Error() string {
	if e.Err != nil {
		return fmt.Sprintf("%s: %v", e.Message, e.Err)
	}
	return e.Message
}

func BadRequest(msg string) *AppError {
	return &AppError{Code: http.StatusBadRequest, Message: msg}
}

func NotFound(msg string) *AppError {
	return &AppError{Code: http.StatusNotFound, Message: msg}
}

业务 handler 中直接 return BadRequest("user ID required")，不手动写 http.Error
Err 字段保留原始错误（如数据库超时、JSON 解析失败），便于日志追踪，但不暴露给前端
避免用字符串拼接做错误类型判断（如 strings.Contains(err.Error(), "not found")），应通过类型断言：if ae, ok := err.(*AppError); ok { ... }

统一响应包装器：把 error 转成标准 JSON 返回

所有 handler 不该各自调用 json.NewEncoder(w).Encode(...)。应在中间件或顶层 wrapper 中统一处理成功与错误响应格式：

type Response struct {
	Code    int         `json:"code"`
	Message string      `json:"message"`
	Data    interface{} `json:"data,omitempty"`
}

func Respond(w http.ResponseWriter, status int, data interface{}, err error) {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.WriteHeader(status)

	resp := Response{
		Code:    status,
		Message: http.StatusText(status),
		Data:    data,
	}

	if appErr, ok := err.(*AppError); ok {
		resp.Code = appErr.Code
		resp.Message = appErr.Message
	}

	if err := json.NewEncoder(w).Encode(resp); err != nil {
		log.Printf("failed to encode response: %v", err)
	}
}

成功响应也走这个函数（Respond(w, http.StatusOK, user, nil)），保证结构一致
注意 w.WriteHeader(status) 必须在写 body 前调用，否则会被 json.Encoder 自动设为 200
不要在 Respond 里加额外日志——错误日志应在 error 生成时或中间件中记录，避免重复

Handler 内部如何返回错误而不中断流程

Go 没有 try/catch，但大量嵌套 if err != nil { return err } 很丑。可用两种轻量方式保持可读性：

使用 errors.Join（Go 1.20+）合并多个校验错误，一次性返回：var errs []error; if x == "" { errs = append(errs, errors.New("x required")) }; if y 0 { retu rn errors.Join(errs) }
对 DB/HTTP 等外部调用，封装带 context 和重试的工具函数，内部自动转成 *AppError，例如：user, err := GetUser(ctx, id); if err != nil { return InternalError("failed to fetch user").Wrap(err) }（Wrap 方法可附加原始错误）
切忌在 handler 里用 log.Fatal 或 os.Exit——这会 kill 整个 server

最易被忽略的是：错误响应体里的 code 字段别和 HTTP 状态码强绑定。比如业务需要返回 {"code": 40001, "message": "token expired"}，此时 HTTP 状态码仍应是 401，而 JSON 中的 code 是业务码——两者语义不同，混用会导致前端判断混乱。