Java Date 與 Calendar 常用操作速查手冊

雖然 Java 8+ 引入 java.time 新時間 API，但大量存量系統仍使用 java.util.Date 與 java.util.Calendar。本文匯總兩類核心操作：互轉、格式化、欄位存取、日期運算、星期判斷，並標註常見坑點與遷移建議。

核心類關係速覽

Date ↔ String 格式化互轉

Date now = new Date();
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");

// Date → String
String str = sdf.format(now);  // "2024-03-15 14:30:45"

// String → Date
Date parsed = sdf.parse("2024-03-15 14:30:45");

常用格式符號：

Date ↔ Calendar 互轉

// Date → Calendar
Calendar cal = Calendar.getInstance();
cal.setTime(date);

// Calendar → Date
Date date = cal.getTime();

Calendar 欄位存取與操作

Calendar cal = Calendar.getInstance(); // 當前時間
// cal.set(2024, Calendar.MARCH, 15); // 月份 0-based: JAN=0

// 獲取欄位
int year       = cal.get(Calendar.YEAR);
int month      = cal.get(Calendar.MONTH) + 1; // +1 顯示給人看
int dayOfMonth = cal.get(Calendar.DAY_OF_MONTH);
int hour       = cal.get(Calendar.HOUR_OF_DAY); // 24制
int minute     = cal.get(Calendar.MINUTE);
int second     = cal.get(Calendar.SECOND);
int dayOfWeek  = cal.get(Calendar.DAY_OF_WEEK); // SUN=1 ... SAT=7
int weekOfYear = cal.get(Calendar.WEEK_OF_YEAR);
int weekOfMonth= cal.get(Calendar.WEEK_OF_MONTH);

// 日期加減（自動處理進位/借位、閏年）
cal.add(Calendar.YEAR, 1);      // +1 年
cal.add(Calendar.MONTH, -3);    // -3 月
cal.add(Calendar.DAY_OF_MONTH, 7); // +7 天
cal.add(Calendar.HOUR, -2);     // -2 小時

// 設定欄位（不自動重算其他欄位，慎用）
cal.set(Calendar.HOUR_OF_DAY, 0);
cal.set(Calendar.MINUTE, 0);
cal.set(Calendar.SECOND, 0);
cal.set(Calendar.MILLISECOND, 0); // 當天 00:00:00.000

常見實用片段

判斷某日期是星期幾

Calendar cal = Calendar.getInstance();
cal.set(2024, Calendar.MARCH, 15); // 2024-03-15
String[] weeks = {"", "星期日", "星期一", "星期二", "星期三", "星期四", "星期五", "星期六"};
System.out.println(weeks[cal.get(Calendar.DAY_OF_WEEK)]); // 星期五

取得本月第一天/最後一天 00:00:00

Calendar cal = Calendar.getInstance();
// 本月第一天
cal.set(Calendar.DAY_OF_MONTH, 1);
cal.set(Calendar.HOUR_OF_DAY, 0);
cal.set(Calendar.MINUTE, 0);
cal.set(Calendar.SECOND, 0);
cal.set(Calendar.MILLISECOND, 0);
Date monthStart = cal.getTime();

// 本月最後一天
cal.add(Calendar.MONTH, 1);
cal.add(Calendar.DAY_OF_MONTH, -1);
Date monthEnd = cal.getTime();

計算兩日期天數差

long diffMs = date2.getTime() - date1.getTime();
long diffDays = diffMs / (1000 * 60 * 60 * 24);
// 注意：夏令時切換日可能非 24h，精確場景請用 java.time

關鍵坑點與避坑指南

1. 月份 0-based：Calendar.JANUARY = 0，Calendar.DECEMBER = 11。設定/讀取月份必須 +1 或 -1。
2. SimpleDateFormat 非執行緒安全：多執行緒環境請用 ThreadLocal 或每次新建實例，或改用 DateTimeFormatter (java.time)。
3. Calendar.getInstance() 返回具體實現類：如 GregorianCalendar，不可直接轉型為其他曆法。
4. set() 不重算欄位：cal.set(MONTH, 11); cal.set(DAY_OF_MONTH, 31) 在 30 天月份會自動滾到下個月 1 日，建議用 add() 或 roll()。
5. Date 無時區概念：內部儲存 UTC 毫秒數，toString() 使用預設時區顯示，跨時區傳輸請用 ISO-8601 字串或時間戳。

遷移至 java.time (Java 8+) 快速對照

總結

維護舊系統時熟練掌握 Calendar.add()、月份 0-based、SimpleDateFormat 執行緒安全問題；新專案**直接使用 java.time**，享受不可變、執行緒安全、功能豐富的現代 API。