本文介绍如何在 Go 项目中设计结构化错误类型，通过自定义错误包装器（如 HTTPError、SerializationError）实现错误来源的精准识别与分层处理，避免字符串匹配，提升 API 响应码映射的可靠性与可维护性。
本文介绍如何在 go 项目中设计结构化错误类型，通过自定义错误包装器（如 `httperror`、`serializationerror`）实现错误来源的精准识别与分层处理，避免字符串匹配，提升 api 响应码映射的可靠性与可维护性。
在 Go 中，错误（error）是一等公民，但其接口的简洁性（仅含 Error() string 方法）也带来了挑战：当多个错误来源共存时，仅靠 err != nil 或 strings.Contains(err.Error(), "...") 判断，既脆弱又难以维护。尤其在构建分层服务（如上层 HTTP API 封装底层第三方客户端）时，必须区分“网络不可达”“远程服务返回业务错误”“本地反序列化失败”等语义截然不同的异常场景，并据此返回恰当的 HTTP 状态码（如 503、404、400、500）。此时，简单地透传原始错误已不再足够。
理想的解决方案是建立语义明确、可类型断言的错误分类体系。核心思路是：不隐藏错误根源，而是用轻量级结构体对原始错误进行语义包装，并保留完整的错误链信息。以下是一个生产就绪的实践模式：
1. 定义领域专属错误类型
package a // 第三方 API 客户端包
import "fmt"
// HTTPError 表示请求发送阶段失败（如连接超时、DNS 解析失败）
type HTTPError struct {
Err error
}
func (e HTTPError) Error() string { return fmt.Sprintf("HTTP transport error: %v", e.Err) }
func (e HTTPError) Unwrap() error { return e.Err } // 支持 errors.Unwrap（Go 1.13+）
// APIError 表示第三方服务返回了非 2xx 响应（如 404 User Not Found）
type APIError struct {
StatusCode int
Message string
RawBody []byte
}
func (e APIError) Error() string {
return fmt.Sprintf("API error %d: %s", e.StatusCode, e.Message)
}
func (e APIError) StatusCode() int { return e.StatusCode } // 提供便捷访问器
// SerializationError 表示 JSON 解析/序列化失败
type SerializationError struct {
Err error
}
func (e SerializationError) Error() string { return fmt.Sprintf("serialization error: %v", e.Err) }
func (e SerializationError) Unwrap() error { return e.Err }
✅ 关键设计点：每个类型都实现
Unwrap()方法，使errors.Is()和errors.As()可沿错误链向下检查；APIError还暴露StatusCode()方法，便于上层直接提取状态码。
2. 在客户端中主动包装错误
func (c *Client) GetUser(id string) (*User, error) {
url := fmt.Sprintf("https://graph.facebook.com/v19.0/%s", id)
resp, err := c.httpClient.Get(url)
if err != nil {
return nil, HTTPError{Err: err} // 网络层失败 → 包装为 HTTPError
}
defer resp.Body.Close()
if resp.StatusCode = 300 {
var body []byte
io.ReadFull(resp.Body, body)
msg := string(body)
if len(msg) > 100 { msg = msg[:100] + "..." }
return nil, APIError{
StatusCode: resp.StatusCode,
Message: msg,
RawBody: body,
}
}
var user User
if err := json.NewDecoder(resp.Body).Decode(&user); err != nil {
return nil, SerializationError{Err: err} // 解析失败 → 包装为 SerializationError
}
return &user, nil
}
3. 在上层 API 中按类型精准响应
func (h *Handler) GetUser(w http.ResponseWriter, r *http.Request) {
id := chi.URLParam(r, "id")
user, err := h.client.GetUser(id)
if err != nil {
switch {
case errors.As(err, &a.HTTPError{}):
http.Error(w, "Service unavailable", http.StatusServiceUnavailable)
case errors.As(err, &a.APIError{}):
var apiErr a.APIError
if errors.As(err, &apiErr) {
// 直接映射第三方状态码（如 404 → 404，400 → 400）
http.Error(w, apiErr.Error(), apiErr.StatusCode())
}
case errors.As(err, &a.SerializationError{}):
http.Error(w, "Invalid response format", http.StatusBadRequest)
default:
// 未预期错误，记录日志并返回 500
log.Printf("Unexpected error: %+v", err)
http.Error(w, "Internal error", http.StatusInternalServerError)
}
return
}
json.NewEncoder(w).Encode(user)
}
注意事项与进阶建议
-
避免过度包装：仅对需要差异化处理的错误层级做包装；底层 I/O 错误（如
os.Open失败）通常无需再包装，除非需统一语义。 -
兼容标准库：始终实现
Unwrap()并支持errors.Is(err, target)，以便与io.EOF、context.Canceled等标准错误协同工作。 -
错误日志需完整：记录错误时使用
fmt.Printf("%+v", err)（而非err.Error()），可输出完整错误栈和包装结构。 -
考虑
github.com/pkg/errors或entgo.io/ent的错误工具：若需更丰富的堆栈追踪，可引入成熟错误库，但务必确保其与errors.As/Is兼容。
通过这种分层包装策略，你的 package a 保持了纯粹的业务职责（不感知 HTTP 状态码），而上层服务则获得了清晰、类型安全的错误分类能力——这正是 Go 错误处理从“能用”走向“好用”的关键一步。
