JSR 310：新一代 Java 日期時間 API 深度解析

JSR 310 是獲推薦納入 Java SE 7 的日期時間 API，旨在取代現有的 java.util.Date 和 java.util.Calendar，並保持向後相容。目前仍在開發中，已提供實驗性 Javadoc。

改進現有 Java 6 日期時間 API 的痛點

• 效能與可預測性： Calendar 同時以毫秒偏移量與日曆欄位儲存日期，導致非預期的重新計算與不可預測效能。JSR 310 僅以奈秒偏移量儲存，僅在需要時計算日曆欄位。
• 模型完整性： Java 6 缺乏表示區域時間（無時區）、持續時間、時間間隔的類別，迫使開發者用 int 表示持續時間等混淆做法。JSR 310 提供對應類別，支援更明確的程式設計。
• 執行緒安全： JSR 310 使用不可變類別實現執行緒安全；Date 和 Calendar 皆可變，非執行緒安全。

五大核心日期時間概念

JSR 310 基於 Joda Time 經驗，圍繞五大概念建構：

1. 離散時間線
2. 瞬間
3. 不完全時間
4. 持續時間
5. 時段
6. 時間間隔

離散時間線

時間建模為由固定持續時間分隔的連續瞬間序列，具奈秒解析度。可表示「2008 年 1 月 1 日午夜後 1 奈秒」，但無法表示皮秒級別。

瞬間

離散時間線上的特定點，如「UTC 2008-01-07 23:00:00.0」或「UTC 1970-01-01 後 20,000,000 奈秒」。主要類別：

• Instant
• OffsetDateTime - 含 UTC 偏移量（如 +1:00）
• ZonedDateTime - 含時區 ID（如 America/New_York），可處理夏令時等區域規則

皆實作 ReadableInstant 介面。建立範例：

Clock systemClock = Clock.system();
ZonedDateTime currentTime = systemClock.currentZonedDateTime();

// 預先確定日期
TimeZone defaultTimeZone = systemClock.timeZone();
ZonedDateTime theDate = ZonedDateTime.dateTime(2000, 1, 1, 0, 0, defaultTimeZone);

不完全時間

不足以指定時間線上唯一點的日期或時間表示，如「6 月 7 日」（缺年份與時間）。無法用奈秒偏移量表示，必須基於日曆欄位定義。常用類別：

• MonthDay - 年度假期
• LocalDate - 無時間、時區的日期
• LocalTime - 無時區的時間

MonthDay christmas = MonthDay.monthDay(12, 25);

持續時間

表示精確流逝的奈秒數，如「100,000 奈秒」。可加至瞬間產生新瞬間。建立方式：

• 指定秒/毫秒/奈秒跨度
• 提供起始與結束瞬間

Duration d = Duration.duration(3600 * hours); // 預先確定長度
Duration d = Duration.durationBetween(instant1, instant2); // 兩瞬間間

時段

同樣表示流逝時間，但以日曆欄位定義（如「4 年 8 天」、「1 小時」）。與持續時間關鍵差異：無法轉換為確切奈秒數。瞬間/時段加法將各欄位值相加；瞬間/持續時間加法則加總奈秒數。因夏令時關係，某天可能非 24 小時，導致兩者結果不同。

Period thePeriod = Periods.periodBuilder().years(8).months(3).build();

時間間隔

表示時間線上兩瞬間之間的跨度，可包含或排除端點。使用 InstantInterval 類別：

InstantInterval interval1 = InstantInterval.intervalBetween(time1.toInstant(), time2.toInstant()); // 含起始、排除結束
InstantInterval interval2 = InstantInterval.intervalBetween(time1.toInstant(), false, time2.toInstant(), true); // 排除起始、含結束

實際應用範例

週期性瞬間事件： 用 ZonedDateTime + Duration，下一實例 = 前一實例 + Duration。

ZonedDateTime secondTime = ZonedDateTime.dateTime(
    firstTime.toInstant().plus(repeatTime), defaultZone);

週期性非瞬間事件： 用 ZonedDateTime + Period。

ZonedDateTime secondTime = firstTime.plus(repeatPeriod);

判斷兩瞬間事件是否同時：

if (time1.equals(time2)) { ... }

瞬間事件與不完全時間（如聖誕節）是否重疊：

if (christmas.matchesDate(time1.localDate())) { ... }

時間跨度事件與瞬間事件是否重疊：

if (event1.contains(event2)) { ... }

結語

JSR 310 為 Java 7 帶來全新的日期時間 API，核心概念涵蓋瞬間、不完全時間、持續時間、時段、時間間隔。尚有進階日期時間比對等功能未介紹，且 API 仍在演進中。詳細資訊請參考官方規格文件。