Date & Time Formats Reference

Practical Snippet

Key points: (1) declare the timestamp unit in the contract and validate magnitude server side — anything above 1e11 cannot be seconds; (2) store UTC as an ISO string or a number, never a zoneless string such as 2024-06-01 12:00:00; (3) Date.toString() embeds the local zone with English month names and is not reversibly parseable, so it must not be persisted; (4) HTTP header dates must use the IMF-fixdate form from toUTCString(); (5) bare local times do not exist or repeat on DST transition days, so schedule in UTC or with CRON_TZ.

const d = new Date()

// ① 三种输出，各自的用途
console.log(d.toISOString())            // 2024-06-01T12:00:00.000Z  ← 存储/传输用这个
console.log(d.toJSON())                 // 同上（Date 专有）
console.log(d.getTime())                // 1717243200000          毫秒，注意是 13 位

// ② 🔴 单位混用的防御：量级校验
function toDate(v) {
  if (typeof v === 'number') {
    if (v < 1e11) return new Date(v * 1000)     // 看着像秒 ⇒ 当秒处理
    if (v > 1e14) throw new Error('不像毫秒时间戳: ' + v)
    return new Date(v)                          // 13 位 ⇒ 毫秒
  }
  if (typeof v === 'string') {
    if (/^d{10}$/.test(v)) return new Date(Number(v) * 1000)
    return new Date(v)                          // ISO 字符串直接解析
  }
  throw new TypeError('不支持的类型')
}
console.log(toDate(1717171717).toISOString())    // 秒 ⇒ 正常
console.log(toDate(1717171717000).toISOString())  // 毫秒 ⇒ 正常

// ③ 存储一律 UTC，展示再本地化（不要存本地时间字符串）
const record = { createdAt: d.toISOString() }    // ✅
const LOCAL = '2024-06-01 12:00:00'             // ❌ 不带时区，无法推断

// ④ 手动格式化（仅用于展示；库更省事）
const pad = n => String(n).padStart(2, '0')
const fmtLocal = x => x.getFullYear() + '-' +
  pad(x.getMonth() + 1) + '-' + pad(x.getDate()) + ' ' +
  pad(x.getHours()) + ':' + pad(x.getMinutes())

// ⑤ RFC 7231 的 HTTP 头日期（必须用 UTC 的英文格式）
console.log(new Date().toUTCString())
// Mon, 01 Jun 2024 12:00:00 GMT

// ⑥ 陷阱：toString() 结果不可解析，不要用于持久化
console.log(d.toString())       // 本地时区 + 空格分隔 + 英文月份，不可逆