Czas w Golang: Now, Sleep, Format, Parse i Duration

Podstawy w jednym programie

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() zwraca bieżący czas lokalny, time.Sleep wstrzymuje bieżącą goroutine, time.Since mierzy upływ czasu, a time.Date tworzy konkretną chwilę. Reszta tej strony omawia każdy element po kolei. Przykłady używają stałych dat i UTC, więc ich wynik jest taki sam, gdziekolwiek je uruchomisz.

Sleep i Duration

time.Duration to liczba nanosekund typu int64. Pakiet definiuje stałe do tworzenia czytelnych wartości:

Nie ma time.Day, bo doba nie zawsze ma 24 godziny, gdy strefa czasowa zmienia się przy przejściu na czas letni. Do dni kalendarzowych używaj AddDate (patrz niżej).

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

Dwa częste błędy wynikają z tego, że Duration to liczba całkowita:

• time.Sleep(5) usypia na 5 nanosekund. Zawsze mnóż przez jednostkę: time.Sleep(5 * time.Second).
• time.Sleep(n * time.Second) się nie kompiluje, gdy n jest zmienną typu int. Skonwertuj ją: time.Duration(n) * time.Second. Stała taka jak 5 działa bez konwersji, bo stałe bez typu dopasowują się do typu Duration.

ParseDuration przyjmuje ns, us (lub µs), ms, s, m i h, łączone w stylu "2h45m" lub "1.5s". Nie ma jednostki dla dni.

Formatowanie: układ wzorcowy 2006-01-02

Go nie używa %Y-%m-%d ani yyyy-MM-dd. Układ to czas wzorcowy

Mon Jan 2 15:04:05 MST 2006

zapisany tak, jak ma wyglądać wynik. Wartości dobrano tak, by każda była unikalna: miesiąc 1, dzień 2, godzina 3 (lub 15), minuta 4, sekunda 5, rok 6 (2006), przesunięcie strefy -7 (-0700). Czytaj to jako 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))
	}
}

Najczęściej potrzebne tokeny układu:

Predefiniowane układy:

Klasyczny błąd to układ zapisany złymi liczbami, na przykład "2023-01-01". Go go nie odrzuca. Kopiuje znaki, których nie rozpoznaje, i podstawia te, które rozpoznaje: każda 2 to dzień, 3 to godzina w zegarze 12-godzinnym, a oba 01 to miesiąc, więc 5 marca o 9:07 zostaje sformatowany jako 5059-03-03. Układ taki jak "YYYY-MM-DD" nie zawiera żadnych tokenów i wypisuje się bez zmian. Jeśli sformatowane daty wyglądają dziwnie, sprawdź, czy układ używa dokładnie wartości wzorcowych.

Parsowanie stringów na czas

time.Parse(layout, value) używa tych samych układów i zwraca błąd, który musisz sprawdzić:

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

Bez strefy w danych wejściowych Parse zwraca UTC. Ten sam zapis czasu zegarowego może oznaczać różne chwile w zależności od strefy, dlatego istnieje ParseInLocation. Komunikat błędu wskazuje część, która nie pasuje, co pomaga przy debugowaniu układu.

Strefy czasowe

time.Time to chwila plus lokalizacja używana do wyświetlania. Zmiana lokalizacji przez In zmienia sposób wypisywania, a nie to, jaka to chwila.

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 jest zawsze dostępne. Przechowuj i przesyłaj czasy w UTC (albo w RFC 3339 z przesunięciem) i konwertuj tylko do wyświetlania.
• time.Local to strefa maszyny. Na serwerach i w kontenerach to często UTC, a na laptopie nie, więc kod, który od niej zależy, zachowuje się różnie w każdym miejscu.
• time.LoadLocation("Europe/Berlin") czyta bazę IANA z systemu operacyjnego. Minimalne obrazy kontenerów często jej nie mają i wtedy wywołanie zwraca błąd. Pusty import _ "time/tzdata" osadza bazę w binarce (około 450 KB), więc zawsze działa. Zawsze obsługuj błąd.
• time.FixedZone(name, offsetSeconds) tworzy strefę ze stałym przesunięciem. Nie ma reguł czasu letniego, więc używaj jej dla otrzymanych przesunięć, a nie dla nazwanych regionów.

Arytmetyka i porównywanie

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

Na co zwrócić uwagę w wyniku:

• AddDate(0, 1, 0) dla 31 stycznia daje 3 marca, a nie 28 lutego. Go dodaje jeden miesiąc, otrzymuje „31 lutego”, a potem normalizuje nadmiar. Jeśli potrzebujesz „tego samego dnia w następnym miesiącu, przyciętego do jego końca”, napisz tę logikę samodzielnie.
• Sub zwraca Duration, która kończy się na około 292 latach. Dla różnic w dniach kalendarzowych porównuj daty o północy UTC i dziel przez 24 godziny.
• Aby dostać początek dnia, zbuduj czas na nowo z Date(). t.Truncate(24 * time.Hour) zaokrągla względem czasu zerowego w UTC, więc daje złą odpowiedź dla każdej strefy innej niż UTC.

Porównuj przez Equal, Before, After, nigdy przez ==. time.Now() zawiera odczyt zegara monotonicznego, dzięki któremu time.Since pozostaje poprawne, nawet gdy zegar systemowy zostanie przestawiony. == porównuje ten odczyt, a także lokalizację, więc dwie wartości Time dla tej samej chwili mogą być różne. Z tego samego powodu nie używaj time.Time jako klucza mapy bez wcześniejszej normalizacji (t.UTC().Round(0) usuwa odczyt monotoniczny).

Zerowy time.Time to 1 stycznia roku 1, 00:00 UTC. Sprawdzaj go przez t.IsZero().

Mierzenie upływu czasu

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

time.Since(start) to time.Now().Sub(start), a time.Until(deadline) to deadline.Sub(time.Now()). Oba używają zegara monotonicznego, gdy jest dostępny, więc są odporne na zmiany zegara systemowego. Do benchmarkowania kodu używaj wsparcia dla benchmarków w pakiecie testing zamiast ręcznego mierzenia czasu.

Timery i tickery

time.After(d) zwraca kanał, który odbiera wartość raz, po czasie d. time.Timer to to samo, ale z metodą Stop. time.Ticker dostarcza wartość co określony okres, dopóki go nie zatrzymasz.

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

Trzy tyknięcia po 20, 40 i 60 ms przychodzą długo przed timerem 110 ms, więc program kończy się po trzecim tyknięciu. time.AfterFunc(d, f) uruchamia f we własnej goroutine po czasie d, co przydaje się do jednorazowej opóźnionej pracy.

Od Go 1.23 timery i tickery, do których nie ma już odwołań, są zbierane przez garbage collector, nawet jeśli nigdy nie wywołasz Stop, a kanał zatrzymanego lub zresetowanego timera nie dostarcza już przestarzałej wartości. Wywołanie Stop przez defer nadal jasno mówi, że życie tickera się skończyło. Gdy limit czasu dotyczy całej operacji, a nie jednego oczekiwania, context.WithTimeout zwykle czyta się lepiej niż timer.

Czas w JSON

time.Time automatycznie serializuje się do stringów RFC 3339 w JSON i z nich deserializuje, z precyzją do nanosekund:

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

String JSON w innym formacie nie da się zdeserializować. Dla znaczników czasu Unix lub własnych formatów przechowuj int64 albo string i konwertuj, albo zdefiniuj typ z własną metodą UnmarshalJSON.

Typowe błędy

• time.Sleep(1) lub time.Sleep(n) z samą liczbą. To nanosekundy.
• Układy ze złymi cyframi. "2023-01-01" ani "YYYY-MM-DD" nie są układami. Użyj "2006-01-02".
• Mylenie minut z miesiącami. Minuty to 04, miesiące to 01. "15:01" wypisuje godzinę, a potem miesiąc, a nie minutę.
• Porównywanie przez ==. Użyj Equal.
• Poleganie na time.Local. Różni się między maszynami. Jawnie używaj time.UTC albo wczytanej lokalizacji.
• Ignorowanie błędu z LoadLocation lub Parse. Oba zawodzą na prawdziwych danych. Nieudane Parse zwraca czas zerowy, który wypisuje się jako rok 1, a nieudane LoadLocation zwraca lokalizację nil, przez którą t.In(loc) wywołuje panic.