go函数返回error仅承诺“可能失败时返回非nil error”，不承诺类型、可比性、上下文或必须检查；守契约需定义公开错误变量、实现unwrap/error方法，避免字符串匹配和敏感信息泄露。
Go 函数返回 error 时，到底承诺了什么？
它只承诺：「我可能失败，失败时会返回一个非 nil 的 error」。不承诺错误类型、不承诺错误值是否可比较、不承诺错误是否包含上下文、更不承诺调用方必须检查——这些全靠开发者之间心照不宣的隐式合同。
比如 os.Open 返回 *os.PathError，你用 errors.Is(err, fs.ErrNotExist) 判断文件不存在，这依赖的是 Go 标准库维护的「错误语义契约」；但换成某个第三方包的 DoSomething()，它返回 fmt.Errorf("failed")，你就没法可靠地判断失败原因。
- 隐式合同不是代码强制的，是文档、示例、历史行为共同形成的共识
- 一旦包作者改写错误构造方式（比如从
fmt.Errorf改成errors.New），或升级错误包装逻辑，下游可能 silently break - 用
errors.As或errors.Is前，先确认该函数是否明确声明支持这些操作——查它的 godoc、看测试用例里怎么断言错误
如何写一个守契约的 Go 错误返回函数？
核心是让错误「可识别、可分类、可测试」，而不是只图方便 return fmt.Errorf("xxx %v", v)。
- 对关键错误场景定义公开的错误变量，如
var ErrTimeout = errors.New("timeout")，供调用方用errors.Is判断 - 需要携带数据时，定义带字段的错误类型，并实现
Unwrap() error和Error() string，确保能被errors.As提取 - 避免在错误信息里拼接敏感数据（如密码、token），也不依赖错误字符串做逻辑分支——
strings.Contains(err.Error(), "permission")是典型反模式 - 如果函数有前置条件（例如参数不能为 nil），应在文档注释里明确写
// Panics if x is nil，而不是靠返回error来兜底
panic 和 error 的边界在哪？
Go 不鼓励用 panic 处理业务错误，但也不禁止——关键看谁该负责恢复。
立即学习“go语言免费学习笔记（深入）”；
-
panic适用于「程序无法继续执行」的异常状态：空指针解引用、索引越界、传入非法状态导致内部 invariant 被破坏 -
error适用于「预期中的失败」：网络超时、磁盘满、用户输入校验失败、API 返回 404 - 常见踩坑：把 HTTP 客户端请求失败（如
http.Get返回 500）当成 panic 场景；其实它应返回error，由上层决定重试、降级或告警 - 另一个坑：在 defer 中 recover 后直接忽略 panic，却不记录日志或透出上下文——这等于把严重问题伪装成静默失败
为什么 context.Context 里的取消和超时不算「错误」？
因为 ctx.Err() 返回的 context.Canceled 或 context.DeadlineExceeded 是控制流信号，不是操作失败的结果。它们描述的是「我主动停止了」，而非「我没能完成」。
- 如果你的函数接受
ctx context.Context，应当在每次循环或阻塞前检查ctx.Err() != nil，并立即返回——此时返回的错误应是ctx.Err()本身，而不是另造一个新错误 - 不要把
ctx.Err()包进其他错误里再返回（如fmt.Errorf("read failed: %w", ctx.Err())），除非你明确要添加额外上下文；否则会干扰调用方对取消/超时的统一处理逻辑 - 注意：
context.DeadlineExceeded是一个导出变量，可用errors.Is(err, context.DeadlineExceeded)安全判断，这是标准库给出的契约保障
隐式合同最危险的地方在于：它不报错，却让逻辑在某次升级后悄然偏离预期。多看源码里错误怎么构造、怎么测试，比背诵最佳实践管用得多。
