如何使用Golang封装第三方错误_保持系统内部错误统一格式

发布日期： 2025-12-24 阅读量： 作者： P粉602998670

统一错误格式的关键是选择性封装第三方错误并保留原始上下文，区分可恢复业务错误与需透传的底层错误；推荐轻量AppError结构体，仅在错误语义转变时封装，HTTP层通过中间件统一处理。

在 Go 项目中，统一错误格式的核心不是“包装所有错误”，而是有选择地封装第三方错误，同时保留原始上下文和语义。关键在于区分“可恢复的业务错误”和“需透传的底层错误”，避免过度封装导致调试困难。

明确错误分类边界

Go 的 error 是接口，但不同来源的错误应有不同的处理策略：

第三方库返回的 error（如 database/sql、redis、http.Client）：多数是底层异常（连接失败、超时、协议错误），应原样透传或仅加一层上下文，不强行转成业务错误码
业务逻辑主动 return 的 error（如用户不存在、参数校验失败）：适合封装为带 code、message、details 的结构体错误
panic 捕获的 error（如空指针、越界）：不应封装，而应记录 panic 栈并转为系统级错误（500）

定义内部错误结构体

推荐轻量结构，避免嵌套过深：

type AppError struct {
	Code    int    `json:"code"`    // HTTP 状态码或自定义业务码，如 4001（用户未登录）
	Message string `json:"message"` // 用户/前端可见提示
	Details string `json:"details,omitempty"` // 可选，用于日志追踪（如 SQL、请求 ID、参数快照）
}

func (e *AppError) Error() string {
	return e.Message
}

// 实现 Unwrap 支持 errors.Is/As
func (e *AppError) Unwrap() error { return nil }

注意：不要让 AppError 包含原始 error 字段并实现 Unwrap 返回它——这会破坏错误链语义。若需保留原始错误，用 errors.Join 或 errors.WithStack（需搭配第三方库如 github.com/pkg/errors）。

封装时机与方式

只在错误语义发生转变时封装：

数据库查询返回 sql.ErrNoRows → 封装为 “用户不存在”（code=404）
调用下游 HTTP 接口返回 401 → 封装为 “认证失效，请重新登录”（code=401）
redis.Conn.Do 返回 timeout error → 不封装，直接 return，由上层中间件统一转为 503

示例：

func (s *UserService) GetUser(ctx context.Context, id int) (*User, error) {
  u, err := s.db.GetUserByID(ctx, id)
  if err != nil {
    if errors.Is(err, sql.ErrNoRows) {
      return nil, &AppError{
        Code:    404,
        Message: "用户不存在",
        Details: fmt.Sprintf("user_id=%d", id),
      }
    }
    return nil, err // 其他 db 错误（如连接中断）直接透传
  }
  return u, nil
}

全局错误处理中间件

HTTP 层统一拦截，将 error 转为标准响应：

func ErrorHandler(next http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    defer func() {
      if r := recover(); r != nil {
        log.Printf("panic: %v", r)
        writeErrorResponse(w, 500, "系统繁忙，请稍后再试")
        return
      }
    }()

    next.ServeHTTP(w, r)
  })
}

func writeErrorResponse(w http.ResponseWriter, statusCode int, message string) {
  w.Header().Set("Content-Type", "application/json; charset=utf-8")
  w.WriteHeader(statusCode)
  json.NewEncoder(w).Encode(map[string]interface{}{
    "code": statusCode,
    "message": message,
  })
}

在 handler 中只需：

func (h *UserHandler) Get(w http.ResponseWriter, r *http.Request) {
  user, err := h.service.GetUser(r.Context(), userID)
  if err != nil {
    // 若是 *AppError，取其 Code 和 Message；否则默认 500
    code := 500
    msg := "系统繁忙"
    if appErr, ok := err.(*AppError); ok {
      code = appErr.Code
      msg = appErr.Message
    }
    writeErrorResponse(w, code, msg)
    return
  }
  // ...
}

上一篇: Mac怎么快速锁屏_Mac锁定屏幕的4种快捷方法【必会】

下一篇: Mac怎么设置开机问候语_Mac锁屏显示自定义文字

如何使用Golang封装第三方错误_保持系统内部错误统一格式

随便看看

南昌壹佳企网络通信有限公司