CustomError与error对比：Golang错误指针返回实践

本文深入剖析了 Go 语言中自定义错误类型（*CustomError）与内置 error 接口的交互本质，澄清了“指针能赋值给 error 是因语法特殊”的常见误解——实则源于 Go 接口的隐式实现机制：只要 *CustomError 实现了 Error() 方法，它就天然满足 error 接口；而值类型若未单独实现，则无法直接使用，极易引发编译错误。文章不仅厘清 errors.Is/As 的底层行为（依赖动态类型而非值比较，强调传参必须是正确类型的实例或地址）、指出 fmt.Errorf("%w") 包装 nil *CustomError 的隐蔽陷阱，还给出了务实的工程建议：仅当需携带结构化字段、支持精确类型识别或统一监控时才定义 *CustomError，避免过度设计；推荐统一采用指针实现以规避复制开销和逃逸问题，并提醒在高频路径慎用 errors.As。这是一份兼顾原理深度与落地实践的 Go 错误处理指南。

为什么 *CustomError 不等于 error 类型但能赋值给它

因为 Go 的接口是隐式实现的：error 是一个只含 Error() 方法的接口，只要某个类型（哪怕是指针类型）实现了这个方法，它就满足 error 接口。所以 *CustomError 能直接返回，不是因为“指针特殊”，而是因为它实现了方法；而 CustomError 值类型如果没实现，就不能用。

常见错误现象：return CustomError{msg: "x"} 编译失败，报 cannot use ... (type CustomError) as type error —— 就是因为你只给 *CustomError 实现了 Error()，没给值类型实现。

• 推荐统一用指针实现：func (e *CustomError) Error() string，避免值类型意外逃逸或复制开销
• 如果同时支持值/指针调用，得额外给值类型也实现：func (e CustomError) Error() string，但通常没必要
• 注意：fmt.Errorf("wrap: %w", err) 中的 %w 要求 err 是 error 接口，*CustomError 没问题，但 nil *CustomError 传进去会变成非 nil 的 error，这点容易被忽略

errors.Is 和 errors.As 对 *CustomError 的行为差异

这两个函数底层依赖接口的动态类型信息，不是靠值比较。它们能正确识别 *CustomError，但前提是错误链里确实存的是该指针类型，而不是被中间某层转成了其他 error（比如 fmt.Errorf("%w", err) 后再包装）。

使用场景：你想判断某个错误是否是自定义类型，或者想提取其中的字段做日志/重试逻辑。

• errors.As(err, &target) 要求 target 是 *CustomError 类型的变量地址，不能传 CustomError{} 或 nil
• errors.Is(err, &CustomError{}) 写法是错的 —— &CustomError{} 是临时指针，类型是 *CustomError，但 errors.Is 比较的是具体值，应该用 errors.Is(err, myErr)，其中 myErr 是包级变量或已构造好的实例
• 性能影响：每次 errors.As 都要反射检查类型，高频路径慎用；可先用 errors.Is 快速判断是否是同一类错误

什么时候该返回 *CustomError，而不是 fmt.Errorf 或 errors.New

核心判断标准：是否需要携带结构化信息（如 code、traceID、重试策略），或是否需要被下游精确识别和处理。纯字符串错误（比如 “file not found”）用 errors.New 更轻量；带上下文的错误链建议用 fmt.Errorf + %w；只有需要下游做类型断言、字段提取、或统一监控上报时，才值得定义 *CustomError。

• 别为了“看起来专业”而堆砌自定义错误 —— 多数 HTTP handler 里 return fmt.Errorf("failed to parse json: %w", err) 就够了
• 如果错误只在本包内使用，且无外部依赖，优先用未导出的 *customError，避免暴露实现细节
• 兼容性注意：Go 1.13+ 的错误链机制对 *CustomError 完全友好，但老版本（%w，此时若用了包装，下游 errors.Unwrap 可能拿不到原始 *CustomError

nil *CustomError 的陷阱：它不是 nil error

这是最常踩的坑：var e *CustomError 是 nil 指针，但把它直接 return，Go 会自动转成 error 接口，此时接口的动态类型是 *CustomError，动态值是 nil —— 所以整个接口不为 nil！if err != nil 判断会失败，但 errors.As(err, &e) 却能成功，只是解出来是 nil 指针。

• 正确写法永远是：return (*CustomError)(nil) 或更清晰地写成 return &CustomError{...} / return nil（当你要返回空 error）
• 构造函数里别写 return &CustomError{} 然后忘记填字段，否则 err.Error() 可能 panic 或返回空字符串
• 测试时别只测 err != nil，还要测 errors.As(err, &e) 后 e 是否非 nil —— 尤其在中间件或封装层

类型断言和错误包装的组合很容易掩盖 nil 指针问题，上线后可能表现为“错误没被正确捕获”或“日志里看不到预期字段”，查起来要翻好几层调用栈。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《CustomError与error对比：Golang错误指针返回实践》文章吧，也可关注golang学习网公众号了解相关技术文章。