Epoch, ISO 8601 mi RFC 3339 mü? API Tarih Formatı

Tarihlere dokunan her API sonunda tek bir soruyu yanıtlamak zorunda kalır: bir zaman damgası alanı ağ üzerinde gerçekte neye benzer? Yaygın kullanımda gerçekten üç aday vardır — ham bir Unix epoch tamsayısı, bir ISO 8601 dizesi ve onun daha sıkı kuzeni RFC 3339. Hepsi zamanda aynı anı tanımlar, ama akış aşağısında bir şeyler yanlış gittiğinde farklı biçimde bozulurlar ve doğru olanı baştan seçmek, sonrasında koca bir “bu tarih neden birkaç saat kaymış” hata raporu kategorisini önler.

Her formatın gerçekte ne olduğu

Bir Unix epoch zaman damgasıbir tamsayıdır: POSIX'in time_ttanımına göre 1970-01-01T00:00:00Z'den bu yana geçen saniye (veya milisaniye, ya da daha az yaygın olarak mikrosaniye veya nanosaniye) sayısı. Hiçbir saat dilimi taşımaz — yapısı gereği her zaman UTC'ye görelidir — ama hiçbir birim işareti de taşımaz; gerçek dünyadaki sorunlarının çoğu buradan gelir.

ISO 8601, tarih ve saatleri metin olarak temsil etmek için uluslararası standarttır ve kasten geniştir: takvim tarihlerine, hafta numaralandırmalı tarihlere, sıra tarihlerine, sürelere, aralıklara, azaltılmış hassasiyete (yalnızca bir yıl veya bir yıl ve ay) ve UTC farkı olan veya olmayan saat değerlerine izin verir. Bu esneklik, “ISO 8601 uyumlu” ifadesini kulağa geldiğinden daha zayıf bir garanti yapan tam olarak şeydir — iki sistem de teknik olarak uyumlu olabilir ve yine de birbirinin ayrıştıramayacağı dizeler üretebilir.

RFC 3339, ISO 8601'in IETF'in internete yönelik profilidir: tam olarak tek bir şekli korur (YYYY-MM-DDTHH:MM:SS[.ffffff](Z|±HH:MM)) ve ISO 8601'in izin verdiği ama otomatik ayrıştırmayı belirsiz kılacak her şeyi düşürür — hafta tarihi yok, azaltılmış hassasiyet yok ve bir fark zorunludur, asla ima edilmez. İnsanlar bir API bağlamında “ISO 8601 zaman damgası” dediğinde, neredeyse her zaman kastettikleri ve kodlarının neredeyse her zaman beklediği şey RFC 3339'dur.

Her biri gerçekte nerede bozulur

Epoch tamsayıları sessizce bozulur, bu da yüksek sesle bozulmaktan daha kötüdür. 1700000000, ister saniye (14 Kasım 2023) ister milisaniye (20 Ocak 1970) anlamına gelsin, kusursuz geçerli bir sayıdır — yanlış bir birim varsayımı hata fırlatmaz, yalnızca büyüklük sırasına göre yanlış olan ve birisi fark edene kadar makul görünen bir tarih üretir. Bu, epoch değerlerini farklı dillerde yazılmış servisler arasında aktaran sistemlerde en yaygın tek zaman damgası hatasıdır; her servisin kendi varsayılan birimi vardır.

Düz ISO 8601 dizeleri farkta bozulur. 2023-11-14T22:13:20 gibi bir dize, bir Z veya ±hh:mmolmadan geçerli bir ISO 8601'dir ama gerçekten belirsizdir — UTC mi, yerel sunucu saati mi, yoksa isteği başlatan kullanıcının yerel saati mi? Her tüketici tahmin etmek veya bant dışı belgelere başvurmak zorunda kalır ve farklı tüketiciler bazen farklı tahmin eder.

RFC 3339, yapısı gereği her iki hata modunu da büyük ölçüde önler; bu yüzden API stil kılavuzlarında varsayılan tavsiyedir — örneğin Google'ın AIP-142'si, yeni API'lerde zaman damgası alanları için onu zorunlu kılar. Kalan uç durumu, kesirli saniye hassasiyetidir: spesifikasyon, ondalık noktasından sonra herhangi bir sayıda haneye izin verir; bu yüzden nanosaniye hassasiyeti üreten bir üretici ile milisaniyeye kesen bir tüketici, bir birim uyuşmazlığından çok daha küçük bir marjla da olsa tam anda hâlâ anlaşamayabilir.

Yeni bir alan için format seçmek

Herkese açık veya servisler arası bir API için, varsayılan olarak bir RFC 3339 dizesi kullanın. Ham loglarda ve hata ayıklayıcılarda çözmeye gerek kalmadan okunabilir, hem saat dilimi hem de hassasiyet konusunda belirsizlik içermez ve neredeyse her ana akım dilin tarih kütüphanesi onu doğal olarak ayrıştırır ve üretir. Tek bedeli, bir tamsayıya kıyasla değer başına birkaç fazladan bayttır — neredeyse her API yükü için önemsiz.

Alan yüksek hacimli telemetri, bir metrik zaman damgası veya her üretici ve tüketicinin sizin kontrolünüzde olduğu ve birimde zaten anlaştığı dahili bir sıralama/anahtar olduğunda bir epoch tamsayısına başvurun. O zaman bile, kurala güvenmek yerine birimi alan adında açıkça belgeleyin (yalnızca created_at değil, created_at_ms). Belgelenmemiş bir epoch alanını tersine mühendislik yapmanız gerektiğinde hane sayısına dayalı birim tespitinin nasıl çalıştığını Unix zaman damgaları açıklaması rehberimiz kapsar.

Kısa özet

Epoch tamsayıları kompakttır ama birim taşımaz; düz ISO 8601 geniştir ama farkı atlayabilir; RFC 3339, çoğu API aracının “ISO tarihi” dediğinde gerçekte beklediği, ISO 8601'in dar, belirsizlik içermeyen dilimidir. Yeni bir alan tasarlıyorsanız ve yük boyutunu optimize etmek için güçlü bir nedeniniz yoksa, RFC 3339 tüm bir servisler arası zaman damgası hatası kategorisini daha başlamadan ortadan kaldırır.