[ADP-704] ID 欄位慣例

指導原則

• 除非有令人信服的理由使用不同格式，否則應該(SHOULD)使用 UUID v4 作為 ID 值。
  • 如果資源本質上是基於計數的，例如 /bugs/123，可以(MAY)使用遞增數字。
• 必須(MUST)確保 ID 值在其資源類型內是唯一的。
• 如果 ID 欄位可能存在歧義，可以(MAY)添加 ${resourceType} 作為欄位名稱前綴。

設計理由

每個資源對象都必須有 id 欄位，當多個資源對象嵌套（作為子資源）時，可能導致歧義。使用資源類型作為前綴可以提高識別對象類型的清晰度。這種方法符合 API 設計中的清晰性和自描述原則。

示例

應該:

{
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "orderId": "98765432-10ab-cdef-1234-567890abcdef"
}

錯誤做法

{
  "id": "123",
  "order_id": 456
}

OpenAPI 規範

components:
  schemas:
    User:
      type: object
      properties:
        userId:
          type: string
          format: uuid
          description: 用戶的唯一標識符
    Order:
      type: object
      properties:
        orderId:
          type: string
          format: uuid
          description: 訂單的唯一標識符

相關 ADPs

• ADP-701: 屬性設計
• ADP-705: 名稱欄位慣例

參考資料

• RFC 4122: 通用唯一標識符 (UUID) URN 命名空間
• JSON API 規範 - 資源識別