時間獲取三大體系演進
| 體系 | 代表類別 | 特點 | 適用場景 |
| **舊版 (Java 1.0+)** | `java.util.Date`, `java.sql.Date/Time/Timestamp`, `SimpleDateFormat` | 可變、非線程安全、設計缺陷多、時區處理痛苦 | 維護舊代碼、JDBC 交互 |
| **Calendar (Java 1.1+)** | `java.util.Calendar`, `GregorianCalendar` | 可變、線程不安全、API 繁瑣、月份 0 基索引 | 舊代碼、需欄位運算 (加月/日) |
| **現代 (Java 8+ java.time)** | `Instant`, `LocalDateTime`, `ZonedDateTime`, `DateTimeFormatter`, `Duration`, `Period` | **不可變、線程安全、領域驅動設計、ISO-8601 標準、納秒精度** | **所有新專案首選** |
現代 java.time 核心用法 (推薦)
1. 獲取當前時間 (各精度)
// 瞬時時間點 (UTC, 納秒) - 適合日誌、時間戳、資料庫 TIMESTAMP
Instant nowInstant = Instant.now();
long epochMilli = nowInstant.toEpochMilli(); // 毫秒時間戳
long epochNano = nowInstant.getEpochSecond() * 1_000_000_000 + nowInstant.getNano();
// 本地日期時間 (無時區) - 適合業務邏輯、表單綁定
LocalDateTime nowLocal = LocalDateTime.now();
LocalDate today = LocalDate.now();
LocalTime nowTime = LocalTime.now();
// 帶時區時間 - 適合用戶顯示、跨時區業務
ZonedDateTime nowZoned = ZonedDateTime.now(ZoneId.of("Asia/Shanghai"));
ZonedDateTime nowSystem = ZonedDateTime.now(); // 系統預設時區
2. 格式化輸出 (DateTimeFormatter)
// 預定義格式
DateTimeFormatter ISO = DateTimeFormatter.ISO_LOCAL_DATE_TIME; // 2024-01-15T14:30:45.123
DateTimeFormatter FULL_CN = DateTimeFormatter.ofPattern("yyyy年MM月dd日 EEEE a hh:mm:ss", Locale.CHINESE);
// 2024年01月15日 星期一 下午 02:30:45
// 自訂格式 (線程安全,可靜態常量複用)
private static final DateTimeFormatter DT_FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private static final DateTimeFormatter DT_FMT_MS = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS");
String formatted = nowLocal.format(DT_FMT);
String formattedMs = nowLocal.format(DT_FMT_MS);
3. 解析字串為時間物件
LocalDateTime parsed = LocalDateTime.parse("2024-01-15 14:30:45", DT_FMT);
ZonedDateTime parsedZoned = ZonedDateTime.parse("2024-01-15T14:30:45+08:00[Asia/Shanghai]");
Instant parsedInstant = Instant.parse("2024-01-15T06:30:45Z"); // ISO-8601 UTC
4. 時間運算 (不可變,返回新物件)
LocalDateTime tomorrow = nowLocal.plusDays(1);
LocalDateTime lastMonth = nowLocal.minusMonths(1);
LocalDateTime specific = nowLocal.withHour(0).withMinute(0).withSecond(0).withNano(0); // 當天 00:00:00
// 期間/持續時間
Period period = Period.between(LocalDate.now(), LocalDate.of(2025,1,1)); // 年月日差
Duration duration = Duration.between(Instant.now(), Instant.now().plusHours(2)); // 時分秒納秒差
5. 舊 API 互操作
// Date → Instant → LocalDateTime
Date legacyDate = new Date();
Instant instant = legacyDate.toInstant();
LocalDateTime ldt = instant.atZone(ZoneId.systemDefault()).toLocalDateTime();
// LocalDateTime → Instant → Date
LocalDateTime ldt2 = LocalDateTime.now();
Date date = Date.from(ldt2.atZone(ZoneId.systemDefault()).toInstant());
// sql.Timestamp 互轉
Timestamp ts = Timestamp.valueOf(ldt2);
LocalDateTime ldt3 = ts.toLocalDateTime();
舊版 API 速查 (維舊專案用)
// 1. Date + SimpleDateFormat (非線程安全,需 ThreadLocal 或每次 new)
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
String nowStr = sdf.format(new Date());
Date parsed = sdf.parse("2024-01-15 14:30:45");
// 2. Calendar (月份 0-11 陷阱)
Calendar cal = Calendar.getInstance();
int year = cal.get(Calendar.YEAR);
int month = cal.get(Calendar.MONTH) + 1; // +1!
int day = cal.get(Calendar.DAY_OF_MONTH);
int hour = cal.get(Calendar.HOUR_OF_DAY); // 24制
int min = cal.get(Calendar.MINUTE);
int sec = cal.get(Calendar.SECOND);
cal.add(Calendar.DAY_OF_MONTH, 7); // 加 7 天
// 3. System.currentTimeMillis() / System.nanoTime()
long ms = System.currentTimeMillis(); // 1970 至今毫秒,適合計算耗時、生成 ID
long ns = System.nanoTime(); // 相對時間納秒,適合高精度效能測量
資料庫時間類型映射建議
| 資料庫類型 | Java 類型 (java.time) | JDBC 交互 |
| DATE | LocalDate | `rs.getObject(i, LocalDate.class)` / `ps.setObject(i, localDate)` |
| TIME | LocalTime | `rs.getObject(i, LocalTime.class)` |
| DATETIME / TIMESTAMP (無時區) | LocalDateTime | `rs.getObject(i, LocalDateTime.class)` |
| TIMESTAMP WITH TIME ZONE | OffsetDateTime / ZonedDateTime | `rs.getObject(i, OffsetDateTime.class)` |
**要求**:JDBC 驅動 4.2+ (JDBC 4.2 規範支援 `getObject/setObject` 直接轉換)。
工具類封裝範例 (生產就緒)
public final class DateTimeUtils {
private DateTimeUtils() {}
public static final ZoneId SHANGHAI = ZoneId.of("Asia/Shanghai");
public static final DateTimeFormatter DT_FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
public static final DateTimeFormatter DT_FMT_MS = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS");
public static final DateTimeFormatter DATE_FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd");
public static LocalDateTime nowLocal() { return LocalDateTime.now(SHANGHAI); }
public static ZonedDateTime nowZoned() { return ZonedDateTime.now(SHANGHAI); }
public static Instant nowInstant() { return Instant.now(); }
public static long nowMilli() { return System.currentTimeMillis(); }
public static String format(LocalDateTime ldt) { return ldt.format(DT_FMT); }
public static String formatMs(LocalDateTime ldt) { return ldt.format(DT_FMT_MS); }
public static String formatDate(LocalDate ld) { return ld.format(DATE_FMT); }
public static String formatInstant(Instant ins) { return ins.atZone(SHANGHAI).format(DT_FMT_MS); }
public static LocalDateTime parse(String str) { return LocalDateTime.parse(str, DT_FMT); }
public static LocalDate parseDate(String str) { return LocalDate.parse(str, DATE_FMT); }
public static String toHttpHeader(Instant ins) { // RFC 1123 / HTTP-date
return DateTimeFormatter.RFC_1123_DATE_TIME.format(ins.atZone(ZoneOffset.UTC));
}
}
避坑指南
- ❌ `SimpleDateFormat` 定為 `static` 共用 → 線程不安全,數據錯亂。
✅ 用 `ThreadLocal`、每次 `new`、或改用 `DateTimeFormatter` (線程安全)。
- ❌ `Calendar.MONTH` 0 基索引 (0=1月) 忘記 `+1`。
✅ 改用 `LocalDate.getMonthValue()` (1-12)。
- ❌ 直接 `new Date()` 當業務時間 → 依賴伺服器系統時區,部署環境變更導致 Bug。
✅ 明確指定 `ZoneId`,業務層統一用 `LocalDateTime`/`ZonedDateTime`。
- ❌ 用 `System.currentTimeMillis()` 測量代碼執行時間 → 受系統時鐘調整影響 (NTP 校時會跳變)。
✅ 用 `System.nanoTime()` 計算相對耗時。