17370845950

新闻动态

Java REST响应中Epoch毫秒时间戳到java.time类型的优雅转换

本文深入探讨了在Java应用中，如何将REST服务返回的Epoch毫秒时间戳（long类型）反序列化为java.time.LocalDateTime或java.time.LocalDate。针对Jackson库在处理此类转换时可能遇到的错误，文章提供了三种主流解决方案：通过构造函数手动解析、利用全局配置配合Instant类型，以及实现自定义反序列化器。每种方法都附有详细的代码示例和适用场景分析，旨在帮助开发者选择最适合其项目需求的实践方案。

理解问题：Jackson对Epoch时间戳的默认处理

当从REST服务接收到的JSON数据中包含Epoch毫秒时间戳（例如1666190973000），并尝试直接将其反序列化到Java 8的java.time.LocalDateTime或java.time.LocalDate类型时，Jackson库默认行为可能会导致错误。常见的错误信息提示raw timestamp ... not allowed for java.time.LocalDateTime: need additional information such as an offset or time-zone，或对于LocalDate，提示Invalid value for EpochDay。

这是因为LocalDateTime和LocalDate本身不包含时区信息，而Epoch时间戳是基于UTC的，需要一个时区或偏移量才能正确地转换为本地日期时间。此外，即使添加了jackson-datatype-jsr310模块，Jackson也需要明确的配置来知道如何处理数字形式的Epoch时间戳，因为它默认可能期望ISO 8601格式的字符串，或者在某些情况下，将其解析为纳秒精度。

为了解决这个问题，我们需要引导Jackson正确地将Epoch毫秒时间戳转换为java.time API中的日期时间类型。以下是几种可行的解决方案。

解决方案一：构造函数手动解析

这种方法的核心思想是在目标Java对象的构造函数中，接收原始的long类型Epoch毫秒时间戳，然后手动将其转换为所需的LocalDateTime类型。这种方式提供了最直接的控制，不需要复杂的全局配置。

实现步骤：

在目标类中定义一个全参数构造函数。
使用@JsonProperty注解将JSON字段名映射到构造函数参数。
将表示时间戳的参数类型设置为long。
在构造函数内部，使用Instant.ofEpochMilli()将long时间戳转换为Instant，然后通过atZone()指定时区（通常使用ZoneOffset.UTC作为基准），最后调用toLocalDateTime()获取LocalDateTime。

示例代码：

import com.fasterxml.jackson.annotation.JsonProperty;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;

public class MyLocalApplicationClass {
    private String name;
    private LocalDateTime creationDate;
    private String createdBy;

    // 默认构造函数（可选，如果需要Jackson创建空对象后再设置属性）
    public MyLocalApplicationClass() {
    }

    // 全参数构造函数，用于反序列化
    public MyLocalApplicationClass(@JsonProperty("name") String name,
                                   @JsonProperty("creation_date") long creationDate,
                                   @JsonProperty("created_by") String createdBy) {
        this.name = name;
        this.createdBy = createdBy;
        // 将Epoch毫秒转换为LocalDateTime，这里假设时间戳是UTC时间
        this.creationDate = Instant
            .ofEpochMilli(creationDate)
            .atZone(ZoneOffset.UTC) // 明确指定时区，通常UTC是安全的选择
            .toLocalDateTime();
    }

    // Getter和Setter（省略）
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public LocalDateTime getCreationDate() { return creationDate; }
    public void setCreationDate(LocalDateTime creationDate) { this.creationDate = creationDate; }
    public String getCreatedBy() { return createdBy; }
    public void setCreatedBy(String createdBy) { this.createdBy = createdBy; }

    @Override
    public String toString() {
        return "MyLocalApplicationClass{" +
               "name='" + name + '\'' +
               ", creationDate=" + creationDate +
               ", createdBy='" + createdBy + '\'' +
               '}';
    }
}

优点：

对单个字段的反序列化逻辑有精确控制。
不依赖全局Jackson配置，适用于特定场景。

缺点：

如果有很多日期时间字段需要转换，会引入重复的样板代码。
需要手动处理时区，如果时区逻辑复杂，可能需要更精细的控制。

解决方案二：全局配置配合 Instant 类型

此方案通过配置Jackson的ObjectMapper来全局处理Epoch毫秒时间戳。它要求将目标字段类型更改为java.time.Instant，因为Instant是时间线上的一个瞬时点，不带时区信息，与Epoch时间戳的概念更匹配。然后，我们可以通过配置告诉Jackson如何将Epoch毫秒反序列化为Instant。

核心配置：

注册JavaTimeModule： 这是处理java.time类型的基础。
设置DeserializationFeature.READ_DATE_TIMESTAMPS_AS_NANOSECONDS为false： 告诉Jackson将数字时间戳视为毫秒（而不是纳秒），这对于Epoch毫秒时间戳是关键。

2.1 使用 Jackson2ObjectMapperBuilder 配置

在Spring Boot应用中，可以通过定义Jackson2ObjectMapperBuilder和ObjectMapper的Bean来定制Jackson的行为。

配置类示例：

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.json.Jackson2ObjectMapperBuilder;

@Configuration
public class JsonConfig {

    @Bean
    public Jackson2ObjectMapperBuilder jackson2ObjectMapperBuilder() {
        return new Jackson2ObjectMapperBuilder();
    }

    @Bean
    public ObjectMapper objectMapper() {
        return jackson2ObjectMapperBuilder()
            .build()
            .registerModule(new JavaTimeModule()) // 注册JavaTimeModule
            .configure(DeserializationFeature.READ_DATE_TIMESTAMPS_AS_NANOSECONDS, false); // 配置为毫秒精度
    }
}

目标类示例：

import com.fasterxml.jackson.annotation.JsonProperty;
import java.time.Instant;

public class MyLocalApplicationClass {
    private String name;
    @JsonProperty("creation_date") // 如果JSON字段名与Java属性名不匹配，仍需此注解
    private Instant creationDate; // 将类型改为Instant
    @JsonProperty("created_by")
    private String createdBy;

    // 默认构造函数，Getter和Setter（省略）
    public MyLocalApplicationClass() {}

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public Instant getCreationDate() { return creationDate; }
    public void setCreationDate(Instant creationDate) { this.creationDate = creationDate; }
    public String getCreatedBy() { return createdBy; }
    public void setCreatedBy(String createdBy) { this.createdBy = createdBy; }

    @Override
    public String toString() {
        return "MyLocalApplicationClass{" +
               "name='" + name + '\'' +
               ", creationDate=" + creationDate + // Instant默认输出ISO格式
               ", createdBy='" + createdBy + '\'' +
               '}';
    }
}

接收到Instant后，如果需要LocalDateTime，可以在业务逻辑中通过instant.atZone(ZoneOffset.UTC).toLocalDateTime()进行转换。

2.2 简化配置：通过 application.properties

Spring Boot的JacksonAutoConfiguration会自动检测并注册JavaTimeModule。因此，对于Spring Boot应用，最简便的方法是在application.properties或application.yml中直接配置Jackson属性，无需手动定义ObjectMapper Bean。

application.properties 配置：

spring.jackson.deserialization.read-date-timestamps-as-nanoseconds=false

目标类示例：

MyLocalApplicationClass的定义与2.1节中相同，creationDate字段类型仍为Instant。

优点：

全局生效，简化了多个日期时间字段的处理。
POJO更加简洁，无需在每个字段上添加自定义注解。
Instant类型与Epoch时间戳概念匹配度高。

缺点：

要求将目标字段类型改为Instant。如果业务逻辑强烈依赖LocalDateTime，则需要额外的转换。
全局配置可能影响其他Jackson日期时间的反序列化行为，需谨慎。

解决方案三：自定义反序列化器

如果前两种方案不适用，或者需要对特定字段进行高度定制的日期时间反序列化逻辑，可以实现一个自定义的反序列化器。这种方法允许你完全控制如何将JSON值转换为Java对象。

实现步骤：

创建一个类继承StdDeserializer（其中T是目标类型，如LocalDateTime）。
重写deserialize()方法，在该方法中手动解析JsonParser获取时间戳，并将其转换为目标类型。
在目标类的日期时间字段上使用@JsonDeserialize(using = YourCustomDeserializer.class)注解。

自定义反序列化器示例：

import com.fasterxml.jackson.core.JacksonException;
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.databind.DeserializationContext;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.deser.std.StdDeserializer;

import java.io.IOException;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneOffset;

public class DateTimeDeserializer extends StdDeserializer {

    public DateTimeDeserializer() {
        super(LocalDateTime.class);
    }

    @Override
    public LocalDateTime deserialize(JsonParser p,
                                     DeserializationContext ctxt) throws IOException, JacksonException {
        JsonNode node = p.getCodec().readTree(p);
        long timestamp = node.longValue(); // 获取原始的long类型时间戳

        // 将Epoch毫秒转换为LocalDateTime
        return Instant
            .ofEpochMilli(timestamp)
            .atZone(ZoneOffset.UTC) // 假设时间戳是UTC时间
            .toLocalDateTime();
    }
}

目标类示例：

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
import java.time.LocalDateTime;

public class MyLocalApplicationClass {

    private String name;

    @JsonDeserialize(using = DateTimeDeserializer.class) // 指定使用自定义反序列化器
    @JsonProperty("creation_date")
    private LocalDateTime creationDate; // 字段类型可以直接是LocalDateTime

    @JsonProperty("created_by")
    private String createdBy;

    // 默认构造函数，Getter和Setter（省略）
    public MyLocalApplicationClass() {}

    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public LocalDateTime getCreationDate() { return creationDate; }
    public void setCreationDate(LocalDateTime creationDate) { this.creationDate = creationDate; }
    public String getCreatedBy() { return createdBy; }
    public void setCreatedBy(String createdBy) { this.createdBy = createdBy; }

    @Override
    public String toString() {
        return "MyLocalApplicationClass{" +
               "name='" + name + '\'' +
               ", creationDate=" + creationDate +
               ", createdBy='" + createdBy + '\'' +
               '}';
    }
}

优点：

提供了最大的灵活性，可以处理任何复杂的日期时间格式或转换逻辑。
允许直接将字段类型定义为LocalDateTime或LocalDate，无需额外转换。
字段级别的控制，不会影响其他日期时间字段。

缺点：

需要编写更多的样板代码，尤其是当有多个字段需要相同或类似转换时。
增加了代码的复杂性。

注意事项与总结

jackson-datatype-jsr310模块： 无论选择哪种方案，确保项目中已引入com.fasterxml.jackson.datatype:jackson-datatype-jsr310依赖。这是Jackson支持Java 8日期时间API的基础。
时区处理： Epoch时间戳本身是无时区概念的，通常被认为是UTC时间。在将其转换为LocalDateTime时，务必通过atZone()方法指定一个时区（如ZoneOffset.UTC），否则可能会得到意外的结果。如果需要转换为特定本地时区的LocalDateTime，则应使用相应的ZoneId。
选择合适的方案：
- 如果只需要处理少数几个日期时间字段，且对代码侵入性要求低，构造函数手动解析是一个简单直接的选择。
- 如果应用中大量字段需要将Epoch毫秒转换为日期时间，且接受将字段类型定义为Instant，那么全局配置是最简洁高效的方案。对于Spring Boot应用，通过application.properties配置是首选。
- 如果需要对特定日期时间字段进行高度定制的转换逻辑，或者不能将字段类型更改为Instant，则自定义反序列化器提供了最大的灵活性。

理解Jackson处理日期时间的工作原理，并根据项目需求选择最合适的策略，能够有效避免反序列化错误，确保数据转换的准确性和代码的健壮性。

17370845950

理解问题：Jackson对Epoch时间戳的默认处理

解决方案一：构造函数手动解析

解决方案二：全局配置配合 Instant 类型

2.1 使用 Jackson2ObjectMapperBuilder 配置

2.2 简化配置：通过 application.properties

解决方案三：自定义反序列化器

注意事项与总结

关于我们

服务项目

广告推广

案例欣赏