Go项目错误处理实战教程

Go中错误是需显式检查的接口，非异常；必须立即处理每个函数返回的error，用errors.Is/As判断类型，自定义错误应实现Error()和Unwrap()，HTTP handler需返回对应状态码。

Go里错误不是异常，error 是一个接口，必须显式检查

Go 没有 try/catch，也不把错误当控制流。你写的每个可能出错的函数（比如 os.Open、json.Unmarshal）都返回 error，但不会自动中断执行。漏掉 if err != nil 就等于忽略失败——程序可能继续用空指针、零值或脏数据运行，崩溃时堆栈还找不到源头。

常见错误现象：文件读取失败但后续代码仍尝试解析 nil 的 *os.File；JSON 解析出错却直接访问未初始化的结构体字段。

• 所有 I/O、编码、网络调用后必须立刻检查 err，不要攒到函数末尾统一处理
• 不要用 if err != nil { panic(err) } 替代处理——这在 CLI 工具里勉强可接受，在服务中等于主动宕机
• 如果当前函数无法处理错误（比如没权限重试或补救），就用 return err 向上抛，别吞掉

用 errors.Is 和 errors.As 判断错误类型，别用 == 或 strings.Contains

Go 1.13 引入了错误链（fmt.Errorf("xxx: %w", err)），旧方式如 err == io.EOF 或 err.Error() == "no such file" 在嵌套错误下会失效。比如 os.Open 失败再被 fmt.Errorf 包装一次，原始错误就被藏在底层了。

正确做法是用标准库提供的判断工具：

if errors.Is(err, os.ErrNotExist) {
    // 文件不存在，可以创建默认配置
} else if errors.As(err, &pathErr) {
    // 获取具体路径错误信息：pathErr.Path, pathErr.Err
}

• errors.Is 用于匹配预定义错误（如 os.ErrNotExist、io.EOF）
• errors.As 用于提取底层具体错误类型，方便访问字段或调用方法
• 避免对 err.Error() 做字符串匹配——语言环境变化、拼写微调都会让逻辑崩坏

自定义错误要实现 Error() 方法，必要时嵌入 Unwrap()

项目一长，光靠 fmt.Errorf("failed to parse config: %w", err) 不够。你需要区分“配置格式错”和“磁盘读取错”，否则上层无法做差异化响应（比如前者该提示用户改 YAML，后者该重试）。

定义错误类型时，优先用结构体 + 实现 error 接口：

type ConfigParseError struct {
    File string
    Line int
    Err  error
}

func (e *ConfigParseError) Error() string {
    return fmt.Sprintf("parse error in %s:%d: %v", e.File, e.Line, e.Err)
}

func (e *ConfigParseError) Unwrap() error {
    return e.Err
}

• 必须实现 Error() string 方法，否则不是合法 error
• 如果想保留原始错误供 errors.Is/As 使用，就得实现 Unwrap() error
• 不要导出内部错误字段（如 Err），防止调用方绕过错误链直接操作

HTTP handler 中错误不能只打日志，要写响应并设状态码

Web 服务里最典型错误处理失当：数据库查不到记录，只记了一行 log.Printf("user not found: %v", err)，然后返回空 JSON 或 200 状态码。前端收到 {} 却以为成功，逻辑错乱。

每个 handler 都应明确错误出口：

func getUser(w http.ResponseWriter, r *http.Request) {
    id := chi.URLParam(r, "id")
    u, err := db.FindUser(id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            http.Error(w, "user not found", http.StatusNotFound)
            return
        }
        http.Error(w, "internal error", http.StatusInternalServerError)
        log.Printf("db.FindUser(%s) failed: %v", id, err)
        return
    }
    json.NewEncoder(w).Encode(u)
}

• 业务错误（如资源不存在、参数非法）用 4xx 状态码，带简明英文消息
• 系统错误（DB 连接断、磁盘满）用 5xx，不暴露细节给前端，但务必记完整日志
• 别在中间件里统一 recover panic 来“兜底”——panic 是真异常，不该用来替代错误处理

实际项目中最容易被忽略的，是错误发生后上下文是否干净：临时文件删没删、数据库事务回滚没回滚、goroutine 是否泄漏。错误处理不是加几行 if err != nil 就完事，而是每次 return err 前，确认资源已释放、状态已还原。