[ADP-707] 日期時間和時間數據
指導原則
- 客戶端和伺服器之間交換的所有日期時間和時間值必須(MUST)嚴格遵守 RFC 3339 格式。這個要求確保日期時間表示是明確的、一致的，並且在不同系統和平台之間具有互操作性。
- 所有 API 必須(MUST)在其回應中以 RFC 3339 格式返回日期時間和時間值。
- 所有接受日期時間和時間輸入的 API 必須(MUST)接受 RFC 3339 格式的值。
- 當需要時，API 可以(MAY)使用包含微秒精度的格式。
RFC 3339 格式概述
RFC 3339 是 ISO 8601 標準的一個日期和時間表示配置文件。它為日期時間值定義了一個清晰且明確的格式，包括以下組件:
- 日期: 完整日期格式為
YYYY-MM-DD - 時間: 一天中的時間格式為
hh:mm:ss - 時區: 與 UTC 的時間偏移格式為
±hh:mm或字面值Z表示 UTC
示例
RFC 3339 日期時間字符串的示例:
http
2024-07-13T14:23:55Z這表示 2024 年 7 月 13 日 14:23:55 UTC。
詳細分解
- 日期:
2024-07-13 - 時間:
14:23:55 - 時區:
Z(UTC)
可選的小數秒
RFC 3339 允許可選地包含最高精度為納秒的小數秒。帶毫秒的示例:
http
2024-07-13T14:23:55.123Z時區偏移
當指定時區偏移時，必須包括小時和分鐘的偏移:
http
2024-07-13T14:23:55+02:00這表示 2024 年 7 月 13 日 14:23:55，比 UTC 提前兩小時。
設計思路
通常，timestamp 用於描述特定時間，但它可能以秒或毫秒為單位，且無法明確表示時區資訊。此外，ISO-8601 定義了基本的時間格式，但它對時間的規範較為寬鬆。因此，我們的標準是採用更為嚴格的 RFC 3339。