Go中结构体方法返回error是强制规范，涉及I/O、网络等外部依赖必须返回；应立即检查并返回错误，用%w包装保留错误链，避免硬编码全局错误变量。
结构体方法返回 error 是标准做法，不是可选技巧
Go 语言中，结构体方法返回 error 不是“要不要加”的问题，而是接口契约和调用方预期的一部分。如果你的方法可能失败（比如读文件、发 HTTP 请求、校验字段），就必须返回 error；否则调用方无法感知失败，只能靠 panic 或静默忽略——这两者都破坏可控性。
常见错误现象：method does not return error, but caller expects it（实际是逻辑错配，编译器不会报错，但测试或运行时暴露）；或者更隐蔽的：方法内部用 log.Fatal 或 panic 替代返回 error，导致无法在上层统一处理超时、重试或降级。
- 所有 I/O、网络、解析、校验类方法，只要可能失败，签名必须含
error返回值 - 不要在方法内部直接
os.Exit或panic，除非是真正不可恢复的程序级错误（如配置加载失败且无默认值） - 若方法逻辑上“不可能失败”，比如纯内存计算，可不返回
error；但一旦涉及外部依赖，就默认要加
if err != nil 后立即 return 是最安全的惯用写法
Go 社区广泛接受“错误即刻返回”模式，它让控制流清晰、避免嵌套过深，也天然适配 defer 清理资源。重点不是“写得短”，而是让错误路径和主路径分离明确。
使用场景：任何调用可能返回 error 的结构体方法后，都应立刻检查。例如调用 user.Save()、cfg.Load()、parser.Parse()。
立即学习“go语言免费学习笔记（深入）”；
- 不要写成
if err == nil { /* success logic */ }—— 主逻辑被缩进，易漏掉 else 分支 - 不要把多个方法调用挤在一行再统一检查，如
a(); b(); c(); if err != nil { ... }—— 你根本不知道哪个出错了 - 如果需要在错误前做清理（如关闭文件），用
defer+ 显式return，而不是把清理逻辑塞进else
func (u *User) Save() error {
f, err := os.OpenFile("users.json", os.O_APPEND|os.O_WRONLY, 0644)
if err != nil {
return fmt.Errorf("failed to open file: %w", err)
}
defer f.Close()
data, err := json.Marshal(u)
if err != nil {
return fmt.Errorf("failed to marshal user: %w", err)
}
if _, err := f.Write(data); err != nil {
return fmt.Errorf("failed to write user data: %w", err)
}
return nil}
包装错误用 %w 而不是 %v 或字符串拼接
用 fmt.Errorf("xxx: %w", err) 才能保留原始错误链，支持后续用 errors.Is 或 errors.As 判断类型或提取底层错误。用 %v、%s 或 err.Error() 拼接，等于主动切断错误上下文。
性能影响极小，但调试价值巨大：HTTP 客户端超时、数据库连接拒绝、JSON 解析失败……这些错误类型差异极大，靠字符串匹配极易误判。
- 只在日志输出或用户提示时用
err.Error()；在返回给调用方时，永远优先用%w - 不要重复包装同一错误多次，比如
fmt.Errorf("step1: %w", fmt.Errorf("step2: %w", err))—— 堆叠无意义，还增加开销 - 如果只是加上下文（如“saving user ID=123”），用
%w；如果要转换错误类型（如把*json.SyntaxError转成自定义InvalidDataError），用fmt.Errorf("...: %w", &InvalidDataError{...})
结构体方法里别用全局 var ErrXXX = errors.New(...) 硬编码错误
硬编码错误变量（如 var ErrNotFound = errors.New("not found")）适合包级通用错误，但结构体方法往往需要携带实例上下文（比如哪个 ID 没找到、哪条字段校验失败）。直接返回全局错误会丢失关键信息，迫使调用方额外传参或拼字符串。
容易踩的坑：为图省事，在 User.FindByID(id) 里返回 ErrNotFound，结果上层无法知道是 id=123 还是 id=456 没找到，日志里全是模糊的 “not found”。
- 对带参数的错误，用
fmt.Errorf("user %d not found: %w", id, ErrNotFound)，既保留类型又带上下文 - 如果错误需被程序逻辑判断（如重试策略），定义带字段的自定义错误类型，并实现
Unwrap()和Error() - 避免在方法内 new 一个全新错误（如
errors.New("save failed")）而不包装原错误——等于丢弃根因
复杂点在于：错误链越深，越要克制地加包装。不是每个调用都要 %w，关键是让上游能区分“是网络断了”还是“是数据格式错了”，而不是看到一串 “failed to … failed to … failed to …”。
