Time en Golang : Now, Sleep, Format, Parse et durées

L'essentiel en un programme

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() renvoie l'heure locale actuelle, time.Sleep met en pause la goroutine courante, time.Since mesure le temps écoulé, et time.Date construit un instant précis. La suite de cette page reprend chaque élément un par un. Les exemples utilisent des dates fixes et l'UTC pour que leur sortie soit la même où que vous les exécutiez.

Sleep et Duration

Un time.Duration est un int64 qui compte des nanosecondes. Le package définit des constantes pour construire des valeurs lisibles :

Il n'y a pas de time.Day, parce qu'une journée ne fait pas toujours 24 heures quand un fuseau horaire passe à l'heure d'été. Utilisez AddDate pour les jours calendaires (voir plus bas).

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

Deux bugs courants viennent du fait que Duration est un entier :

• time.Sleep(5) dort 5 nanosecondes. Multipliez toujours par une unité : time.Sleep(5 * time.Second).
• time.Sleep(n * time.Second) ne compile pas quand n est une variable int. Convertissez-la : time.Duration(n) * time.Second. Une constante comme 5 fonctionne sans conversion parce que les constantes non typées s'adaptent au type Duration.

ParseDuration accepte ns, us (ou µs), ms, s, m et h, combinés comme "2h45m" ou "1.5s". Il n'a pas d'unité pour les jours.

Formatage : la disposition de référence 2006-01-02

Go n'utilise ni %Y-%m-%d ni yyyy-MM-dd. Une disposition (layout) est l'heure de référence

Mon Jan 2 15:04:05 MST 2006

écrite comme vous voulez que votre sortie apparaisse. Les valeurs sont choisies pour que chacune soit unique : mois 1, jour 2, heure 3 (ou 15), minute 4, seconde 5, année 6 (2006), décalage horaire -7 (-0700). Lisez-la comme 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))
	}
}

Les éléments de disposition dont vous aurez le plus besoin :

Dispositions prédéfinies :

L'erreur classique consiste à écrire une disposition avec les mauvais chiffres, par exemple "2023-01-01". Go ne la rejette pas. Il recopie les caractères qu'il ne reconnaît pas et remplace ceux qu'il reconnaît : chaque 2 est le jour, 3 est l'heure sur 12 heures et les deux 01 sont le mois, donc le 5 mars à 9 h 07 s'affiche 5059-03-03. Une disposition comme "YYYY-MM-DD" ne contient aucun élément et s'affiche telle quelle. Si des dates formatées ont l'air étranges, vérifiez que la disposition utilise exactement les valeurs de référence.

Parser des chaînes en instants

time.Parse(layout, value) utilise les mêmes dispositions, et renvoie une erreur que vous devez vérifier :

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

Sans fuseau dans l'entrée, Parse renvoie de l'UTC. La même chaîne d'heure locale peut désigner des instants différents selon le fuseau, c'est pourquoi ParseInLocation existe. Le message d'erreur nomme la partie qui n'a pas correspondu, ce qui aide quand vous déboguez une disposition.

Fuseaux horaires

Un time.Time est un instant plus une localisation utilisée pour l'affichage. Changer la localisation avec In change la façon dont il s'affiche, pas l'instant qu'il représente.

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 est toujours disponible. Stockez et transmettez les instants en UTC (ou en RFC 3339 avec un décalage) et ne convertissez que pour l'affichage.
• time.Local est le fuseau de la machine. Sur les serveurs et dans les conteneurs, c'est souvent l'UTC, et sur un portable ce n'est pas le cas, donc le code qui en dépend se comporte différemment selon l'endroit.
• time.LoadLocation("Europe/Berlin") lit la base IANA du système d'exploitation. Les images de conteneur minimales ne l'ont souvent pas, et l'appel renvoie alors une erreur. L'import blanc _ "time/tzdata" intègre la base dans votre binaire (environ 450 Ko) pour que cela fonctionne toujours. Gérez toujours l'erreur.
• time.FixedZone(name, offsetSeconds) crée un fuseau avec un décalage constant. Il n'a pas de règles d'heure d'été, donc utilisez-le pour des décalages que vous avez reçus, pas pour des régions nommées.

Arithmétique et comparaison

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

À remarquer dans la sortie :

• AddDate(0, 1, 0) sur le 31 janvier donne le 3 mars, pas le 28 février. Go ajoute un mois pour obtenir « 31 février » puis normalise le dépassement. Si vous avez besoin de « même jour le mois suivant, borné », écrivez cette logique vous-même.
• Sub renvoie une Duration, qui plafonne à environ 292 ans. Pour des différences en jours calendaires, comparez des dates à minuit UTC et divisez par 24 heures.
• Pour obtenir le début de la journée, reconstruisez l'instant à partir de Date(). t.Truncate(24 * time.Hour) arrondit par rapport à l'instant zéro en UTC, donc donne une mauvaise réponse pour tout fuseau autre que l'UTC.

Comparez avec Equal, Before, After, jamais avec ==. time.Now() inclut une lecture de l'horloge monotone, utilisée pour que time.Since reste correct si l'horloge murale est ajustée. == compare aussi cette lecture et la localisation, donc deux valeurs Time du même instant peuvent être inégales. Pour la même raison, n'utilisez pas time.Time comme clé de map sans le normaliser d'abord (t.UTC().Round(0) retire la lecture monotone).

Le time.Time zéro est le 1er janvier de l'an 1, 00:00 UTC. Testez-le avec t.IsZero().

Mesurer le temps écoulé

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

time.Since(start) équivaut à time.Now().Sub(start), et time.Until(deadline) à deadline.Sub(time.Now()). Les deux utilisent l'horloge monotone quand elle est disponible, donc ils résistent aux changements de l'horloge système. Pour mesurer les performances du code, utilisez les benchmarks du package testing plutôt qu'un chronométrage à la main.

Timers et tickers

time.After(d) renvoie un channel qui reçoit une fois après d. Un time.Timer est la même chose avec une méthode Stop. Un time.Ticker fournit une valeur à chaque période jusqu'à ce que vous l'arrêtiez.

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

Les trois ticks à 20, 40 et 60 ms arrivent bien avant le timer de 110 ms, donc le programme s'arrête après le troisième tick. time.AfterFunc(d, f) exécute f dans sa propre goroutine après d, ce qui est pratique pour un travail différé ponctuel.

Depuis Go 1.23, les timers et tickers qui ne sont plus référencés sont récupérés par le ramasse-miettes même si vous n'appelez jamais Stop, et le channel d'un timer arrêté ou réinitialisé ne fournit plus de valeur périmée. Appeler Stop avec defer reste la façon claire de dire que la vie du ticker est terminée. Quand une limite de temps s'applique à toute une opération plutôt qu'à une seule attente, un context.WithTimeout se lit généralement mieux qu'un timer.

Le temps en JSON

time.Time se sérialise automatiquement en JSON vers et depuis des chaînes RFC 3339, avec une précision à la nanoseconde :

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

Une chaîne JSON dans un autre format échoue à la désérialisation. Pour des timestamps Unix ou des formats personnalisés, stockez un int64 ou une chaîne et convertissez, ou définissez un type avec son propre UnmarshalJSON.

Erreurs courantes

• time.Sleep(1) ou time.Sleep(n) avec un nombre seul. Ce sont des nanosecondes.
• Des dispositions avec les mauvais chiffres. "2023-01-01" ou "YYYY-MM-DD" ne sont pas des dispositions. Utilisez "2006-01-02".
• Confondre minutes et mois. Les minutes sont 04, les mois 01. "15:01" affiche l'heure puis le mois, pas la minute.
• Comparer avec ==. Utilisez Equal.
• Compter sur time.Local. Il diffère d'une machine à l'autre. Soyez explicite avec time.UTC ou une localisation chargée.
• Ignorer l'erreur de LoadLocation ou de Parse. Les deux échouent sur de vraies entrées. Un Parse en échec renvoie l'instant zéro, qui s'affiche comme l'an 1, et un LoadLocation en échec renvoie une localisation nil qui fait paniquer t.In(loc).