詳解LocalDateTime、OffsetDateTime、ZonedDateTime互轉(zhuǎn),這一篇絕對喂飽你
你好,我是A哥(YourBatman)。
在JSR 310日期時間體系了,一共有三個API可用于表示日期時間:
- LocalDateTime:本地日期時間
- OffsetDateTime:帶偏移量的日期時間
- ZonedDateTime:帶時區(qū)的日期時間
也許平時開發(fā)中你只用到過LocalDateTime這個API,那是極好的,但是不能止步于此,否則就圖樣圖森破了。
隨著場景的多樣性變化,咱們開發(fā)者接觸到OffsetDateTime/ZonedDateTime的概率越來越大,但凡和國際化產(chǎn)生上關(guān)系的大概率都會用得到它們。本文依然站在實用的角度,輔以具體代碼示例,介紹它三。
本文提綱

版本約定
JDK:8
正文
下面這張圖是一個完整的日期時間,拆解各個部分的含義,一目了然(建議收藏此圖):

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

ISO-8601日歷系統(tǒng)中不帶時區(qū)的日期時間。
- ❝說明:ISO-8601日系統(tǒng)是現(xiàn)今世界上絕大部分國家/地區(qū)使用的,這就是我們國人所說的公歷,有閏年的特性❞
LocalDateTime是一個不可變的日期-時間對象,它表示一個日期時間,通常被視為年-月-日-小時-分鐘-秒。還可以訪問其他日期和時間字段,如day-of-year、day-of-week和week-of-year等等,它的精度能達(dá)納秒級別。
該類不存儲時區(qū),所以適合日期的描述,比如用于生日、deadline等等。但是請記住,如果沒有偏移量/時區(qū)等附加信息,一個時間是不能表示時間線上的某一時刻的。
代碼示例
最大/最小值:
- @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
構(gòu)造:
- @Test
- public void test2() {
- System.out.println("當(dāng)前時區(qū)的本地時間:" + LocalDateTime.now());
- System.out.println("當(dāng)前時區(qū)的本地時間:" + LocalDateTime.of(LocalDate.now(), LocalTime.now()));
- System.out.println("紐約時區(qū)的本地時間:" + LocalDateTime.now(ZoneId.of("America/New_York")));
- }
- 輸出:
- 當(dāng)前時區(qū)的本地時間:2021-01-17T17:00:41.446
- 當(dāng)前時區(qū)的本地時間:2021-01-17T17:00:41.447
- 紐約時區(qū)的本地時間:2021-01-17T04:00:41.450
注意,最后一個構(gòu)造傳入了ZoneId,并不是說LocalDateTime和時區(qū)有關(guān)了,而是告訴說這個Local指的是紐約,細(xì)品這句話。
計算:
- @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("相差天數(shù):" + period.getDays());
- Duration duration = Duration.between(now.toLocalTime(), after.toLocalTime());
- System.out.println("相差小時數(shù):" + duration.toHours());
- }
- 輸出:
- 計算前:2021-01-17T17:10:15.381
- 計算后:2021-01-20T14:10:15.381
- 相差天數(shù):3
- 相差小時數(shù):-3
格式化:
- @Test
- public void test4() {
- LocalDateTime now = LocalDateTime.now(ZoneId.systemDefault());
- // System.out.println("格式化輸出:" + DateTimeFormatter.ISO_LOCAL_DATE_TIME.format(now));
- System.out.println("格式化輸出(本地化輸出,中文環(huán)境):" + 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)));
- }
- 輸出:
- 格式化輸出(本地化輸出,中文環(huán)境):21-1-17 下午5:15
- 解析后輸出:2021-01-17T18:00
什么是OffsetDateTime?

ISO-8601日歷系統(tǒng)中與UTC偏移量有關(guān)的日期時間。OffsetDateTime是一個帶有偏移量的日期時間類型。存儲有精確到納秒的日期時間,以及偏移量。可以簡單理解為 OffsetDateTime = LocalDateTime + ZoneOffset。

OffsetDateTime、ZonedDateTime和Instant它們?nèi)寄茉跁r間線上以納秒精度存儲一個瞬間(請注意:LocalDateTime是不行的),也可理解我某個時刻。OffsetDateTime和Instant可用于模型的字段類型,因為它們都表示瞬間值并且還不可變,所以適合網(wǎng)絡(luò)傳輸或者數(shù)據(jù)庫持久化。
- ❝ZonedDateTime不適合網(wǎng)絡(luò)傳輸/持久化,因為即使同一個ZoneId時區(qū),不同地方獲取到瞬時值也有可能不一樣❞
代碼示例
最大/最小值:
- @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內(nèi)部的限制決定的。
構(gòu)造:
- @Test
- public void test6() {
- System.out.println("當(dāng)前位置偏移量的本地時間:" + OffsetDateTime.now());
- System.out.println("偏移量-4(紐約)的本地時間::" + OffsetDateTime.of(LocalDateTime.now(), ZoneOffset.of("-4")));
- System.out.println("紐約時區(qū)的本地時間:" + OffsetDateTime.now(ZoneId.of("America/New_York")));
- }
- 輸出:
- 當(dāng)前位置偏移量的本地時間:2021-01-17T19:02:06.328+08:00
- 偏移量-4(紐約)的本地時間::2021-01-17T19:02:06.329-04:00
- 紐約時區(qū)的本地時間:2021-01-17T06:02:06.330-05:00
計算:略
格式化:
- @Test
- public void test7() {
- OffsetDateTime now = OffsetDateTime.now(ZoneId.systemDefault());
- System.out.println("格式化輸出(本地化輸出,中文環(huán)境):" + DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT, FormatStyle.SHORT).format(now));
- String dateTimeStrParam = "2021-01-17T18:00:00+07:00";
- System.out.println("解析后輸出:" + OffsetDateTime.parse(dateTimeStrParam));
- }
- 輸出:
- 格式化輸出(本地化輸出,中文環(huán)境):21-1-17 下午7:06
- 解析后輸出:2021-01-17T18:00+07:00
轉(zhuǎn)換:LocalDateTime -> OffsetDateTime
- @Test
- public void test8() {
- LocalDateTime localDateTime = LocalDateTime.of(2021, 01, 17, 18, 00, 00);
- System.out.println("當(dāng)前時區(qū)(北京)時間為:" + localDateTime);
- // 轉(zhuǎn)換為偏移量為 -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 對應(yīng)的-4地方的時間點
- System.out.println("當(dāng)前地區(qū)對應(yīng)的-4地方的時間:" + OffsetDateTime.ofInstant(localDateTime.toInstant(ZoneOffset.ofHours(8)), ZoneOffset.ofHours(-4)));
- }
- 輸出:
- 當(dāng)前時區(qū)(北京)時間為:2021-01-17T18:00
- -4偏移量地方的晚上18點:2021-01-17T18:00-04:00
- -4偏移量地方的晚上18點(方式二):2021-01-17T18:00-04:00
- 當(dāng)前地區(qū)對應(yīng)的-4地方的時間:2021-01-17T06:00-04:00
通過此例值得注意的是:LocalDateTime#atOffset()/atZone()只是增加了偏移量/時區(qū),本地時間是并沒有改變的。若想實現(xiàn)本地時間到其它偏移量的對應(yīng)的時間只能通過其ofInstant()系列構(gòu)造方法。
OffsetDateTime -> LocalDateTime
- @Test
- public void test81() {
- OffsetDateTime offsetDateTime = OffsetDateTime.of(LocalDateTime.now(), ZoneOffset.ofHours(-4));
- System.out.println("-4偏移量時間為:" + offsetDateTime);
- // 轉(zhuǎn)為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國際標(biāo)準(zhǔn)日歷系統(tǒng)中帶有時區(qū)的日期時間。它存儲所有的日期和時間字段,精度為納秒,以及一個時區(qū),帶有用于處理不明確的本地日期時間的時區(qū)偏移量。
這個API可以處理從LocalDateTime -> Instant -> ZonedDateTime的轉(zhuǎn)換,其中用zone時區(qū)來表示偏移量(并非直接用offset哦)。兩個時間點之間的轉(zhuǎn)換會涉及到使用從ZoneId訪問的規(guī)則計算偏移量(換句話說:偏移量并非寫死而是根據(jù)規(guī)則計算出來的)。
獲取瞬間的偏移量很簡單,因為每個瞬間只有一個有效的偏移量。但是,獲取本地日期時間的偏移量并不簡單。存在這三種情況:
- 正常情況:有一個有效的偏移量。對于一年中的絕大多數(shù)時間,適用正常情況,即本地日期時間只有一個有效的偏移量
- 時間間隙情況:沒有有效偏移量。這是由于夏令時開始時從“冬季”改為“夏季”而導(dǎo)致時鐘向前撥的時候。在間隙中,沒有有效偏移量
- 重疊情況:有兩個有效偏移量。這是由于秋季夏令時從“夏季”到“冬季”的變化,時鐘會向后撥。在重疊部分中,有兩個有效偏移量
這三種情況如果要自己處理,估計頭都大了。這就是使用JSR 310的優(yōu)勢,ZonedDateTime全幫你搞定,讓你使用無憂。
ZonedDateTime可簡單認(rèn)為是LocalDateTime和ZoneId的組合。而ZoneOffset是其內(nèi)置的動態(tài)計算出來的一個次要信息,以確保輸出一個瞬時值而存在,畢竟在某個瞬間偏移量ZoneOffset肯定是確定的。ZonedDateTime也可以理解為保存的狀態(tài)相當(dāng)于三個獨立的對象:LocalDateTime、ZoneId和ZoneOffset。某個瞬間 = LocalDateTime + ZoneOffset。ZoneId確定了偏移量如何改變的規(guī)則。所以偏移量我們并不能自由設(shè)置(不提供set方法,構(gòu)造時也不行),因為它由ZoneId來控制的。

代碼示例
構(gòu)造:
- @Test
- public void test9() {
- System.out.println("當(dāng)前位置偏移量的本地時間:" + ZonedDateTime.now());
- System.out.println("紐約時區(qū)的本地時間:" + ZonedDateTime.of(LocalDateTime.now(), ZoneId.of("America/New_York")));
- System.out.println("北京實現(xiàn)對應(yīng)的紐約時區(qū)的本地時間:" + ZonedDateTime.now(ZoneId.of("America/New_York")));
- }
- 輸出:
- 當(dāng)前位置偏移量的本地時間:2021-01-17T19:25:10.520+08:00[Asia/Shanghai]
- 紐約時區(qū)的本地時間:2021-01-17T19:25:10.521-05:00[America/New_York]
- 北京實現(xiàn)對應(yīng)的紐約時區(qū)的本地時間:2021-01-17T06:25:10.528-05:00[America/New_York]
計算:略
格式化:略
轉(zhuǎn)換:LocalDateTime -> ZonedDateTime
- @Test
- public void test10() {
- LocalDateTime localDateTime = LocalDateTime.of(2021, 01, 17, 18, 00, 00);
- System.out.println("當(dāng)前時區(qū)(北京)時間為:" + localDateTime);
- // 轉(zhuǎn)換為偏移量為 -4的OffsetDateTime時間
- // 1、-4地方的晚上18點
- System.out.println("紐約時區(qū)晚上18點:" + ZonedDateTime.of(localDateTime, ZoneId.of("America/New_York")));
- System.out.println("紐約時區(qū)晚上18點(方式二):" + localDateTime.atZone(ZoneId.of("America/New_York")));
- // 2、北京時間晚上18:00 對應(yīng)的-4地方的時間點
- System.out.println("北京地區(qū)此時間對應(yīng)的紐約的時間:" + ZonedDateTime.ofInstant(localDateTime.toInstant(ZoneOffset.ofHours(8)), ZoneOffset.ofHours(-4)));
- System.out.println("北京地區(qū)此時間對應(yīng)的紐約的時間:" + ZonedDateTime.ofInstant(localDateTime, ZoneOffset.ofHours(8), ZoneOffset.ofHours(-4)));
- }
- 輸出:
- 當(dāng)前時區(qū)(北京)時間為:2021-01-17T18:00
- 紐約時區(qū)晚上18點:2021-01-17T18:00-05:00[America/New_York]
- 紐約時區(qū)晚上18點(方式二):2021-01-17T18:00-05:00[America/New_York]
- 北京地區(qū)此時間對應(yīng)的紐約的時間:2021-01-17T06:00-04:00
- 北京地區(qū)此時間對應(yīng)的紐約的時間: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);
- // 轉(zhuǎn)換為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]
本例有值得關(guān)注的點:
- atZoneSameInstant():將此日期時間與時區(qū)結(jié)合起來創(chuàng)建ZonedDateTime,以確保結(jié)果具有相同的Instant
所有偏移量-4 -> -5,時間點也從19 -> 18,確保了Instant保持一致嘛
- atZoneSimilarLocal:將此日期時間與時區(qū)結(jié)合起來創(chuàng)建ZonedDateTime,以確保結(jié)果具有相同的本地時間
所以直接效果和toLocalDateTime()是一樣的,但是它會盡可能的保留偏移量(所以你看-4變?yōu)榱?5,保持了真實的偏移量)
我這里貼出紐約2021年的夏令時時間區(qū)間:

也就是說在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);
- // 轉(zhuǎn)換為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]
看到了吧,偏移量變?yōu)榱?4。感受到夏令時的“威力”了吧。
OffsetDateTime和ZonedDateTime的區(qū)別
LocalDateTime、OffsetDateTime、ZonedDateTime這三個哥們,LocalDateTime好理解,一般都沒有異議。但是很多同學(xué)對OffsetDateTime和ZonedDateTime傻傻分不清,這里說說它倆的區(qū)別。
- OffsetDateTime = LocalDateTime + 偏移量ZoneOffset;ZonedDateTime = LocalDateTime + 時區(qū)ZoneId
- OffsetDateTime可以隨意設(shè)置偏移值,但ZonedDateTime無法自由設(shè)置偏移值,因為此值是由時區(qū)ZoneId控制的
- OffsetDateTime無法支持夏令時等規(guī)則,但ZonedDateTime可以很好的處理夏令時調(diào)整
- OffsetDateTime得益于不變性一般用于數(shù)據(jù)庫存儲、網(wǎng)絡(luò)通信;而ZonedDateTime得益于其時區(qū)特性,一般在指定時區(qū)里顯示時間非常方便,無需認(rèn)為干預(yù)規(guī)則
- OffsetDateTime代表一個瞬時值,而ZonedDateTime的值是不穩(wěn)定的,需要在某個瞬時根據(jù)當(dāng)時的規(guī)則計算出來偏移量從而確定實際值
總的來說,OffsetDateTime和ZonedDateTime的區(qū)別主要在于ZoneOffset和ZoneId的區(qū)別。如果你只是用來傳遞數(shù)據(jù),請使用OffsetDateTime,若你想在特定時區(qū)里做時間顯示那么請務(wù)必使用ZonedDateTime。
總結(jié)
本著拒絕淺嘗輒止的態(tài)度,深度剖析了很多同學(xué)可能不太熟悉的OffsetDateTime、ZonedDateTime兩個API??偠灾?,想要真正掌握日期時間體系(不限于Java語言,而是所有語言,甚至日常生活),對時區(qū)、偏移量的了解是繞不過去的砍,這塊知識有所欠缺的朋友可往前翻翻補補課。
最后在使用它們?nèi)倪^程中,有兩個提醒給你:
所有日期/時間都是不可變的類型,所以若需要比較的話,請不要使用==,而是用equals()方法。2、任何時候,構(gòu)造一個日期時間(包括它們?nèi)?請永遠(yuǎn)務(wù)必顯示的指定時區(qū),哪怕是默認(rèn)時區(qū)。這么做的目的就是明確代碼的意圖,消除語義上的不確定性。比如若沒指定時區(qū),那到底是寫代碼的人欠考慮了呢,還是就是想用默認(rèn)時區(qū)呢?總之顯示指定絕大部分情況下比隱式“指定”語義上好得多。
本文思考題
看完了不一定懂,看懂了不一定會。來,文末3個思考題幫你復(fù)盤:
如何用LocalDateTime描述美國紐約本地時間?
OffsetDateTime和ZonedDateTime你到底該使用誰?
一個人的生日應(yīng)該用什么Java類型存儲呢?