الوقت في Golang: Now وSleep وFormat وParse والمدد

الأساسيات في برنامج واحد

package main

import (
	"fmt"
	"time"
)

func main() {
	start := time.Now()

	time.Sleep(50 * time.Millisecond)

	elapsed := time.Since(start)
	fmt.Println("slept at least 50ms:", elapsed >= 50*time.Millisecond)

	t := time.Date(2026, time.September, 23, 14, 30, 0, 0, time.UTC)
	fmt.Println(t)
	fmt.Println(t.Format("2006-01-02 15:04"))
	fmt.Println(t.Format("Monday, January 2, 2006"))
	fmt.Println("in 90 minutes:", t.Add(90*time.Minute).Format(time.Kitchen))
}

تعيد time.Now() الوقت المحلي الحالي، وتوقف time.Sleep الـ goroutine الحالية، وتقيس time.Since الوقت المنقضي، وتبني time.Date لحظة محدّدة. تتناول بقية هذه الصفحة كل قطعة بدورها. تستخدم الأمثلة تواريخ ثابتة وتوقيت UTC لتكون مخرجاتها واحدة أينما شغّلتها.

Sleep وDuration

الـ time.Duration عدد من النوع int64 للنانوثواني. تعرّف الحزمة ثوابت لبناء قيم مقروءة:

لا يوجد time.Day، لأن اليوم ليس دائمًا 24 ساعة عندما تتغيّر المنطقة الزمنية للتوقيت الصيفي. استخدم AddDate للأيام التقويمية (انظر أدناه).

package main

import (
	"fmt"
	"time"
)

func main() {
	d := 90 * time.Minute
	fmt.Println(d)                      // 1h30m0s
	fmt.Println(d.Hours(), d.Minutes()) // float64 values
	fmt.Println(2*time.Hour + 15*time.Second)

	// Multiplying by a variable needs a conversion: int * Duration does not compile.
	retries := 3
	backoff := time.Duration(retries) * 200 * time.Millisecond
	fmt.Println("backoff:", backoff)

	// Parse a duration from a string (for flags and config files).
	timeout, err := time.ParseDuration("1m30s")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("timeout:", timeout, "=", timeout.Seconds(), "seconds")

	// Round and truncate a measured duration for display.
	measured := 1234567891 * time.Nanosecond
	fmt.Println(measured, measured.Round(time.Millisecond), measured.Truncate(time.Second))
}

خطآن شائعان يأتيان من كون Duration عددًا صحيحًا:

• time.Sleep(5) تنام 5 نانوثوانٍ. اضرب دائمًا بوحدة: time.Sleep(5 * time.Second).
• time.Sleep(n * time.Second) لا تُترجم عندما يكون n متغيّرًا من النوع int. حوّله: time.Duration(n) * time.Second. والثابت مثل 5 يعمل دون تحويل لأن الثوابت عديمة النوع تتكيّف مع النوع Duration.

تقبل ParseDuration الوحدات ns وus (أو µs) وms وs وm وh، مدمجة مثل "2h45m" أو "1.5s". ولا وحدة فيها للأيام.

التنسيق: تخطيط المرجع 2006-01-02

لا تستخدم Go الصيغة %Y-%m-%d ولا yyyy-MM-dd. التخطيط هو الوقت المرجعي

Mon Jan 2 15:04:05 MST 2006

مكتوبًا بالشكل الذي تريد أن تبدو به مخرجاتك. اختيرت القيم بحيث تكون كل منها فريدة: الشهر 1، واليوم 2، والساعة 3 (أو 15)، والدقيقة 4، والثانية 5، والسنة 6 (2006)، وإزاحة المنطقة -7 (-0700). اقرأها هكذا: 01/02 03:04:05PM '06 -0700.

package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.Date(2026, time.March, 5, 9, 7, 3, 250_000_000, time.UTC)

	layouts := []string{
		"2006-01-02",
		"02/01/2006",
		"01/02/06",
		"Jan 2, 2006",
		"Monday 2 January 2006",
		"15:04:05",
		"3:04 PM",
		"2006-01-02T15:04:05.000Z07:00",
		time.RFC3339,
		time.DateTime,
		time.RFC1123,
	}
	for _, l := range layouts {
		fmt.Printf("%-32q %s\n", l, t.Format(l))
	}
}

رموز التخطيط التي ستحتاجها أكثر:

التخطيطات المعرّفة مسبقًا:

الخطأ الكلاسيكي كتابة تخطيط بأرقام خاطئة، مثل "2023-01-01". لا ترفضه Go. بل تنسخ الأحرف التي لا تعرفها وتستبدل التي تعرفها: كل 2 هو اليوم، و3 ساعة نظام 12 ساعة، و01 كلاهما الشهر، فيُنسَّق 5 مارس الساعة 9:07 بالشكل 5059-03-03. والتخطيط مثل "YYYY-MM-DD" لا يحتوي أي رموز أصلًا فيطبع نفسه دون تغيير. إذا بدت التواريخ المنسّقة غريبة، فتحقّق من أن التخطيط يستخدم قيم المرجع بالضبط.

تحليل النصوص إلى أوقات

تستخدم time.Parse(layout, value) التخطيطات نفسها، وتعيد خطأ يجب أن تفحصه:

package main

import (
	"fmt"
	"time"
)

func main() {
	t, err := time.Parse("2006-01-02 15:04", "2026-09-23 18:45")
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t, "| location:", t.Location())

	// A string with an offset keeps that offset.
	t2, err := time.Parse(time.RFC3339, "2026-09-23T18:45:00+02:00")
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t2, "| in UTC:", t2.UTC())

	// Interpret a zone-less string in a specific zone.
	tokyo := time.FixedZone("JST", 9*60*60)
	t3, err := time.ParseInLocation(time.DateTime, "2026-09-23 18:45:00", tokyo)
	if err != nil {
		fmt.Println("parse error:", err)
		return
	}
	fmt.Println(t3, "| in UTC:", t3.UTC())

	// A wrong input produces a descriptive error.
	_, err = time.Parse(time.DateOnly, "23/09/2026")
	fmt.Println("error:", err)
}

دون منطقة في المدخل تعيد Parse توقيت UTC. النص نفسه لوقت الساعة قد يعني لحظات مختلفة حسب المنطقة، ولهذا توجد ParseInLocation. تسمّي رسالة الخطأ الجزء الذي فشلت مطابقته، وهذا يساعد عند تتبّع أخطاء تخطيط.

المناطق الزمنية

الـ time.Time لحظة زائد موقع يُستخدم للعرض. تغيير الموقع بـ In يغيّر طريقة الطباعة، لا اللحظة.

package main

import (
	"fmt"
	"time"
	_ "time/tzdata" // embed the zone database so LoadLocation works anywhere
)

func main() {
	meeting := time.Date(2026, time.September, 23, 15, 0, 0, 0, time.UTC)

	ny, err := time.LoadLocation("America/New_York")
	if err != nil {
		fmt.Println("load location:", err)
		return
	}
	india := time.FixedZone("IST", 5*60*60+30*60) // +05:30, no DST rules

	fmt.Println("UTC:     ", meeting.Format(time.RFC1123))
	fmt.Println("New York:", meeting.In(ny).Format(time.RFC1123))
	fmt.Println("India:   ", meeting.In(india).Format(time.RFC1123))
	fmt.Println("same instant:", meeting.Equal(meeting.In(ny)))
}

• time.UTC متاح دائمًا. خزّن الأوقات وأرسلها بتوقيت UTC (أو RFC 3339 مع إزاحة) وحوّل فقط للعرض.
• time.Local هي منطقة الجهاز. على الخوادم وفي الحاويات تكون غالبًا UTC، وعلى الحاسوب المحمول ليست كذلك، فتتصرّف الشيفرة التي تعتمد عليها بشكل مختلف في كل مكان.
• تقرأ time.LoadLocation("Europe/Berlin") قاعدة بيانات IANA من نظام التشغيل. صور الحاويات المصغّرة تفتقدها غالبًا، فيعيد الاستدعاء عندها خطأ. الاستيراد الفارغ _ "time/tzdata" يضمّن قاعدة البيانات في ملفك التنفيذي (نحو 450 KB) فتعمل دائمًا. عالج الخطأ دائمًا.
• تنشئ time.FixedZone(name, offsetSeconds) منطقة بإزاحة ثابتة. لا قواعد توقيت صيفي فيها، فاستخدمها للإزاحات التي تلقّيتها، لا للمناطق المسمّاة.

الحساب والمقارنة

package main

import (
	"fmt"
	"time"
)

func main() {
	start := time.Date(2026, time.January, 31, 10, 0, 0, 0, time.UTC)
	end := time.Date(2026, time.March, 1, 12, 30, 0, 0, time.UTC)

	fmt.Println("difference:", end.Sub(start))
	fmt.Println("in days:   ", int(end.Sub(start).Hours()/24))

	fmt.Println("+36h:      ", start.Add(36*time.Hour).Format(time.DateTime))
	fmt.Println("-1 week:   ", start.AddDate(0, 0, -7).Format(time.DateOnly))
	fmt.Println("+1 month:  ", start.AddDate(0, 1, 0).Format(time.DateOnly)) // Jan 31 + 1 month

	fmt.Println("before:", start.Before(end), "after:", start.After(end), "equal:", start.Equal(end))

	// Start of the day, and parts of a date.
	y, m, d := end.Date()
	midnight := time.Date(y, m, d, 0, 0, 0, 0, end.Location())
	fmt.Println("midnight:", midnight.Format(time.DateTime))
	fmt.Println("weekday:", end.Weekday(), "day of year:", end.YearDay())

	// Unix timestamps.
	fmt.Println("unix:", start.Unix(), "ms:", start.UnixMilli())
	fmt.Println("from unix:", time.Unix(1_790_000_000, 0).UTC())
}

أمور تلاحظها في المخرجات:

• تعطي AddDate(0, 1, 0) على 31 يناير 3 مارس، لا 28 فبراير. تضيف Go شهرًا لتحصل على "31 فبراير" ثم تطبّع الفائض. إذا احتجت "اليوم نفسه في الشهر التالي مع التقييد بآخر الشهر"، فاكتب ذلك المنطق بنفسك.
• تعيد Sub قيمة Duration، وحدّها الأقصى نحو 292 سنة. للفروق بالأيام التقويمية، قارن التواريخ عند منتصف الليل UTC واقسم على 24 ساعة.
• للحصول على بداية اليوم، أعد بناء الوقت من Date(). تقرّب t.Truncate(24 * time.Hour) بالنسبة إلى الوقت الصفري في UTC، فتعطي إجابة خاطئة لأي منطقة غير UTC.

قارن بـ Equal وBefore وAfter، ولا تقارن بـ == أبدًا. يتضمّن time.Now() قراءة ساعة رتيبة، تُستخدم لتبقى time.Since صحيحة إذا عُدّلت ساعة النظام. تقارن == تلك القراءة والموقع أيضًا، فقد لا تتساوى قيمتا Time للحظة نفسها. وللسبب نفسه لا تستخدم time.Time مفتاحًا لخريطة دون تطبيعه أولًا (تزيل t.UTC().Round(0) القراءة الرتيبة).

الـ time.Time الصفري هو 1 يناير من السنة 1، الساعة 00:00 UTC. افحصه بـ t.IsZero().

قياس الوقت المنقضي

start := time.Now()
doWork()
log.Printf("doWork took %v", time.Since(start))

time.Since(start) تساوي time.Now().Sub(start)، وtime.Until(deadline) تساوي deadline.Sub(time.Now()). كلتاهما تستخدمان الساعة الرتيبة عند توفّرها، فهما آمنتان من تغييرات ساعة النظام. ولقياس أداء الشيفرة استخدم دعم قياس الأداء في الحزمة testing بدل التوقيت اليدوي.

المؤقّتات والـ tickers

تعيد time.After(d) قناة تستقبل مرة واحدة بعد d. وtime.Timer هو الشيء نفسه مع تابع Stop. وtime.Ticker يسلّم قيمة كل فترة حتى توقفه.

package main

import (
	"fmt"
	"time"
)

func main() {
	ticker := time.NewTicker(20 * time.Millisecond)
	defer ticker.Stop()

	done := time.NewTimer(110 * time.Millisecond)
	defer done.Stop()

	ticks := 0
	for {
		select {
		case <-ticker.C:
			ticks++
			fmt.Println("tick", ticks)
			if ticks == 3 {
				fmt.Println("got three ticks, stopping early")
				return
			}
		case <-done.C:
			fmt.Println("timer fired first")
			return
		}
	}
}

تصل النبضات الثلاث عند 20 و40 و60 ms قبل مؤقّت الـ 110 ms بوقت طويل، فيتوقّف البرنامج بعد النبضة الثالثة. تشغّل time.AfterFunc(d, f) الدالة f في goroutine خاصة بها بعد d، وهذا مفيد لعمل مؤجّل لمرة واحدة.

منذ Go 1.23 تُجمع المؤقّتات والـ tickers التي لم يعد يشير إليها شيء حتى لو لم تستدعِ Stop قط، ولم تعد قناة المؤقّت الموقوف أو المعاد ضبطه تسلّم قيمة قديمة. لكن استدعاء Stop مع defer يبقى الطريقة الواضحة للقول إن حياة الـ ticker انتهت. وعندما ينطبق حد زمني على عملية كاملة لا على انتظار واحد، تُقرأ context.WithTimeout عادة أفضل من مؤقّت.

الوقت في JSON

يُسلسَل time.Time من نصوص RFC 3339 وإليها في JSON تلقائيًا، بدقة النانوثانية:

type Event struct {
	Name string    `json:"name"`
	At   time.Time `json:"at"`
}
// {"name":"deploy","at":"2026-09-23T14:30:00Z"}

نص JSON بصيغة مختلفة يفشل فكّ ترميزه. للطوابع الزمنية Unix أو الصيغ المخصّصة، خزّن int64 أو نصًا وحوّل، أو عرّف نوعًا له UnmarshalJSON خاص به.

أخطاء شائعة

• time.Sleep(1) أو time.Sleep(n) برقم مجرّد. هذه نانوثوانٍ.
• تخطيطات بأرقام خاطئة. "2023-01-01" و"YYYY-MM-DD" ليست تخطيطات. استخدم "2006-01-02".
• الخلط بين الدقائق والشهور. الدقائق 04، والشهور 01. تطبع "15:01" الساعة ثم الشهر، لا الدقيقة.
• المقارنة بـ ==. استخدم Equal.
• الاعتماد على time.Local. تختلف بين الأجهزة. كن صريحًا بـ time.UTC أو بموقع محمّل.
• تجاهل الخطأ الصادر عن LoadLocation أو Parse. كلتاهما تفشلان مع المدخلات الحقيقية. تعيد Parse الفاشلة الوقت الصفري، الذي يُطبع كسنة 1، وتعيد LoadLocation الفاشلة موقعًا nil يجعل t.In(loc) تسبّب panic.