ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-128] ETag ​

ETag (實體標籤) 是一種用於網頁快取驗證的 HTTP 回應標頭。它是由網頁伺服器為資源的特定版本分配的唯一識別碼。ETag 通過允許瀏覽器發出條件請求來提高效率，減少不必要的數據傳輸。

關鍵點 ​

  1. 目的: ETag 使快取系統能夠確定資源的內容是否已更改。

  2. 格式: ETag 通常是一個用雙引號括起來的字串,例如 ETag: "686897696a7c876b7e"。

  3. 類型:

    • 強 ETag: 如果回應主體有任何差異就會改變。
    • 弱 ETag: 只有在發生重大語義變化時才會改變。

  4. 使用方式:

    • 伺服器隨回應發送 ETag。
    • 客戶端在後續請求中使用 If-None-Match 標頭包含 ETag。
    • 伺服器比較 ETag 以確定資源是否已更改。

  5. 優點:

    • 減少頻寬使用。
    • 提高伺服器性能。
    • 確保數據一致性。

  6. 注意事項:

    • 生成方法可能影響性能。
    • 應與其他快取機制結合使用。

指導原則 ​

  • 應該(SHOULD)為所有可快取的資源使用 ETag。
  • 必須(MUST)為資源的每個版本生成唯一的 ETag。
  • 應該(SHOULD)使用強 ETag，除非性能考慮需要使用弱 ETag。
  • 必須(MUST)在 GET 和 HEAD 請求的回應標頭中包含 ETag。
  • 應該(SHOULD)支持使用 If-Match 和 If-None-Match 標頭的條件請求。
  • 如果條件 GET 請求中的 ETag 匹配，必須(MUST)返回 304 Not Modified 回應。
  • 應該(SHOULD)在分散式系統中使用一致的 ETag 生成方法。

範例 ​

http
HTTP/1.1 200 OK
Content-Type: text/html
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"

[Resource content]

使用共享標頭定義 ​

yaml
headers:
   ETag:
      - "$ref": "https://vivotek-it.github.io/api-design-principles/definitions.yaml#/parameters/Etag"

相關 ADP ​

參考資料 ​