Golang项目中错误处理规范示例_技术教程

Go 错误必须显式判断，不可忽略；应使用 %w 包装、errors.Is 判断、统一 HTTP 错误映射，并在测试中覆盖各类错误场景。

Go 中错误类型必须显式判断，不能忽略 `error` 返回值

Go 的设计哲学是“错误不是异常”，error 是普通返回值，不处理就等于放任失败。常见错误是写成 json.Unmarshal(data, &v) 后直接用 v，没检查第二个返回的 error。一旦解码失败，v 处于未定义状态，后续逻辑可能 panic 或静默出错。

正确做法是每次调用后立即判断：

if err := json.Unmarshal(data, &v); err != nil {
    return fmt.Errorf("failed to parse config: %w", err)
}

永远不要用 _ 忽略 error，除非你明确知道该函数在当前上下文中绝不会返回非 nil 错误（如 fmt.Sprintf）
用 %w 包装错误可保留原始调用链，方便后续用 errors.Is 或 errors.As 判断
避免裸写 return err 在业务入口，应补充上下文，比如 return fmt.Errorf("create user: %w", err)

自定义错误类型优先用 `errors.New` 和 `fmt.Errorf`，而非结构体

90% 的场景不需要定义新 struct 类型来表示错误。过度封装会增加维护成本，且 Go 标准库的错误处理机制（如 errors.Is、errors.Unwrap）对字符串错误同样有效。

反例（不必要）：

type ValidationError struct {
    Field string
    Msg   string
}
func (e *ValidationError) Error() string { return e.Msg }

正例（更轻量、更通用）：

err := fmt.Errorf("validation failed on field %q: %w", field, errors.New("must be non-empty"))

需要携带字段或状态时，用 fmt.Errorf + 命名参数（如 fmt.Errorf("timeout after %v: %w", timeout, err)）更清晰
只有当需实现特定接口（如 Timeout() bool）或需被第三方库深度集成时，才考虑自定义 error struct
所有自定义 error 类型必须实现 Error() string，且不应暴露内部字段给调用方直接比较

HTTP handler 中错误要转为标准状态码，避免泄露内部细节

Web 服务中，把底层存储错误（如 "pq: duplicate key violates unique constraint"）直接返回给前端，既不安全也不友好。应统一拦截、分类、映射。

推荐在中间件或统一响应构造处处理：

func handleError(w http.ResponseWriter, err error) {
    switch {
    case errors.Is(err, sql.ErrNoRows):
        http.Error(w, "not found", http.StatusNotFound)
    case strings.Contains(err.Error(), "duplicate key"):
        http.Error(w, "conflict", http.StatusConflict)
    default:
        log.Printf("unhandled error: %v", err)
        http.Error(w, "internal error", http.StatusInternalServerError)
    }
}

不要用 http.Error 返回原始错误消息，尤其涉及数据库、文件路径、配置键名等敏感信息
用 errors.Is 比对已知错误（如 os.ErrNotExist），比字符串匹配更健壮
若使用 Gin/Echo 等框架，应在全局 Recovery 中间件里做类似转换，而不是每个 handler 里重复写

测试中验证错误行为比验证成功路径更重要

很多 Go 项目只测“能跑通”，但线上故障往往来自边界错误。比如一个依赖外部 API 的函数，必须测它在 HTTP 超时、JSON 解析失败、空响应等场景下是否返回预期错误类型和消息。

示例测试片段：

func TestFetchUser(t *testing.T) {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusBadGateway)
        w.Write([]byte(`{"error":"upstream failed"}`))
    }))
    defer server.Close()

    _, err := FetchUser(context.Background(), server.URL)
    if !strings.Contains(err.Error(), "upstream failed") {
        t.Fatal("expected upstream error in message")
    }
    if !errors.Is(err, ErrUpstreamFailed) {
        t.Fatal("expected ErrUpstreamFailed error")
    }
}