Error di Golang: Wrap, errors.Is, errors.As, dan Tipe Kustom

Tiga jenis error

Kode Go memakai tiga bentuk error, dari yang paling sederhana sampai yang paling kaya:

1. Error ad hoc: errors.New("...") atau fmt.Errorf("...") yang dibuat di tempat. Pemanggil hanya bisa membaca pesannya.
2. Sentinel error: variabel di level package seperti io.EOF. Pemanggil bisa memeriksanya dengan errors.Is.
3. Tipe error: struct dengan method Error() yang membawa field. Pemanggil bisa mengambilnya dengan errors.As dan membaca field-nya.

Pilih yang paling sederhana yang tetap memungkinkan pemanggil melakukan apa yang mereka perlukan.

Sentinel error

Sentinel adalah nilai error yang dideklarasikan sekali dan dibandingkan berdasarkan identitasnya. Menurut konvensi, namanya diawali 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)
		}
	}
}

Output:

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

Dua pemanggilan errors.New dengan teks yang sama menghasilkan error yang berbeda: errors.New("x") == errors.New("x") bernilai false. Karena itulah sentinel harus berupa satu variabel yang dipakai bersama.

Sentinel menjadi bagian dari API package-mu. Begitu pemanggil memeriksa ErrNotFound, kamu tidak bisa berhenti mengembalikannya tanpa merusak kode mereka. Ekspor hanya sentinel yang memang perlu dipakai pemanggil untuk menentukan percabangan.

Tipe error kustom

Saat pemanggil butuh detail (field yang mana, status code yang mana, jeda retry berapa lama), definisikan sebuah tipe.

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)
	}
}

Output:

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

Method-nya punya pointer receiver dan fungsinya mengembalikan &ValidationError{...}, jadi target untuk errors.As adalah *ValidationError, dan kamu mengirim alamatnya (&ve, sebuah **ValidationError). Salah di level ini adalah kesalahan klasik saat memakai errors.As: dengan value receiver, kamu akan mengembalikan ValidationError{...} dan mendeklarasikan var ve ValidationError. go vet menangkap kekeliruan yang paling umum, yaitu mengirim ve alih-alih &ve: second argument to errors.As must be a non-nil pointer to either a type that implements error, or to any interface type.

Membungkus dengan %w

fmt.Errorf dengan %w mengembalikan error yang mengingat error yang dibungkusnya. Setiap lapisan menambahkan konteks dan menjaga rantainya tetap utuh.

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))
}

Output:

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

Dengan %v, pesannya sama tetapi rantainya terputus, jadi errors.Is mengembalikan false. Pilih %w saat pemanggil seharusnya bisa melihat penyebabnya, dan %v saat penyebabnya adalah detail implementasi yang tidak ingin kamu jadikan sandaran bagi mereka.

Sejak Go 1.20, satu pemanggilan bisa membungkus beberapa error: fmt.Errorf("%w; %w", err1, err2). errors.Is lalu cocok dengan salah satunya.

errors.Join: beberapa error sekaligus

Validasi dan pembersihan sering menghasilkan lebih dari satu error. errors.Join (Go 1.20) menggabungkannya.

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)
}

Output:

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

errors.Join mengembalikan nil saat setiap argumennya nil, jadi fungsi di atas tidak butuh penanganan khusus untuk kondisi "tidak ada error".

Method Unwrap dan Is

errors.Is dan errors.As menemukan error yang dibungkus dengan memanggil method Unwrap. Tipe kustom yang menyimpan penyebab sebaiknya menyediakannya:

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
}

Tipe yang membungkus beberapa error mengimplementasikan Unwrap() []error sebagai gantinya.

Sebuah tipe juga bisa mendefinisikan Is(target error) bool untuk menentukan kesamaannya sendiri, misalnya agar cocok dengan *HTTPError mana pun yang punya status code sama. Kamu jarang membutuhkannya; membungkus sentinel dan mengembalikannya dari Unwrap biasanya sudah cukup.

Jebakan typed nil

Jangan pernah mendeklarasikan variabel error dengan tipe konkretmu lalu mengembalikannya lewat error:

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

if err != nil di sisi pemanggil bernilai true, karena interface yang berisi pointer nil bertipe tidaklah nil. Kembalikan nil literal saat berhasil, dan biarkan variabel error lokal bertipe error. Halaman interface menjelaskan alasannya.

Jenis mana yang dipilih

Kesalahan umum

• Membandingkan error yang dibungkus dengan ==. Pakai errors.Is.
• Mengirim nilai yang bukan pointer ke errors.As. Fungsi ini butuh pointer ke variabel bertipe target.
• Membuat "sentinel" di dalam fungsi. return errors.New("not found") membuat nilai baru di setiap pemanggilan; pemanggil tidak bisa membandingkan dengannya.
• Mengekspor setiap error. Setiap sentinel atau tipe yang diekspor adalah janji API.
• Mencocokkan berdasarkan err.Error(). String itu untuk dibaca manusia.