Java Memcached 客戶端過期時間設定陷阱與正確用法

使用 spymemcached 或 xmemcached 等 Java 客戶端操作 Memcached 時，expiry 參數易被誤解為「絕對過期時間點」，實際為「相對秒數」或「Unix 時間戳」，導致資料無法正常存入或立即失效。

錯誤示範

// 錯誤：傳入「一小時後的 Date 物件」
Date expiry = new Date(System.currentTimeMillis() + 3600000);
client.add("key", "value", expiry);  // 實際行為異常

原始碼揭秘

客戶端內部實際發送命令時，會將 Date 轉換：

expiry.getTime() / 1000L  // 轉為 Unix 秒數

String cmd = "set key flags " + (expiry.getTime() / 1000L) + " " + val.length + "\r\n";

Memcached 協定規範

• exptime = 0：永不過期
• exptime < 30天 (2592000秒)：視為相對秒數（從現在起 N 秒後過期）
• exptime ≥ 30天：視為 Unix 時間戳（絕對過期時間點）

正確用法

方式一：相對秒數（推薦）

// 1 小時 = 3600 秒
client.add("key", "value", 3600);  // int/long 秒數

方式二：Date 物件（需注意閾值）

// 正確：建立「相對毫秒數」的 Date
// new Date(millis) 表示「1970 年起經過 millis 毫秒」
// 此處 3600000ms = 3600秒 < 30天 → 會被視為相對秒數 3600
Date relativeExpiry = new Date(3600000L);  
client.add("key", "value", relativeExpiry);

方式三：絕對時間點

// 明確指定 2025-12-31 23:59:59 過期
Calendar cal = Calendar.getInstance();
cal.set(2025, 11, 31, 23, 59, 59);
client.add("key", "value", cal.getTime());  // 秒數 > 30天閾值 → 視為絕對時間

最佳實踐建議

1. 優先使用 int seconds 多載方法，語義最清晰
2. 若用 Date，務必確認秒數是否超過 30 天閾值
3. 單元測試驗證實際過期行為
4. 監控 Memcached stats 確認 expired_unfetched 指標

常見誤區總結