在Go语言里，错误处理贯穿了几乎所有函数的返回值设计。很多初学者习惯用errors.New或fmt.Errorf生成一句文本就往上抛，但当系统变复杂后，调用方往往难以判断这个错误到底是网络断了、参数非法还是数据库超时。Go的error本质上是一个内建接口，只要类型实现了Error() string方法就能成为错误。利用这一点，我们可以定义自己的结构体，把错误码、上下文信息和方法行为都装进去，从而让错误处理从“看字符串猜原因”升级为“按类型做分支”。
理解error接口与自定义类型的底层约定
Go中的error接口定义非常精简，仅包含一个方法：Error() string。这意味着任何拥有了该方法的类型，都能赋值给error变量。标准库的errors.New返回的是*errors.errorString结构体，它内部只有一个字符串字段，并在Error方法中原样返回。这种实现简单却缺乏扩展能力，因为调用方拿到错误后除了读文本外，无法获取结构化字段。
当我们定义自定义错误类型时，实际上是创建了一个普通的结构体，并为其绑定Error方法。由于方法接收者可以是值或指针，通常建议使用指针接收者，这样在传递大结构体或需要修改内部状态时更安全。只要该结构体实现了接口，编译器就会把它当作error使用，函数签名依旧写成返回error，对上层完全兼容。
底层上，接口变量由“类型信息”和“数据指针”两部分组成。当把自定义结构体赋给error接口时，接口内部记录了真实类型。调用方通过类型断言（如e.(*MyError)）或errors.As就能还原出原类型，从而访问其中的字段。这种机制让错误从扁平文本变成了可查询的对象，是构建大型系统错误体系的基石。
用结构体实现带字段的自定义错误
最常见的做法是定义一个结构体，包含错误码、消息以及发生时间等字段，然后实现Error方法拼接输出。下面示例展示了一个业务错误类型，它能够区分不同错误码，并携带用户ID等上下文：
package main
import (
"fmt"
"time"
)
// 定义错误码常量
type ErrCode int
const (
ErrInvalidParam ErrCode = 1001
ErrTimeout ErrCode = 1002
)
// 自定义错误结构体
type BizError struct {
Code ErrCode
Msg string
UserID int64
Time time.Time
}
// 实现error接口
func (e *BizError) Error() string {
return fmt.Sprintf("[code:%d] %s (user:%d at %s)", e.Code, e.Msg, e.UserID, e.Time.Format("15:04:05"))
}
// 构造函数
func NewBizError(code ErrCode, msg string, uid int64) *BizError {
return &BizError{
Code: code,
Msg: msg,
UserID: uid,
Time: time.Now(),
}
}
func doWork(uid int64) error {
if uid <= 0 {
return NewBizError(ErrInvalidParam, "用户ID非法", uid)
}
return nil
}
func main() {
err := doWork(0)
if err != nil {
// 类型断言获取详细字段
if be, ok := err.(*BizError); ok {
fmt.Println("错误码:", be.Code)
}
fmt.Println(err)
}
}
上面的代码中，BizError通过指针接收者实现接口，构造函数统一初始化时间字段。调用方在main里使用类型断言拿到具体结构体，就能基于Code做分支处理，而不是用字符串包含判断。这种方式在API层尤其有用，比如把ErrInvalidParam映射为HTTP 400，把ErrTimeout映射为502。
相比只用fmt.Errorf，结构体方案的优势是字段明确、易于测试。单元测试中可以直接比较错误码而不依赖文案；日志系统也能稳定提取UserID做告警分组。缺点是如果错误类型过多，需要写较多样板代码，此时可以结合代码生成或减少字段数量来平衡。
错误包装、类型判断与最佳实践
Go 1.13之后引入了errors.Is和errors.As，让自定义错误可以嵌套底层错误而不丢失类型。我们可以在结构体里加一个Err error字段，在Error方法中把底层信息一并输出，同时实现Unwrap() error方法以支持链式的errors.Is判断。
package main
import (
"errors"
"fmt"
)
type WrapError struct {
Msg string
Err error
}
func (w *WrapError) Error() string {
if w.Err != nil {
return w.Msg + ": " + w.Err.Error()
}
return w.Msg
}
func (w *WrapError) Unwrap() error {
return w.Err
}
var baseErr = errors.New("连接被拒绝")
func main() {
we := &WrapError{Msg: "调用下游服务失败", Err: baseErr}
// 使用errors.Is沿链判断
if errors.Is(we, baseErr) {
fmt.Println("根因是连接被拒绝")
}
}
在真实项目中，建议把错误码统一定义在独立包中，避免魔法数字散落。同时为高频错误提供构造函数或哨兵变量，减少重复。对于需要跨服务传递的错误，可考虑把Code转成字符串或JSON，在网关层做翻译，这样内部细节不会直接暴露给终端用户。
另一个实践是不要在自定义错误的Error方法里做耗时操作，比如网络请求或锁竞争，因为该方法可能在日志打印、监控采集时被高频调用。保持它纯字符串拼接最安全。如果业务需要行为方法，如IsTimeout() bool，应单独定义接口并由自定义类型实现，调用方用类型断言或errors.As获取后调用，而不是直接在Error里隐含逻辑。
最后，自定义错误类型虽好，也不要滥用。对于纯粹的一次性非法状态，直接用errors.New即可；只有那些调用方确实需要区分、需要附加上下文、或需要统一转换协议的场景，才值得为之定义结构体。把握好这个度，能让代码既清晰又不冗余。