وثائق Go قابلة للتشغيل: الحزمة context

Q: لماذا يُستخدم context في Go؟

يخبر context.Context الدالة وكل ما تستدعيه متى تتوقّف: لأن المستدعي ألغى، أو لأن الموعد النهائي مرّ، أو لأن العميل قطع الاتصال. ويمكنه أيضًا حمل قيم خاصة بالطلب مثل معرّف الطلب. اصطلاحًا يكون المعامل الأول، واسمه ctx.

Q: ما الفرق بين context.Background وcontext.TODO؟

كلاهما يعيد سياقًا فارغًا لا يُلغى أبدًا وليس له موعد نهائي ولا قيم. سلوكهما متطابق. Background() هو الجذر في main والاختبارات والإعداد العلوي. أما TODO() فيعلّم مكانًا يجب أن يُمرَّر إليه سياق حقيقي لكن الشيفرة المحيطة لا تملكه بعد، فيسهل العثور عليه لاحقًا.

Q: لماذا يجب استدعاء cancel بعد context.WithTimeout؟

تسجّل WithTimeout وWithDeadline وWithCancel السياق الجديد لدى أبيه وقد تشغّل مؤقّتًا. استدعاء cancel يحرّر هذه الموارد فور انتهائك، بدل انتظار انقضاء المهلة أو إلغاء الأب. اكتب defer cancel() مباشرة بعد إنشائه؛ ويحذّر go vet عند إهمال دالة الإلغاء.

Q: ماذا تعني رسالة "context deadline exceeded" في Go؟

هي نص context.DeadlineExceeded، الخطأ الذي تعيده ctx.Err() بعد مرور الموعد النهائي للسياق. الدوال التي تحترم السياق، مثل عملاء HTTP ومشغّلات قواعد البيانات، تعيده (مغلّفًا غالبًا) عند نفاد الوقت. تحقّق منه بـ errors.Is(err, context.DeadlineExceeded).

Q: هل أستخدم context.WithValue لتمرير المعاملات؟

لا. استخدمها فقط للبيانات الخاصة بالطلب التي تعبر حدود الواجهات البرمجية ولا تحتاج الدوال الوسيطة إلى معرفتها، مثل معرّف التتبّع أو المستخدم الموثَّق. كل ما تحتاجه الدالة لأداء عملها مكانه معاملاتها، حيث يتحقّق منه المترجم.

مهلة زمنية في عشرة أسطر

وظيفة context.Context أن يخبر الشيفرة متى تتوقّف. هنا تحصل عملية بطيئة على 50 ms، وتستسلم عندما يطلب السياق ذلك:

package main

import (
	"context"
	"fmt"
	"time"
)

func slowQuery(ctx context.Context, d time.Duration) (string, error) {
	select {
	case <-time.After(d): // stands in for real work
		return "rows", nil
	case <-ctx.Done():
		return "", ctx.Err()
	}
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
	defer cancel()

	res, err := slowQuery(ctx, 10*time.Millisecond)
	fmt.Println("fast query:", res, err)

	res, err = slowQuery(ctx, 200*time.Millisecond)
	fmt.Println("slow query:", res, err)
}

ينتهي الاستدعاء الأول في 10 ms ويعيد rows <nil>. الثاني يحتاج 200 ms، لكن السياق ينتهي عند 50 ms (محسوبة من لحظة إنشائه)، فيعيد context deadline exceeded.

لا شيء يُوقَف بالقوة. لا تملك Go طريقة لقتل goroutine من الخارج. السياق إشارة، وعلى الشيفرة أن تتحقّق منها: بالانتظار على ctx.Done() داخل select، أو بفحص ctx.Err() بين الخطوات، أو بتمرير ctx إلى استدعاءات مكتبات (http.NewRequestWithContext وdb.QueryContext وexec.CommandContext) تتحقّق منه نيابة عنك.

الواجهة Context

type Context interface {
	Deadline() (deadline time.Time, ok bool)
	Done() <-chan struct{}
	Err() error
	Value(key any) any
}

التابع	ما يعيده
`Done()`	قناة تُغلق عند إلغاء السياق أو انقضاء مهلته (`nil` لسياق لا يمكن إلغاؤه أبدًا)
`Err()`	`nil` ما دام نشطًا، ثم `context.Canceled` أو `context.DeadlineExceeded`
`Deadline()`	الموعد النهائي و`true`، أو `ok == false` إن لم يوجد
`Value(key)`	القيمة المخزّنة تحت `key` في هذا السياق أو أحد أسلافه، أو `nil`

السياقات غير قابلة للتعديل. لا تغيّر سياقًا أبدًا؛ بل تشتقّ منه ابنًا بإحدى دوال With، فيضيف الابن إشارة إلغاء أو موعدًا نهائيًا أو قيمة.

من أين يأتي السياق

تبدأ كل شجرة سياقات من جذر:

context.Background() في main وinit والاختبارات والإعداد العلوي للخوادم.
context.TODO() عندما يجب أن تأخذ الدالة سياقًا لكن المستدعي لا يملكه بعد. يتصرّف تمامًا مثل Background؛ الاسم علامة لإعادة الهيكلة لاحقًا.

داخل معالج HTTP لا تنشئ جذرًا. بل تستخدم r.Context()، الذي يلغيه الخادم عند انقطاع العميل أو عودة المعالج.

WithCancel: التوقّف عند الطلب

تعيد context.WithCancel سياقًا ابنًا ودالة cancel. استدعاء cancel يغلق قناة Done للابن وقنوات Done لكل ما اشتُقّ منه.

package main

import (
	"context"
	"fmt"
)

func producer(ctx context.Context, out chan<- int) {
	defer close(out)
	for i := 1; ; i++ {
		select {
		case out <- i:
		case <-ctx.Done():
			return // stop and close out
		}
	}
}

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	nums := make(chan int)
	go producer(ctx, nums)

	sum := 0
	for n := range nums {
		sum += n
		if n == 5 {
			cancel() // the consumer has what it needs
			break
		}
	}
	fmt.Println("sum of first five:", sum)

	for range nums { // wait until the producer has closed the channel
	}
	fmt.Println("producer has exited:", ctx.Err())
}

يقع إرسال المنتج داخل select بجوار ctx.Done(). وهذا ما يسمح له بالتوقّف: لو كان out <- i وحده لتوقّف إلى الأبد بعد أن يكفّ المستهلك عن القراءة، ولتسرّبت الـ goroutine. تنتظر for range nums الأخيرة حتى يغلق المنتج القناة. وأثناء التفريغ قد يتمكّن المنتج من إرسال قيمة أو اثنتين، لأن Go تختار حالة عشوائيًا عندما تكون حالتا select جاهزتين؛ الإلغاء سريع لكنه ليس فوريًا.

استدعاء cancel آمن أكثر من مرة ومن أي goroutine. الاستدعاء الأول وحده يفعل شيئًا.

WithTimeout وWithDeadline

WithTimeout(parent, d) تساوي WithDeadline(parent, time.Now().Add(d)). استخدم المهلة لمعنى "على الأكثر هذه المدة"، والموعد النهائي عندما يكون لديك وقت مطلق.

بعد مرور الوقت تُغلق Done وتعيد Err القيمة context.DeadlineExceeded. وإذا استُدعيت cancel أولًا تعيد Err القيمة context.Canceled. تحقّق من أيهما بـ errors.Is، لأن المكتبات تغلّف الخطأ عادة:

package main

import (
	"context"
	"errors"
	"fmt"
	"time"
)

func work(ctx context.Context) error {
	select {
	case <-time.After(100 * time.Millisecond):
		return nil
	case <-ctx.Done():
		return fmt.Errorf("work: %w", ctx.Err())
	}
}

func describe(err error) string {
	switch {
	case err == nil:
		return "finished"
	case errors.Is(err, context.DeadlineExceeded):
		return "timed out: " + err.Error()
	case errors.Is(err, context.Canceled):
		return "cancelled: " + err.Error()
	default:
		return "failed: " + err.Error()
	}
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
	defer cancel()
	fmt.Println(describe(work(ctx)))

	ctx2, cancel2 := context.WithCancel(context.Background())
	cancel2()
	fmt.Println(describe(work(ctx2)))

	deadline, ok := ctx.Deadline()
	fmt.Println("has deadline:", ok, "in the past:", time.Now().After(deadline))
}

استدعِ cancel دائمًا، حتى لمهلة ستنقضي من تلقاء نفسها. يحتفظ السياق بمؤقّت وبموضع لدى أبيه حتى يحدث أحدهما، وdefer cancel() تحرّرهما فور عودة الدالة. يبلغ go vet عن دالة إلغاء مهملة: the cancel function returned by context.WithTimeout should be called, not discarded, to avoid a context leak.

الأبناء لا يعيشون أطول من آبائهم

تشكّل السياقات شجرة. إلغاء الأب يلغي كل الأحفاد. قد يكون للابن موعد نهائي أقصر من أبيه، لكن ليس أطول أبدًا: الموعد الأبكر يفوز دائمًا.

package main

import (
	"context"
	"fmt"
	"time"
)

func main() {
	parent, cancelParent := context.WithTimeout(context.Background(), 30*time.Millisecond)
	defer cancelParent()

	// Asking for 10 seconds does not extend the parent's 30 ms.
	child, cancelChild := context.WithTimeout(parent, 10*time.Second)
	defer cancelChild()

	d, _ := child.Deadline()
	fmt.Println("child deadline is within 30ms:", time.Until(d) <= 30*time.Millisecond)

	<-child.Done()
	fmt.Println("child:", child.Err())

	// Cancelling a child never affects the parent.
	p2, cancelP2 := context.WithCancel(context.Background())
	defer cancelP2()
	c2, cancelC2 := context.WithCancel(p2)
	cancelC2()
	fmt.Println("c2:", c2.Err(), "| p2:", p2.Err())
}

هذا ما يجعل السياقات مفيدة عبر الطبقات. يحصل معالج HTTP على سياق يموت مع الطلب؛ واستدعاء قاعدة بيانات بعد ثلاث طبقات يشتقّ منه مهلة ثانيتين. إذا أغلق العميل الاتصال بعد 100 ms، يُلغى الاستعلام حينها، لا بعد ثانيتين.

انتظر دائمًا على ctx.Done() عندما تتوقّف

كل goroutine تنتظر (إرسالًا على قناة، أو استقبالًا، أو مؤقّتًا) يجب أن تنتظر ctx.Done() في الوقت نفسه. أما الحلقات الحسابية التي لا تتوقّف أبدًا، فافحص فيها ctx.Err() بين حين وآخر:

for i, item := range items {
	if i%1000 == 0 {
		if err := ctx.Err(); err != nil {
			return err
		}
	}
	process(item)
}

استخدم time.After داخل select للانتظار البسيط، لكن فضّل مؤقّتًا يمكنك إيقافه (أو مهلة سياق) عندما يُلغى الانتظار كثيرًا.

أسباب الإلغاء (Go 1.20 و1.21)

لا تقول ctx.Err() إلا canceled أو deadline exceeded. لتسجيل السبب استخدم صيغ Cause:

package main

import (
	"context"
	"errors"
	"fmt"
)

var errShutdown = errors.New("server shutting down")

func main() {
	ctx, cancel := context.WithCancelCause(context.Background())
	cancel(errShutdown)

	fmt.Println("Err:  ", ctx.Err())
	fmt.Println("Cause:", context.Cause(ctx))
	fmt.Println("is shutdown:", errors.Is(context.Cause(ctx), errShutdown))
}

وصلت WithCancelCause في Go 1.20، وWithTimeoutCause وWithDeadlineCause في Go 1.21. تستمر Err في إعادة القيم القياسية فتبقى الفحوص الموجودة تعمل؛ وcontext.Cause تعطي التفاصيل.

WithValue، باعتدال

تربط context.WithValue(parent, key, value) قيمة واحدة. وتبحث ctx.Value(key) عنها عبر سلسلة الآباء.

package main

import (
	"context"
	"fmt"
)

// An unexported key type: no other package can collide with it.
type ctxKey int

const requestIDKey ctxKey = 0

func WithRequestID(ctx context.Context, id string) context.Context {
	return context.WithValue(ctx, requestIDKey, id)
}

func RequestID(ctx context.Context) string {
	id, _ := ctx.Value(requestIDKey).(string)
	return id
}

func handle(ctx context.Context) {
	fmt.Printf("[%s] handling request\n", RequestID(ctx))
}

func main() {
	ctx := WithRequestID(context.Background(), "req-42")
	handle(ctx)
	handle(context.Background()) // no ID set: empty string
}

قواعد القيم:

استخدم نوعًا غير مُصدَّر للمفاتيح، ولا تستخدم string عاديًا أبدًا. حزمتان تستخدمان كلتاهما "user" ستكتب إحداهما فوق الأخرى. (لا يكتشف go vet ذلك؛ أما staticcheck فيكتشفه.)
غلّف الوصول بدوال مساعدة ذات أنواع مثل WithRequestID وRequestID، كي لا يرى المستدعون any ولا المفتاح.
خزّن فقط البيانات الخاصة بالطلب التي تمرّ عبر الواجهات البرمجية: معرّفات التتبّع والطلب، والمستخدم الموثَّق، والمسجِّل. لا تخزّن أبدًا المعاملات الاختيارية أو مقابض قواعد البيانات أو الإعدادات. مكانها وسائط الدوال أو حقول البنى، حيث يتحقّق منها المترجم ويراها القرّاء.
يمرّ البحث على السلسلة أبًا بعد أب، فكل قيمة تضيفها تطيل البحث عن الأخريات خطوة.

الأعراف

ctx context.Context هو المعامل الأول لكل دالة تجري إدخالًا وإخراجًا، أو تتوقّف، أو تستدعي ما يفعل ذلك: func Fetch(ctx context.Context, url string) error.
لا تخزّن سياقًا في بنية. مرّره إلى كل استدعاء تابع. السياق يخصّ عملية واحدة، والبنية تعيش عادة أطول منها. (الاستثناء نوع يمثّل عملية واحدة، مثل http.Request.)
لا تمرّر nil سياقًا أبدًا. استخدم context.TODO() إن لم يكن لديك أفضل منه.
أعد ctx.Err()، أو غلّفها بـ %w، عندما تتوقّف بسبب السياق، ليميّز المستدعون المهلة من فشل حقيقي.

السياق في خوادم HTTP وعملائه

جهة الخادم: يُلغى r.Context() عند انقطاع العميل، أو عودة المعالج، أو إعادة ضبط تدفّق HTTP/2. جهة العميل: تجعل http.NewRequestWithContext الطلب يحترم المهلة أو الإلغاء. يشغّل هذا البرنامج الطرفين عبر httptest:

package main

import (
	"context"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"time"
)

func main() {
	serverSaw := make(chan error, 1)

	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		select {
		case <-time.After(500 * time.Millisecond): // a slow report
			fmt.Fprintln(w, "report ready")
			serverSaw <- nil
		case <-r.Context().Done():
			serverSaw <- r.Context().Err() // client went away: stop working
		}
	}))
	defer srv.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
	defer cancel()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, srv.URL, nil)
	if err != nil {
		panic(err)
	}
	resp, err := http.DefaultClient.Do(req)
	if err == nil {
		body, _ := io.ReadAll(resp.Body)
		resp.Body.Close()
		fmt.Print("client got: ", string(body))
	} else {
		fmt.Println("client: deadline exceeded:", errors.Is(err, context.DeadlineExceeded))
	}

	fmt.Println("server handler stopped with:", <-serverSaw)
}

يستسلم العميل عند 50 ms ويغلق الاتصال. يلاحظ الخادم ذلك، فيُلغى سياق طلبه، ويتوقّف المعالج بدل إنفاق 450 ميلي ثانية أخرى على تقرير لن يقرأه أحد. في معالج حقيقي تمرّر r.Context() إلى كل استدعاء قاعدة بيانات وHTTP، فتتوقّف كلها معًا.

دوال مساعدة أخرى (Go 1.21)

تعيد context.WithoutCancel(ctx) سياقًا بالقيم نفسها لا يُلغى عند إلغاء ctx. استخدمها لعمل يجب أن يكتمل بعد انتهاء الطلب، مثل كتابة سجل تدقيق.
تشغّل context.AfterFunc(ctx, f) الدالة f في goroutine خاصة بها بعد انتهاء ctx، وتعيد دالة stop لإلغاء تسجيلها.

أخطاء شائعة

عدم استدعاء cancel. اكتب دائمًا defer cancel() مباشرة بعد WithCancel أو WithTimeout أو WithDeadline.
تشغيل goroutine تتجاهل ctx. إذا توقّفت دون الانتظار على ctx.Done()، فالإلغاء لا يفعل شيئًا وتتسرّب الـ goroutine.
إنشاء context.Background() جديد في عمق سلسلة استدعاءات. يقطع ذلك الصلة بالموعد النهائي للمستدعي وبإلغائه. مرّر الـ ctx الذي أُعطي لك.
مقارنة الأخطاء بـ ==. استخدم errors.Is(err, context.DeadlineExceeded)؛ معظم المكتبات تغلّف الخطأ.
استخدام WithValue للاعتماديات. مقبض قاعدة بيانات مخبّأ في سياق هو معامل لم يعد المترجم قادرًا على التحقّق منه.
توقّع أن يكون الإلغاء فوريًا. لا تلاحظ الشيفرة الإلغاء إلا عند فحصها التالي. الحلقة الطويلة دون فحص تستمر في العمل.

الأسئلة الشائعة

لماذا يُستخدم context في Go؟

يخبر context.Context الدالة وكل ما تستدعيه متى تتوقّف: لأن المستدعي ألغى، أو لأن الموعد النهائي مرّ، أو لأن العميل قطع الاتصال. ويمكنه أيضًا حمل قيم خاصة بالطلب مثل معرّف الطلب. اصطلاحًا يكون المعامل الأول، واسمه ctx.

ما الفرق بين context.Background وcontext.TODO؟

كلاهما يعيد سياقًا فارغًا لا يُلغى أبدًا وليس له موعد نهائي ولا قيم. سلوكهما متطابق. Background() هو الجذر في main والاختبارات والإعداد العلوي. أما TODO() فيعلّم مكانًا يجب أن يُمرَّر إليه سياق حقيقي لكن الشيفرة المحيطة لا تملكه بعد، فيسهل العثور عليه لاحقًا.

لماذا يجب استدعاء cancel بعد context.WithTimeout؟

تسجّل WithTimeout وWithDeadline وWithCancel السياق الجديد لدى أبيه وقد تشغّل مؤقّتًا. استدعاء cancel يحرّر هذه الموارد فور انتهائك، بدل انتظار انقضاء المهلة أو إلغاء الأب. اكتب defer cancel() مباشرة بعد إنشائه؛ ويحذّر go vet عند إهمال دالة الإلغاء.

ماذا تعني رسالة "context deadline exceeded" في Go؟

هي نص context.DeadlineExceeded، الخطأ الذي تعيده ctx.Err() بعد مرور الموعد النهائي للسياق. الدوال التي تحترم السياق، مثل عملاء HTTP ومشغّلات قواعد البيانات، تعيده (مغلّفًا غالبًا) عند نفاد الوقت. تحقّق منه بـ errors.Is(err, context.DeadlineExceeded).

هل أستخدم context.WithValue لتمرير المعاملات؟

لا. استخدمها فقط للبيانات الخاصة بالطلب التي تعبر حدود الواجهات البرمجية ولا تحتاج الدوال الوسيطة إلى معرفتها، مثل معرّف التتبّع أو المستخدم الموثَّق. كل ما تحتاجه الدالة لأداء عملها مكانه معاملاتها، حيث يتحقّق منه المترجم.

مفاهيم ذات صلة