time em Golang: Now, Sleep, Format, Parse e durações

O básico em um programa

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() devolve o horário local atual, time.Sleep pausa a goroutine atual, time.Since mede o tempo decorrido e time.Date monta um momento específico. O resto da página trata de cada peça. Os exemplos usam datas fixas e UTC para que a saída seja a mesma onde quer que você os execute.

Sleep e Duration

Um time.Duration é um int64 que conta nanossegundos. O pacote define constantes para montar valores legíveis:

Não existe time.Day, porque um dia nem sempre tem 24 horas quando um fuso horário muda por causa do horário de verão. Use AddDate para dias de calendário (veja abaixo).

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

Dois bugs comuns vêm de o Duration ser um inteiro:

• time.Sleep(5) dorme 5 nanossegundos. Sempre multiplique por uma unidade: time.Sleep(5 * time.Second).
• time.Sleep(n * time.Second) não compila quando n é uma variável int. Converta: time.Duration(n) * time.Second. Uma constante como 5 funciona sem conversão porque constantes não tipadas se adaptam ao tipo Duration.

ParseDuration aceita ns, us (ou µs), ms, s, m e h, combinados como "2h45m" ou "1.5s". Ele não tem unidade para dias.

Formatação: o layout de referência 2006-01-02

O Go não usa %Y-%m-%d nem yyyy-MM-dd. Um layout é o horário de referência

Mon Jan 2 15:04:05 MST 2006

escrito do jeito que você quer que a saída fique. Os valores foram escolhidos para que cada um seja único: mês 1, dia 2, hora 3 (ou 15), minuto 4, segundo 5, ano 6 (2006), deslocamento de fuso -7 (-0700). Leia como 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))
	}
}

Os tokens de layout de que você mais vai precisar:

Layouts predefinidos:

O erro clássico é escrever um layout com os números errados, por exemplo "2023-01-01". O Go não o rejeita. Ele copia os caracteres que não reconhece e substitui os que reconhece: cada 2 é o dia, 3 é a hora no relógio de 12 horas e os dois 01 são o mês, então 5 de março às 9:07 fica formatado como 5059-03-03. Um layout como "YYYY-MM-DD" não contém nenhum token e imprime a si mesmo sem mudança. Se as datas formatadas parecerem estranhas, confira se o layout usa exatamente os valores de referência.

Convertendo strings em horários

time.Parse(layout, value) usa os mesmos layouts e devolve um erro que você precisa verificar:

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

Sem fuso na entrada, o Parse devolve UTC. A mesma string de horário pode significar instantes diferentes dependendo do fuso, e é por isso que existe o ParseInLocation. A mensagem de erro nomeia a parte que não casou, o que ajuda quando você está depurando um layout.

Fusos horários

Um time.Time é um instante mais uma localização usada na exibição. Mudar a localização com In muda como ele é impresso, não qual momento ele é.

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á sempre disponível. Guarde e transmita horários em UTC (ou em RFC 3339 com deslocamento) e converta só para exibir.
• time.Local é o fuso da máquina. Em servidores e containers muitas vezes é UTC, e em um notebook não é, então o código que depende dele se comporta de forma diferente em cada lugar.
• time.LoadLocation("Europe/Berlin") lê o banco de dados IANA do sistema operacional. Imagens de container mínimas muitas vezes não o têm, e aí a chamada devolve um erro. O import em branco _ "time/tzdata" embute o banco no seu binário (cerca de 450 KB) para que sempre funcione. Sempre trate o erro.
• time.FixedZone(name, offsetSeconds) cria um fuso com deslocamento constante. Ele não tem regras de horário de verão, então use-o para deslocamentos que você recebeu, não para regiões com nome.

Aritmética e comparação

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

O que reparar na saída:

• AddDate(0, 1, 0) em 31 de janeiro dá 3 de março, não 28 de fevereiro. O Go soma um mês, chega a "31 de fevereiro" e depois normaliza o excesso. Se você precisa de "mesmo dia do mês seguinte, limitado ao fim do mês", escreva essa lógica você mesmo.
• Sub devolve um Duration, que chega no máximo a cerca de 292 anos. Para diferenças em dias de calendário, compare as datas à meia-noite UTC e divida por 24 horas.
• Para pegar o início do dia, remonte o horário a partir de Date(). t.Truncate(24 * time.Hour) arredonda em relação ao tempo zero em UTC, então dá a resposta errada para qualquer fuso diferente de UTC.

Compare com Equal, Before e After, nunca com ==. time.Now() inclui uma leitura do relógio monotônico, usada para que time.Since continue correto se o relógio de parede for ajustado. O == compara essa leitura e também a localização, então dois valores Time do mesmo instante podem ser diferentes. Pelo mesmo motivo, não use time.Time como chave de map sem normalizá-lo antes (t.UTC().Round(0) remove a leitura monotônica).

O time.Time zero é 1º de janeiro do ano 1, 00:00 UTC. Verifique-o com t.IsZero().

Medindo o tempo decorrido

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

time.Since(start) é time.Now().Sub(start), e time.Until(deadline) é deadline.Sub(time.Now()). Os dois usam o relógio monotônico quando disponível, então ficam imunes a mudanças no relógio do sistema. Para fazer benchmark de código, use o suporte a benchmarks do pacote testing em vez de medir à mão.

Timers e tickers

time.After(d) devolve um channel que recebe uma vez depois de d. Um time.Timer é a mesma coisa com um método Stop. Um time.Ticker entrega um valor a cada período até você pará-lo.

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

Os três ticks em 20, 40 e 60 ms chegam bem antes do timer de 110 ms, então o programa para depois do terceiro tick. time.AfterFunc(d, f) executa f na sua própria goroutine depois de d, o que é prático para trabalhos atrasados avulsos.

Desde o Go 1.23, timers e tickers que não são mais referenciados são recolhidos pelo coletor de lixo mesmo que você nunca chame Stop, e o channel de um timer parado ou reiniciado não entrega mais um valor velho. Chamar Stop com defer continua sendo a forma clara de dizer que a vida do ticker acabou. Quando um limite de tempo vale para uma operação inteira, e não para uma única espera, um context.WithTimeout costuma ficar mais legível que um timer.

Horários em JSON

time.Time é convertido para e de strings RFC 3339 no JSON automaticamente, com precisão de nanossegundos:

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

Uma string JSON em outro formato falha no unmarshal. Para timestamps Unix ou formatos próprios, guarde um int64 ou uma string e converta, ou defina um tipo com o seu próprio UnmarshalJSON.

Erros comuns

• time.Sleep(1) ou time.Sleep(n) com um número puro. São nanossegundos.
• Layouts com os dígitos errados. "2023-01-01" ou "YYYY-MM-DD" não são layouts. Use "2006-01-02".
• Confundir minutos e meses. Minutos são 04, meses são 01. "15:01" imprime a hora e depois o mês, não o minuto.
• Comparar com ==. Use Equal.
• Depender de time.Local. Ele muda de máquina para máquina. Seja explícito com time.UTC ou com uma localização carregada.
• Ignorar o erro de LoadLocation ou Parse. Os dois falham com entradas reais. Um Parse que falhou devolve o horário zero, que é impresso como ano 1, e um LoadLocation que falhou devolve uma localização nil que faz t.In(loc) causar panic.