Fuso Horário & Gotchas do time.Parse

Um relatório mostra a data de ontem para eventos que aconteceram hoje, mas apenas para usuários em um fuso horário e apenas após o horário de verão.

Esta página cobre as regras de localização do time.Parse, o comportamento do relógio monotônico, a serialização JSON e as etapas de depuração que expõem defeitos de tempo sem adivinhação.

Resumo

Valores time.Time representam um instante na linha do tempo mais um local opcional para exibição.

Erros de análise - omitir a zona no layout, misturar local e UTC, ignorar o horário de verão - produzem bugs sutis de horas de diferença que testes em uma zona não detectam.

APIs JSON adicionam outra camada: a serialização padrão usa RFC3339 UTC, enquanto os clientes podem interpretar strings como hora local de parede.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// Analisa com zona explícita no layout
t, err := time.Parse(time.RFC3339, "2026-07-15T09:00:00-07:00")
 
// Analisa hora local de parede em uma zona específica
loc, _ := time.LoadLocation("America/Los_Angeles")
t, err := time.ParseInLocation("2006-01-02 15:04", "2026-07-15 09:00", loc)
 
// Armazena/compara em UTC, exibe na zona do usuário
utc := t.UTC()
display := utc.In(loc)

Quando usar isso:

• Análise de timestamps CSV ou de log sem deslocamentos
• APIs JSON que aceitam strings de data
• Agendamento de tarefas entre limites de horário de verão
• Comparação de time.Now() com tempos históricos analisados
• Depuração de "funciona no dev, errado na produção" com desvio de fuso horário

Exemplo de Trabalho

package main
 
import (
    "encoding/json"
    "fmt"
    "time"
)
 
type Event struct {
    At time.Time `json:"at"`
}
 
func main() {
    // Análise sem zona -> UTC
    t1, _ := time.Parse("2006-01-02 15:04:05", "2026-07-15 09:00:00")
    fmt.Println("analisado sem zona:", t1.Format(time.RFC3339), "loc", t1.Location())
 
    loc, _ := time.LoadLocation("America/New_York")
    t2, _ := time.ParseInLocation("2006-01-02 15:04:05", "2026-07-15 09:00:00", loc)
    fmt.Println("analisado NY:     ", t2.Format(time.RFC3339), "loc", t2.Location())
 
    fmt.Println("instante igual?", t1.Equal(t2))
 
    b, _ := json.Marshal(Event{At: t2})
    fmt.Println("json:", string(b))
}

O que isso demonstra:

• time.Parse sem zona na string de layout atribui UTC para entrada sem zona
• Os mesmos dígitos de relógio de parede em zonas diferentes são instantes diferentes
• Equal compara instantes; a saída de Format depende do local
• JSON usa RFC3339 com deslocamento ou Z para UTC

Análise Profunda

Como Funciona

• Layout de tempo de referência: Mon Jan 2 15:04:05 MST 2006 → use o estilo 2006-01-02 nos layouts
• time.Parse usa UTC quando o layout não tem zona; ParseInLocation define a zona pretendida
• Relógio monotônico: time.Time pode incluir leitura monotônica para Sub/Since; removido por Format e JSON
• time.Now() retorna a zona local do ambiente, a menos que você chame UTC()

JSON e APIs

Notas do Go

// Compare instantes, não strings formatadas
if !a.UTC().Equal(b.UTC()) { /* momento diferente */ }
 
// Trunca para o dia do calendário em uma zona
day := time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, loc)

Gotchas

• Análise sem zona no layout - A entrada "2006-01-02 15:04:05" se torna UTC, não local. Correção: ParseInLocation ou exija deslocamento na entrada.
• Comparando saídas de Format - Strings diferem para o mesmo instante em zonas diferentes. Correção: Equal ou compare unix UTC.
• Assumindo que time.Now().Location() é UTC em contêineres - Imagens sem TZ podem usar UTC; laptops usam local. Correção: defina TZ ou sempre UTC() em servidores.
• Falta de tzdata em imagens scratch - LoadLocation falha em distroless sem o pacote tzdata. Correção: incorpore a importação _ "time/tzdata".
• Lacuna e sobreposição do horário de verão - Horas locais de parede podem ser ambíguas ou inexistentes uma vez por ano. Correção: armazene UTC; converta apenas para exibição.
• Subtração de tempos de fontes diferentes - Mistura de tempos monotônicos vs. apenas de relógio em Sub. Correção: use t.UTC() antes da aritmética entre tempos analisados e de relógio.

Y29kZWd1aWRlcy5pb3xjZ2lvNDk4fDIwMjYwNw==

Alternativas

FAQs

Relacionados

• Depurando Go: Falhas Observáveis e Bordas Afiadas - família de sintomas de desvio de tempo
• Noções Básicas de Depuração Go - registre RFC3339 e locais
• Tags de Struct para JSON, DB e Validação - tags e formatos de campo de tempo
• Melhores Práticas de Tipos de Dados - semântica de valor comparável
• Melhores Práticas de Depuração e Cenários de Defeito - regras de registro de tempo de incidentes

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).