Golang函数返回error的最佳实践

go要求业务错误必须显式返回Error值，panic仅用于不可恢复的程序异常；需用fmt.Errorf(“%w”)包装错误以保留调用链；自定义error仅在需额外行为或精确匹配时定义；错误检查必须显式进行，不可依赖defer或忽略。

error 类型必须显式返回，不能用 panic 替代业务错误

Go 的设计哲学是把错误当作值来处理，panic 仅用于真正不可恢复的程序异常（如空指针解引用、切片越界）。业务逻辑中的失败（比如文件不存在、数据库查不到记录、参数校验不通过）必须通过返回 error 值暴露给调用方。

常见错误是把本该返回 error 的地方写成 panic(fmt.Errorf(...))，导致调用方无法判断、无法重试、无法记录上下文，甚至让整个 goroutine 崩溃。

• http handler 中用户传了非法 ID？返回 fmt.Errorf("invalid user id: %s", id)，而不是 panic
• 调用第三方 API 返回 404？构造一个带状态码和原始响应体的自定义 error，而不是 log.Fatal 或 os.Exit
• 数据库 Scan 失败？检查 err != nil 并原样返回，不要忽略或转成 panic

用 errors.New 或 fmt.Errorf 包装原始 error，别直接返回底层 error

底层库（比如 os.Open、json.Unmarshal）返回的 error 通常缺乏调用链上下文。直接透传会让上层难以定位问题源头。

推荐在每一层做一次语义化包装，用 fmt.Errorf("xxx: %w", err) 保留原始 error 链，同时添加当前层的意图信息。

立即学习“go语言免费学习笔记（深入）”；

func LoadConfig(path String) (*Config, error) {     data, err := os.ReadFile(path)     if err != nil {         return nil, fmt.Errorf("failed to read config file %q: %w", path, err)     }     var cfg Config     if err := json.Unmarshal(data, &cfg); err != nil {         return nil, fmt.Errorf("failed to parse config JSON: %w", err)     }     return &cfg, nil }

这样调用方可以用 errors.Is 或 errors.As 判断原始错误类型，也能用 fmt.printf("%+v", err) 看完整调用栈。

自定义 error 类型只在需要行为区分时才定义

95% 的场景用 fmt.Errorf + %w 就够了。只有当你需要为某类错误提供额外方法（比如 .StatusCode()、.Retryable()），或者要精确匹配（errors.As(err, &myErr)）时，才值得定义结构体 error。

定义时注意：实现 Error() string 方法；如果要支持 unwrap，加上 Unwrap() error；避免暴露内部字段，用方法封装访问逻辑。

type ValidationError struct {     Field   string     Message string }  func (e *ValidationError) Error() string {     return fmt.Sprintf("validation failed on field %q: %s", e.Field, e.Message) }  func (e *ValidationError) Unwrap() error { return nil }

别为了“看起来专业”而堆砌自定义 error —— 维护成本高，且多数日志/监控系统只读取 Error() 字符串。

error 检查必须显式，不要依赖 defer 或全局变量隐藏判断逻辑

有些开发者会写 defer func() { if err != nil { log.Error(err) } }()，这看似简洁，实则掩盖了错误处理责任。调用方依然得自己检查 err，而 defer 里的日志可能没包含关键上下文（比如请求 ID、输入参数）。

正确做法是在每个可能出错的调用后立即检查，并按需处理：

• 可重试？加 if errors.Is(err, context.DeadlineExceeded) { ... }
• 要降级？分支里返回默认值或调用备选路径
• 必须终止？用 return nil, fmt.Errorf("xxx: %w", err) 向上传播

别把 error 处理逻辑推给某个中心化函数——它没法知道当前上下文该重试、告警还是静默丢弃。

最常被忽略的一点：error 是接口类型，零值是 nil。只要函数签名里有 error 返回，就代表它可能失败；哪怕文档没写、测试没覆盖，也得检查。漏掉一次 if err != nil，就可能让一个配置加载失败静默变成空结构体，后续 panic 更难排查。