Golang自定义error设计步骤详解

自定义错误类型通过实现error接口来封装业务语义，常用结构体携带Code、Message等字段，并提供构造函数以增强封装性；在业务逻辑中返回具体错误，在调用端使用errors.As或errors.Is进行类型判断与针对性处理；还可为错误类型添加StatusCode等扩展方法以支持HTTP状态映射，提升错误处理的可读性与一致性。

在 Go 语言中，错误处理是通过返回 error 类型值来实现的。为了更好地表达业务语义、提高可读性和便于错误判断，我们常常需要为自定义业务逻辑设计专用的错误类型。以下是定义和使用自定义 error 的标准步骤与实践方式。

1. 定义自定义错误类型

你可以通过实现 error 接口（即定义一个带有 Error() string 方法的类型）来自定义错误。最常见的方式是定义一个结构体或字符串类型。

type BusinessError struct {
    Code    string
    Message string
    Field   string // 可选：用于表示出错字段
}

func (e *BusinessError) Error() string {
    return fmt.Sprintf("[%s] %s (field: %s)", e.Code, e.Message, e.Field)
}

type ValidationError string

func (e ValidationError) Error() string {
    return string(e)
}

2. 提供构造函数创建错误实例

避免直接暴露结构体字段，建议提供工厂函数来创建错误实例，提升封装性与可维护性。

func NewValidationError(field string, msg string) *BusinessError {
    return &BusinessError{
        Code:    "VALIDATION_ERROR",
        Message: msg,
        Field:   field,
    }
}

func NewAuthorizationError() error {
    return &BusinessError{
        Code:    "AUTH_ERROR",
        Message: "用户无权限操作",
    }
}

3. 在业务逻辑中返回自定义错误

在具体的业务函数中根据条件返回你定义好的错误类型。

func CreateUser(username string) error {
    if username == "" {
        return NewValidationError("username", "用户名不能为空")
    }
    // 其他逻辑...
    return nil
}

4. 调用端识别并处理特定错误

使用 errors.As 或 errors.Is 来判断是否为某种自定义错误，从而进行针对性处理。

err := CreateUser("")
if err != nil {
    var busiErr *BusinessError
    if errors.As(err, &busiErr) {
        log.Printf("业务错误：%v", busiErr)
        if busiErr.Code == "VALIDATION_ERROR" {
            // 返回前端友好的提示
            respondWithError(http.StatusBadRequest, busiErr.Message)
        }
    } else {
        // 处理其他系统级错误
        log.Printf("未知错误：%v", err)
    }
}

注意：errors.Is 适用于判断是否是某个具体错误值（如用 var ErrNotFound = errors.New("not found") 定义），而 errors.As 用于判断是否能转换为某一错误类型。

5. （可选）扩展错误行为：添加额外方法

结构体形式的错误可以拥有更多方法，比如获取 HTTP 状态码、序列化成 JSON 等。

func (e *BusinessError) StatusCode() int {
    switch e.Code {
    case "AUTH_ERROR":
        return http.StatusForbidden
    case "VALIDATION_ERROR":
        return http.StatusBadRequest
    default:
        return http.StatusInternalServerError
    }
}

这样在中间件中可以直接调用 err.(interface{ StatusCode() int }).StatusCode() 来动态设置响应状态码。

基本上就这些。Go 的自定义 error 设计核心在于“清晰表达业务含义”和“便于调用方判断处理”。合理使用结构体 + 构造函数 + errors 包工具链，能让错误处理更可控、更专业。不复杂但容易忽略的是错误类型的可扩展性和一致性命名。