Go接口方法的错误返回必须严格为error类型，不可省略或替换；需显式声明、统一用error返回并避免panic；错误应归一化、隐藏实现细节，且error不等于日志。
Go 接口函数的错误返回必须是 error 类型，不能省略或用其他类型替代
Go 语言中接口方法签名一旦定义，所有实现都必须严格匹配。如果接口方法声明返回 error，那实现函数就必须返回 error（哪怕总是返回 nil），不能返回 *errors.Error、string 或自定义错误结构体——否则编译直接报错：cannot use … as … value in return statement: wrong type for error result。
常见错误是误以为“只要最后能转成 error 就行”，比如写成：
func (s *Service) Do() string {
return "failed"
}
这无法满足 Do() error 接口要求。正确做法是始终用 error 作为返回类型，并在需要时用 errors.New 或 fmt.Errorf 构造值：
func (s *Service) Do() error {
if failed {
return fmt.Errorf("do failed: %w", io.ErrUnexpectedEOF)
}
return nil
}
接口定义中应显式声明 error 返回，而非依赖隐式约定
很多初学者会把错误处理“藏”在结构体字段或全局变量里，比如：
立即学习“go语言免费学习笔记（深入）”；
type Reader interface {
Read([]byte) int // ❌ 没有 error 返回，无法区分 EOF 和真实错误
}
这是反模式。标准库的 io.Reader 正确写法是：
type Reader interface {
Read(p []byte) (n int, err error)
}
关键点：
- 每个可能失败的操作，接口方法必须显式返回
error - 不要靠调用方“猜”是否出错（比如返回负数、空字符串）
- 若方法逻辑上不可能失败（如纯内存计算），才可不返回
error
错误链传递要用 %w，但接口实现中要避免暴露内部错误细节
调用下游接口时，常需包装错误并保留原始上下文。用 fmt.Errorf("xxx: %w", err) 可以让 errors.Is 和 errors.As 正常工作。但要注意：
- 接口方法返回的错误，不应暴露底层实现细节（如数据库驱动名、HTTP 状态码、文件路径）
- 对外暴露的错误建议用自定义类型 + 实现
Error()方法，隐藏敏感字段 - 若使用
fmt.Errorf包装，确保最外层错误消息对调用方有意义，而不是层层嵌套的 “failed to call db: failed to exec: pq: duplicate key”
例如，一个用户注册接口不应返回：
return fmt.Errorf("db insert failed: %w", pgErr) // ❌ 泄露 pg 驱动细节
而应归一化为业务错误：
if errors.Is(pgErr, pg.ErrDuplicateKey) {
return fmt.Errorf("user already exists: %w", pgErr) // ✅ 清晰、可判断、不泄露技术栈
}
不要在接口方法里 panic，错误必须通过 error 返回
Go 接口设计哲学是“显式错误处理”。即使内部发生不可恢复错误（如配置缺失、空指针解引用），也应提前校验并返回 error，而不是依赖 panic —— 因为 panic 无法被接口调用方统一 recover，且破坏了接口契约的确定性。
典型反例：
func (s *Service) Get(id int) (*User, error) {
if s.db == nil {
panic("db not initialized") // ❌ 调用方无法预期 panic，也无法写 unit test 模拟
}
// ...
}
正确做法是在初始化阶段检查依赖，或在方法开头返回明确错误：
func (s *Service) Get(id int) (*User, error) {
if s.db == nil {
return nil, errors.New("service db not ready")
}
// ...
}
真正需要 panic 的场景极少，仅限于开发期断言（如 assert 工具函数），绝不应出现在公开接口实现中。
最容易被忽略的一点：错误不是日志。返回 error 不代表你已经记录了它；调用方决定是否记录、如何重试、是否告警。接口本身只负责“告知失败”，不越界做副作用。
