Introducción#

El manejo de fechas es uno de esos temas que parece simple al principio, pero que esconde una complejidad importante cuando construimos aplicaciones. En este artículo, vamos a descubrir los principales problemas que pueden surgir al trabajar con fechas y cómo podemos evitarlos con un enfoque adecuado.

El Problema Oculto de las Fechas#

Antes de sumergirnos en el código, entendamos por qué trabajar con fechas y horas puede ser un tema algo complejo y de alto riesgo cuando no se maneja correctamente.

Imaginemos un e-commerce con presencia internacional que lanza una promoción flash de 50% de descuento válida por solo 1 hora. El equipo de marketing ubicado en Lima, Perú programa la promoción para que inicie mañana a las 2:00 PM sin tener en cuenta las diferentes zonas horarias. Al ver esta fecha en la página web, cada usuario asume que será en su zona horaria local. Sin embargo, esto es lo que sucede el día de la promoción:

• 🇵🇪 Anthony - Lima, Perú: Ingresa a la página web a las 2:00 PM y aprovecha la promoción. ✅
• 🇨🇱 Lucía - Santiago, Chile: Ingresa a la página web a las 2:00 PM, pero la promoción aún no ha comenzado (comenzará a las 3:00 PM hora Chile). ❌
• 🇦🇷 Luis - Buenos Aires, Argentina: Ingresa a la página web a las 2:00 PM, pero la promoción aún no ha comenzado (comenzará a las 4:00 PM hora Argentina). ❌

Principales Formas de Trabajar con Fechas#

Con estas tres formas de representar fechas cubriremos la mayoría de casos de uso en aplicaciones Spring Boot. Son las opciones más comunes y recomendadas para empezar.

1
@Entity
2
public class Event {
3
    @Id
4
    @GeneratedValue(strategy = GenerationType.IDENTITY)
5
    private Long id;
6

7
    private String name;
8

9
    private LocalDate eventDate;
10

11
    // Constructores, getters y setters...
12
}

1
@Entity
2
public class Product {
3
    @Id
4
    @GeneratedValue(strategy = GenerationType.IDENTITY)
5
    private Long id;
6

7
    private String name;
8

9
    private LocalDateTime expirationDate;
10

11
    // Constructores, getters y setters...
12
}

1
@Entity
2
public class Meeting {
3
    @Id
4
    @GeneratedValue(strategy = GenerationType.IDENTITY)
5
    private Long id;
6

7
    private String title;
8

9
    private Instant scheduledDate;
10

11
    // Constructores, getters y setters...
12
}

Otras Formas de Trabajar con Fechas#

Estas opciones son un poco más complejas y generalmente se usan en escenarios que requieren un manejo especial de zonas horarias y fechas.

IMPORTANT

JPA no soporta estas clases como tipo de dato para columnas de una entidad, por lo que se pierde la información de zona horaria original y solo se almacenan los timestamps en UTC. Sin embargo, con Hibernate es posible preservar esta información usando anotaciones especiales. Más información

1
@Entity
2
public class TransactionWithOffset {
3
    @Id
4
    @GeneratedValue(strategy = GenerationType.IDENTITY)
5
    private Long id;
6

7
    private double amount;
8

9
    // Almacenamos el timestamp en UTC
10
    private Instant transactionDate;
11

12
    // Almacenamos el offset como String
13
    private String timeOffset;
14

15
    // Método helper para obtener OffsetDateTime completo
16
    public OffsetDateTime getTransactionDateWithOffset() {
17
        return transactionDate.atOffset(ZoneOffset.of(timeOffset));
18
    }
19

20
    // Método helper para establecer desde OffsetDateTime
21
    public void setTransactionDate(OffsetDateTime offsetDateTime) {
22
        this.transactionDate = offsetDateTime.toInstant();
23
        this.timeOffset = offsetDateTime.getOffset().toString(); // Ejm: "+05:00"
24
    }
25
}

1
@Entity
2
public class AppointmentWithTimezone {
3
    @Id
4
    @GeneratedValue(strategy = GenerationType.IDENTITY)
5
    private Long id;
6

7
    private String description;
8

9
    // Almacenamos el timestamp en UTC
10
    private Instant appointmentTime;
11

12
    // Almacenamos la zona horaria como String
13
    private String timeZone;
14

15
    // Método helper para obtener ZonedDateTime completo
16
    public ZonedDateTime getAppointmentWithTimezone() {
17
        return appointmentTime.atZone(ZoneId.of(timeZone));
18
    }
19

20
    // Método helper para establecer desde ZonedDateTime
21
    public void setAppointmentTime(ZonedDateTime zonedDateTime) {
22
        this.appointmentTime = zonedDateTime.toInstant();
23
        this.timeZone = zonedDateTime.getZone().getId(); // Ejm: "America/Lima"
24
    }
25

26
    // Método para convertir a otra zona horaria
27
    public ZonedDateTime getAppointmentInTimezone(String targetTimezone) {
28
        return appointmentTime.atZone(ZoneId.of(targetTimezone));
29
    }
30
}

Forma legacy de trabajar con fechas#

Las anteriores clases que vimos son enfoques modernos disponibles desde Java 8 (en el paquete java.time). Sin embargo, existe una clase anterior que aún se encuentra en muchos proyectos pero que no es recomendable usar: Date.

1
@Entity
2
public class LegacyEvent {
3
    @Id
4
    @GeneratedValue(strategy = GenerationType.IDENTITY)
5
    private Long id;
6

7
    private String name;
8

9
    // Almacenamos la fecha. También podemos usar @Temporal(TemporalType.TIMESTAMP) o @Temporal(TemporalType.TIME)
10
    @Temporal(TemporalType.DATE)
11
    private Date eventDate;
12

13
    // Constructores, getters y setters...
14
}

Recomendación: Trabajar con UTC#

Cuanto más lo pensamos, más complejo se vuelve el tema de las fechas; por lo tanto, para la mayoría de aplicaciones, es más simple y efectivo trabajar con Instant (UTC) en el backend y manejar las conversiones de zona horaria en la capa de presentación o en las aplicaciones cliente. Esto ofrece múltiples ventajas:

• ✅ Simplicidad en la BD: Una sola columna timestamp, sin campos adicionales
• ✅ Consistencia global: Todos los timestamps están en la misma base temporal
• ✅ Facilita ordenamientos: Los timestamps son directamente comparables
• ✅ Sin bugs de zona horaria: Elimina errores por cambios de horario de verano/invierno
• ✅ Escalabilidad: Los servidores pueden estar en diferentes zonas horarias sin problemas
• ✅ Fechas adaptadas: Las aplicaciones cliente (frontend) se adaptan automáticamente a la zona horaria del usuario, esto quiere decir que si el usuario usa la aplicación en Lima, Sao Paulo o Tokyo la fecha y hora se mostrarán correctamente en su zona horaria.

Sobre la serialización de fechas en JSON#

Por defecto, Spring Boot con Jackson (la biblioteca por defecto para serializar y deserializar JSON) serializa las fechas en formato ISO 8601. Por ejemplo:

• LocalDate: "2025-07-02"
• LocalDateTime: "2025-07-02T15:00:00"
• Instant: "2025-07-02T15:00:00Z"
• OffsetDateTime: "2025-07-02T15:00:00+05:00"
• ZonedDateTime: "2025-07-02T15:00:00+05:00[America/Lima]"

Se recomienda mantener este formato ya que es el estándar para representar fechas y horas en APIs y en internet en general. A continuación, un diagrama que ilustra las fechas en formato ISO 8601 y sus diferentes representaciones:

Conclusión#

El manejo correcto de fechas en Spring Boot y JPA no tiene por qué ser complejo si seguimos principios claros y consistentes. La clave está en adoptar UTC como el estándar universal y mantener las conversiones de zona horaria en las aplicaciones cliente. Además, implementar estas prácticas desde el inicio nos ahorrará horas de debugging y nos dará la confianza de que nuestra aplicación manejará fechas correctamente sin importar dónde estén nuestros usuarios.