معالجة الأخطاء في Golang: if err != nil والتغليف والفحص

الأخطاء قيم

دالة Go التي قد تفشل تعيد error كآخر نتيجة. ويفحصها المستدعي فورًا.

package main

import (
	"fmt"
	"strconv"
)

func main() {
	for _, s := range []string{"42", "forty-two"} {
		n, err := strconv.Atoi(s)
		if err != nil {
			fmt.Println("could not parse:", err)
			continue
		}
		fmt.Println("parsed:", n)
	}
}

المخرجات:

parsed: 42
could not parse: strconv.Atoi: parsing "forty-two": invalid syntax

هذه هي الآلية كلها. لا استثناءات، ولا try أو catch، ولا تدفّق تحكّم خفي: الخطأ ينتقل فقط حيث تمرّره شيفرتك. الثمن هو تكرار ظاهر لـ if err != nil. والفائدة أن كل نقطة فشل ظاهرة في الصفحة، وأنت تقرّر عند كل منها ما يحدث.

النوع error

error واجهة مدمجة لها تابع واحد:

type error interface {
	Error() string
}

أي نوع له تابع Error() string هو خطأ. الخطأ nil يعني النجاح. طباعة الخطأ بـ fmt.Println(err) أو %v تستدعي Error().

إنشاء الأخطاء

دالتان تغطّيان معظم الحالات.

package main

import (
	"errors"
	"fmt"
)

func withdraw(balance, amount int) (int, error) {
	if amount <= 0 {
		return balance, errors.New("amount must be positive")
	}
	if amount > balance {
		return balance, fmt.Errorf("insufficient funds: have %d, need %d", balance, amount)
	}
	return balance - amount, nil
}

func main() {
	b := 100
	for _, amt := range []int{30, -5, 500} {
		nb, err := withdraw(b, amt)
		if err != nil {
			fmt.Println("error:", err)
			continue
		}
		b = nb
		fmt.Println("balance:", b)
	}
}

تنشئ errors.New خطأ بنص ثابت. وتنسّق fmt.Errorf خطأ بالأفعال نفسها التي تستخدمها Printf. اصطلاحًا تبدأ نصوص الأخطاء بحرف صغير ولا تنتهي بعلامة ترقيم، لأنها تُضمَّن عادة في رسائل أطول: load config: open app.yaml: no such file or directory.

نمط if err != nil

الشكل المعتاد: استدعِ، افحص، عُد مبكرًا. يبقى مسار النجاح عند بداية السطر، ويخرج كل فشل لحظة حدوثه.

func loadUser(id int) (*User, error) {
	row, err := db.Query(id)
	if err != nil {
		return nil, err
	}
	u, err := parseUser(row)
	if err != nil {
		return nil, err
	}
	if err := u.Validate(); err != nil {
		return nil, err
	}
	return u, nil
}

عرفان تجدر ملاحظتهما:

• عند الخطأ أعد القيمة الصفرية للنتائج الأخرى (nil و0 و""). ويجب ألا يستخدمها المستدعون عندما يكون err != nil.
• تحصر if err := f(); err != nil نطاق err داخل if عندما تعيد الدالة خطأ فقط. وهذا يبقي النطاق الخارجي نظيفًا.

تجنّب else بعد إعادة خطأ. if err != nil { return err } else { ... } يزيح المسار الناجح بلا سبب.

إضافة سياق عند إعادة الخطأ

الخطأ الذي يُمرَّر صعودًا دون تغيير يفقد قصة مصدره. open config.yaml: no such file or directory لا تخبرك أي خطوة من بدء التشغيل فشلت. أضف سياقًا بـ fmt.Errorf والفعل %w:

package main

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

func readConfig(path string) ([]byte, error) {
	data, err := os.ReadFile(path)
	if err != nil {
		return nil, fmt.Errorf("read config: %w", err)
	}
	return data, nil
}

func start() error {
	if _, err := readConfig("/etc/myapp/config.yaml"); err != nil {
		return fmt.Errorf("start server: %w", err)
	}
	return nil
}

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

	// The original error is still inside, and can be checked.
	fmt.Println(errors.Is(err, fs.ErrNotExist))
}

المخرجات:

start server: read config: open /etc/myapp/config.yaml: no such file or directory
true

كل طبقة تضيف ما كانت تفعله، وتُقرأ الرسالة النهائية كأثر من أعلى الاستدعاء حتى السبب. السياق الجيد يسمّي العملية والمدخل: parse line 12 وfetch user 42. لا تضف "error" أو "failed" في كل مستوى؛ الرسالة خطأ أصلًا.

%w يغلّف: يحتفظ بالخطأ الأصلي داخل الجديد، فتستطيع errors.Is وerrors.As إيجاده. أما %v فينسخ النص فقط. استخدم %v عندما تريد عمدًا إخفاء تفصيل داخلي عن المستدعين، مثلًا كي لا يعتمدوا على نوع خطأ مشغّل قاعدة بيانات.

فحص أخطاء محدّدة: errors.Is وerrors.As

أحيانًا يحتاج المستدعي إلى التصرّف حيال نوع واحد من الفشل: ملف مفقود يعني "استخدم القيم الافتراضية"، ومهلة منقضية تعني "أعد المحاولة". دالتان تجيبان عن ذلك، وكلتاهما تنظر عبر كل طبقات التغليف.

package main

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

func main() {
	_, err := os.Open("missing.txt")
	wrapped := fmt.Errorf("load: %w", err)

	// errors.Is: is this (or anything it wraps) a specific error value?
	if errors.Is(wrapped, fs.ErrNotExist) {
		fmt.Println("file does not exist, using defaults")
	}

	// errors.As: is there an error of this type in the chain? If so, give it to me.
	var pathErr *fs.PathError
	if errors.As(wrapped, &pathErr) {
		fmt.Println("operation:", pathErr.Op, "path:", pathErr.Path)
	}

	_, err = strconv.Atoi("12x")
	var numErr *strconv.NumError
	if errors.As(err, &numErr) {
		fmt.Println("bad input:", numErr.Num, "reason:", numErr.Err)
	}
}

قواعد عملية:

• قارن بقيم الأخطاء المعرّفة مسبقًا (الأخطاء الحارسة مثل io.EOF وos.ErrNotExist وsql.ErrNoRows) بـ errors.Is لا بـ ==. تفشل == بمجرّد تغليف الخطأ.
• استخرج الخطأ ذا النوع بـ errors.As لا بتأكيد نوع، للسبب نفسه. تأخذ errors.As مؤشرًا إلى متغيّر من النوع الهدف.
• لا تطابق على نص err.Error() أبدًا. الرسائل تتغيّر بين الإصدارات، والمطابقة النصية تنكسر بصمت عندما يحدث ذلك.

تعريف أخطائك الحارسة وأنواع أخطائك الخاصة، وجمع عدة أخطاء بـ errors.Join، مشروحة في صفحة الأخطاء المخصّصة.

عالج الخطأ مرة واحدة

يجب أن يُعالج الخطأ مرة واحدة بالضبط. والمعالجة تعني أحد الأمور التالية: إعادته (مغلّفًا عادة)، أو تسجيله والمتابعة، أو إعادة المحاولة، أو تحويله إلى ردّ للمستخدم. فعل اثنين منها هو أشيع خطأ في معالجة الأخطاء في شيفرات Go.

// Wrong: logged here, and returned, so it is logged again by every caller.
if err != nil {
	log.Printf("could not fetch user: %v", err)
	return err
}

// Right: add context and return. The top of the program logs once.
if err != nil {
	return fmt.Errorf("fetch user %d: %w", id, err)
}

التسجيل مع الإعادة ينتج الفشل نفسه عدة مرات في السجلات، كل مرة بسياق أقل من الرسالة النهائية. دع الأخطاء تصعد إلى المكان القادر على تقرير ما يُفعل (معالج HTTP، أو main، أو حلقة عامل)، وسجّلها هناك.

أين تنتهي الأخطاء

في أعلى البرنامج يجب أن يتصرّف شيء ما حيال الخطأ. في main يعني ذلك عادة طباعته والخروج بحالة غير صفرية:

package main

import (
	"errors"
	"fmt"
	"os"
)

func run(args []string) error {
	if len(args) < 2 {
		return errors.New("usage: app <name>")
	}
	fmt.Println("hello,", args[1])
	return nil
}

func main() {
	if err := run(os.Args); err != nil {
		fmt.Fprintln(os.Stderr, "error:", err)
		os.Exit(1)
	}
}

تشغيل هذا دون وسائط يطبع error: usage: app <name> إلى stderr ويخرج بالحالة 1 (اكتب اسمًا في لوحة Args لترى المسار الآخر). إبقاء main بهذا الشكل، والعمل الحقيقي في run، يجعل البرنامج قابلًا للاختبار ويعني أن عبارات defer داخل run ما زالت تُنفَّذ، لأن os.Exit تتخطّى الاستدعاءات المؤجّلة.

في خادم HTTP يكون الأعلى هو المعالج: يحوّل الخطأ إلى رمز حالة ورسالة آمنة للعميل، ويسجّل الرسالة المفصّلة لك.

أخطاء قد تتجاهلها، وأخرى لا يجوز

تجاهل الخطأ صحيح أحيانًا، لكن اجعله صريحًا بـ _ ليعرف القرّاء أنه كان قرارًا:

_ = conn.SetDeadline(t) // best effort

بعض الاستدعاءات لا تفشل عمليًا (strings.Builder.WriteString وbytes.Buffer.Write). وأخرى تبدو غير مؤذية وهي ليست كذلك: Close على ملف كتبت فيه قد تبلغ أن البيانات لم تصل إلى القرص قط، وjson.Marshal تفشل مع القنوات والدوال. عند الشك افحص.

تبلغ أداة الفحص errcheck (المضمّنة في golangci-lint) عن الأخطاء غير المفحوصة. أما go vet فلا يبلغ عنها وحده.

الأخطاء وpanic

لدى Go أيضًا panic، لكنها ليست نظام استثناءات. استخدم الأخطاء لكل ما قد يسوء في التشغيل العادي: مدخلات خاطئة، ملفات مفقودة، أعطال شبكة. واحتفظ بـ panic لأخطاء البرمجة (حالة مستحيلة، ثابت مكسور) ولإخفاقات بدء التشغيل التي لا معنى للمتابعة بعدها. يجب ألا تسبّب المكتبة panic عبر واجهتها البرمجية تقريبًا أبدًا. راجع صفحة panic وrecover.

تقليل التكرار

if err != nil مطوّلة، ورُفضت مقترحات إضافة صيغة جديدة لها مرارًا؛ وأعلن فريق Go في 2025 أنه لم يعد يسعى إلى تغييرات في صيغة معالجة الأخطاء. بعض الأنماط تقلّل الضجيج ضمن اللغة:

• عُد مبكرًا وأبقِ الدوال صغيرة. معظم التكرار يأتي من دوال طويلة تنفّذ خطوات كثيرة.
• الخطأ اللاصق. لسلسلة كتابات احتفظ بأول خطأ في حقل بنية واجعل الاستدعاءات اللاحقة لا تفعل شيئًا بعد ضبطه. تعمل bufio.Writer بهذه الطريقة: تفحص الخطأ مرة واحدة بعد Flush.
• غلّف مرة واحدة لكل دالة. إغلاق مؤجّل على نتيجة مسمّاة يمكنه إضافة السياق نفسه إلى كل خطأ تعيده الدالة (راجع defer).

أخطاء شائعة

• استخدام قيمة عندما يكون err غير nil. افحص أولًا، ثم استخدم.
• التسجيل مع الإعادة. اختر واحدًا.
• المقارنة بـ == بعد التغليف. استخدم errors.Is.
• فقدان السبب بـ %v. استخدم %w ما لم يكن الإخفاء هو المقصود.
• إعادة مؤشر nil ذي نوع كـ error. var e *MyErr; return e ليست nil عند المستدعي. أعد nil حرفيًا.
• رسائل تبدأ بحرف كبير أو تنتهي بعلامة ترقيم. errors.New("Failed to connect.") تُقرأ بشكل سيئ بعد التغليف. اكتب connect to db: ....