Lỗi trong Golang: wrap, errors.Is, errors.As, kiểu lỗi riêng

Ba loại lỗi

Code Go dùng ba dạng lỗi (error), từ đơn giản nhất đến phong phú nhất:

1. Lỗi tạm thời: errors.New("...") hoặc fmt.Errorf("...") tạo ngay tại chỗ. Bên gọi chỉ đọc được thông điệp.
2. Sentinel error: một biến ở cấp package như io.EOF. Bên gọi có thể kiểm tra nó bằng errors.Is.
3. Kiểu lỗi: một struct có phương thức Error(), mang theo các trường. Bên gọi có thể lấy nó ra bằng errors.As và đọc các trường.

Hãy chọn dạng đơn giản nhất mà vẫn cho bên gọi làm được điều họ cần.

Sentinel error

Sentinel là một giá trị lỗi được khai báo một lần và so sánh theo danh tính. Theo quy ước, tên bắt đầu bằng Err.

package main

import (
	"errors"
	"fmt"
)

var (
	ErrNotFound   = errors.New("not found")
	ErrOutOfStock = errors.New("out of stock")
)

var stock = map[string]int{"mug": 3, "cap": 0}

func buy(item string) error {
	n, ok := stock[item]
	if !ok {
		return fmt.Errorf("buy %q: %w", item, ErrNotFound)
	}
	if n == 0 {
		return fmt.Errorf("buy %q: %w", item, ErrOutOfStock)
	}
	stock[item]--
	return nil
}

func main() {
	for _, item := range []string{"mug", "cap", "hat"} {
		err := buy(item)
		switch {
		case err == nil:
			fmt.Println(item, "bought")
		case errors.Is(err, ErrOutOfStock):
			fmt.Println(item, "is out of stock, notify me later")
		case errors.Is(err, ErrNotFound):
			fmt.Println(err)
		}
	}
}

Đầu ra:

mug bought
cap is out of stock, notify me later
buy "hat": not found

Hai lời gọi errors.New với cùng nội dung tạo ra hai lỗi khác nhau: errors.New("x") == errors.New("x") là false. Đó là lý do sentinel phải là một biến duy nhất được dùng chung.

Sentinel trở thành một phần API của package. Khi bên gọi đã kiểm tra ErrNotFound, bạn không thể ngừng trả về nó mà không làm hỏng code của họ. Chỉ export những sentinel mà bên gọi thật sự cần để rẽ nhánh.

Kiểu lỗi tùy chỉnh

Khi bên gọi cần chi tiết (trường nào, mã trạng thái nào, thời gian chờ thử lại bao lâu), hãy định nghĩa một kiểu.

package main

import (
	"errors"
	"fmt"
)

type ValidationError struct {
	Field  string
	Reason string
}

func (e *ValidationError) Error() string {
	return fmt.Sprintf("%s: %s", e.Field, e.Reason)
}

func validateAge(age int) error {
	if age < 0 || age > 150 {
		return &ValidationError{Field: "age", Reason: "must be between 0 and 150"}
	}
	return nil
}

func register(age int) error {
	if err := validateAge(age); err != nil {
		return fmt.Errorf("register: %w", err)
	}
	return nil
}

func main() {
	err := register(200)
	fmt.Println(err)

	var ve *ValidationError
	if errors.As(err, &ve) {
		fmt.Println("bad field:", ve.Field)
	}
}

Đầu ra:

register: age: must be between 0 and 150
bad field: age

Phương thức có receiver con trỏ và hàm trả về &ValidationError{...}, nên đích của errors.As là một *ValidationError, và bạn truyền địa chỉ của nó (&ve, một **ValidationError). Nhầm mức con trỏ này là lỗi kinh điển với errors.As: với receiver giá trị, bạn sẽ trả về ValidationError{...} và khai báo var ve ValidationError. go vet bắt được sơ suất phổ biến nhất, truyền ve thay vì &ve: second argument to errors.As must be a non-nil pointer to either a type that implements error, or to any interface type.

Bọc lỗi bằng %w

fmt.Errorf với %w trả về một lỗi nhớ lỗi mà nó bọc. Mỗi tầng thêm ngữ cảnh và giữ nguyên chuỗi lỗi.

package main

import (
	"errors"
	"fmt"
)

var ErrTimeout = errors.New("timeout")

func dial() error    { return ErrTimeout }
func connect() error { return fmt.Errorf("connect db: %w", dial()) }
func start() error   { return fmt.Errorf("start: %w", connect()) }

func main() {
	err := start()
	fmt.Println(err)

	// Walk the chain by hand.
	for e := err; e != nil; e = errors.Unwrap(e) {
		fmt.Printf("  %T: %v\n", e, e)
	}

	fmt.Println(errors.Is(err, ErrTimeout))

	hidden := fmt.Errorf("start: %v", connect()) // %v: text only
	fmt.Println(errors.Is(hidden, ErrTimeout))
}

Đầu ra:

start: connect db: timeout
  *fmt.wrapError: start: connect db: timeout
  *fmt.wrapError: connect db: timeout
  *errors.errorString: timeout
true
false

Với %v, thông điệp giống hệt nhưng chuỗi bị cắt đứt, nên errors.Is trả về false. Chọn %w khi bên gọi cần thấy được nguyên nhân, %v khi nguyên nhân là chi tiết cài đặt mà bạn không muốn họ phụ thuộc vào.

Từ Go 1.20, một lời gọi có thể bọc nhiều lỗi: fmt.Errorf("%w; %w", err1, err2). Khi đó errors.Is khớp với bất kỳ lỗi nào trong hai.

errors.Join: nhiều lỗi cùng lúc

Kiểm tra dữ liệu và dọn dẹp thường sinh ra nhiều hơn một lỗi. errors.Join (Go 1.20) gom chúng lại.

package main

import (
	"errors"
	"fmt"
)

var ErrRequired = errors.New("required")

type Form struct {
	Name, Email string
	Age         int
}

func (f Form) Validate() error {
	var errs []error
	if f.Name == "" {
		errs = append(errs, fmt.Errorf("name: %w", ErrRequired))
	}
	if f.Email == "" {
		errs = append(errs, fmt.Errorf("email: %w", ErrRequired))
	}
	if f.Age < 0 {
		errs = append(errs, errors.New("age: negative"))
	}
	return errors.Join(errs...) // nil when errs is empty
}

func main() {
	err := Form{Age: -1}.Validate()
	fmt.Println(err)
	fmt.Println("---")
	fmt.Println(errors.Is(err, ErrRequired))
	fmt.Println(Form{Name: "Ana", Email: "a@x.com"}.Validate() == nil)
}

Đầu ra:

name: required
email: required
age: negative
---
true
true

errors.Join trả về nil khi mọi đối số đều nil, nên hàm ở trên không cần xử lý riêng trường hợp "không có lỗi".

Phương thức Unwrap và Is

errors.Is và errors.As tìm lỗi được bọc bằng cách gọi phương thức Unwrap. Một kiểu tùy chỉnh chứa nguyên nhân nên cung cấp nó ra ngoài:

package main

import (
	"errors"
	"fmt"
	"io/fs"
	"os"
)

type QueryError struct {
	Query string
	Err   error
}

func (e *QueryError) Error() string { return "query " + e.Query + ": " + e.Err.Error() }
func (e *QueryError) Unwrap() error { return e.Err }

func main() {
	_, openErr := os.Open("/no/such/db")
	err := &QueryError{Query: "SELECT 1", Err: openErr}

	fmt.Println(err)
	fmt.Println(errors.Is(err, fs.ErrNotExist)) // found through Unwrap
}

Một kiểu bọc nhiều lỗi thì cài đặt Unwrap() []error.

Một kiểu cũng có thể định nghĩa Is(target error) bool để tự quyết định thế nào là bằng nhau, ví dụ để khớp mọi *HTTPError có cùng mã trạng thái. Bạn hiếm khi cần đến nó; bọc một sentinel và trả nó về từ Unwrap thường là đủ.

Bẫy nil có kiểu

Đừng bao giờ khai báo biến lỗi bằng kiểu cụ thể của bạn rồi trả nó về qua error:

func check() error {
	var err *ValidationError // nil pointer
	// ... no problem found
	return err // non-nil error! Its type is *ValidationError
}

if err != nil của bên gọi cho kết quả true, vì một interface chứa con trỏ nil có kiểu thì không phải nil. Hãy trả về nil trực tiếp khi thành công, và giữ các biến lỗi cục bộ ở kiểu error. Trang interfaces giải thích lý do.

Nên chọn loại nào

Lỗi thường gặp

• So sánh lỗi đã bọc bằng ==. Hãy dùng errors.Is.
• Truyền giá trị không phải con trỏ cho errors.As. Nó cần một con trỏ tới một biến thuộc kiểu đích.
• Tạo "sentinel" bên trong hàm. return errors.New("not found") tạo một giá trị mới ở mỗi lần gọi; bên gọi không thể so sánh với nó.
• Export mọi lỗi. Mỗi sentinel hoặc kiểu được export là một cam kết API.
• So khớp dựa trên err.Error(). Chuỗi thông điệp là để con người đọc.