17370845950

Go错误处理应避免字符串匹配，优先用errors.Is/As和导出错误变量；库中禁用panic除非编程错误；错误信息需含上下文但不冗余或泄露敏感数据；公开错误契约须稳定并文档化。

错误值应该可判断而非仅靠字符串匹配

Go 中的 error 是接口，不是字符串。用 err.Error() == "xxx" 判断错误类型是脆弱的：一旦底层库修改了错误消息（比如加了空格、翻译成英文、补充上下文），你的判断就失效了。

正确做法是使用类型断言或标准库提供的判断函数：

• 对自定义错误，导出可比较的变量，如 var ErrNotFound = errors.New("not found")，然后用 errors.Is(err, ErrNotFound)
• 对包装错误（如 fmt.Errorf("failed: %w", io.EOF)），必须用 errors.Is() 或 errors.As()，不能用 ==
• 调用第三方库时，优先查其文档是否导出了错误变量（如 sql.ErrNoRows），而不是硬编码字符串

不要在库中 panic，除非是真正的编程错误

库代码面向调用方，panic 会中断调用栈，且无法被常规 recover 捕获（尤其跨包时行为不可控）。只有以下情况才考虑 panic：

• 违反函数前提条件（precondition），例如传入 nil 指针且文档明确要求非空
• 内部状态严重不一致（如 sync.Pool 返回了已释放对象）
• 配置解析失败且该配置由库自身硬编码、不可能出错——但这种情况本身就该避免

常见反例：json.Unmarshal 遇到非法 JSON 返回 error；time.Parse 格式错误也返回 error；它们从不 panic。

错误信息要包含上下文，但避免冗余和敏感数据

库返回的错误应帮助调用方定位问题，而不是让对方再层层打日志。但“加 context”不等于无脑拼接字符串。

• 用 fmt.Errorf("read header: %w", err) 包装，保留原始错误链，支持 errors.Unwrap 和 Is/As
• 避免重复前缀：如果调用方已在日志里打了 "[upload] failed"，库里就不必再写 "upload: failed to write file: permission denied"
• 绝不把用户输入、token、密码、路径全量塞进错误字符串——攻击者可能通过 API 错误响应获取敏感信息

func (s *Service) CreateUser(ctx context.Context, u User) error {
	if u.Email == "" {
		return fmt.Errorf("CreateUser: email required") // ✅ 清晰、无敏感内容、可定位
	}
	if err := s.store.Insert(ctx, u); err != nil {
		return fmt.Errorf("CreateUser: insert user: %w", err) // ✅ 包装并保留原始错误
	}
	return nil
}

公开接口的错误返回需稳定，且文档化

库的 API 错误契约是公共合约的一部分。一旦声明某个函数可能返回 io.EOF 或自定义 ErrTimeout，就不能在后续版本中静默替换为其他错误类型，否则调用方的 errors.Is(err, io.EOF) 会突然失效。

• 在 godoc 注释里明确列出所有可能返回的错误，尤其是自定义错误变量
• 避免用 errors.New("unknown error") 这类模糊错误；要么导出具体变量，要么确保它能被 errors.Is 合理识别
• 如果必须变更错误行为（如升级依赖导致底层错误类型变化），属于不兼容变更，需升主版本号

最常被忽略的一点：错误的「可测试性」。如果你的库导出错误变量，测试才能用 assert.Equal(t, err, mypkg.ErrInvalidID)；如果只返回临时 errors.New，测试只能退化为字符串匹配，这就回到了第一个坑。