1
type error interface {
2
    Error() string
3
}

1
// src/errors/errors.go — https://github.com/golang/go/blob/go1.25.0/src/errors/errors.go
2
type errorString struct {
3
    s string
4
}
5

6
func (e *errorString) Error() string {
7
    return e.s
8
}

1
func divide(a, b int) (int, error) {
2
    if b == 0 {
3
        return 0, errors.New("division by zero")
4
    }
5
    return a / b, nil
6
}

1
func openConfig(path string) (*os.File, error) {
2
    f, err := os.Open(path)
3
    if err != nil {
4
        return nil, fmt.Errorf("failed to open config file %q: %w", path, err)
5
    }
6
    return f, nil
7
}

1
// 业务错误码
2
type ErrorCode int
3

4
const (
5
    ErrNotFound ErrorCode = iota + 1
6
    ErrUnauthorized
7
    ErrInvalidInput
8
)
9

10
// 自定义错误类型
11
type BusinessError struct {
12
    Code    ErrorCode
13
    Message string
14
    Cause   error // 原始错误
15
}
16

17
func (e *BusinessError) Error() string {
18
    if e.Cause != nil {
19
        return fmt.Sprintf("[%d] %s: %v", e.Code, e.Message, e.Cause)
20
    }
21
    return fmt.Sprintf("[%d] %s", e.Code, e.Message)
22
}
23

24
// 实现 Unwrap 方法，支持 errors.Is/As
25
func (e *BusinessError) Unwrap() error {
26
    return e.Cause
27
}
28

29
// 工厂函数
30
func NewNotFoundError(resource string, cause error) error {
31
    return &BusinessError{
32
        Code:    ErrNotFound,
33
        Message: fmt.Sprintf("%s not found", resource),
34
        Cause:   cause,
35
    }
36
}

1
// 好的做法：提供有意义的错误信息
2
type ValidationError struct {
3
    Field   string
4
    Value   any
5
    Message string
6
}
7

8
func (e *ValidationError) Error() string {
9
    return fmt.Sprintf("validation failed on field %q: %s (got %v)",
10
        e.Field, e.Message, e.Value)
11
}
12

13
// 提供类型断言方法（避免导出内部字段）
14
func IsValidationError(err error) bool {
15
    var ve *ValidationError
16
    return errors.As(err, &ve)
17
}
18

19
// 实现 Is 方法，支持自定义相等语义
20
func (e *ValidationError) Is(target error) bool {
21
    t, ok := target.(*ValidationError)
22
    if !ok {
23
        return false
24
    }
25
    return e.Field == t.Field
26
}

1
func processOrder(orderID string) error {
2
    order, err := fetchOrder(orderID)
3
    if err != nil {
4
        return fmt.Errorf("failed to process order %s: %w", orderID, err)
5
    }
6
    // ...
7
    return nil
8
}
9

10
func fetchOrder(orderID string) (*Order, error) {
11
    row := db.QueryRow("SELECT * FROM orders WHERE id = ?", orderID)
12
    var order Order
13
    if err := row.Scan(&order); err != nil {
14
        return fmt.Errorf("failed to fetch order: %w", err)
15
    }
16
    return &order, nil
17
}

1
// errors.Is：检查错误链中是否包含特定错误值
2
if errors.Is(err, sql.ErrNoRows) {
3
    // 处理"记录不存在"的情况
4
}
5

6
// errors.As：提取错误链中特定类型的错误
7
var berr *BusinessError
8
if errors.As(err, &berr) {
9
    // 根据 ErrorCode 进行不同处理
10
    switch berr.Code {
11
    case ErrNotFound:
12
        // ...
13
    case ErrUnauthorized:
14
        // ...
15
    }
16
}

1
func validateUser(user *User) error {
2
    var errs []error
3

4
    if user.Name == "" {
5
        errs = append(errs, errors.New("name is required"))
6
    }
7
    if user.Email == "" {
8
        errs = append(errs, errors.New("email is required"))
9
    }
10
    if user.Age < 0 {
11
        errs = append(errs, errors.New("age must be positive"))
12
    }
13

14
    return errors.Join(errs...)
15
}
16

17
// 使用
18
if err := validateUser(user); err != nil {
19
    // err.Error() 会返回所有错误的组合信息
20
    fmt.Println(err)
21
    // Output: name is required
22
    //         email is required
23

24
    // 注意：errors.Is 比较的是错误值（指针），不是错误消息
25
    // 必须使用哨兵错误变量，而非 errors.New() 直接构造
26
    // 因为 errors.New() 每次返回不同的指针，errors.Is 永远为 false
27
    var ErrNameRequired = errors.New("name is required")
28
    if errors.Is(err, ErrNameRequired) {
29
        // ...
30
    }
31
}

1
// 标准库中的哨兵错误
2
var (
3
    ErrUnsupported = errors.New("unsupported operation")
4
    ErrNotExist    = errors.New("does not exist")
5
    ErrExist       = errors.New("already exists")
6
)

1
// 定义
2
var (
3
    ErrUserNotFound    = errors.New("user not found")
4
    ErrUserDisabled    = errors.New("user is disabled")
5
    ErrInvalidPassword = errors.New("invalid password")
6
)
7

8
// 使用
9
func authenticate(username, password string) error {
10
    user, err := getUser(username)
11
    if err != nil {
12
        return fmt.Errorf("authentication failed: %w", err)
13
    }
14

15
    if user.Status == "disabled" {
16
        return fmt.Errorf("authentication failed: %w", ErrUserDisabled)
17
    }
18

19
    if !verifyPassword(user.PasswordHash, password) {
20
        return fmt.Errorf("authentication failed: %w", ErrInvalidPassword)
21
    }
22

23
    return nil
24
}
25

26
// 调用方
27
err := authenticate("alice", "password123")
28
if errors.Is(err, ErrUserNotFound) {
29
    // 用户不存在
30
} else if errors.Is(err, ErrUserDisabled) {
31
    // 用户被禁用
32
} else if errors.Is(err, ErrInvalidPassword) {
33
    // 密码错误
34
}

1
type wrappedError struct {
2
    msg string
3
    err error
4
}
5

6
func (e *wrappedError) Error() string {
7
    return e.msg + ": " + e.err.Error()
8
}
9

10
func (e *wrappedError) Unwrap() error {
11
    return e.err
12
}

1
func printErrorChain(err error) {
2
    for err != nil {
3
        fmt.Println("-", err.Error())
4
        err = errors.Unwrap(err)
5
    }
6
}

1
type DetailedError struct {
2
    Op      string // 操作名称
3
    Path    string // 相关路径
4
    Err     error  // 原始错误
5
}
6

7
func (e *DetailedError) Error() string {
8
    return fmt.Sprintf("%s %s: %v", e.Op, e.Path, e.Err)
9
}
10

11
func (e *DetailedError) Unwrap() error {
12
    return e.Err
13
}

1
// 每一层只添加最相关的上下文
2
func handleRequest(w http.ResponseWriter, r *http.Request) {
3
    data, err := fetchUserData(r.Context(), userID)
4
    if err != nil {
5
        // 只添加请求级别的上下文
6
        err = fmt.Errorf("handling request for user %s: %w", userID, err)
7
        handleError(w, err)
8
        return
9
    }
10
    // ...
11
}
12

13
func fetchUserData(ctx context.Context, userID string) (*UserData, error) {
14
    user, err := db.GetUser(ctx, userID)
15
    if err != nil {
16
        // 只添加数据访问级别的上下文
17
        return nil, fmt.Errorf("fetching user from database: %w", err)
18
    }
19
    // ...
20
}
21

22
// 避免在每一层都重复相同的上下文
23
func badExample() error {
24
    err := doSomething()
25
    if err != nil {
26
        // 这里的"user foo"和下面的"user foo"重复了
27
        return fmt.Errorf("processing user foo: %w", err)
28
    }
29
    // ...
30
}

1
func example() (err error) {
2
    defer func() {
3
        if r := recover(); r != nil {
4
            // 将 panic 转换为 error
5
            err = fmt.Errorf("panic recovered: %v", r)
6
            // 打印堆栈以便调试
7
            debug.PrintStack()
8
        }
9
    }()
10

11
    // 可能 panic 的代码
12
    riskyOperation()
13
    return nil
14
}

1
// 1. 不可能的条件（程序错误）
2
func MustCompile(pattern string) *Regexp {
3
    re, err := Compile(pattern)
4
    if err != nil {
5
        panic(`regexp: Compile(` + quote(pattern) + `): ` + err.Error())
6
    }
7
    return re
8
}
9

10
// 2. 初始化失败
11
func init() {
12
    if os.Getenv("REQUIRED_VAR") == "" {
13
        panic("REQUIRED_VAR environment variable is required")
14
    }
15
}

1
// 1. HTTP 服务器的错误隔离
2
func middleware(next http.Handler) http.Handler {
3
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
4
        defer func() {
5
            if err := recover(); err != nil {
6
                log.Printf("panic recovered: %v", err)
7
                http.Error(w, "Internal Server Error", 500)
8
            }
9
        }()
10
        next.ServeHTTP(w, r)
11
    })
12
}
13

14
// 2. goroutine 隔离
15
func safeGo(fn func() error) <-chan error {
16
    errCh := make(chan error, 1)
17
    go func() {
18
        defer func() {
19
            if r := recover(); r != nil {
20
                errCh <- fmt.Errorf("panic: %v", r)
21
            }
22
        }()
23
        errCh <- fn()
24
    }()
25
    return errCh
26
}

1
// 不要用 panic 做常规错误处理
2
func badExample(path string) error {
3
    if !fileExists(path) {
4
        panic("file not found") // 错误！应该返回 error
5
    }
6
    return nil
7
}
8

9
// 正确做法
10
func goodExample(path string) error {
11
    if !fileExists(path) {
12
        return os.ErrNotExist
13
    }
14
    return nil
15
}

1
// 错误示范：每一层都记录
2
func service() error {
3
    if err := repo(); err != nil {
4
        log.Printf("service error: %v", err) // 第一次记录
5
        return err
6
    }
7
    return nil
8
}
9

10
func repo() error {
11
    if err := db(); err != nil {
12
        log.Printf("repo error: %v", err) // 第二次记录
13
        return err
14
    }
15
    return nil
16
}
17

18
// 正确做法：只在最外层记录
19
func handler(w http.ResponseWriter, r *http.Request) {
20
    if err := service(); err != nil {
21
        log.Printf("request failed: %v", err) // 唯一记录点
22
        http.Error(w, "internal error", 500)
23
    }
24
}
25

26
func service() error {
27
    return repo() // 只传递，不记录
28
}

1
import "log/slog"
2

3
func processOrder(ctx context.Context, orderID string) error {
4
    order, err := fetchOrder(ctx, orderID)
5
    if err != nil {
6
        // 包含完整的上下文信息
7
        slog.Error("failed to process order",
8
            "order_id", orderID,
9
            "error", err,
10
            "trace_id", traceIDFromContext(ctx),
11
        )
12
        return err
13
    }
14
    return nil
15
}

1
type ErrorWithCode struct {
2
    Code    string
3
    Message string
4
    Err     error
5
}
6

7
func (e *ErrorWithCode) Error() string {
8
    return e.Message
9
}
10

11
func (e *ErrorWithCode) Unwrap() error {
12
    return e.Err
13
}
14

15
// 记录时提取错误码用于监控
16
func logError(err error) {
17
    var e *ErrorWithCode
18
    code := "UNKNOWN"
19
    if errors.As(err, &e) {
20
        code = e.Code
21
    }
22

23
    metrics.Counter("errors").WithLabelValues(code).Inc()
24
    slog.Error("error occurred", "code", code, "error", err)
25
}

1
import "github.com/pkg/errors"
2

3
func main() {
4
    err := readFile("config.json")
5
    if err != nil {
6
        // 打印带堆栈的错误
7
        fmt.Printf("%+v\n", err)
8
    }
9
}
10

11
func readFile(path string) error {
12
    _, err := os.ReadFile(path)
13
    if err != nil {
14
        // 自动捕获调用堆栈
15
        return errors.Wrap(err, "failed to read config")
16
    }
17
    return nil
18
}

1
// 错误包装
2
err = fmt.Errorf("context: %w", err)
3

4
// 多错误合并
5
err = errors.Join(err1, err2, err3)
6

7
// 错误检查
8
errors.Is(err, target)
9
errors.As(err, &target)
10

11
// 遍历错误链
12
errors.Unwrap(err)

1
func CreateUser(name, email string, age int) (*User, error) {
2
    // 在操作前验证所有输入
3
    if name == "" {
4
        return nil, &ValidationError{
5
            Field:   "name",
6
            Message: "name is required",
7
        }
8
    }
9
    if !isValidEmail(email) {
10
        return nil, &ValidationError{
11
            Field:   "email",
12
            Message: "invalid email format",
13
        }
14
    }
15
    if age < 0 || age > 150 {
16
        return nil, &ValidationError{
17
            Field:   "age",
18
            Message: "age must be between 0 and 150",
19
        }
20
    }
21

22
    // 通过验证，执行创建
23
    return &User{Name: name, Email: email, Age: age}, nil
24
}

1
// 模式 1：立即返回
2
func pattern1() error {
3
    if err := step1(); err != nil {
4
        return err
5
    }
6
    if err := step2(); err != nil {
7
        return err
8
    }
9
    return nil
10
}
11

12
// 模式 2：延迟清理
13
func pattern2(path string) (err error) {
14
    f, err := os.Create(path)
15
    if err != nil {
16
        return err
17
    }
18
    defer func() {
19
        if cerr := f.Close(); cerr != nil && err == nil {
20
            err = cerr
21
        }
22
    }()
23

24
    // 使用 f...
25
    return nil
26
}
27

28
// 模式 3：错误分组（Go 1.20+）
29
func pattern3(ctx context.Context) error {
30
    var g errgroup.Group
31

32
    g.Go(func() error { return task1(ctx) })
33
    g.Go(func() error { return task2(ctx) })
34

35
    return g.Wait()
36
}

1
func processFile(path string) error {
2
    f, err := os.Open(path)
3
    if err != nil {
4
        return fmt.Errorf("open file: %w", err)
5
    }
6
    defer f.Close()
7

8
    scanner := bufio.NewScanner(f)
9
    for scanner.Scan() {
10
        // 处理每一行
11
        if err := processLine(scanner.Text()); err != nil {
12
            // 即使出错，defer 也会确保文件关闭
13
            return fmt.Errorf("process line: %w", err)
14
        }
15
    }
16

17
    if err := scanner.Err(); err != nil {
18
        return fmt.Errorf("scan file: %w", err)
19
    }
20

21
    return nil
22
}

1
// 错误定义（internal/errors/errors.go）
2
type AppError struct {
3
    Code       string
4
    HTTPStatus int
5
    Message    string
6
    Err        error
7
}
8

9
func (e *AppError) Error() string {
10
    return e.Message
11
}
12

13
func (e *AppError) Unwrap() error {
14
    return e.Err
15
}
16

17
// 预定义错误
18
var (
19
    ErrNotFound = &AppError{
20
        Code:       "NOT_FOUND",
21
        HTTPStatus: http.StatusNotFound,
22
        Message:    "resource not found",
23
    }
24
    ErrUnauthorized = &AppError{
25
        Code:       "UNAUTHORIZED",
26
        HTTPStatus: http.StatusUnauthorized,
27
        Message:    "unauthorized",
28
    }
29
)
30

31
// Repository 层
32
func (r *userRepository) GetByID(ctx context.Context, id string) (*User, error) {
33
    var user User
34
    err := r.db.GetContext(ctx, &user, "SELECT * FROM users WHERE id = ?", id)
35
    if err != nil {
36
        if errors.Is(err, sql.ErrNoRows) {
37
            return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
38
        }
39
        return nil, fmt.Errorf("query user: %w", err)
40
    }
41
    return &user, nil
42
}
43

44
// Service 层
45
func (s *userService) GetProfile(ctx context.Context, userID string) (*Profile, error) {
46
    user, err := s.repo.GetByID(ctx, userID)
47
    if err != nil {
48
        return nil, err // 直接传递，不重复包装
49
    }
50

51
    // 业务逻辑...
52
    return &Profile{User: user}, nil
53
}
54

55
// Handler 层
56
func (h *handler) GetProfile(w http.ResponseWriter, r *http.Request) {
57
    userID := chi.URLParam(r, "userID")
58

59
    profile, err := h.service.GetProfile(r.Context(), userID)
60
    if err != nil {
61
        respondWithError(w, err)
62
        return
63
    }
64

65
    respondJSON(w, http.StatusOK, profile)
66
}
67

68
// 统一错误响应
69
func respondWithError(w http.ResponseWriter, err error) {
70
    var appErr *AppError
71
    if errors.As(err, &appErr) {
72
        respondJSON(w, appErr.HTTPStatus, ErrorResponse{
73
            Code:    appErr.Code,
74
            Message: appErr.Message,
75
        })
76
        return
77
    }
78

79
    // 未知错误，返回 500
80
    slog.Error("internal error", "error", err)
81
    respondJSON(w, http.StatusInternalServerError, ErrorResponse{
82
        Code:    "INTERNAL_ERROR",
83
        Message: "an internal error occurred",
84
    })
85
}

1
// 错误：忽略错误
2
func bad() {
3
    _, _ = os.Open("file.txt") // 忽略错误
4
}
5

6
// 错误：记录但不返回
7
func alsoBad() error {
8
    if err := doSomething(); err != nil {
9
        log.Printf("error: %v", err) // 只记录不返回
10
        // 继续执行...
11
    }
12
    return nil
13
}
14

15
// 正确：处理并返回
16
func good() error {
17
    if err := doSomething(); err != nil {
18
        return fmt.Errorf("do something: %w", err)
19
    }
20
    return nil
21
}

1
// 每一层都添加相似的信息
2
func bad() error {
3
    if err := service(); err != nil {
4
        return fmt.Errorf("failed to process order: %w", err)
5
    }
6
    return nil
7
}
8

9
func service() error {
10
    if err := repo(); err != nil {
11
        return fmt.Errorf("failed to process order: %w", err) // 重复！
12
    }
13
    return nil
14
}

1
// 错误
2
func validate(input string) {
3
    if input == "" {
4
        panic("input is empty")
5
    }
6
}
7

8
// 正确
9
func validate(input string) error {
10
    if input == "" {
11
        return errors.New("input is empty")
12
    }
13
    return nil
14
}

1
// 1. 错误只传递不处理，在最外层统一处理
2
// 2. 每层只添加自己层级的上下文
3
// 3. 使用 errors.Is/As 而非 == 比较
4
// 4. 结构化日志，包含 trace_id 等上下文
5
// 5. 区分可恢复错误和不可恢复错误

1
需要处理错误？
2
├── 能处理 → 处理并返回 nil 或新错误
3
├── 需要添加上下文 → fmt.Errorf("context: %w", err)
4
└── 不能处理 → 直接返回 err