[ADP-364] 自定義標頭欄位設計

指導

標頭命名

• 不應(SHOULD NOT)使用"X-"前綴作為自定義標頭名稱。

  TIP

  根據IETF建議(RFC 6648)，這種做法已被棄用。

  INFO

  對於已經成為慣例的自訂義標頭，保留其命名，比如：X-Request-Id。

• 應(SHOULD)使用清晰、描述性的名稱，以傳達標頭的目的和用途。
• 應(SHOULD)在整個應用程序中保持一致的標頭命名慣例。
• 應(SHOULD)遵循與應用程序整體命名慣例相匹配的模式，以提高可讀性和可維護性。
• DRAFT 應(SHOULD) 在內部 API 入口網站註冊表中註冊自定義標頭，以確保不同專案能夠統一使用，類似於 IANA 註冊表的做法。
• 應(SHOULD)更新自定義標頭到共用的 OpenAPI headers.yaml 並更新版本號，請參閱 ADP-767: 共用常見標頭。
• 在創建自定義標頭之前，應(SHOULD)評估現有的標準標頭，參閱ADP-121。
  • 如果現有的標準標頭滿足需求，必須(MUST)使用該標準標頭，而不是創建新的自定義標頭。

示例

不要:

X-User-Role: admin

應該:

User-Role: admin

參考

• https://datatracker.ietf.org/doc/html/rfc6648