自訂 HTTP 標頭的設計哲學
在現代 Web 架構中，HTTP 標頭（Headers）扮演了傳遞中繼資料的關鍵角色。除了標準的 Content-Type 或 Authorization 之外，自訂標頭（Custom Headers）提供了擴展 API 功能的靈活性。開發者可以利用這些標頭來傳遞特定的業務邏輯參數，例如追蹤請求的來源或標記特定的裝置類型。
設計自訂標頭時，建議遵循 X- 前綴的舊式習慣已經逐漸被淘汰。現代標準建議直接使用具有語義意義的名稱，例如 'X-Request-ID' 或 'App-Version'。這些標頭不僅能幫助後端工程師進行除錯，還能讓前端介面根據伺服器回應採取不同的動作。
常見的自訂標頭應用場景
自訂標頭在分散式系統中尤其重要。例如，透過 'X-Correlation-ID'，開發者可以在微服務架構中追蹤一個請求如何跨越不同的服務節點。此外，標頭還可用於版本控制，透過 'API-Version' 標頭，伺服器可以根據客戶端的需求提供不同版本的 API 回應，而不必更改 URL 路徑。
除了追蹤與版本控制，安全性也是自訂標頭的重要應用領域。透過特定的標頭傳遞權限令牌，可以避免將敏感資訊直接放入 URL 或查詢字串中。這種做法符合 RESTful 設計原則，因為資源的識別與權限的驗證被區隔開來。
實作細節與最佳實務
在實作時，必須考慮到跨來源資源共用（CORS）的限制。如果你希望瀏覽器端能夠讀取特定的自訂標頭，必須在伺服器回應中明確設定 'Access-Control-Expose-Headers'。如果不進行此設定，前端將無法取得這些自訂資訊。
此外，標頭的命名應保持簡潔且具有描述性。避免使用過長或過於複雜的名稱，這會增加網路傳輸的負擔，雖然在現代頻寬下影響微乎其微，但保持簡潔始終是良好的工程習慣。
標頭安全性與隱私考量
過度暴露標頭資訊可能會導致資訊洩漏。例如，不要在標頭中傳遞伺服器軟體版本或底層架構細節，這會讓攻擊者更容易針對特定的漏洞進行掃描。應僅傳遞業務所需的必要資訊，並對標頭內容進行適當的驗證與 sanitization。
對於敏感資料，務必使用 HTTPS 加密傳輸。即便標頭資訊看起來無害，也可能包含使用者的行為軌跡，應嚴格遵守資料最小化原則，只在必要時才透過標頭傳遞資料。
常見標頭實作對照表
| 標頭名稱 | 用途 | 建議使用時機 |
|---|---|---|
| X-Request-ID | 請求追蹤 | 分散式系統日誌紀錄 |
| App-Version | 版本控管 | 多版本 API 並存時 |
| X-Device-Type | 裝置辨識 | 行動端與網頁端區分 |
| X-Auth-Token | 權限驗證 | 無狀態 API 認證 |
如何處理 CORS 與自訂標頭
當開發單頁應用（SPA）時，CORS 經常是自訂標頭的絆腳石。當瀏覽器發出預檢請求（Preflight Request）時，必須在 'Access-Control-Allow-Headers' 中列出您預計使用的所有自訂標頭名稱，否則請求將會被拒絕。
這是一個經常被忽略的步驟，導致前端開發者在除錯時發現標頭無法正確傳遞。請務必在伺服器端配置中，將相關標頭納入允許列表，確保通訊順暢。
總結設計與維運的平衡
設計良好的自訂標頭系統，能讓 API 維護變得更加輕鬆。透過標準化的命名規則與明確的用途定義，團隊成員可以快速理解系統間的互動方式。最後，記得定期審查標頭的使用狀況，移除不再需要的欄位，以維持系統的輕量與安全性。
- 使用 HTTP 標頭進行版本控制。
- 確保預檢請求包含所有自訂標頭。
- 避免在標頭中暴露伺服器架構資訊。
- 使用唯一的請求 ID 進行日誌追蹤。
- 遵循 HTTP 語義，不要濫用標頭。
- 對標頭內容進行嚴格的輸入驗證。
- 考慮使用 HTTPS 保護標頭資訊。
- 定期清理不再使用的自訂標頭。
- 在文件記錄每個標頭的用途。
- 透過 CORS 設定確保前端可讀取標頭。