介紹

在SpringBoot項目中，接口中的日期和時間類型的參數(shù)，配置格式。

日期格式

接口中常用的日期時間格式有兩種：

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

這兩種方式各有優(yōu)勢。

• 字符串格式表示時間，直觀清晰，便于識別出時間。但是，字符串格式存在時區(qū)問題，需要在字段中描述出時區(qū)（SpringMVC的默認時間格式中帶有時區(qū)），或者前后端規(guī)定好默認時區(qū)，比如東八區(qū)（GMT+8）。
• 時間戳，用數(shù)字表示時間，準確定位時間，不存在時區(qū)問題。缺點是，不夠直觀，無法直接識別出時間戳對應的具體時間（需要轉(zhuǎn)換），不便于從接口直接判斷時間是否正確，測試比較費時費力。

格式配置

日期參數(shù)的格式，可以配置。分為：全局配置和局部配置。

• 全局配置：作用于項目全局的時間參數(shù)。
• 局部配置：只作用于配置的字段，覆蓋全局配置，其余字段不受影響。

全局配置

Query時間入?yún)?#xff0c;使用字符串

配置

spring:mvc:format:# Query參數(shù)，時間格式（轉(zhuǎn)換 java.util.Date）date: yyyy-MM-dd HH:mm:ss

Query參數(shù)實體示例

Query參數(shù)，使用 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;}

接口調(diào)用成功

日期格式正確，接口調(diào)用成功。

打印日志：

查詢用戶列表。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)

接口調(diào)用失敗

接口輸入必須符合格式，否則會調(diào)用失敗（報出異常）。

Body時間入?yún)⒑晚憫獣r間出參

默認響應中的時間參數(shù)，會轉(zhuǎn)換成字符串，默認時間格式舉例：

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

配置

目標格式為：yyyy-MM-dd HH:mm:ss，東八區(qū)。

spring:jackson:# Body參數(shù)和響應，時間格式（轉(zhuǎn)換 java.util.Date）date-format: yyyy-MM-dd HH:mm:sstime-zone: GMT+8

Body時間入?yún)?#xff1a;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;}

效果

接口調(diào)用：

控制臺打印參數(shù)：

新增用戶，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;}

效果

響應時間出參：時間戳

配置

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

效果

響應時間出參，為時間戳格式。

局部配置

Query時間入?yún)?#xff1a;局部格式

Query時間入?yún)?#xff0c;如果某個字段需要的時間格式和全局不相同，可以配置這個字段的自定義的入?yún)⒏袷健?/p>

使用注解：@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;}

效果

Body時間入?yún)?#xff1a;局部格式

使用注解：@JsonFormat

配置示例

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;}

效果

編輯用戶，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)

問題

注意：如下圖傳遞參數(shù)，接口也能調(diào)用成功。
接口收到的參數(shù)，只包含年月日。

編輯用戶，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)

響應時間出參：局部格式

使用注解：@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;}

效果