Zona horaria y errores de time.Parse

Un informe muestra la fecha de ayer para eventos que ocurrieron hoy, pero solo para usuarios en una zona horaria y solo después del horario de verano.

Esta página cubre las reglas de ubicación de time.Parse, el comportamiento del reloj monotónico, la serialización JSON y los pasos de depuración que exponen los defectos de tiempo sin adivinar.

Resumen

Los valores time.Time representan un instante en la línea de tiempo más una ubicación opcional para mostrar.

Los errores de análisis (omitir la zona en el layout, mezclar local y UTC, ignorar el horario de verano) producen sutiles errores de "horas de diferencia" que las pruebas en una sola zona no detectan.

Las API JSON añaden otra capa: la serialización por defecto usa RFC3339 UTC, mientras que los clientes pueden interpretar las cadenas como hora local del reloj de pared.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

// Analizar con zona explícita en el layout
t, err := time.Parse(time.RFC3339, "2026-07-15T09:00:00-07:00")
 
// Analizar hora local del reloj de pared en una zona específica
loc, _ := time.LoadLocation("America/Los_Angeles")
t, err := time.ParseInLocation("2006-01-02 15:04", "2026-07-15 09:00", loc)
 
// Almacenar/comparar en UTC, mostrar en la zona del usuario
utc := t.UTC()
display := utc.In(loc)

Cuándo usar esto:

• Al analizar marcas de tiempo CSV o de registros sin compensaciones de zona
• API JSON que aceptan cadenas de fecha
• Al programar trabajos a través de límites de horario de verano
• Al comparar time.Now() con tiempos históricos analizados
• Al depurar el desajuste de zona horaria "funciona en desarrollo, incorrecto en producción"

Ejemplo de trabajo

package main
 
import (
    "encoding/json"
    "fmt"
    "time"
)
 
type Event struct {
    At time.Time `json:"at"`
}
 
func main() {
    // Análisis sin zona -> UTC
    t1, _ := time.Parse("2006-01-02 15:04:05", "2026-07-15 09:00:00")
    fmt.Println("analizado sin 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("analizado 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))
}

Lo que esto demuestra:

• time.Parse sin zona en la cadena de layout asigna UTC para entradas sin zona
• Los mismos dígitos del reloj de pared en diferentes zonas son instantes diferentes
• Equal compara instantes; la salida de Format depende de la ubicación
• JSON usa RFC3339 con compensación o Z para UTC

Análisis Profundo

Cómo funciona

• Layout de tiempo de referencia: Mon Jan 2 15:04:05 MST 2006 → usa el estilo 2006-01-02 en los layouts
• time.Parse usa UTC cuando el layout no tiene zona; ParseInLocation establece la zona deseada
• Reloj monotónico: time.Time puede incluir una lectura monotónica para Sub/Since; se elimina con Format y JSON
• time.Now() devuelve la zona local del entorno a menos que llames a UTC()

JSON y API

Notas de Go

// Compara instantes, no cadenas formateadas
if !a.UTC().Equal(b.UTC()) { /* momento diferente */ }
 
// Trunca al día del calendario en una zona
day := time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, loc)

Errores comunes

• Análisis sin zona en el layout - La entrada "2006-01-02 15:04:05" se convierte en UTC, no local. Solución: ParseInLocation o exigir compensación en la entrada.
• Comparación de salidas de Format - Las cadenas difieren para el mismo instante en diferentes zonas. Solución: Equal o comparar Unix UTC.
• Asumir que time.Now().Location() es UTC en contenedores - Las imágenes sin TZ pueden usar UTC; las portátiles usan local. Solución: establecer TZ o siempre UTC() en servidores.
• Falta tzdata en imágenes scratch - LoadLocation falla en distroless sin el paquete tzdata. Solución: incrustar la importación _ "time/tzdata".
• Brecha y solapamiento del horario de verano (DST) - Las horas locales del reloj de pared pueden ser ambiguas o inexistentes una vez al año. Solución: almacenar en UTC; convertir solo para mostrar.
• Sub con tiempos de diferentes fuentes - Mezcla de tiempos monotónicos y solo de reloj de pared en Sub. Solución: usar t.UTC() antes de la aritmética entre tiempos analizados y de reloj.

Y29kZWd1aWRlcy5pb3xjZ2lvNDk4fDIwMjYwNw==

Alternativas

Preguntas frecuentes

Relacionado

• Depuración de Go: Fallos observables y bordes afilados - familia de síntomas de desajuste de tiempo
• Conceptos básicos de depuración de Go - registra RFC3339 y ubicaciones
• Etiquetas de struct para JSON, DB y validación - etiquetas y formatos de campos de tiempo
• Mejores prácticas para tipos de datos - semántica de valores comparables
• Mejores prácticas para depuración y escenarios de defectos - reglas de registro de tiempo de incidentes

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de Green Tea GC, go fix modernizers - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).