ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-361] HTTP 快取 ​

概述 ​

本文件概述了在 RESTful API 中實施 HTTP 快取的指南和最佳實踐，以提高性能、減少延遲並降低伺服器負載。

背景知識 ​

HTTP 快取標頭 ​

HTTP 快取通過 HTTP 請求和回應中的特定標頭來控制。用於快取的主要標頭包括:

  • Cache-Control
  • ETag
  • Last-Modified
  • Expires

實施細節 ​

伺服器端實施 ​

  1. 生成 ETag: 確保每個資源都有唯一的 ETag 並將其包含在回應標頭中。
  2. 設置 Cache-Control 指令: 為每個端點確定適當的快取策略，並包含 Cache-Control 標頭。
  3. 包含 Last-Modified: 將 Last-Modified 標頭設置為資源的最後修改日期。
  4. 處理條件請求: 實現邏輯以處理 If-None-Match 和 If-Modified-Since 標頭，如果資源未更改，則返回 304 Not Modified 狀態。

客戶端實施 ​

  1. 存儲快取標頭: 將 ETag、Last-Modified 和其他相關標頭與快取的回應一起存儲。
  2. 包含條件標頭: 發出請求時，包含 If-None-Match 和 If-Modified-Since 標頭以驗證快取。
  3. 處理 304 回應: 如果收到 304 Not Modified 狀態，則更新快取，保持相同的回應數據。

示例端點 ​

http
GET /resource/123 HTTP/1.1
Host: example.com
If-None-Match: "abc123"
If-Modified-Since: Tue, 20 Jul 2021 19:30:00 GMT

HTTP/1.1 200 OK
Cache-Control: public, max-age=3600, must-revalidate
ETag: "abc123"
Last-Modified: Tue, 20 Jul 2021 19:30:00 GMT
Expires: Wed, 21 Jul 2021 19:30:00 GMT
Content-Type: application/json

{
  "id": 123,
  "name": "資源名稱",
  "updatedAt": "2021-07-20T19:30:00Z"
}

指導 ​

  • 必須(MUST)為所有返回靜態或半靜態數據的 GET 請求實施快取機制。
  • 應該(SHOULD)為所有可能隨時間變化的資源使用 ETag。
  • 應該(SHOULD)根據資源的易變性和訪問模式設置適當的 Cache-Control 標頭。
  • 可以(MAY)為不同類型的資源或端點使用不同的快取策略。
  • 應該(SHOULD)在 API 文件中記錄快取行為。

關聯 ADPs ​

參考資料 ​

Changelog ​

  • 2024.09.24 Remove unwanted /api path in the samples
  • 2024.10.01 Add reference topic