核心結論先行
| 函數 | 語法 | 計算邏輯 | 返回值符號 |
|---|
DATEDIFF | DATEDIFF(date1, date2) | date1 - date2 | date1 早 → 負數 |
TIMESTAMPDIFF | TIMESTAMPDIFF(unit, datetime1, datetime2) | datetime2 - datetime1 | datetime1 早 → 正數 |
實測驗證
DATEDIFF
SELECT DATEDIFF('2012-12-12', '2012-12-15');
-- 結果：-3 （12日 - 15日 = -3天）
-- 兼容帶時間的字符串
SELECT DATEDIFF(DATE_FORMAT('2012-12-12 11:10:02', '%Y-%m-%d'), '2012-12-15');
-- 結果：-3
TIMESTAMPDIFF
SELECT TIMESTAMPDIFF(MINUTE,
DATE_FORMAT('1-1-1 11:12', '%Y-%m-%d %H:%i:%s'),
DATE_FORMAT('1-1-1 11:15', '%Y-%m-%d %H:%i:%s'));
-- 結果：3 （11:15 - 11:12 = 3分鐘）
-- 註：第一參數為單位（MINUTE/HOUR/DAY...），後兩參數順序與 DATEDIFF 相反！
易錯場景與避坑指南
| 場景 | 錯誤寫法 | 正確寫法 | 說明 |
|---|
| 計算「幾天前」 | DATEDIFF(NOW(), create_time) | DATEDIFF(create_time, NOW()) 或 TIMESTAMPDIFF(DAY, create_time, NOW()) | DATEDIFF 早減晚為負，需反序或改用 TIMESTAMPDIFF |
| 計算精確分鐘/秒差 | DATEDIFF(...)*1440 | TIMESTAMPDIFF(MINUTE, start, end) | TIMESTAMPDIFF 支援 MICROSECOND/SECOND/MINUTE/HOUR/DAY/WEEK/MONTH/QUARTER/YEAR |
| 跨時區比較 | 直接用 datetime 列 | 統一轉 UTC：CONVERT_TZ(dt, 'SYSTEM', '+00:00') | 避免夏令時/時區導致差值偏移 |
最佳實踐建議
- 統一使用
TIMESTAMPDIFF：參數順序符合直覺（起點、終點）、支援多種時間單位、處理 datetime 精度更準；
- 僅需「天數差」且不關心符號時，可用
ABS(DATEDIFF(...))；
- 文檔註釋標註參數順序，代碼審查重點檢查雙參數時間差函數。
