Java 日期時間處理完全指南：Calendar、SimpleDateFormat、加減運算與比較最佳實踐 (JDK 8 前)

核心類選型建議

• java.util.Calendar：線程不安全，但功能全面，JDK 1.1+ 推薦替代 Date 進行字段操作。
• java.text.SimpleDateFormat：線程不安全，日期⇄字符串轉換核心工具。
• ⚠️ 多線程環境：請使用 ThreadLocal 包裝或升級 JDK 8+ java.time 套件。

1. 日期取值與字段操作

Calendar cal = Calendar.getInstance(); // 默認時區/ Locale
// Calendar cal = Calendar.getInstance(TimeZone.getTimeZone("UTC"), Locale.US);

int year       = cal.get(Calendar.YEAR);
int month      = cal.get(Calendar.MONTH) + 1; // 0-based，需 +1
int day        = cal.get(Calendar.DATE);      // 或 DAY_OF_MONTH
int hour24     = cal.get(Calendar.HOUR_OF_DAY);
int minute     = cal.get(Calendar.MINUTE);
int second     = cal.get(Calendar.SECOND);
int dayOfWeek  = cal.get(Calendar.DAY_OF_WEEK); // 1=周日, 2=周一...

Date date = cal.getTime(); // 轉 Date

設置字段

cal.set(Calendar.YEAR, 2025);
cal.set(2025, 11, 25, 14, 30, 0); // 月份 0-based
cal.setTime(new Date()); // 從 Date 同步

2. 日期⇄字符串轉換

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
// yyyy 年, MM 月, dd 日, HH 24時, hh 12時, mm 分, ss 秒

// Date → String
String str = sdf.format(new Date());

// String → Date
try {
    Date parsed = sdf.parse("2025-12-25 14:30:00");
} catch (ParseException e) {
    // 處理解析失敗
}

💡 線程安全寫法：ThreadLocal<SimpleDateFormat> tl = ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));

3. 日期加減運算

基於某時間點偏移

Calendar cal = Calendar.getInstance();
cal.add(Calendar.YEAR, 1);   // 明年
cal.add(Calendar.MONTH, -3); // 3 個月前
cal.add(Calendar.DATE, 10);  // 10 天後
// 支援所有字段：HOUR, MINUTE, SECOND 等

計算兩日期間隔天數

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
Date d1 = sdf.parse("2025-01-01");
Date d2 = sdf.parse("2025-12-31");
long diffDays = (d2.getTime() - d1.getTime()) / (1000 * 60 * 60 * 24);
System.out.println("間隔 " + diffDays + " 天");

4. 日期比較三種標準姿勢

Date d1 = sdf.parse("2025-01-01 10:00:00");
Date d2 = sdf.parse("2025-12-31 10:00:00");

// 1. before / after (最常用)
boolean early = d1.before(d2); // true
boolean late  = d2.after(d1);  // true

// 2. compareTo (排序/精確比較)
int cmp = d1.compareTo(d2); // -1 (d1d2)

// 3. getTime() 比較毫秒值 (底層邏輯)
long ms1 = d1.getTime();
long ms2 = d2.getTime();

5. 常見坑點速查表

升級建議：JDK 8+ java.time

新專案強烈建議遷移至 java.time：

• LocalDate/LocalDateTime：不可變、線程安全、API 清晰。
• DateTimeFormatter：替代 SimpleDateFormat。
• Period/Duration：替代手動毫秒運算。
• ZoneId/ZonedDateTime：完善時區支持。

// JDK 8+ 範例
LocalDate today = LocalDate.now();
LocalDate nextWeek = today.plusWeeks(1);
long days = ChronoUnit.DAYS.between(today, nextWeek);
String formatted = today.format(DateTimeFormatter.ofPattern("yyyy年MM月dd日"));