Java 8 introdujo el paquete java.time como JSR-310, diseñado por Stephen Colebourne (creador de Joda-Time). El paquete se centra en cinco clases principales: Instant, OffsetDateTime, ZonedDateTime, LocalDateTime y LocalDate. Cada una representa un nivel distinto de información sobre un momento en el tiempo, y elegir la correcta es la base de un manejo adecuado de zonas horarias.
La regla de selección es usar la clase con la mínima información necesaria. Usa LocalDate o LocalDateTime cuando no haya zona horaria implicada, OffsetDateTime cuando baste un desfase UTC, ZonedDateTime cuando necesites la semántica de zona IANA que siga futuros cambios de horario de verano, e Instant cuando solo te importe un momento absoluto. Elegir el tipo menos expresivo que encaje previene la pérdida accidental de información y simplifica el razonamiento.
Instant representa un momento absoluto como nanosegundos desde la época Unix (1970-01-01T00:00:00Z). No lleva información de zona horaria y representa el mismo momento en toda la Tierra. Las marcas de tiempo de logs, tiempos de creación de eventos y tiempos de respuesta de API normalmente deberían ser Instant porque su significado es independiente de cualquier zona horaria local.
La aritmética con Instant es directa y predecible. plus(Duration.ofHours(1)) siempre avanza exactamente una hora física, independientemente de cualquier transición de horario de verano. La contrapartida es que Instant no puede responder directamente a preguntas como «¿qué fecha es en Tokio?» sin combinarse primero con un ZoneId. La conversión solo ocurre en la presentación, que es exactamente el lugar correcto para ella.
ZonedDateTime combina un LocalDateTime con un ZoneId como Asia/Tokyo. Lleva el nombre de zona IANA y, por tanto, rastrea futuros cambios de horario de verano y actualizaciones históricas de zona. Para horas de reloj ambiguas durante transiciones de horario de verano, ZonedDateTime ofrece withEarlierOffsetAtOverlap() y withLaterOffsetAtOverlap() para hacer la elección explícita.
La aritmética de ZonedDateTime respeta la semántica de reloj de pared. Llamar a plusHours(1) en un ZonedDateTime que cruza un límite de adelanto de hora de verano efectivamente añade dos horas al instante subyacente, coincidiendo con la intuición humana de «la misma hora mañana». Si en cambio quieres avanzar tiempo físico, convierte primero a Instant. Incluye siempre pruebas en los límites de horario de verano cuando la aritmética es crítica.
OffsetDateTime es similar a ZonedDateTime, pero almacena solo un desfase UTC como +09:00 en lugar de una zona IANA completa. El momento es inequívoco porque el desfase fija la hora UTC, pero no rastrea futuros cambios de política de horario de verano. Esto lo hace ideal para formatos de serialización como ISO 8601 y RFC 3339, donde tanto la hora local como el desfase UTC se expresan textualmente.
La columna TIMESTAMP WITH TIME ZONE de PostgreSQL almacena valores internamente como UTC, y el driver JDBC típicamente la mapea a OffsetDateTime o Instant. Persistir OffsetDateTime preserva el desfase original para propósitos de auditoría, permitiendo al mismo tiempo la conversión inequívoca a UTC. Usar ZonedDateTime para datos almacenados arriesga una reinterpretación si el país cambia posteriormente su política de horario de verano de forma retroactiva.
Spring Boot 3.x y Hibernate 6 soportan Instant y OffsetDateTime como tipos de campo de entidad directamente. El código legacy que usa java.util.Date o Calendar debería migrarse, seleccionando los tipos de columna correspondientes: TIMESTAMP para horas locales sin zona, TIMESTAMPTZ (PostgreSQL) o TIMESTAMP (MySQL con serverTimezone configurado) para horas absolutas. El mapeo que elijas a nivel de entidad determina directamente si los errores de zona horaria son posibles o no.
La serialización JSON con Jackson puede emitir silenciosamente Instants como segundos epoch numéricos, sorprendiendo a consumidores de API que esperan cadenas ISO 8601. Configurar spring.jackson.serialization.write-dates-as-timestamps=false produce salida ISO 8601, que es el estándar moderno y lo que esperan bibliotecas JavaScript como Day.js y Luxon. Alinear las convenciones de serialización a lo largo de toda la pila ahorra innumerables errores de interoperabilidad.
Empieza con la pregunta «¿necesito aquí una noción de geografía humana?». Si la respuesta es no (logs, eventos, marcas de tiempo de máquina), usa Instant. Si es sí, pregunta si el valor debe seguir futuros cambios en las reglas de zona. Para eventos futuros programados por usuarios, como alarmas, ZonedDateTime es lo correcto. Para registros históricos y transacciones completadas, OffsetDateTime es más seguro porque el significado queda congelado en el momento de escritura. Para fechas puras sin componente horario, LocalDate es la respuesta correcta.
Es normal y saludable que una aplicación use múltiples tipos de java.time. Forzar todo a ZonedDateTime da a los logs más información de la necesaria y complica la serialización. Documenta en las capas de frontera (DTOs, columnas de BD, contratos de API) qué tipo usa cada campo, y el 90 por ciento de los errores de zona horaria simplemente desaparecen. El 10 por ciento restante suele tratarse de cobertura de pruebas en los límites de horario de verano, algo que las pruebas unitarias adecuadas pueden detectar a tiempo.
¿Te resultó útil este artículo?
Las tareas cron configuradas en hora local se ejecutan dos veces o se saltan silenciosamente durante las transiciones de horario de verano. Este artículo repasa los modos de fallo, el caso a favor de ejecutar programaciones en UTC, el campo timeZone de Kubernetes CronJob y cómo los planificadores en la nube gestionan el mismo problema.
Elegir entre DATE, TIME, TIMESTAMP y TIMESTAMPTZ determina si tu aplicación maneja correctamente las zonas horarias. Este artículo recorre sistemas de reservas, programación de eventos futuros, registros de auditoría y estrategias de migración para esquemas heredados que ignoraron las zonas horarias.
Los nómadas digitales enfrentan una versión más aguda del desafío horario: su ubicación cambia constantemente, así que el desfase con los clientes varía semana a semana. Este artículo cubre la estrategia de zona ancla, los cambios graduales de horario, las herramientas y los límites que hacen sostenible el trabajo nómada.