שגיאות ב-Golang: עטיפה, errors.Is, errors.As וטיפוסים מותאמים

שלושה סוגי שגיאות

קוד Go משתמש בשלוש צורות של שגיאות, מהפשוטה לעשירה:

1. שגיאה אד הוק: errors.New("...") או fmt.Errorf("...") שנוצרת במקום. הקוראים יכולים רק לקרוא את ההודעה.
2. שגיאת sentinel: משתנה ברמת החבילה כמו io.EOF. הקוראים יכולים לבדוק אותה עם errors.Is.
3. טיפוס שגיאה: struct עם מתודת Error(), שנושא שדות. הקוראים יכולים לחלץ אותו עם errors.As ולקרוא את השדות.

בחרו את הפשוטה ביותר שמאפשרת לקוראים לעשות את מה שהם צריכים.

שגיאות sentinel

sentinel הוא ערך שגיאה שמוצהר פעם אחת ומושווה לפי זהות. לפי המוסכמה השמות מתחילים ב-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)
		}
	}
}

פלט:

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

שתי קריאות ל-errors.New עם אותו טקסט יוצרות שגיאות שונות: errors.New("x") == errors.New("x") הוא false. לכן sentinel חייב להיות משתנה משותף יחיד.

sentinels הופכים לחלק מה-API של החבילה שלכם. ברגע שקוראים בודקים את ErrNotFound, אי אפשר להפסיק להחזיר אותה בלי לשבור אותם. ייצאו רק את אלה שהקוראים באמת צריכים כדי להסתעף לפיהם.

טיפוסי שגיאה מותאמים

כשמי שקורא צריך פרטים (איזה שדה, איזה קוד סטטוס, כמה זמן לחכות לפני ניסיון חוזר), הגדירו טיפוס.

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

פלט:

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

למתודה יש receiver מסוג מצביע והפונקציה מחזירה &ValidationError{...}, ולכן היעד של errors.As הוא *ValidationError, ומעבירים את הכתובת שלו (&ve, מטיפוס **ValidationError). טעות ברמת ההפניה הזאת היא הטעות הקלאסית עם errors.As: עם receiver מסוג ערך הייתם מחזירים ValidationError{...} ומצהירים var ve ValidationError. go vet תופס את הפספוס הנפוץ ביותר, העברת ve במקום &ve: second argument to errors.As must be a non-nil pointer to either a type that implements error, or to any interface type.

עטיפה עם %w

fmt.Errorf עם %w מחזירה שגיאה שזוכרת את זו שהיא עוטפת. כל שכבה מוסיפה הקשר ושומרת על השרשרת שלמה.

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

פלט:

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

עם %v ההודעה זהה אבל השרשרת נחתכת, ולכן errors.Is מחזירה false. בחרו ב-%w כשהקוראים צריכים לראות את הסיבה, וב-%v כשהסיבה היא פרט מימוש שאתם לא רוצים שיסתמכו עליו.

החל מ-Go 1.20, קריאה אחת יכולה לעטוף כמה שגיאות: fmt.Errorf("%w; %w", err1, err2). errors.Is מתאימה אז לכל אחת מהן.

errors.Join: כמה שגיאות בבת אחת

ולידציה וניקוי מייצרים לעיתים קרובות יותר משגיאה אחת. errors.Join (Go 1.20) מאגדת אותן.

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

פלט:

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

errors.Join מחזירה nil כשכל הארגומנטים הם nil, ולכן הפונקציה שלמעלה לא צריכה טיפול מיוחד במקרה של "אין שגיאות".

המתודות Unwrap ו-Is

errors.Is ו-errors.As מוצאות שגיאות עטופות על ידי קריאה למתודת Unwrap. טיפוס מותאם שמחזיק סיבה צריך לחשוף אותה:

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
}

טיפוס שעוטף כמה שגיאות מממש במקום זאת את Unwrap() []error.

טיפוס יכול גם להגדיר Is(target error) bool כדי להחליט בעצמו על שוויון, למשל כדי להתאים לכל *HTTPError עם אותו קוד סטטוס. לעיתים רחוקות צריך את זה; עטיפת sentinel והחזרתו מ-Unwrap בדרך כלל עושות את העבודה.

מלכודת ה-nil עם טיפוס

אף פעם אל תצהירו על משתנה שגיאה עם הטיפוס הקונקרטי שלכם ותחזירו אותו דרך error:

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

ה-if err != nil של מי שקרא יהיה true, כי interface שמחזיק מצביע nil עם טיפוס אינו nil. החזירו nil מפורש במקרה של הצלחה, והשאירו משתני שגיאה מקומיים מטיפוס error. הדף על interfaces מסביר למה.

איזה סוג לבחור

טעויות נפוצות

• השוואת שגיאות עטופות עם ==. השתמשו ב-errors.Is.
• העברת ערך שאינו מצביע ל-errors.As. היא צריכה מצביע למשתנה מטיפוס היעד.
• יצירת "sentinel" בתוך פונקציה. return errors.New("not found") יוצר ערך חדש בכל קריאה; הקוראים לא יכולים להשוות מולו.
• ייצוא כל שגיאה. כל sentinel או טיפוס מיוצא הוא הבטחה של API.
• התאמה לפי err.Error(). מחרוזות נועדו לבני אדם.