Java 8 的日期時間套件以及在 Spring Boot Controller 接收

日期：

https://unsplash.com/photos/white-and-pink-analog-alarm-clock-jOeh3Lv88xA

筆者的第一份工作，公司對於日期時間一律都使用舊式的「java.util.Date」類別來處理。若想做增減，還要搭配 Apache 提供的 DateUtils 來完成。

後來才在網路上得知如「LocalDateTime」、「ZonedDateTime」這種 Java 8 推出的類別。本文將會介紹它們，除了了解操作方式，也要知道如何在 Spring Boot 的 controller，以這些型態來接收資料。

此篇轉載自本人的 iThome 鐵人賽文章。

一、無時區的日期時間

這些日期時間套件，位於「java.time」的 package 中。

（一）LocalDate

代表日期，只儲存了年、月、日。

要注意的是，該物件儲存的日期是不可變的（immutable），因此進行日期的增減後，要將回傳值接起來。

（二）LocalTime

代表時間，除了儲存時、分、秒，也能儲存奈秒。

（三）LocalDateTime

封裝了上述的 LocalDate 和 LocalTime。


二、格式化與解析

DateTimeFormatter 可用來進行日期時間物件，與字串之間的互換。

讀者可注意到，這裡不必像舊式的 SimpleDateFormat 那樣，還要處理 ParseException 這個 checked exception。


三、有時區的日期時間

（一）ZonedDateTime

ZonedDateTime 類別加入了時區的概念，便於我們進行換算。

從範例程式中能看出，由 LocalDateTime 與 ZoneId，可組合出 ZonedDateTime。此處建立的是「臺北時間 15:30」

若要換算成其他地區的時間，請呼叫 withZoneSameInstant 方法，並傳入指定時區的 ZoneId 即可。此處換算成「東京時間」後，輸出的時間為 16:30。

（二）ZoneId

在上面的範例程式中，藉由「Taipei」和「Tokyo」這樣子的 key，可建立出 ZoneId 物件，用來代表時區。呼叫 ZoneId.getAvailableZoneIds() 方法，我們能得到所有支援的 key，舉例幾個如下：

  • Asia/Taipei
  • Asia/Tokyo
  • America/New_York
  • Australia/Sydney
  • Greenwich
  • ...

然而在開發中，要我們配合上面這份清單，感覺並不方便。因此除了傳入地區，也能直接使用偏移量（offset），即 UTC/GMT，來定義 ZoneId。

ZoneId 偏移量的寫法，尚有 h、hh、hhmm、hh:mm 等多種格式，如 +8、-10、-0800、+10:00。

四、在 Spring Boot Controller 接收

本節示範這些日期時間類別，要如何應用在 Spring Boot 中的 controller 上，以便好好地與前端串接。

（一）用於 request body

以下是一個用來當作 request body 的範例類別。

而以下是簡單的 RESTful API。

當前端發出 request 時，JSON 欄位值有一定的預設格式，如此才能讓後端正確接收日期時間的資料。

POST http://localhost:8080/date-time-body
{
    "birthday": "2023-01-01",
    "playStartTime": "20:30:00",
    "bookingDateTime": "2023-01-01T20:30:00",
    "arrivalDateTime": "2023-01-01T20:30:00+08:00"
}

當讀者用開發工具的 debug 模式確認，會發現 ZonedDateTime 被換算成 UTC+0 的時間了。這可以在 application.properties 檔案添加以下參數來避免掉。

spring.jackson.deserialization.ADJUST_DATES_TO_CONTEXT_TIME_ZONE=false

如果想要定義自己的日期時間格式，請在欄位冠上 Jackson 套件提供的 @JsonFormat 標記，並於 pattern 參數傳入格式。

這次的範例自訂了「年月日」之間與「時分秒」之間的分隔符號，故 request body 中的欄位值，可以更改格式了！

POST http://localhost:8080/date-time-body
{
    "birthday": "2023/01/01",
    "playStartTime": "20.30.00",
    "bookingDateTime": "2023/01/01 20.30.00",
    "arrivalDateTime": "2023/01/01T20.30.00+08:00"
}

（二）用於查詢字串（@RequestParam）

若是在 controller 經由 @RequestParam 標記接收查詢字串（query string），則最簡單的做法是加上 @DateTimeFormat 標記，於 pattern 參數傳入格式。

要留意的是，如果想將 2023-01-01T20:30:00+08:00 這樣的格式當作 query string，考慮到「+」號，要記得做 url encode（變成「%2B」），否則會被視為字串串接。

以下是一個攜帶 query string 的 url 範例。

GET http://localhost:8080/date-time-param?birthday=2023-01-01&playStartTime=20:30:00&bookingDateTime=2023-01-01 20:30:00&arrivalDateTime=2023-01-01T20:30:00%2B08:00

（三）用於查詢字串（@ModelAttribute）

如果讀者想用 @ModelAttribute 標記，將 query string 都收集到一個自訂的類別物件中，資料的轉換就得手動處理了。

此處的自訂類別叫做 DateTimeParam，其 setter 方法要改成以 String 的型態來接收參數。並在賦值時使用 parse 方法，自行轉換為日期時間物件，如下：

這些 parse 方法所接受的日期時間格式，預設與本節第一段介紹的相同。如果想要定義自己的格式，請搭配第二節介紹的 DateTimeFormatter，對不同種類的日期時間做解析。

讀者亦可設計一些 util method，並由統一的 DateTimeFormatter 來解析。

參考資料：
Java 8 新增的時間系列用法
Java 8之新日期時間API筆記（四）ZoneId

留言

張貼留言