apcu_entry 與apcu_add 的差異及應用場景

gitbox 2025-05-26

在使用PHP 的APCu 緩存擴展時，開發者經常會接觸到apcu_entry()和apcu_add()這兩個函數。它們都用於向緩存中寫入數據，但行為方式和適用場景卻有明顯差異。本文將從實現原理、使用場景及性能角度分析二者的區別，並結合實際示例加以說明。

apcu_add(string $key, mixed $var, int $ttl = 0): bool

該函數將一個值添加到緩存中，如果指定的$key已經存在，則添加失敗，返回false 。這意味著apcu_add()是一種“只添加一次”的操作，常用於初始化或需要避免覆蓋的場景。

apcu_entry(string $key, callable $generator, int $ttl = 0): mixed

該函數會嘗試從緩存中獲取$key對應的值；如果該鍵不存在，則調用$generator回調函數生成數據，並寫入緩存。其典型用途是“懶加載”場景，避免重複執行昂貴操作。

判斷鍵是否存在：
- apcu_add()是原子性的，它直接嘗試添加，如果鍵已存在則返回失敗，避免了讀寫競態。
- apcu_entry()內部先嘗試讀取，如果未命中，再調用回調生成數據，並嘗試寫入。這在並發下可能出現重複計算（儘管實際發生概率較低）。
寫入行為：
- apcu_add()永遠不會覆蓋已有值，適合只想“設一次”的情境。
- apcu_entry()會在緩存不存在時自動計算並寫入，適合懶加載。
簡潔性：
- apcu_entry()提供了更清晰的封裝結構，一行代碼實現緩存讀取+失效時生成邏輯，語義更清楚。
- apcu_add()需要開發者手動寫讀取和判斷邏輯。

$config = [
    'site_name' => 'GitBox',
    'max_upload' => 100
];

$key = 'site_config';
if (!apcu_add($key, $config, 3600)) {
    // 已存在，不做任何處理
}

適合用於部署或初始化階段寫入的配置數據，確保不會被重複設置或覆蓋。

$data = apcu_entry('user_list', function() {
    // 假設這個函數查詢數據庫
    return file_get_contents('https://gitbox.net/api/users');
}, 600);

這裡user_list會在不存在時通過訪問API 獲取數據並緩存，非常適合頻繁讀取但偶爾變化的數據。

在高並發環境中， apcu_entry()雖然方便，但其內部邏輯並非強一致，多個進程可能同時判斷鍵不存在並生成數據。因此，如果回調代價很高或結果必須唯一，建議增加鎖機製或使用apcu_add()輔助判斷。

 $key = 'report_2025';
if (!apcu_add($key, true, 300)) {
    // 任務已在別的進程中執行
    return;
}
generateExpensiveReport();  // 執行一次即可