Spring Boot 3.2 时间格式化实战：@JsonFormat 与 @DateTimeFormat 的深度应用

在前后端分离架构中，时间数据的处理一直是开发者面临的典型挑战。Spring Boot 3.2 提供了强大的时间格式化支持，其中 @JsonFormat 和 @DateTimeFormat 注解是解决这一问题的利器。本文将深入探讨这两个注解在五种典型业务场景中的应用，并提供可落地的解决方案。

1. 基础概念与核心差异

@DateTimeFormat 和 @JsonFormat 虽然都用于时间格式化，但它们的职责和使用场景有本质区别：

特性	@DateTimeFormat	@JsonFormat
提供方	Spring Framework	Jackson 库
主要作用	请求参数绑定	JSON 序列化/反序列化
影响方向	仅处理输入	处理输入和输出
时区处理	无内置时区支持	支持 timezone 参数
适用场景	表单提交、GET 参数	REST API JSON 数据交互

关键差异示例 ：

public class EventDTO {
    // 仅影响参数绑定
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm") 
    private Date startTime;
    
    // 影响JSON输入输出
    @JsonFormat(pattern = "yyyy/MM/dd", timezone = "Asia/Shanghai")
    private Date endTime;
}

2. 五种实战场景解析

2.1 REST API 中的完整请求-响应流程

在前后端通过JSON交互时，通常需要同时使用两个注解：

@PostMapping("/events")
public Event createEvent(@RequestBody EventRequest request) {
    // 业务处理...
    return eventService.create(request);
}

// 请求体DTO
public class EventRequest {
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date eventTime;
    // 其他字段...
}

// 响应体DTO
public class EventResponse {
    @JsonFormat(pattern = "yyyy年MM月dd日 HH时mm分", timezone = "GMT+8")
    private Date displayTime;
    // 其他字段...
}

典型问题 ：当只使用 @JsonFormat 时，GET 请求的参数绑定会失效。解决方案是同时添加 @DateTimeFormat 。

2.2 Feign 客户端间的时间传递

微服务架构中，Feign 客户端调用时的时间格式化需要特别注意：

// 服务提供方
@GetMapping("/api/orders")
public List<Order> getOrders(
    @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) 
    @RequestParam LocalDateTime start) {
    // 查询逻辑
}

// Feign 客户端接口
public interface OrderClient {
    @GetMapping("/api/orders")
    List<Order> getOrders(
        @RequestParam 
        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME)
        LocalDateTime start);
}

注意：Feign 默认使用 JSON 序列化，GET 请求带对象参数时需使用 @SpringQueryMap 并确保 DTO 中包含 @JsonFormat 注解。

2.3 全局配置与注解的优先级

Spring Boot 允许通过配置实现全局时间格式：

# application.properties
spring.mvc.format.date-time=yyyy-MM-dd HH:mm:ss
spring.jackson.time-zone=GMT+8
spring.jackson.date-format=yyyy-MM-dd HH:mm:ss

当全局配置与注解共存时，优先级为：

1. 字段级 @JsonFormat / @DateTimeFormat
2. 类级注解
3. 全局配置

2.4 时区问题的系统化解决方案

跨时区应用需要统一时区处理策略：

@Configuration
public class TimeConfig {
    @Bean
    public Jackson2ObjectMapperBuilderCustomizer jacksonObjectMapperCustomization() {
        return builder -> builder
            .timeZone(TimeZone.getTimeZone("Asia/Shanghai"))
            .simpleDateFormat("yyyy-MM-dd'T'HH:mm:ss");
    }
}

推荐实践 ：

• 数据库存储 UTC 时间
• 前端传递时间带上时区信息（如 2023-06-01T10:00:00+08:00 ）
• 后端接口使用 @JsonFormat(timezone = "GMT+8")

2.5 复杂类型的特殊处理

对于 LocalDateTime 等 Java 8 时间类型，需要额外配置：

<!-- pom.xml -->
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
</dependency>

public class TimeWrapper {
    @JsonFormat(pattern = "yyyy年MM月dd日")
    private LocalDate chinaDate;
    
    @DateTimeFormat(iso = ISO.DATE_TIME)
    @JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss")
    private LocalDateTime preciseTime;
}

3. 典型错误与排查指南

以下是常见问题及解决方案对照表：

问题现象	原因分析	解决方案
时间比实际晚8小时	未指定时区	添加 timezone="GMT+8"
GET 请求时间参数绑定失败	缺少 @DateTimeFormat	补全注解
POST JSON 反序列化失败	格式不匹配	检查 pattern 一致性
Feign 调用时间字段为null	未正确序列化	使用 @SpringQueryMap
Swagger 文档显示时间戳	未配置文档插件	集成 springdoc-openapi

日志排查技巧 ：

# 开启Jackson调试日志
logging.level.org.springframework.web=DEBUG
logging.level.com.fasterxml.jackson.databind=TRACE

4. 高级技巧与性能优化

4.1 自定义序列化器

对于特殊格式需求，可以创建自定义序列化器：

public class ChineseDateSerializer extends JsonSerializer<Date> {
    private static final SimpleDateFormat format = 
        new SimpleDateFormat("yyyy年MM月dd日");

    @Override
    public void serialize(Date value, JsonGenerator gen, 
        SerializerProvider provider) throws IOException {
        gen.writeString(format.format(value));
    }
}

// 使用示例
public class Report {
    @JsonSerialize(using = ChineseDateSerializer.class)
    private Date reportDate;
}

4.2 缓存 DateTimeFormatter

频繁创建格式化对象会影响性能：

public class DateUtils {
    private static final DateTimeFormatter CACHED_FORMATTER =
        DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
    
    public static String format(LocalDateTime time) {
        return CACHED_FORMATTER.format(time);
    }
}

5. 测试策略与最佳实践

完善的测试应覆盖以下场景：

@SpringBootTest
public class TimeFormatTest {
    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    void shouldFormatOutput() {
        var response = restTemplate.getForEntity(
            "/api/now", TimeResponse.class);
        
        assertThat(response.getBody().getTime())
            .matches("\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}");
    }

    @Test
    void shouldParseInput() {
        var request = new TimeRequest();
        request.setTime("2023-06-01 12:00:00");
        
        var response = restTemplate.postForEntity(
            "/api/parse", request, String.class);
        
        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
    }
}

工程化建议 ：

1. 在父类 DTO 中定义通用时间格式
2. 使用接口测试验证边界情况
3. 在 CI 流程中加入时区敏感测试
4. 文档中明确标注时间格式要求