Java 時間處理：Calendar 類深度解析與常見坑點避坑指南

為什麼用 Calendar？

Date 多數方法已棄用，Calendar 為抽象類，提供完整的日期時間運算、欄位存取、國際化支援。主流實作為 GregorianCalendar（公曆）。

實例化方式

// 方式 1：工廠方法（推薦）
Calendar cal = Calendar.getInstance(); // 預設時區/地區
Calendar cal = Calendar.getInstance(TimeZone.getTimeZone("GMT+8"), Locale.TRADITIONAL_CHINESE);

// 方式 2：子類實例化
Calendar cal = new GregorianCalendar();

核心欄位常數

⚠️ 常見坑：直接印常數值

System.out.println(Calendar.DAY_OF_MONTH); // 輸出 5 (常數編碼)，非今天日期！
System.out.println(cal.get(Calendar.DAY_OF_MONTH)); // 正確：取實際值

常數是 static final int 編碼，必須透過實例 get() 取值。

核心操作方法

get(field)

int year = cal.get(Calendar.YEAR);
long millis = cal.getTimeInMillis(); // 取毫秒數，常用於比較/存儲

add(field, amount) — 智慧運算

cal.add(Calendar.DATE, -1);  // 昨天 (自動處理跨月/跨年)
cal.add(Calendar.MONTH, 3);  // 3個月後
cal.add(Calendar.YEAR, -1);  // 去年

set 系列

cal.set(Calendar.YEAR, 2025);
cal.set(2025, Calendar.JANUARY, 1); // 月份仍用常數或 0-based
cal.set(2025, 0, 1, 12, 0, 0);      // 年、月(0-based)、日、時、分、秒
cal.setTime(new Date());            // 從 Date 同步

比較方法

cal1.after(cal2);      // cal1 在 cal2 之後？
cal1.before(cal2);     // cal1 在 cal2 之前？
cal1.compareTo(cal2);  // >0 後、<0 前、=0 同

clear() 與 isSet()

cal.clear();                    // 全部重置為 1970/01/01 00:00:00
cal.clear(Calendar.YEAR);       // 單欄重置為預設值 (年→1970)
cal.isSet(Calendar.DATE);       // 欄位是否已被設定過

格式化輸出

SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
System.out.println(sdf.format(cal.getTime()));

總結

• Calendar 為抽象類，用 getInstance() 取得實例
• **月份 0-based、週日為 1** 是兩大易錯點
• 常數值 ≠ 實際值，務必用 get()
• add() 比手動運算安全（自動進位）
• 新專案建議優先使用 Java 8 java.time 套件（LocalDateTime 等）