Time ב-Golang: Now, Sleep, Format, Parse ו-Durations

הבסיס בתוכנית אחת

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

ה-tokens של הפריסה שתצטרכו הכי הרבה:

פריסות מוגדרות מראש:

הטעות הקלאסית היא לכתוב פריסה עם המספרים הלא נכונים, למשל "2023-01-01". Go לא דוחה אותה. היא מעתיקה תווים שהיא לא מזהה ומחליפה את אלה שהיא כן מזהה: כל 2 הוא היום, 3 הוא השעה בשעון של 12 שעות ושני ה-01 הם החודש, כך ש-5 במרץ בשעה 9:07 מעוצב כ-5059-03-03. פריסה כמו "YYYY-MM-DD" לא מכילה אף token ומודפסת כמו שהיא. אם תאריכים מעוצבים נראים מוזר, בדקו שהפריסה משתמשת בדיוק בערכי הייחוס.

פענוח מחרוזות לזמנים

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 כמפתח של map בלי לנרמל אותו קודם (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()). שתיהן משתמשות בשעון המונוטוני כשהוא זמין, ולכן הן בטוחות מפני שינויים בשעון המערכת. למדידת ביצועים של קוד, השתמשו בתמיכה של Go ב-benchmarks בחבילה testing במקום למדוד זמן ביד.

Timers ו-tickers

time.After(d) מחזירה channel שמקבל ערך פעם אחת אחרי 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
		}
	}
}

שלושת ה-ticks ב-20, 40 ו-60 ms מגיעים הרבה לפני ה-timer של 110 ms, כך שהתוכנית נעצרת אחרי ה-tick השלישי. time.AfterFunc(d, f) מריצה את f ב-goroutine משלה אחרי d, וזה נוח לעבודה חד פעמית מושהית.

מאז Go 1.23, timers ו-tickers שאין אליהם עוד הפניה מפונים על ידי ה-garbage collector גם אם אף פעם לא קוראים ל-Stop, וה-channel של timer שנעצר או אופס כבר לא מספק ערך ישן. קריאה ל-Stop עם defer היא עדיין הדרך הברורה לומר שחייו של ה-ticker הסתיימו. כשמגבלת זמן חלה על פעולה שלמה ולא על המתנה אחת, context.WithTimeout בדרך כלל נקרא טוב יותר מ-timer.

זמן ב-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 בפורמט אחר נכשלת ב-unmarshal. ל-Unix timestamps או לפורמטים מותאמים, שמרו 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.