Date e orari in Golang: Now, Sleep, Format, Parse e Duration

Le basi in un programma

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() restituisce l'ora locale attuale, time.Sleep mette in pausa la goroutine corrente, time.Since misura il tempo trascorso e time.Date costruisce un momento preciso. Il resto della pagina tratta ogni parte una alla volta. Gli esempi usano date fisse e UTC, così il loro output è lo stesso ovunque tu li esegua.

Sleep e Duration

Un time.Duration è un int64 che conta nanosecondi. Il pacchetto definisce delle costanti per costruire valori leggibili:

Non esiste time.Day, perché un giorno non dura sempre 24 ore quando un fuso orario cambia per l'ora legale. Usa AddDate per i giorni di calendario (vedi più avanti).

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

Due bug comuni nascono dal fatto che Duration è un intero:

• time.Sleep(5) dorme 5 nanosecondi. Moltiplica sempre per un'unità: time.Sleep(5 * time.Second).
• time.Sleep(n * time.Second) non compila quando n è una variabile int. Convertila: time.Duration(n) * time.Second. Una costante come 5 funziona senza conversione perché le costanti senza tipo si adattano al tipo Duration.

ParseDuration accetta ns, us (o µs), ms, s, m e h, combinati come "2h45m" o "1.5s". Non ha un'unità per i giorni.

Formattare: il layout di riferimento 2006-01-02

Go non usa %Y-%m-%d né yyyy-MM-dd. Un layout è l'orario di riferimento

Mon Jan 2 15:04:05 MST 2006

scritto nel modo in cui vuoi che appaia l'output. I valori sono scelti in modo che ognuno sia unico: mese 1, giorno 2, ora 3 (o 15), minuto 4, secondo 5, anno 6 (2006), offset del fuso -7 (-0700). Leggilo come 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))
	}
}

I token di layout che userai di più:

Layout predefiniti:

L'errore classico è scrivere un layout con i numeri sbagliati, per esempio "2023-01-01". Go non lo rifiuta. Copia i caratteri che non riconosce e sostituisce quelli che riconosce: ogni 2 è il giorno, 3 è l'ora nel formato 12 ore ed entrambi gli 01 sono il mese, quindi il 5 marzo alle 9:07 diventa 5059-03-03. Un layout come "YYYY-MM-DD" non contiene nessun token e stampa se stesso invariato. Se le date formattate sembrano strane, controlla che il layout usi esattamente i valori di riferimento.

Convertire stringhe in date

time.Parse(layout, value) usa gli stessi layout e restituisce un errore che devi controllare:

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

Se l'input non ha un fuso, Parse restituisce UTC. La stessa stringa di ora locale può indicare istanti diversi a seconda del fuso, ed è per questo che esiste ParseInLocation. Il messaggio di errore indica la parte che non corrisponde, e questo aiuta quando fai il debug di un layout.

Fusi orari

Un time.Time è un istante più una location usata per la visualizzazione. Cambiare la location con In cambia il modo in cui viene stampato, non il momento che rappresenta.

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 è sempre disponibile. Memorizza e trasmetti gli orari in UTC (o in RFC 3339 con un offset) e converti solo per la visualizzazione.
• time.Local è il fuso della macchina. Su server e container è spesso UTC, su un portatile no, quindi il codice che dipende da esso si comporta in modo diverso in ogni posto.
• time.LoadLocation("Europe/Berlin") legge il database IANA dal sistema operativo. Le immagini container minimali spesso non ce l'hanno, e allora la chiamata restituisce un errore. L'import vuoto _ "time/tzdata" incorpora il database nel tuo binario (circa 450 KB) così funziona sempre. Gestisci sempre l'errore.
• time.FixedZone(name, offsetSeconds) crea un fuso con un offset costante. Non ha regole per l'ora legale, quindi usalo per offset che hai ricevuto, non per regioni con un nome.

Calcoli e confronti

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

Cose da notare nell'output:

• AddDate(0, 1, 0) sul 31 gennaio dà il 3 marzo, non il 28 febbraio. Go aggiunge un mese ottenendo il "31 febbraio" e poi normalizza l'eccedenza. Se ti serve "lo stesso giorno del mese successivo, limitato all'ultimo giorno", scrivi tu quella logica.
• Sub restituisce una Duration, che arriva al massimo a circa 292 anni. Per le differenze in giorni di calendario, confronta le date a mezzanotte UTC e dividi per 24 ore.
• Per ottenere l'inizio della giornata, ricostruisci l'orario da Date(). t.Truncate(24 * time.Hour) arrotonda rispetto all'orario zero in UTC, quindi dà la risposta sbagliata per qualsiasi fuso diverso da UTC.

Confronta con Equal, Before, After, mai con ==. time.Now() include una lettura dell'orologio monotono, usata perché time.Since resti corretto se l'orologio di sistema viene regolato. == confronta anche quella lettura e la location, quindi due valori Time per lo stesso istante possono risultare diversi. Per lo stesso motivo, non usare time.Time come chiave di una mappa senza prima normalizzarlo (t.UTC().Round(0) rimuove la lettura monotona).

Il time.Time al valore zero è il 1 gennaio dell'anno 1, 00:00 UTC. Verificalo con t.IsZero().

Misurare il tempo trascorso

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

time.Since(start) equivale a time.Now().Sub(start), e time.Until(deadline) equivale a deadline.Sub(time.Now()). Entrambi usano l'orologio monotono quando è disponibile, quindi non risentono delle modifiche all'orologio di sistema. Per fare benchmark del codice, usa il supporto ai benchmark di Go nel pacchetto testing invece di cronometrare a mano.

Timer e ticker

time.After(d) restituisce un canale che riceve un valore una volta dopo d. Un time.Timer è la stessa cosa con un metodo Stop. Un time.Ticker consegna un valore a ogni periodo finché non lo fermi.

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

I tre tick a 20, 40 e 60 ms arrivano ben prima del timer da 110 ms, quindi il programma si ferma dopo il terzo tick. time.AfterFunc(d, f) esegue f in una goroutine separata dopo d, comodo per un lavoro ritardato una tantum.

Da Go 1.23 timer e ticker non più referenziati vengono raccolti dal garbage collector anche se non chiami mai Stop, e il canale di un timer fermato o reimpostato non consegna più un valore scaduto. Chiamare Stop con defer resta il modo chiaro per dire che la vita del ticker è finita. Quando un limite di tempo si applica a un'intera operazione e non a una singola attesa, un context.WithTimeout di solito si legge meglio di un timer.

Date in JSON

time.Time viene convertito automaticamente da e verso stringhe RFC 3339 in JSON, con precisione al nanosecondo:

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

Una stringa JSON in un formato diverso non viene decodificata. Per timestamp Unix o formati personalizzati, memorizza un int64 o una stringa e converti, oppure definisci un tipo con un proprio UnmarshalJSON.

Errori comuni

• time.Sleep(1) o time.Sleep(n) con un numero da solo. Sono nanosecondi.
• Layout con le cifre sbagliate. "2023-01-01" o "YYYY-MM-DD" non sono layout. Usa "2006-01-02".
• Confondere minuti e mesi. I minuti sono 04, i mesi 01. "15:01" stampa l'ora e poi il mese, non il minuto.
• Confrontare con ==. Usa Equal.
• Affidarsi a time.Local. Cambia da una macchina all'altra. Sii esplicito con time.UTC o con una location caricata.
• Ignorare l'errore di LoadLocation o Parse. Entrambi falliscono con input reali. Un Parse fallito restituisce l'orario zero, che viene stampato come anno 1, e un LoadLocation fallito restituisce una location nil che fa andare in panic t.In(loc).