Spring Boot 中的 @DateTimeFormat 和 @JsonFormat 的用法及作用

在开发 Spring Boot 应用时，处理日期和时间数据是一个常见的需求。Spring Boot 提供了两个注解 @DateTimeFormat 和 @JsonFormat 来帮助我们处理这些问题。这两个注解分别用于将日期字符串解析为日期对象以及将日期对象格式化为字符串。本文将详细介绍这两个注解的用法及作用，并通过实例代码进行说明。

@DateTimeFormat 注解

@DateTimeFormat 是一个 Spring 框架提供的注解，用于格式化和解析日期时间字段。它主要用于将请求参数或表单数据中的日期字符串解析为 Java 的日期对象。

用法

@DateTimeFormat 可以应用于以下数据类型：

• java.util.Date
• java.util.Calendar
• java.time.LocalDate
• java.time.LocalDateTime
• java.time.ZonedDateTime

该注解的常用属性包括：

• pattern：指定日期格式的模式字符串，例如 "yyyy-MM-dd"。
• iso：指定标准的 ISO 日期时间格式。可选值为 DateTimeFormat.ISO.DATE、DateTimeFormat.ISO.TIME 和 DateTimeFormat.ISO.DATE_TIME。

示例

假设我们有一个处理日期的 REST 控制器：

java复制代码

package com.example.demo.controller;

import org.springframework.format.annotation.DateTimeFormat;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

@RestController
public class DateController {

    @GetMapping("/date")
    public String handleDate(@RequestParam("date") @DateTimeFormat(pattern = "yyyy-MM-dd") LocalDate date) {
        return "Parsed date: " + date.format(DateTimeFormatter.ISO_DATE);
    }

    @GetMapping("/datetime")
    public String handleDateTime(@RequestParam("datetime") @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) LocalDateTime dateTime) {
        return "Parsed datetime: " + dateTime.format(DateTimeFormatter.ISO_DATE_TIME);
    }
}

在上述示例中：

• /date 端点处理格式为 "yyyy-MM-dd" 的字符串，并将其解析为 LocalDate 对象。
• /datetime 端点处理 ISO 标准格式的日期时间字符串，并将其解析为 LocalDateTime 对象。

你可以通过以下 URL 测试这些端点：

复制代码

http://localhost:8080/date?date=2023-10-01
http://localhost:8080/datetime?datetime=2023-10-01T10:15:30

@JsonFormat 注解

@JsonFormat 是 Jackson 库提供的注解，用于序列化和反序列化 JSON 数据中的日期时间字段。它可以帮助我们将日期时间对象格式化为特定的字符串格式，或将特定格式的字符串解析为日期时间对象。

用法

@JsonFormat 可以应用于类的字段或方法上。其常用属性包括：

• pattern：指定日期时间格式的模式字符串。
• shape：指定日期时间的格式化类型。常用值为 JsonFormat.Shape.STRING。
• timezone：指定时区。

示例

假设我们有一个包含日期时间字段的实体类，并使用 @JsonFormat 注解格式化日期时间：

java复制代码

package com.example.demo.model;

import com.fasterxml.jackson.annotation.JsonFormat;

import java.time.LocalDate;
import java.time.LocalDateTime;

public class Event {

    private String name;

    @JsonFormat(pattern = "yyyy-MM-dd")
    private LocalDate date;

    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "UTC")
    private LocalDateTime dateTime;

    // getters and setters
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public LocalDate getDate() {
        return date;
    }

    public void setDate(LocalDate date) {
        this.date = date;
    }

    public LocalDateTime getDateTime() {
        return dateTime;
    }

    public void setDateTime(LocalDateTime dateTime) {
        this.dateTime = dateTime;
    }
}

接着，我们创建一个 REST 控制器来测试该实体类的序列化和反序列化：

java复制代码

package com.example.demo.controller;

import com.example.demo.model.Event;
import org.springframework.web.bind.annotation.*;

import java.time.LocalDate;
import java.time.LocalDateTime;

@RestController
public class EventController {

    @GetMapping("/event")
    public Event getEvent() {
        Event event = new Event();
        event.setName("Spring Boot Workshop");
        event.setDate(LocalDate.of(2023, 10, 1));
        event.setDateTime(LocalDateTime.of(2023, 10, 1, 10, 15, 30));
        return event;
    }

    @PostMapping("/event")
    public String createEvent(@RequestBody Event event) {
        // 持久化逻辑...
        return "Event created: " + event.getName();
    }
}

在上述示例中：

• /event GET 端点返回一个 Event 对象，其中日期和日期时间字段将根据 @JsonFormat 注解指定的格式序列化为 JSON 字符串。
• /event POST 端点接受一个 JSON 请求体，并将其反序列化为 Event 对象。

你可以通过以下方式测试这些端点：

GET 请求

复制代码

curl -X GET http://localhost:8080/event

返回结果：

json复制代码

{
    "name": "Spring Boot Workshop",
    "date": "2023-10-01",
    "dateTime": "2023-10-01 10:15:30"
}

POST 请求

bash复制代码

curl -X POST http://localhost:8080/event -H "Content-Type: application/json" -d '{
    "name": "Spring Boot Workshop",
    "date": "2023-10-01",
    "dateTime": "2023-10-01 10:15:30"
}'

返回结果：

复制代码

Event created: Spring Boot Workshop

小结

在本文中，我们详细介绍了 Spring Boot 中的 @DateTimeFormat 和 @JsonFormat 注解的用法及作用。@DateTimeFormat 主要用于将请求参数或表单数据中的日期字符串解析为日期对象，而 @JsonFormat 则用于序列化和反序列化 JSON 数据中的日期时间字段。

通过这些注解，我们可以更方便地处理日期和时间数据，确保数据在不同层次间传递时的格式一致性。这对于开发高质量的 Spring Boot 应用至关重要。