LocalDateTime、OffsetDateTime、ZonedDateTime互轉,這一篇絕對餵飽你

前言

你好,我是A哥(YourBatman)。

在JSR 310日期時間體系了,一共有三個API可用於表示日期時間:

  • LocalDateTime:本地日期時間
  • OffsetDateTime:帶偏移量的日期時間
  • ZonedDateTime:帶時區的日期時間

也許平時開發中你只用到過LocalDateTime這個API,那是極好的,但是不能止步於此,否則就圖樣圖森破了。

隨着場景的多樣性變化,咱們開發者接觸到OffsetDateTime/ZonedDateTime的概率越來越大,但凡和國際化產生上關係的大概率都會用得到它們。本文依然站在實用的角度,輔以具體代碼示例,介紹它三。

本文提綱

版本約定

  • JDK:8

正文

下面這張圖是一個完整的日期時間,拆解各個部分的含義,一目瞭然(建議收藏此圖):

因爲LocalDate、LocalTime等理解起來比較簡單,就不用再花筆墨介紹了,重點放在LocalDateTime、OffsetDateTime、ZonedDateTime它三身上。

什麼是LocalDateTime?

ISO-8601日曆系統中不帶時區的日期時間。

說明:ISO-8601日系統是現今世界上絕大部分國家/地區使用的,這就是我們國人所說的公曆,有閏年的特性

LocalDateTime是一個不可變的日期-時間對象,它表示一個日期時間,通常被視爲年-月-日-小時-分鐘-秒。還可以訪問其他日期和時間字段,如day-of-year、day-of-week和week-of-year等等,它的精度能達納秒級別。

該類不存儲時區,所以適合日期的描述,比如用於生日、deadline等等。但是請記住,如果沒有偏移量/時區等附加信息,一個時間是不能表示時間線上的某一時刻的。

代碼示例

最大/最小值:

@Test
public void test1() {
    LocalDateTime min = LocalDateTime.MIN;
    LocalDateTime max = LocalDateTime.MAX;

    System.out.println("LocalDateTime最小值:" + min);
    System.out.println("LocalDateTime最大值:" + max);
    System.out.println(min.getYear() + "-" + min.getMonthValue() + "-" + min.getDayOfMonth());
    System.out.println(max.getYear() + "-" + max.getMonthValue() + "-" + max.getDayOfMonth());
}

輸出:
LocalDateTime最小值:-999999999-01-01T00:00
LocalDateTime最大值:+999999999-12-31T23:59:59.999999999
-999999999-1-1
999999999-12-31

構造:

@Test
public void test2() {
    System.out.println("當前時區的本地時間:" + LocalDateTime.now());
    System.out.println("當前時區的本地時間:" + LocalDateTime.of(LocalDate.now(), LocalTime.now()));

    System.out.println("紐約時區的本地時間:" + LocalDateTime.now(ZoneId.of("America/New_York")));
}

輸出:
當前時區的本地時間:2021-01-17T17:00:41.446
當前時區的本地時間:2021-01-17T17:00:41.447
紐約時區的本地時間:2021-01-17T04:00:41.450

注意,最後一個構造傳入了ZoneId,並不是說LocalDateTime和時區有關了,而是告訴說這個Local指的是紐約,細品這句話。

計算:

@Test
public void test3() {
    LocalDateTime now = LocalDateTime.now(ZoneId.systemDefault());
    System.out.println("計算前:" + now);

    // 加3天
    LocalDateTime after = now.plusDays(3);
    // 減4個小時
    after = after.plusHours(-3); // 效果同now.minusDays(3);
    System.out.println("計算後:" + after);

    // 計算時間差
    Period period = Period.between(now.toLocalDate(), after.toLocalDate());
    System.out.println("相差天數:" + period.getDays());
    Duration duration = Duration.between(now.toLocalTime(), after.toLocalTime());
    System.out.println("相差小時數:" + duration.toHours());
}

輸出:
計算前:2021-01-17T17:10:15.381
計算後:2021-01-20T14:10:15.381
相差天數:3
相差小時數:-3

格式化:

@Test
public void test4() {
    LocalDateTime now = LocalDateTime.now(ZoneId.systemDefault());
    // System.out.println("格式化輸出:" + DateTimeFormatter.ISO_LOCAL_DATE_TIME.format(now));
    System.out.println("格式化輸出(本地化輸出,中文環境):" + DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT, FormatStyle.SHORT).format(now));

    String dateTimeStrParam = "2021-01-17 18:00:00";
    System.out.println("解析後輸出:" + LocalDateTime.parse(dateTimeStrParam, DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss", Locale.US)));
}

輸出:
格式化輸出(本地化輸出,中文環境):21-1-17 下午5:15
解析後輸出:2021-01-17T18:00

什麼是OffsetDateTime?

ISO-8601日曆系統中與UTC偏移量有關的日期時間。OffsetDateTime是一個帶有偏移量的日期時間類型。存儲有精確到納秒的日期時間,以及偏移量。可以簡單理解爲 OffsetDateTime = LocalDateTime + ZoneOffset。

OffsetDateTime、ZonedDateTime和Instant它們三都能在時間線上以納秒精度存儲一個瞬間(請注意:LocalDateTime是不行的),也可理解我某個時刻。OffsetDateTime和Instant可用於模型的字段類型,因爲它們都表示瞬間值並且還不可變,所以適合網絡傳輸或者數據庫持久化。

ZonedDateTime不適合網絡傳輸/持久化,因爲即使同一個ZoneId時區,不同地方獲取到瞬時值也有可能不一樣

代碼示例

最大/最小值:

@Test
public void test5() {
    OffsetDateTime min = OffsetDateTime.MIN;
    OffsetDateTime max = OffsetDateTime.MAX;

    System.out.println("OffsetDateTime最小值:" + min);
    System.out.println("OffsetDateTime最大值:" + max);
    System.out.println(min.getOffset() + ":" + min.getYear() + "-" + min.getMonthValue() + "-" + min.getDayOfMonth());
    System.out.println(max.getOffset() + ":" + max.getYear() + "-" + max.getMonthValue() + "-" + max.getDayOfMonth());
}

輸出:
OffsetDateTime最小值:-999999999-01-01T00:00+18:00
OffsetDateTime最大值:+999999999-12-31T23:59:59.999999999-18:00
+18:00:-999999999-1-1
-18:00:999999999-12-31

偏移量的最大值是+18,最小值是-18,這是由ZoneOffset內部的限制決定的。

構造:

@Test
public void test6() {
    System.out.println("當前位置偏移量的本地時間:" + OffsetDateTime.now());
    System.out.println("偏移量-4(紐約)的本地時間::" + OffsetDateTime.of(LocalDateTime.now(), ZoneOffset.of("-4")));

    System.out.println("紐約時區的本地時間:" + OffsetDateTime.now(ZoneId.of("America/New_York")));
}

輸出:
當前位置偏移量的本地時間:2021-01-17T19:02:06.328+08:00
偏移量-4(紐約)的本地時間::2021-01-17T19:02:06.329-04:00
紐約時區的本地時間:2021-01-17T06:02:06.330-05:00

計算:

格式化:

@Test
public void test7() {
    OffsetDateTime now = OffsetDateTime.now(ZoneId.systemDefault());
    System.out.println("格式化輸出(本地化輸出,中文環境):" + DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT, FormatStyle.SHORT).format(now));

    String dateTimeStrParam = "2021-01-17T18:00:00+07:00";
    System.out.println("解析後輸出:" + OffsetDateTime.parse(dateTimeStrParam));
}

輸出:
格式化輸出(本地化輸出,中文環境):21-1-17 下午7:06
解析後輸出:2021-01-17T18:00+07:00

轉換:
LocalDateTime -> OffsetDateTime

@Test
public void test8() {
    LocalDateTime localDateTime = LocalDateTime.of(2021, 01, 17, 18, 00, 00);
    System.out.println("當前時區(北京)時間爲:" + localDateTime);

    // 轉換爲偏移量爲 -4的OffsetDateTime時間
    // 1、-4地方的晚上18點
    System.out.println("-4偏移量地方的晚上18點:" + OffsetDateTime.of(localDateTime, ZoneOffset.ofHours(-4)));
    System.out.println("-4偏移量地方的晚上18點(方式二):" + localDateTime.atOffset(ZoneOffset.ofHours(-4)));
    // 2、北京時間晚上18:00 對應的-4地方的時間點
    System.out.println("當前地區對應的-4地方的時間:" + OffsetDateTime.ofInstant(localDateTime.toInstant(ZoneOffset.ofHours(8)), ZoneOffset.ofHours(-4)));
}

輸出:
當前時區(北京)時間爲:2021-01-17T18:00
-4偏移量地方的晚上18點:2021-01-17T18:00-04:00
-4偏移量地方的晚上18點(方式二):2021-01-17T18:00-04:00
當前地區對應的-4地方的時間:2021-01-17T06:00-04:00

通過此例值得注意的是:LocalDateTime#atOffset()/atZone()只是增加了偏移量/時區,本地時間是並沒有改變的。若想實現本地時間到其它偏移量的對應的時間只能通過其ofInstant()系列構造方法。

OffsetDateTime -> LocalDateTime

@Test
public void test81() {
    OffsetDateTime offsetDateTime = OffsetDateTime.of(LocalDateTime.now(), ZoneOffset.ofHours(-4));
    System.out.println("-4偏移量時間爲:" + offsetDateTime);

    // 轉爲LocalDateTime 注意:時間還是未變的哦
    System.out.println("LocalDateTime的表示形式:" + offsetDateTime.toLocalDateTime());
}

輸出:
-4偏移量時間爲:2021-01-17T19:33:28.139-04:00
LocalDateTime的表示形式:2021-01-17T19:33:28.139

什麼是ZonedDateTime?

ISO-8601國際標準日曆系統中帶有時區的日期時間。它存儲所有的日期和時間字段,精度爲納秒,以及一個時區,帶有用於處理不明確的本地日期時間的時區偏移量。

這個API可以處理從LocalDateTime -> Instant -> ZonedDateTime的轉換,其中用zone時區來表示偏移量(並非直接用offset哦)。兩個時間點之間的轉換會涉及到使用從ZoneId訪問的規則計算偏移量(換句話說:偏移量並非寫死而是根據規則計算出來的)。

獲取瞬間的偏移量很簡單,因爲每個瞬間只有一個有效的偏移量。但是,獲取本地日期時間的偏移量並不簡單。存在這三種情況:

  • 正常情況:有一個有效的偏移量。對於一年中的絕大多數時間,適用正常情況,即本地日期時間只有一個有效的偏移量
  • 時間間隙情況:沒有有效偏移量。這是由於夏令時開始時從“冬季”改爲“夏季”而導致時鐘向前撥的時候。在間隙中,沒有有效偏移量
  • 重疊情況:有兩個有效偏移量。這是由於秋季夏令時從“夏季”到“冬季”的變化,時鐘會向後撥。在重疊部分中,有兩個有效偏移量

這三種情況如果要自己處理,估計頭都大了。這就是使用JSR 310的優勢,ZonedDateTime全幫你搞定,讓你使用無憂。

ZonedDateTime可簡單認爲是LocalDateTime和ZoneId的組合。而ZoneOffset是其內置的動態計算出來的一個次要信息,以確保輸出一個瞬時值而存在,畢竟在某個瞬間偏移量ZoneOffset肯定是確定的。ZonedDateTime也可以理解爲保存的狀態相當於三個獨立的對象:LocalDateTime、ZoneId和ZoneOffset。某個瞬間 = LocalDateTime + ZoneOffset。ZoneId確定了偏移量如何改變的規則。所以偏移量我們並不能自由設置(不提供set方法,構造時也不行),因爲它由ZoneId來控制的。

代碼示例

構造:

@Test
public void test9() {
    System.out.println("當前位置偏移量的本地時間:" + ZonedDateTime.now());
    System.out.println("紐約時區的本地時間:" + ZonedDateTime.of(LocalDateTime.now(), ZoneId.of("America/New_York")));

    System.out.println("北京實現對應的紐約時區的本地時間:" + ZonedDateTime.now(ZoneId.of("America/New_York")));
}

輸出:
當前位置偏移量的本地時間:2021-01-17T19:25:10.520+08:00[Asia/Shanghai]
紐約時區的本地時間:2021-01-17T19:25:10.521-05:00[America/New_York]
北京實現對應的紐約時區的本地時間:2021-01-17T06:25:10.528-05:00[America/New_York]

計算:

格式化:

轉換:
LocalDateTime -> ZonedDateTime

@Test
public void test10() {
    LocalDateTime localDateTime = LocalDateTime.of(2021, 01, 17, 18, 00, 00);
    System.out.println("當前時區(北京)時間爲:" + localDateTime);

    // 轉換爲偏移量爲 -4的OffsetDateTime時間
    // 1、-4地方的晚上18點
    System.out.println("紐約時區晚上18點:" + ZonedDateTime.of(localDateTime, ZoneId.of("America/New_York")));
    System.out.println("紐約時區晚上18點(方式二):" + localDateTime.atZone(ZoneId.of("America/New_York")));
    // 2、北京時間晚上18:00 對應的-4地方的時間點
    System.out.println("北京地區此時間對應的紐約的時間:" + ZonedDateTime.ofInstant(localDateTime.toInstant(ZoneOffset.ofHours(8)), ZoneOffset.ofHours(-4)));
    System.out.println("北京地區此時間對應的紐約的時間:" + ZonedDateTime.ofInstant(localDateTime, ZoneOffset.ofHours(8), ZoneOffset.ofHours(-4)));
}

輸出:
當前時區(北京)時間爲:2021-01-17T18:00
紐約時區晚上18點:2021-01-17T18:00-05:00[America/New_York]
紐約時區晚上18點(方式二):2021-01-17T18:00-05:00[America/New_York]
北京地區此時間對應的紐約的時間:2021-01-17T06:00-04:00
北京地區此時間對應的紐約的時間:2021-01-17T06:00-04:00

OffsetDateTime -> ZonedDateTime

@Test
public void test101() {
    OffsetDateTime offsetDateTime = OffsetDateTime.of(LocalDateTime.now(), ZoneOffset.ofHours(-4));
    System.out.println("-4偏移量時間爲:" + offsetDateTime);

    // 轉換爲ZonedDateTime的表示形式
    System.out.println("ZonedDateTime的表示形式:" + offsetDateTime.toZonedDateTime());
    System.out.println("ZonedDateTime的表示形式:" + offsetDateTime.atZoneSameInstant(ZoneId.of("America/New_York")));
    System.out.println("ZonedDateTime的表示形式:" + offsetDateTime.atZoneSimilarLocal(ZoneId.of("America/New_York")));
}

-4偏移量時間爲:2021-01-17T19:43:28.320-04:00
ZonedDateTime的表示形式:2021-01-17T19:43:28.320-04:00
ZonedDateTime的表示形式:2021-01-17T18:43:28.320-05:00[America/New_York]
ZonedDateTime的表示形式:2021-01-17T19:43:28.320-05:00[America/New_York]

本例有值得關注的點:

  • atZoneSameInstant():將此日期時間與時區結合起來創建ZonedDateTime,以確保結果具有相同的Instant
    • 所有偏移量-4 -> -5,時間點也從19 -> 18,確保了Instant保持一致嘛
  • atZoneSimilarLocal:將此日期時間與時區結合起來創建ZonedDateTime,以確保結果具有相同的本地時間
    • 所以直接效果和toLocalDateTime()是一樣的,但是它會盡可能的保留偏移量(所以你看-4變爲了-5,保持了真實的偏移量)

我這裏貼出紐約2021年的夏令時時間區間:

也就是說在2021.03.14 - 2021.11.07期間,紐約的偏移量是-4,其餘時候是-5。那麼再看這個例子(我把時間改爲5月5號,也就是處於夏令營期間):

@Test
public void test101() {
    OffsetDateTime offsetDateTime = OffsetDateTime.of(LocalDateTime.of(2021, 05, 05, 18, 00, 00), ZoneOffset.ofHours(-4));
    System.out.println("-4偏移量時間爲:" + offsetDateTime);

    // 轉換爲ZonedDateTime的表示形式
    System.out.println("ZonedDateTime的表示形式:" + offsetDateTime.toZonedDateTime());
    System.out.println("ZonedDateTime的表示形式:" + offsetDateTime.atZoneSameInstant(ZoneId.of("America/New_York")));
    System.out.println("ZonedDateTime的表示形式:" + offsetDateTime.atZoneSimilarLocal(ZoneId.of("America/New_York")));
}

輸出:
-4偏移量時間爲:2021-05-05T18:00-04:00
ZonedDateTime的表示形式:2021-05-05T18:00-04:00
ZonedDateTime的表示形式:2021-05-05T18:00-04:00[America/New_York]
ZonedDateTime的表示形式:2021-05-05T18:00-04:00[America/New_York]

看到了吧,偏移量變爲了-4。感受到夏令時的“威力”了吧。

OffsetDateTime和ZonedDateTime的區別

LocalDateTime、OffsetDateTime、ZonedDateTime這三個哥們,LocalDateTime好理解,一般都沒有異議。但是很多同學對OffsetDateTime和ZonedDateTime傻傻分不清,這裏說說它倆的區別。

  1. OffsetDateTime = LocalDateTime + 偏移量ZoneOffset;ZonedDateTime = LocalDateTime + 時區ZoneId
  2. OffsetDateTime可以隨意設置偏移值,但ZonedDateTime無法自由設置偏移值,因爲此值是由時區ZoneId控制的
  3. OffsetDateTime無法支持夏令時等規則,但ZonedDateTime可以很好的處理夏令時調整
  4. OffsetDateTime得益於不變性一般用於數據庫存儲、網絡通信;而ZonedDateTime得益於其時區特性,一般在指定時區裏顯示時間非常方便,無需認爲干預規則
  5. OffsetDateTime代表一個瞬時值,而ZonedDateTime的值是不穩定的,需要在某個瞬時根據當時的規則計算出來偏移量從而確定實際值

總的來說,OffsetDateTime和ZonedDateTime的區別主要在於ZoneOffset和ZoneId的區別。如果你只是用來傳遞數據,請使用OffsetDateTime,若你想在特定時區裏做時間顯示那麼請務必使用ZonedDateTime。

總結

本着拒絕淺嘗輒止的態度,深度剖析了很多同學可能不太熟悉的OffsetDateTime、ZonedDateTime兩個API。總而言之,想要真正掌握日期時間體系(不限於Java語言,而是所有語言,甚至日常生活),對時區、偏移量的瞭解是繞不過去的砍,這塊知識有所欠缺的朋友可往前翻翻補補課。

最後在使用它們三的過程中,有兩個提醒給你:

  1. 所有日期/時間都是不可變的類型,所以若需要比較的話,請不要使用==,而是用equals()方法。
    2、任何時候,構造一個日期時間(包括它們三)請永遠務必顯示的指定時區,哪怕是默認時區。這麼做的目的就是明確代碼的意圖,消除語義上的不確定性。比如若沒指定時區,那到底是寫代碼的人欠考慮了呢,還是就是想用默認時區呢?總之顯示指定絕大部分情況下比隱式“指定”語義上好得多。

本文思考題

看完了不一定懂,看懂了不一定會。來,文末3個思考題幫你覆盤:

  1. 如何用LocalDateTime描述美國紐約本地時間?
  2. OffsetDateTime和ZonedDateTime你到底該使用誰?
  3. 一個人的生日應該用什麼Java類型存儲呢?

推薦閱讀

GMT UTC CST ISO 夏令時 時間戳,都是些什麼鬼?

全網最全!徹底弄透Java處理GMT/UTC日期時間

全球城市ZoneId和UTC時間偏移量的最全對照表

關注我

分享、成長,拒絕淺嘗輒止。關注【BAT的烏托邦】回覆關鍵字專欄有Spring技術棧、中間件等小而美的純原創專欄。本文已被 https://www.yourbatman.cn 收錄。

本文所屬專欄:JDK日期時間,公號後臺回覆專欄名即可獲取全部內容。

A哥(YourBatman):Spring Framework/Boot開源貢獻者,Java架構師。非常注重基本功修養,相信底層基礎決定上層建築,堅實基礎才能煥發程序員更強生命力。文章特點爲以小而美專欄形式重構知識體系,抽絲剝繭,致力於做人人能看懂的最好的專欄系列。可加我好友(fsx1056342982)共勉哦!

System.out.println("點個贊吧!");
print_r('關注【BAT的烏托邦】!');
var_dump('點個贊吧!');
NSLog(@"關注【BAT的烏托邦】!");
console.log("點個贊吧!");
print("關注【BAT的烏托邦】!");
printf("點個贊吧!");
cout << "關注【BAT的烏托邦】!" << endl;
Console.WriteLine("點個贊吧!");
fmt.Println("關注【BAT的烏托邦】!");
Response.Write("點個贊吧!");
alert("關注【BAT的烏托邦】!");
echo("點個贊吧!");
發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章