الأخطاء المخصّصة في Golang: التغليف وerrors.Is وerrors.As

ثلاثة أنواع من الأخطاء

تستخدم شيفرات Go ثلاثة أشكال من الأخطاء، من الأبسط إلى الأغنى:

1. خطأ عابر: errors.New("...") أو fmt.Errorf("...") يُنشأ في مكانه. لا يستطيع المستدعون إلا قراءة الرسالة.
2. خطأ حارس (sentinel): متغيّر على مستوى الحزمة مثل io.EOF. يستطيع المستدعون فحصه بـ errors.Is.
3. نوع خطأ: بنية لها تابع Error() وتحمل حقولًا. يستطيع المستدعون استخراجها بـ errors.As وقراءة الحقول.

اختر الأبسط الذي يسمح للمستدعين بفعل ما يحتاجونه.

الأخطاء الحارسة

الخطأ الحارس قيمة خطأ تُعرَّف مرة واحدة وتُقارن بهويتها. تبدأ أسماؤها بـ 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. لهذا يجب أن يكون الخطأ الحارس متغيّرًا مشتركًا واحدًا.

تصبح الأخطاء الحارسة جزءًا من الواجهة البرمجية لحزمتك. بمجرّد أن يفحص المستدعون 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

للتابع مستقبِل مؤشر والدالة تعيد &ValidationError{...}، لذا فهدف errors.As هو *ValidationError، وتمرّر عنوانه (&ve، وهو **ValidationError). الخطأ في هذا المستوى هو الخطأ الكلاسيكي مع errors.As: مع مستقبِل قيمة كنت ستعيد 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 له رمز الحالة نفسه. نادرًا ما تحتاجه؛ تغليف خطأ حارس وإعادته من 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 عند المستدعي صحيحًا، لأن الواجهة التي تحمل مؤشرًا nil ذا نوع ليست nil. أعد nil حرفيًا عند النجاح، واجعل متغيّرات الأخطاء المحلية من النوع error. تشرح صفحة الواجهات السبب.

أي نوع تختار

أخطاء شائعة

• مقارنة الأخطاء المغلّفة بـ ==. استخدم errors.Is.
• تمرير قيمة ليست مؤشرًا إلى errors.As. تحتاج مؤشرًا إلى متغيّر من النوع الهدف.
• إنشاء "خطأ حارس" داخل دالة. return errors.New("not found") تنشئ قيمة جديدة في كل استدعاء؛ لا يستطيع المستدعون المقارنة بها.
• تصدير كل خطأ. كل خطأ حارس أو نوع مُصدَّر وعدٌ في الواجهة البرمجية.
• المطابقة على err.Error(). النصوص للبشر.