421. Java 日期時(shí)間 API - 包結(jié)構(gòu) & 方法命名規(guī)范

1. Date-Time API 的包結(jié)構(gòu) ???

Java 的 Date-Time API 主要由一個(gè)核心包和四個(gè)子包組成：

1.1 java.time（核心包）

這是整個(gè) API 的核心，提供最常用的類：

• LocalDate → 只包含日期
• LocalTime → 只包含時(shí)間
• LocalDateTime → 日期 + 時(shí)間（不帶時(shí)區(qū)）
• ZonedDateTime → 帶時(shí)區(qū)的日期和時(shí)間
• Instant → 時(shí)間戳（精確到納秒）
• Duration → 表示兩個(gè)時(shí)間點(diǎn)之間的時(shí)長
• Clock → 提供訪問當(dāng)前時(shí)間和時(shí)區(qū)的方式

?? 特點(diǎn)：這些類都是基于 ISO-8601 日歷系統(tǒng)，不可變（immutable）且線程安全。

示例：

LocalDate today = LocalDate.now();
LocalTime time = LocalTime.now();
LocalDateTime dateTime = LocalDateTime.now();
Instant timestamp = Instant.now();

System.out.println("今天: " + today);
System.out.println("現(xiàn)在的時(shí)間: " + time);
System.out.println("當(dāng)前日期時(shí)間: " + dateTime);
System.out.println("時(shí)間戳: " + timestamp);

1.2 java.time.chrono（替代日歷系統(tǒng)）

提供 非 ISO-8601 日歷，例如：

• Hijrah（伊斯蘭歷）
• JapaneseDate（日本歷法）
• ThaiBuddhistDate（泰國佛歷）

你也可以自己定義日歷系統(tǒng)（不過很少用）。

示例：

HijrahDate hijrahDate = HijrahDate.now();
System.out.println("伊斯蘭歷日期: " + hijrahDate);

JapaneseDate japaneseDate = JapaneseDate.now();
System.out.println("日本歷日期: " + japaneseDate);

1.3 java.time.format（格式化與解析）

提供日期時(shí)間的 格式化（format） 和 解析（parse）。

示例：

LocalDate date = LocalDate.of(2025, 9, 15);
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy年MM月dd日");
System.out.println("格式化日期: " + date.format(formatter));

String input = "2025-09-15";
LocalDate parsedDate = LocalDate.parse(input, DateTimeFormatter.ISO_LOCAL_DATE);
System.out.println("解析后的日期: " + parsedDate);

1.4 java.time.temporal（時(shí)間操作擴(kuò)展）

給框架和庫開發(fā)者用的擴(kuò)展 API：

• TemporalField / ChronoField → 日期時(shí)間的字段（比如 YEAR、MONTH、DAY_OF_MONTH）
• TemporalUnit / ChronoUnit → 時(shí)間單位（比如 DAYS、HOURS、MINUTES）
• 提供 時(shí)間查詢（query） 和 調(diào)整器（adjuster） 功能

示例：

LocalDate today = LocalDate.now();
int dayOfYear = today.get(ChronoField.DAY_OF_YEAR);
System.out.println("今天是一年的第幾天: " + dayOfYear);

LocalDate firstDayOfNextMonth = today.with(TemporalAdjusters.firstDayOfNextMonth());
System.out.println("下個(gè)月的第一天: " + firstDayOfNextMonth);

1.5 java.time.zone（時(shí)區(qū)支持）

提供時(shí)區(qū)和時(shí)區(qū)規(guī)則的支持。常見類：

• ZoneId
• ZoneOffset
• ZoneRules

?? 在大多數(shù)情況下，我們只需要用到 ZonedDateTime、ZoneId、ZoneOffset。

示例：

ZonedDateTime shanghaiTime = ZonedDateTime.now(ZoneId.of("Asia/Shanghai"));
ZonedDateTime newYorkTime = ZonedDateTime.now(ZoneId.of("America/New_York"));

System.out.println("上海時(shí)間: " + shanghaiTime);
System.out.println("紐約時(shí)間: " + newYorkTime);

2. 方法命名規(guī)范 ??

Date-Time API 方法的命名非常一致，方便記憶和使用。下面是常見前綴和它們的作用：

2.1 示例講解 ??

of → 創(chuàng)建對(duì)象

LocalDate date = LocalDate.of(2025, 9, 15);

from → 類型轉(zhuǎn)換

Instant instant = Instant.now();
ZonedDateTime zoned = ZonedDateTime.from(instant.atZone(ZoneId.systemDefault()));

parse → 字符串解析

LocalDate parsed = LocalDate.parse("2025-09-15");

format → 格式化輸出

DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String formatted = LocalDate.now().format(formatter);

get / is → 獲取或判斷

int day = LocalDate.now().getDayOfMonth();
boolean leap = LocalDate.now().isLeapYear();

with → 修改值（返回新對(duì)象）

LocalDate changed = LocalDate.now().withMonth(12);

plus / minus → 加減操作

LocalDate future = LocalDate.now().plusDays(10);
LocalDate past = LocalDate.now().minusWeeks(2);

to → 轉(zhuǎn)換

LocalDateTime ldt = LocalDateTime.now();
Instant inst = ldt.toInstant(ZoneOffset.UTC);

at → 組合

LocalDate today = LocalDate.now();
LocalTime time = LocalTime.of(14, 30);
LocalDateTime combined = today.atTime(time);

總結(jié) ??

• 包結(jié)構(gòu)：核心用 java.time，復(fù)雜需求可擴(kuò)展到 chrono、format、temporal、zone。
• 方法規(guī)范：命名規(guī)則統(tǒng)一，便于記憶；常見操作用 of、with、plus、minus、parse、format。
• 實(shí)際開發(fā)建議：優(yōu)先使用 java.time 包下的類，比如 LocalDateTime、ZonedDateTime，同時(shí)掌握 DateTimeFormatter 來處理輸入輸出。