利用 HTTP ETag 避免重複拉取資源
在 Web 應用程式中,前端經常需要向伺服器拉取較大的資料集,例如全站搜尋索引(Search Index JSON)、字典檔或系統配置。這些資料雖然體積偏大,但變更頻率通常不高。
如果每次使用者觸發功能時都無條件下載完整的 JSON,即使後端已使用快取(如 Redis)加速,仍會消耗寶貴的網路傳輸頻寬與延遲。透過 HTTP 條件式請求(Conditional Request) 與 ETag(實體標記,Entity Tag),當資源內容未變更時,伺服器只需回應 304 Not Modified(不含 Body),就能大幅節省傳輸量並提升回應速度。
什麼是 ETag 與條件式請求?
ETag(Entity Tag) 是 HTTP 回應標頭(Response Header)中的一個字串識別碼,代表特定版本資源的內容摘要或指紋(Fingerprint)。
運作流程
[ 用戶端 (Client) ] [ 伺服器 (Server) ]
| |
| 1. 初次請求: GET /api/search-index |
|----------------------------------------------->|
| | 計算資源 Hash (如 md5)
| 2. 回傳 200 OK + ETag: "abc123" + 完整內容 |
|<-----------------------------------------------|
| (快取內容與 ETag: "abc123") |
| |
| 3. 再次請求: GET /api/search-index |
| Header: If-None-Match: "abc123" |
|----------------------------------------------->|
| | 比對指紋是否一致:
| | 一致 -> 內容未變更
| 4. 回傳 304 Not Modified (空 Body) |
|<-----------------------------------------------|
| (直接使用本地快取資料) |
- 初次請求:用戶端請求資源,伺服器計算該內容的指紋(如雜湊值),透過
ETag標頭回傳,並設定快取驗證原則。 - 後續請求:用戶端再次請求時,瀏覽器或客戶端會自動在標頭帶上
If-None-Match: "<前次 ETag>"。 - 比對驗證:伺服器若發現資源指紋與
If-None-Match一致,直接回傳304 Not Modified且不包含任何回應主體(Body)。
強 ETag vs. 弱 ETag
ETag 分為兩種形式:
- 強 ETag(Strong ETag):例如
"abc123"。表示資源的每一個 Byte 都完全一致(Byte-for-byte identical)。 - 弱 ETag(Weak ETag):以
W/開頭,例如W/"abc123"。表示資源在語意上等價(Semantically equivalent),但位元組層級可能略有差異。
為什麼後端必須同時支援弱 ETag?
許多反向代理伺服器(如 Nginx、Caddy、Cloudflare)在開啟 Gzip 或 Brotli 動態壓縮時,會將後端回傳的強 ETag 自動轉換為弱 ETag(因為壓縮後的 Byte 流不等於原始內容)。
當瀏覽器後續發出請求時,請求標頭很可能帶的是 If-None-Match: W/"abc123"。如果後端程式碼僅嚴格比對 "abc123",就會造成判斷失敗,導致每次請求都被當成內容已變更而回傳 200 OK 下載完整內容。
因此,後端在比對 If-None-Match 時,務必同時相容強 ETag 與弱 ETag。
在 Laravel 中實作 ETag 快取
以下以提供「搜尋索引」的 Controller 為例,實作輕量指紋比對與 304 狀態碼回傳:
<?php
declare(strict_types=1);
namespace App\Http\Controllers;
use App\Services\NoteRepository;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
class SearchIndexController extends Controller
{
public function __construct(
private readonly NoteRepository $noteRepository,
) {}
/**
* 回傳搜尋索引 JSON,並透過 HTTP ETag 實作條件式快取
*/
public function __invoke(Request $request): Response
{
// 1. 取得輕量資源指紋並計算 ETag
$etag = md5($this->noteRepository->fingerprint());
// 2. 判斷客戶端 If-None-Match 是否相符(同時支援強 ETag 與弱 ETag)
if (
in_array('"'.$etag.'"', $request->getETags(), true) ||
in_array('W/"'.$etag.'"', $request->getETags(), true)
) {
return response('', Response::HTTP_NOT_MODIFIED, [
'ETag' => '"'.$etag.'"',
'Cache-Control' => 'public, max-age=0, must-revalidate',
]);
}
// 3. 資源已有更新或初次載入,生成完整資料並附上 ETag 標頭
$response = response()->json($this->noteRepository->searchIndex());
$response->setEtag($etag);
$response->headers->set('Cache-Control', 'public, max-age=0, must-revalidate');
return $response;
}
}
關鍵細節解析
$request->getETags(): Symfony 的 Request 物件內建getETags()方法,能自動解析If-None-Match標頭中以逗號分隔的多個 ETag,並保留W/前綴與雙引號。Cache-Control: public, max-age=0, must-revalidate:max-age=0:告知瀏覽器快取過期時間為 0,表示每次使用快取前必須向伺服器重新驗證(Revalidate)。must-revalidate:伺服器斷線或異常時,不允許回傳過期的陳舊快取(Stale Cache)。- 此設定能確保客戶端「永遠能取得最新狀態」,且「沒有更新時只消耗最微小的 304 驗證封包」。
前端配合機制
1. 瀏覽器原生 fetch() 快取
在一般瀏覽器環境下,使用標準的 fetch() 發送 GET 請求,瀏覽器本身的 HTTP 快取層就會自動管理 ETag 與 If-None-Match:
// 瀏覽器會自動在 Request Header 帶入 If-None-Match
// 若伺服器回傳 304,瀏覽器會透明地從內部 HTTP 快取取出內容並回傳
const res = await fetch('/api/search-index');
const data = await res.json();
2. 單頁應用(SPA)/ 記憶體與 SessionStorage 快取
若前端希望在記憶體或 sessionStorage 自行管理快取狀態,可手動記錄 ETag 標頭並傳入 If-None-Match:
let cachedData: SearchIndex[] | null = null;
let cachedETag: string | null = sessionStorage.getItem('search_etag');
async function getSearchIndex(): Promise<SearchIndex[]> {
const headers: HeadersInit = {};
if (cachedETag) {
headers['If-None-Match'] = cachedETag;
}
const response = await fetch('/api/search-index', { headers });
// 伺服器回傳 304,表示本地快取仍為最新,直接使用
if (response.status === 304 && cachedData) {
return cachedData;
}
// 內容已變更,更新 ETag 與快取
if (response.ok) {
cachedETag = response.headers.get('ETag');
if (cachedETag) {
sessionStorage.setItem('search_etag', cachedETag);
}
cachedData = await response.json();
return cachedData;
}
throw new Error('無法取得搜尋索引');
}
補充:If-Match 與防止更新衝突(Lost Update Problem)
除了搭配 If-None-Match 進行讀取快取外,ETag 還有另一個極為重要的用途:搭配 If-Match 實作樂觀併發控制(Optimistic Concurrency Control),防止遺失更新問題(Lost Update Problem)。
什麼是 Lost Update Problem?
想像以下多使用者編輯的情境:
- Alice 與 Bob 同時打開同一篇文章進行編輯,此時該文章版本為
ETag: "v1"。 - Alice 編輯速度較快,花了一分鐘後送出更新,伺服器儲存成功並將文章版本推進為
ETag: "v2"。 - Bob 編輯了五分鐘後按下送出。在沒有併發控制的情況下,Bob 的提交會無聲無息地覆蓋 Alice 剛剛寫入的內容,導致 Alice 的修改遺失。
利用 If-Match 解決衝突
客戶端在送出修改請求(如 PUT, PATCH, DELETE)時,將上次讀取到的版本透過 If-Match 帶給伺服器:
PUT /api/articles/42 HTTP/1.1
If-Match: "v1"
Content-Type: application/json
{ "title": "Bob 修改的標題", "content": "..." }
- 伺服器驗證:
- 若目前伺服器上的版本仍為
"v1",表示期間沒有其他人修改,允許更新並回傳200 OK及新的ETag: "v2"。 - 若目前伺服器上的版本已被 Alice 改為
"v2",與 Bob 的If-Match: "v1"不符,伺服器立即拒絕請求,並回傳412 Precondition Failed。
- 若目前伺服器上的版本仍為
- 前端處理:前端收到
412錯誤時,可提示使用者「該資源已被他人修改」,並提供內容差異比對或讓使用者重新整理,避免直接覆蓋他人修改。
在 Laravel 中實作範例
public function update(Request $request, Article $article): Response
{
$currentEtag = '"' . md5((string) $article->updated_at->timestamp) . '"';
// 檢查客戶端是否附帶 If-Match 條件
if ($request->hasHeader('If-Match')) {
$ifMatch = $request->header('If-Match');
// If-Match: * 表示「只要資源存在即可」
// 若指定特定 ETag 且與當前版本不符,中斷並回傳 412
if ($ifMatch !== '*' && $ifMatch !== $currentEtag) {
return response()->json([
'message' => '資源已被修改,請重新整理取得最新版本後再試。',
], Response::HTTP_PRECONDITION_FAILED); // 412
}
}
$article->update($request->validated());
$newEtag = '"' . md5((string) $article->fresh()->updated_at->timestamp) . '"';
return response()->json($article, Response::HTTP_OK, [
'ETag' => $newEtag,
]);
}
[!NOTE] 根據 RFC 9110 規範:
- 用於狀態變更(如
PUT/PATCH)的If-Match比對時,原則上必須使用強 ETag,因為修改行為必須確保基於完全確定的位元組版本。If-Match: *具有特殊意義,代表「只要該資源目前存在即可執行」,常用於避免意外建立多個重複實體。
實務注意事項
- ETag 計算成本必須遠小於生成完整內容:
ETag 的好處建立在「能快速得知內容有無變更」。如果為了算 ETag 必須先執行耗時的全表查詢與資料序列化,就失去了節省後端 CPU 與查詢開銷的意義。建議透過輕量指紋(例如關聯檔案的最新
filemtime、資料庫MAX(updated_at)、或版本號)來計算 ETag。 - 反向代理壓縮設定:
若使用 Nginx,確認反向代理設定未強制抹除
ETag標頭。 - 避免 304 回應夾帶 Body:
根據 RFC 規範,HTTP 304 回應不得包含 Message Body。在 Laravel 中應以
response('', 304, ...)回傳空字串。