Go中接口调用错误处理应使用结构化AppError类型，包含Code、Message、HTTPStatus和Err字段，通过工厂函数封装、统一HTTP响应，并映射网络错误、状态码及解析失败等场景。
在 Go 中实现接口调用的错误处理，核心是统一返回标准错误类型（如 error 接口），并结合上下文、状态码、原始错误等信息构造可读、可分类、可序列化的错误。不建议直接裸抛 errors.New 或 fmt.Errorf，而应设计结构化错误类型，便于日志记录、API 响应封装和客户端解析。
定义标准错误结构体
推荐定义一个实现了 error 接口的结构体，包含错误码、消息、HTTP 状态码、原始错误（可选）等字段：
- Code：业务错误码（如 "USER_NOT_FOUND", "INVALID_PARAM"），用于前端或调用方识别
- Message：面向用户/开发者的提示语（避免暴露敏感信息）
- HTTPStatus：对应 HTTP 响应状态码（如 400、401、500）
- Err：底层原始错误（如网络超时、JSON 解析失败），用于日志追踪，不暴露给外部
示例：
type AppError struct {Code string
Message string
HTTPStatus int
Err error
}
实现 Error() 方法：
立即学习“go语言免费学习笔记（深入）”；
func (e *AppError) Error() string {return fmt.Sprintf("[%s] %s", e.Code, e.Message)
}
封装 HTTP 接口调用并统一错误转换
使用 net/http 调用第三方 API 时，需将各类底层错误（连接失败、超时、非 2xx 响应、JSON 解析失败）映射为标准 *AppError：
- 网络层错误（
url.Error、context.DeadlineExceeded）→ 映射为系统错误（如 "SERVICE_UNAVAILABLE"，HTTP 503） - 非成功状态码（如 400/401/404/500）→ 根据响应体解析错误详情，或按状态码默认映射（如 404 → "RESOURCE_NOT_FOUND"）
- JSON 反序列化失败 → 包装为 "INVALID_RESPONSE_FORMAT"，保留原始 error 用于日志
示例片段：
resp, err := http.DefaultClient.Do(req)if err != nil {
return nil, &AppError{
Code: "HTTP_REQUEST_FAILED",
Message: "请求第三方服务失败",
HTTPStatus: http.StatusServiceUnavailable,
Err: err,
}
}
defer resp.Body.Close()
if resp.StatusCode = 300 {
body, _ := io.ReadAll(resp.Body)
return nil, &AppError{
Code: statusCodeToCode(resp.StatusCode),
Message: fmt.Sprintf("第三方服务返回异常状态: %d", resp.StatusCode),
HTTPStatus: resp.StatusCode,
Err: fmt.Errorf("status %d, body: %s", resp.StatusCode, string(body)),
}
}
提供便捷错误构造函数
避免重复 new 结构体，提供工厂函数提升可读性和一致性：
-
NewBadRequest(code, msg string) *AppError→ 返回 400 错误 -
NewUnauthorized(msg string) *AppError→ 返回 401 -
NewInternalError(err error) *AppError→ 包装 panic 或不可预期错误 -
Wrap(err error, code, msg string, status int) *AppError→ 封装底层 error 并补充上下文
这样在业务逻辑中可简洁表达：
if userID == "" {return nil, NewBadRequest("INVALID_USER_ID", "用户ID不能为空")
}
在 HTTP handler 中统一响应错误
所有 handler 应捕获 *AppError 并生成标准 JSON 响应（如 {"code":"xxx","message":"yyy","trace_id":"..."}），同时设置对应 HTTP 状态码：
user, err := h.service.GetUser(r.Context(), r.URL.Query().Get("id"))
if err != nil {
if appErr, ok := err.(*AppError); ok {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(appErr.HTTPStatus)
json.NewEncoder(w).Encode(map[string]interface{}{
"code": appErr.Code,
"message": appErr.Message,
"trace_id": getTraceID(r),
})
return
}
// 非标准错误兜底
w.WriteHeader(http.StatusInternalServerError)
json.NewEncoder(w).Encode(map[string]string{"code": "INTERNAL_ERROR", "message": "服务内部错误"})
return
}
json.NewEncoder(w).Encode(user)
}
