[ADP-124] Cache-Control
概述
Cache-Control HTTP 標頭欄位用於在請求和回應中指定快取機制的指令。正確使用快取可以顯著提高 API 的性能和可擴展性，減少伺服器負載並最小化網絡流量。
指導原則
- 必須(MUST)適當使用 Cache-Control 標頭以優化 API 性能並減少伺服器負載。
- 應該(SHOULD)根據資源變更頻率設置合理的
max-age值。 - 對於包含敏感或個人資訊的回應，必須(MUST)使用
no-store。 - 對於頻繁更新的資源，應該(SHOULD)利用
no-cache以確保新鮮度，同時仍允許快取。 - 應該(SHOULD)結合使用 Vary 標頭和 Cache-Control，以指定哪些標頭影響快取行為。
- 必須(MUST)考慮快取對 API 版本控制和更新的影響。
- 在設置快取持續時間時，平衡新鮮度和伺服器負載。
- 注意快取對 API 版本控制和更新的影響。
- 設置快取策略時，考慮不同客戶端(例如，移動端與網頁端)的需求。
- 隨著 API 的發展，定期審查和更新快取策略。
關鍵指令
對於回應
max-age=<seconds>: 指定資源被認為是新鮮的最長時間。s-maxage=<seconds>: 類似於 max-age，但僅適用於共享快取。public: 表示回應可以被任何快取存儲。private: 表示回應僅供單個用戶使用，不得由共享快取存儲。no-cache: 在使用快取副本之前需要與原始伺服器驗證。no-store: 表示回應不得存儲在任何快取中。must-revalidate: 快取在使用過期資源之前必須驗證其狀態。
對於請求
no-cache: 要求伺服器在使用快取副本之前驗證資源。no-store: 請求不將回應存儲在任何快取中。max-age=<seconds>: 表示客戶端願意接受年齡不超過指定秒數的回應。
最佳實踐
適當使用
max-age: 根據資源變更頻率設置合理的max-age值。對動態內容使用
no-cache: 對於頻繁更新的資源，使用no-cache以確保新鮮度，同時仍允許快取。對敏感數據應用
no-store: 對包含敏感或個人資訊的回應使用no-store。利用
public和private: 對可以被共享快取存儲的回應使用public，對用戶特定的回應使用private。考慮對 CDN 使用
s-maxage: 使用 CDN 時，利用s-maxage為 CDN 和瀏覽器設置不同的快取持續時間。實施條件請求: 結合使用 ETag 或 Last-Modified 標頭與 Cache-Control 進行高效驗證。
示例
http
Cache-Control: max-age=3600, must-revalidate， public此示例將最大年齡設置為一小時，要求重新驗證過期資源，並允許公共快取。
OpenAPI 示例
OpenAPI Example
yaml
openapi: 3.1.0
info:
title: Example API
version: 1.0.0
paths:
/users/{id}:
get:
summary: Get user information
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Successful response
headers:
Cache-Control:
description: Cache-Control header
schema:
type: string
example: max-age=3600, must-revalidate, public
content:
application/json:
schema:
type: object
properties:
id:
type: integer
name:
type: string此 OpenAPI 示例演示了如何使用 OpenAPI 3.1.0 在 API 規範中記錄 Cache-Control 標頭。