Go错误处理与自定义错误类型：工程实践指南

一、Go error接口的设计哲学

Go的错误处理是整个语言设计中最具争议的部分。与Java的try-catch或Rust的Result不同，Go选择将错误视为普通值——一个interface{}，任何类型都可以是错误。这种设计让错误处理极度灵活，也极度容易滥用。

// Go error接口定义（标准库）
type error interface {
    Error() string
}

// 这意味着任何实现了Error() string方法的对象都是合法error：
type MyError struct {
    Msg string
    Code int
}

func (e *MyError) Error() string {
    return fmt.Sprintf("[%d] %s", e.Code, e.Msg)
}

// 优点：自定义错误可以携带任意丰富的信息
// 缺点：Go编译器无法强制检查错误是否被处理（不像Java编译器强制throws）

// 标准库内置的错误包装函数
import "errors"

// errors.New() - 最基础的错误创建方式
var ErrNotFound = errors.New("resource not found")

// errors.Is() - 检查错误链中是否包含指定错误
if errors.Is(err, ErrNotFound) {
    // 安全的错误类型判断
}

// errors.As() - 从错误链中提取具体类型的错误
var e *MyError
if errors.As(err, &e) {
    fmt.Println(e.Code) // 安全地访问MyError的字段
}

1.1 为什么Go不用异常处理错误

Go的错误设计有其深层逻辑：错误是值，值可以传递、处理、组合。异常机制将控制流与错误混在一起，导致"异常吞噬"问题（Java中大量吞掉的异常）和难以追踪的错误来源。Go要求显式处理每一个错误，代价是代码量大，但好处是错误处理路径清晰可见。

二、errors.Is与errors.As：错误链解析

Go 1.13引入的errors.Is和errors.As解决了Go错误处理中最棘手的问题：错误包装后的类型判断。

2.1 错误包装基础

package main

import (
	"errors"
	"fmt"
)

// Go 1.13之前的"类型丢失"问题演示

// 自定义错误类型
type ValidationError struct {
	Field   string
	Message string
}

func (e *ValidationError) Error() string {
	return fmt.Sprintf("validation failed on '%s': %s", e.Field, e.Message)
}

// 旧代码：使用fmt.Sprintf包装错误，丢失了原始类型
func OldStyle() {
	err := &ValidationError{Field: "email", Message: "invalid format"}
	// 旧式包装：类型信息丢失
	wrapped := fmt.Errorf("service layer: %v", err)

	// 旧式类型判断：失败！
	var ve *ValidationError
	if errors.As(wrapped, &ve) { // 居然可以工作！因为fmt.Errorf用%v会调用Error()
		// 但如果wrapped来自第三方库，类型信息就没了
	}
}

// 新式标准：errors.Wrap（Go 1.20+内置）
func NewStyle() {
	err := &ValidationError{Field: "email", Message: "invalid format"}

	// Go 1.20+: errors.Join - 多错误组合
	wrapped := fmt.Errorf("validation failed: %w", err)
	// %w 格式化动词：创建可展开的错误链

	// errors.Is：安全地判断原始错误
	if errors.Is(wrapped, err) {
		fmt.Println("找到了原始错误")
	}

	// errors.As：安全地提取类型
	var ve *ValidationError
	if errors.As(wrapped, &ve) {
		fmt.Printf("字段: %s, 消息: %s\n", ve.Field, ve.Message)
	}
}

2.2 完整错误类型体系

package errtypes

import (
	"errors"
	"fmt"
	"net"
)

// 错误类型层次设计（推荐在项目中使用）

// 顶层接口：定义项目错误能力
type Coder interface {
	Code() int
}

// 错误码定义（业务无关，全系统通用）
const (
	CodeOK           = 0
	CodeNotFound     = 404
	CodeBadRequest   = 400
	CodeUnauthorized = 401
	CodeForbidden    = 403
	CodeInternal     = 500
	CodeTimeout      = 504
)

// 基础错误类型：所有自定义错误的基类
type Error struct {
	Code    int
	Message string
	Err     error   // 底层错误（用于%w包装）
	Meta    map[string]any // 扩展元数据
}

func (e *Error) Error() string {
	if e.Err != nil {
		return fmt.Sprintf("[%d] %s: %v", e.Code, e.Message, e.Err)
	}
	return fmt.Sprintf("[%d] %s", e.Code, e.Message)
}

func (e *Error) Unwrap() error {
	return e.Err
}

func (e *Error) CodeValue() int {
	return e.Code
}

// 实现errors.Coder接口（Go 1.20+）
func (e *Error) Code2() int {
	return e.Code
}

// 工厂函数：创建各类业务错误
var (
	ErrNotFound   = &Error{Code: CodeNotFound, Message: "resource not found"}
	ErrBadRequest = &Error{Code: CodeBadRequest, Message: "bad request"}
)

// 错误创建（推荐使用Option模式）
type Option func(*Error)

func WithMeta(key string, value any) Option {
	return func(e *Error) {
		if e.Meta == nil {
			e.Meta = make(map[string]any)
		}
		e.Meta[key] = value
	}
}

func WithCause(err error) Option {
	return func(e *Error) {
		e.Err = err
	}
}

func NewError(code int, msg string, opts ...Option) *Error {
	e := &Error{Code: code, Message: msg}
	for _, opt := range opts {
		opt(e)
	}
	return e
}

// 常见错误类型
type ValidationErrors []*Error // 批量验证错误

func (ve ValidationErrors) Error() string {
	if len(ve) == 0 {
		return "validation errors: empty"
	}
	msg := "validation errors:\n"
	for _, e := range ve {
		msg += fmt.Sprintf("  - %s\n", e.Error())
	}
	return msg
}

func (ve ValidationErrors) Is(target error) bool {
	// errors.Is(ve, ErrBadRequest) → 检查是否有任意一项匹配
	for _, e := range ve {
		if errors.Is(e, target) {
			return true
		}
	}
	return false
}

// 网络相关错误的特殊处理
type TimeoutError struct {
	Host string
}

func (e *TimeoutError) Error() string {
	return fmt.Sprintf("connection to %s timed out", e.Host)
}

func (e *TimeoutError) Timeout() bool {
	return true
}

// IsTemporary: 临时性错误（可重试）
func (e *TimeoutError) Temporary() bool {
	return true
}

// 简化net.Error接口（网络错误通常附带Temporary/Timeout方法）
var _ net.Error = (*TimeoutError)(nil)

// 错误判断辅助函数
func IsTimeout(err error) bool {
	var ne net.Error
	if errors.As(err, &ne) {
		return ne.Timeout()
	}
	return false
}

func IsTemporary(err error) bool {
	var ne net.Error
	if errors.As(err, &ne) {
		return ne.Temporary()
	}
	return false
}

func IsNotFound(err error) bool {
	var e *Error
	if errors.As(err, &e) {
		return e.Code == CodeNotFound
	}
	return false
}

三、fmt.Errorf与错误包装最佳实践

fmt.Errorf的%w格式化动词是Go 1.13最重要的特性之一，它让错误链可遍历、可分类，是构建良好错误处理体系的基础。

3.1 错误包装的层次设计

package main

import (
	"errors"
	"fmt"
)

// 错误包装的层次原则：每层增加上下文，不丢失底层信息

type User struct {
	ID    int
	Email string
}

// 层级1：底层持久化层
func dbGetUser(id int) (*User, error) {
	// 这里可能发生数据库连接错误、超时、SQL语法错误等
	// 包装：增加"数据库层"上下文
	var connErr *net.DialError
	return nil, fmt.Errorf("db.getUser(%d): %w", id, innerErr)
}

// 层级2：业务服务层
func userServiceGetUser(id int) (*User, error) {
	user, err := dbGetUser(id)
	if err != nil {
		// 业务层增加"用户服务"上下文
		// 注意：%w可以链式使用，错误链不断延伸
		if errors.Is(err, ErrNotFound) {
			return nil, fmt.Errorf("userService.getUser(%d): %w", id, err)
		}
		return nil, fmt.Errorf("userService.getUser(%d): %w", id, err)
	}
	return user, nil
}

// 层级3：API层
func getUserHandler(id int) (*User, error) {
	user, err := userServiceGetUser(id)
	if err != nil {
		// API层增加路由信息
		// 只包装不处理具体逻辑，向上传递
		return nil, fmt.Errorf("GET /users/%d: %w", id, err)
	}
	return user, nil
}

// 最顶层：统一错误处理
func handleError(err error) {
	// 一次性遍历整个错误链，不重复判断
	var e *Error
	if errors.As(err, &e) {
		switch e.Code {
		case CodeNotFound:
			// 404处理
		case CodeBadRequest:
			// 400处理
		case CodeInternal:
			// 500处理，记录详细日志
			// log.Error(err) // 记录完整错误链
		}
	}
}

// Go 1.20+: errors.Join - 组合多个错误
func batchOperation() error {
	var errs []error
	for _, item := range items {
		if err := process(item); err != nil {
			errs = append(errs, err)
		}
	}
	if len(errs) > 0 {
		// errors.Join会创建一个组合错误，支持errors.Is/As
		return fmt.Errorf("batch operation failed: %w", errors.Join(errs...))
	}
	return nil
}

import "net"

3.2 panic/recover vs error的选择

package main

import "errors"

// Go的错误处理原则：区分"预期错误"和"程序错误"

var ErrInvalidInput = errors.New("invalid input")

// 预期错误 → 返回error
func divide(a, b float64) (float64, error) {
	if b == 0 {
		return 0, fmt.Errorf("divide by zero: %w", ErrInvalidInput)
	}
	return a / b, nil
}

// 程序错误（不应该发生的内部状态）→ panic
func criticalSection() {
	// 这里如果执行到，说明代码有严重bug，不是业务层面的问题
	// panic会导致整个goroutine崩溃，在web服务中通常被recover拦截
	if config == nil {
		panic("BUG: config must not be nil - this is a programming error")
	}
}

// 推荐的panic/recover使用场景：
// 1. 不可恢复的初始化错误（main函数中初始化失败）
// 2. 测试中的断言失败（t.Fatal等）
// 3. 不应该发生的"不可能"状态（合约违反）
// 4. 第三方库bug（无法处理的极端情况）

// panic应该被recover捕获，不应该传播到goroutine顶层
import "fmt"

func safeCall(fn func() error) (err error) {
	defer func() {
		if r := recover(); r != nil {
			// 把panic转换为error，防止goroutine崩溃
			err = fmt.Errorf("panic recovered: %v", r)
		}
	}()
	return fn()
}

// defer + panic/recover是Go实现"类try-catch"的唯一方式
// 但推荐只在边界层使用，内部逻辑应该用error

四、gRPC状态码与错误处理集成

在gRPC微服务架构中，错误需要跨越进程边界传播。gRPC有自己独立的错误模型，需要与Go error体系做映射。

4.1 gRPC状态码映射

package grpcerr

import (
	"errors"
	"fmt"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"
)

// gRPC状态码 → HTTP状态码对照
/*
  OK                  → 200
  CANCELLED           → 499 (Client Closed Request)
  UNKNOWN             → 500
  INVALID_ARGUMENT    → 400
  DEADLINE_EXCEEDED   → 504
  NOT_FOUND           → 404
  ALREADY_EXISTS      → 409
  PERMISSION_DENIED   → 403
  RESOURCE_EXHAUSTED  → 429
  FAILED_PRECONDITION → 400
  ABORTED             → 409
  OUT_OF_RANGE        → 400
  UNIMPLEMENTED       → 501
  INTERNAL            → 500
  UNAVAILABLE         → 503
  DATA_LOSS           → 500
  UNAUTHENTICATED     → 401
*/

// 工具函数：将Go error转换为gRPC status
func ToGRPCStatus(err error) *status.Status {
	// 优先检查是否已经是gRPC status
	st, ok := status.FromError(err)
	if ok {
		return st
	}

	// 从自定义错误推断状态码
	var e *Error
	if errors.As(err, &e) {
		switch e.Code {
		case CodeNotFound:
			return status.New(codes.NotFound, e.Message)
		case CodeBadRequest:
			return status.New(codes.InvalidArgument, e.Message)
		case CodeUnauthorized:
			return status.New(codes.Unauthenticated, e.Message)
		case CodeForbidden:
			return status.New(codes.PermissionDenied, e.Message)
		case CodeTimeout:
			return status.New(codes.DeadlineExceeded, e.Message)
		case CodeInternal:
			return status.New(codes.Internal, e.Message)
		default:
			return status.New(codes.Unknown, e.Message)
		}
	}

	// 兜底：未知错误
	return status.New(codes.Unknown, err.Error())
}

// 工具函数：从gRPC status恢复Go error
func FromGRPCStatus(st *status.Status) error {
	return st.Err()
}

// 业务层示例：在service方法中使用
func (s *UserService) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
	user, err := s.repo.FindByID(req.Id)
	if err != nil {
		// 错误已经在repo层正确包装，这里直接转换
		return nil, ToGRPCStatus(err).Err()
	}
	return toPBUser(user), nil
}

// gRPC metadata传递详细错误信息
func WithDetails(err error, details ...any) error {
	st := ToGRPCStatus(err)
	// 可以向metadata中注入额外信息
	// 注意：gRPC标准错误格式是status+details(google.protobuf.Any)
	return st.Err()
}

4.2 gRPC错误传播中间件

package grpcserver

import (
	"context"
	"log"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/status"
)

// gRPC unary interceptor - 统一错误处理中间件
func ErrorHandlingUnaryInterceptor() grpc.UnaryServerInterceptor {
	return func(ctx context.Context, req any, info *grpc.UnaryServerInfo,
		handler grpc.UnaryHandler) (resp any, err error) {

		start := time.Now()

		// 执行实际处理逻辑
		resp, err = handler(ctx, req)

		// 统一错误日志和转换
		if err != nil {
			// 非业务错误（系统异常）才记录日志
			st, ok := status.FromError(err)
			if ok && isServerError(st.Code()) {
				log.Printf("[ERROR] gRPC %s: %v (duration=%v)",
					info.FullMethod, err, time.Since(start))
			}

			// 不要在中间件中修改err类型，只在业务层做包装
			// 这里的err已经是转换后的gRPC status
		}

		return resp, err
	}
}

func isServerError(code codes.Code) bool {
	// 只对服务器端错误记录详细日志
	return code == codes.Internal ||
		code == codes.Unavailable ||
		code == codes.ResourceExhausted
}

// gRPC流式拦截器 - 同样需要处理错误
func ErrorHandlingStreamInterceptor() grpc.StreamServerInterceptor {
	return func(srv any, ss grpc.ServerStream,
		info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {

		// 流式处理也需要recover保护
		err := func() (err error) {
			defer func() {
				if r := recover(); r != nil {
					err = status.Errorf(codes.Internal, "panic recovered: %v", r)
				}
			}()
			return handler(srv, ss)
		}()

		if err != nil {
			// 流式错误处理特殊：无法修改返回的error
			// 只能记录日志
			log.Printf("[ERROR] stream gRPC %s: %v", info.FullMethod, err)
		}
		return err
	}
}

// 服务器启动配置
func newGRPCServer() *grpc.Server {
	opts := []grpc.ServerOption{
		grpc.UnaryInterceptor(ErrorHandlingUnaryInterceptor()),
		grpc.StreamInterceptor(ErrorHandlingStreamInterceptor()),
	}
	return grpc.NewServer(opts...)
}

// 客户端错误处理：自动重试临时错误
func clientWithRetry(ctx context.Context, client pb.UserServiceClient, userID int64) (*pb.User, error) {
	// gRPC客户端根据状态码自动重试
	// UNAVAILABLE、RESOURCE_EXHAUSTED通常可重试
	// 注意：这需要配合gRPC retry policy配置

	for attempt := 0; attempt < 3; attempt++ {
		user, err := client.GetUser(ctx, &pb.GetUserRequest{Id: userID})
		if err == nil {
			return user, nil
		}

		st, ok := status.FromError(err)
		if !ok || !isRetryable(st.Code()) {
			return nil, err // 非重试错误，直接返回
		}

		// 指数退避
		select {
		case <-ctx.Done():
			return nil, ctx.Err()
		case <-time.After(time.Duration(1<