日期时间参数，格式配置（SpringBoot）

我会带着你远行 2024-02-23 07:26 29阅读 0赞

## 介绍 ##

在SpringBoot项目中，接口中的`日期和时间`类型的参数，配置格式。

### 日期格式 ###

接口中常用的日期时间格式有两种：

1.  `字符串`（比如：yyyy-MM-dd HH:mm:ss）
2.  `时间戳`（比如：1696839876955）

这两种方式各有优势。

*  字符串格式表示时间，直观清晰，便于识别出时间。但是，字符串格式存在时区问题，需要在字段中描述出时区（SpringMVC的默认时间格式中带有时区），或者前后端规定好默认时区，比如东八区（GMT+8）。
 *  时间戳，用数字表示时间，准确定位时间，不存在时区问题。缺点是，不够直观，无法直接识别出时间戳对应的具体时间（需要转换），不便于从接口直接判断时间是否正确，测试比较费时费力。

### 格式配置 ###

日期参数的格式，可以配置。分为：`全局配置`和`局部配置`。

*  全局配置：作用于项目全局的时间参数。
 *  局部配置：只作用于配置的字段，覆盖全局配置，其余字段不受影响。

## 全局配置 ##

### Query时间入参，使用字符串 ###

#### 配置 ####

spring:
      mvc:
        format:
          # Query参数，时间格式（转换 java.util.Date）
          date: yyyy-MM-dd HH:mm:ss

#### Query参数实体示例 ####

Query参数，使用 `java.util.Date` 类型接收。

package com.example.web.exception.query;
    
    import com.example.core.validation.phone.query.PhoneQuery;
    import io.swagger.v3.oas.annotations.media.Schema;
    import lombok.Data;
    import org.springdoc.api.annotations.ParameterObject;
    
    import java.util.Date;
    
    @Data
    @ParameterObject
    @Schema(name = "用户Query")
    public class UserQuery {
        
    
        // 其他字段
    
        @Schema(description = "开始时间", example = "2023-01-01 08:30:00")
        private Date beginTime;
    
        @Schema(description = "结束时间", example = "2023-12-31 17:00:00")
        private Date endTime;
    
    }

#### 接口调用成功 ####

日期格式正确，接口调用成功。

![在这里插入图片描述][5af971993a0744febbf994e275f6c9ff.png]

打印日志：

> 查询用户列表。userQuery=UserQuery(name=null, phone=null, beginTime=Sun Jan 01 08:30:00 GMT+08:00 2023, endTime=Sun Dec 31 17:00:00 GMT+08:00 2023, beginDate=null, endDate=null)，pageQuery=PageQuery(pageNumber=1, pageSize=10)

#### 接口调用失败 ####

接口输入必须符合格式，否则会调用失败（报出异常）。  
![在这里插入图片描述][4fd221c58db54b7eac3cccca55cc557d.png]

### Body时间入参和响应时间出参 ###

默认响应中的时间参数，会转换成字符串，默认时间格式举例：

> 2023-10-10T01:31:03.279+00:00

#### 配置 ####

目标格式为：`yyyy-MM-dd HH:mm:ss`，东八区。

spring:
      jackson:
        # Body参数和响应，时间格式（转换 java.util.Date）
        date-format: yyyy-MM-dd HH:mm:ss
        time-zone: GMT+8

#### Body时间入参：UserEditParam ####

package com.example.web.response.model.param;
    
    import com.example.core.validation.phone.strict.Phone;
    import com.fasterxml.jackson.annotation.JsonFormat;
    import io.swagger.v3.oas.annotations.media.Schema;
    import lombok.Data;
    
    import javax.validation.constraints.Email;
    import javax.validation.constraints.NotBlank;
    import javax.validation.constraints.NotEmpty;
    import java.util.Date;
    
    @Data
    @Schema(name = "编辑用户Param")
    public class UserEditParam {
        
    
        // 其他字段
    
        @JsonFormat(pattern = "yyyy-MM-dd")
        @Schema(description = "开始日期", example = "2023-01-01")
        private Date beginDate;
    
        @JsonFormat(pattern = "yyyy-MM-dd")
        @Schema(description = "结束日期", example = "2023-12-31")
        private Date endDate;
    
    }

#### 效果 ####

接口调用：  
![在这里插入图片描述][093af60566ca4b90abac965b4ee707ff.png]  
控制台打印参数：

> 新增用户，Post请求。param=UserAddParam(name=张三, phone=18612345678, email=zhangsan@example.com, beginTime=Sun Jan 01 08:30:00 CST 2023, endTime=Sun Dec 31 17:00:00 CST 2023)

#### 响应时间出参：UserVO ####

package com.example.web.model.vo;
    
    import io.swagger.v3.oas.annotations.media.Schema;
    import lombok.Data;
    
    import java.util.Date;
    
    @Data
    @Schema(name = "用户VO")
    public class UserVO {
        
    
        // 其他字段
    
        @Schema(description = "开始时间", example = "2023-01-01 01:20:30")
        private Date beginTime;
    
        @Schema(description = "结束时间", example = "2023-01-01 01:20:30")
        private Date endTime;
    
    }

#### 效果 ####

![在这里插入图片描述][ec12c7c7dc6b47f3885467f1b3c8c726.png]

### 响应时间出参：时间戳 ###

#### 配置 ####

spring:
      jackson:
        serialization:
          # 时间字段（java.util.Date），返回时间戳。注意，此配置会覆盖掉 spring.jackson.date-format 。
          write-dates-as-timestamps: true

#### 效果 ####

响应时间出参，为时间戳格式。

![在这里插入图片描述][fc1a2e725d7c4a8fa8e355333b94ce21.png]

## 局部配置 ##

### Query时间入参：局部格式 ###

Query时间入参，如果某个字段需要的时间格式和全局不相同，可以配置这个字段的自定义的入参格式。

使用注解：`@DateTimeFormat`

#### 配置示例 ####

package com.example.web.exception.query;
    
    import com.example.core.validation.phone.query.PhoneQuery;
    import io.swagger.v3.oas.annotations.media.Schema;
    import lombok.Data;
    import org.springdoc.api.annotations.ParameterObject;
    import org.springframework.format.annotation.DateTimeFormat;
    
    import java.util.Date;
    
    @Data
    @ParameterObject
    @Schema(name = "用户Query")
    public class UserQuery {
        
    
        // 其他字段
    
        @DateTimeFormat(pattern = "yyyy-MM-dd")
        @Schema(description = "开始日期", example = "2023-01-01")
        private Date beginDate;
    
        @DateTimeFormat(pattern = "yyyy-MM-dd")
        @Schema(description = "结束日期", example = "2023-12-31")
        private Date endDate;
    
    }

#### 效果 ####

![在这里插入图片描述][9beac9a9c7b242bca05547dcd34f0a9b.png]

### Body时间入参：局部格式 ###

使用注解：`@JsonFormat`

#### 配置示例 ####

#### 效果 ####

![在这里插入图片描述][f534077f5b6a4a25a39ef2f603e7cfc7.png]

> 编辑用户，PUT请求。id=1234567890123456789，param=UserEditParam(name=张三, phone=18612345678, email=zhangsan@example.com, beginDate=Sun Jan 01 00:00:00 CST 2023, endDate=Sun Dec 31 00:00:00 CST 2023)

#### 问题 ####

注意：如下图传递参数，接口也能调用成功。  
接口收到的参数，只包含年月日。

![在这里插入图片描述][c8100324091d4cffa2922f1a90cd246f.png]

![在这里插入图片描述][6af3134fed704ba7bb918d13052cfcec.png]

### 响应时间出参：局部格式 ###

使用注解：`@JsonFormat`

#### 配置示例 ####

package com.example.web.model.vo;
    
    import com.fasterxml.jackson.annotation.JsonFormat;
    import io.swagger.v3.oas.annotations.media.Schema;
    import lombok.Data;
    
    import java.util.Date;
    
    @Data
    @Schema(name = "用户VO")
    public class UserVO {
        
    
        // 其他字段
    
        @JsonFormat(pattern = "yyyy-MM-dd")
        @Schema(description = "开始日期", example = "2023-01-01")
        private Date beginDate;
    
        @JsonFormat(pattern = "yyyy-MM-dd")
        @Schema(description = "结束日期", example = "2023-12-31")
        private Date endDate;
    
    }

#### 效果 ####

![在这里插入图片描述][9adbf9f2748e4b8c95f3a834c5b1fcdb.png]

[5af971993a0744febbf994e275f6c9ff.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/23/1252f83223564bf3968f33ea428a7c0e.png
[4fd221c58db54b7eac3cccca55cc557d.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/23/f7e8bfccdea44e12af0ffa5deefabbe1.png
[093af60566ca4b90abac965b4ee707ff.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/23/eb2555d5a26f456397c7a97c473039e0.png
[ec12c7c7dc6b47f3885467f1b3c8c726.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/23/1aa5affc4a4a495b84097eaaa94d380e.png
[fc1a2e725d7c4a8fa8e355333b94ce21.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/23/bef57afed4f143deb1b2b679d4fb6756.png
[9beac9a9c7b242bca05547dcd34f0a9b.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/23/4f5cda1b903649c3ba8a0d2b462bb8c1.png
[f534077f5b6a4a25a39ef2f603e7cfc7.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/23/0665f45cf1264e7cb5b9406e042b7414.png
[c8100324091d4cffa2922f1a90cd246f.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/23/853e4450e4b34a9383d0553fd6a23feb.png
[6af3134fed704ba7bb918d13052cfcec.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/23/700fd7a0b1b44fb9a3639fc655c8a13b.png
[9adbf9f2748e4b8c95f3a834c5b1fcdb.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/23/3613e96eb5114c9586a1d6a25284870d.png