JSON Toolkit

Format apa untuk cap masa dalam JSON

Inti pati: Nombor epoch dan rentetan ISO masing-masing mempunyai trade-off, tetapi mencampurkannya itulah yang sebenarnya merosakkan. Guna ISO 8601 dengan offset, simpan UTC, render dalam zon waktu pengguna.

Pemula~3 min bacaanDiterbitkan 2026-10-30Dikemas kini 2026-10-30
Memilih format cap masa untuk API JSON

Pokoknya: guna ISO 8601 dengan offset eksplisit semasa pemindahan, simpan UTC dengan Z di hujung, dan tukar hanya pada masa paparan; jika anda memilih nombor epoch sebaliknya, tetapkan saat lawan milisaat secara global dan letakkan unit dalam nama medan.

Mengapa 2026-10-30 14:30:00 tidak mencukupi

Rentetan itu tidak membawa zon. 14:30 di Shanghai dan 14:30 di London terpisah lapan jam, dan tiada cara untuk mengetahui yang mana dimaksudkan. new Date('2026-10-30 14:30:00') menghuraikan dalam zon setempat masa jalan, jadi pelayan dan pelayar memperoleh dua saat berbeza daripada satu muatan — jenis bug yang tidak pernah dihasilkan semula.

2026-10-30 yang tulen bukanlah satu saat sama sekali. Baik untuk hari lahir dan tempoh bil, salah untuk masa penciptaan.

Dua format yang boleh dilaksanakan

Rentetan ISO 8601

{
  "createdAt": "2026-10-30T14:30:00+08:00",
  "updatedAt": "2026-10-30T06:30:00Z"
}

Boleh dibaca, boleh disusun apabila formatnya konsisten, ketepatan milisaat jika perlu, dan menerangkan dirinya sendiri.

Nombor epoch

{ "createdAt": 1793519400 }

Padat dan tidak kabur, tetapi tidak boleh dibaca, dan saat lawan milisaat ialah bahaya kekal. Jika anda memilih epoch, piawaikan unit dan letakkan dalam nama medan: createdAtMs jauh lebih selamat daripada createdAt.

Konvensyen yang wajar ditetapkan awal

Perkara Konvensyen
Format pemindahan ISO 8601 dengan Z atau +08:00
Zon penyimpanan UTC, supaya DST tidak pernah masuk gambaran
Ketepatan Milisaat sudah cukup
Penamaan medan createdAt, updatedAt, expiresAt
Tarikh tulen Medan date berasingan, contohnya birthday: "1990-01-01"
Tempoh Integer serta unit, contohnya timeoutMs: 3000

Paparan

new Intl.DateTimeFormat('en-GB', {
  dateStyle: 'medium',
  timeStyle: 'short',
  timeZone: 'Europe/London',
}).format(new Date('2026-10-30T06:30:00Z'));

Nyatakan timeZone secara eksplisit apabila paparan tidak boleh mengikut peranti. Bergantung pada lalai pelayar betul untuk masa yang menghadap pengguna dan salah untuk laporan.

Tiga pepijat berulang

Tarikh tulen dihuraikan sebagai tengah malam UTC. Menurut spesifikasi ECMAScript, rentetan tarikh sahaja adalah UTC manakala rentetan tarikh-masa adalah setempat. Ketidakselarasan itu ialah sumber pepijat terlebih-satu-hari yang boleh diharapkan.

Zon pangkalan data tidak bersetuju dengan pensiri. MySQL datetime tiada zon; tulis setempat, baca sebagai UTC, dan segala-galanya beralih mengikut offset.

Waktu jimat siang. Menyimpan masa setempat masa hadapan mencipta saat yang tidak wujud atau berlaku dua kali. UTC tiada jurang sedemikian.

Soalan Lazim

Bagaimana saya harus memilih antara ISO 8601 dan nombor epoch?

Guna ISO 8601 apabila manusia membaca muatan, apabila anda mahukan susunan leksikal, atau apabila nilai itu mesti membawa zonnya sendiri; kosnya kira-kira sedozen bait tambahan dan pustaka penghuraian. Guna nombor epoch apabila kepadatan dan pengendalian antara bahasa yang remeh lebih penting, tetapi tetapkan saat lawan milisaat secara global dan nyatakan unit yang dipegang oleh medan itu.

Patutkah tarikh tulen dan cap masa berkongsi medan yang sama?

Tidak. 2026-10-30 yang tulen ialah hari kalendar tanpa masa dan tanpa zon, manakala medan cap masa dijangka membawa saat yang tepat. Simpan hari lahir dan tempoh bil dalam medan date berasingan, dan guna medan At ISO 8601 untuk masa penciptaan atau kemas kini.

Bacaan lanjut