JSON Formatlama En İyi Uygulamaları

JSON (JavaScript Object Notation), web'de veri alışverişi için fiili standart haline gelmiştir. API'ler JSON döndürür, yapılandırma dosyaları JSON kullanır ve hatta veritabanları JSON belgeleri depolar. Basitliğine rağmen JSON, ihlal edilmesi kolay katı sözdizimi kurallarına sahiptir ve kötü formatlanmış JSON hata ayıklama zorluklarına, performans sorunlarına ve güvenlik açıklarına yol açabilir. Bu kılavuz, temel sözdiziminden Schema doğrulaması ve büyük dosyaları işleme gibi ileri konulara kadar JSON'ı doğru formatlama hakkında bilmeniz gereken her şeyi kapsar.

JSON Nedir?

JSON, JavaScript nesne literal sözdiziminden türetilen hafif, metin tabanlı bir veri değişim formatıdır. 2000'lerin başında Douglas Crockford tarafından belirtilmiş ve ECMA-404 ve RFC 8259 olarak standartlaştırılmıştır. JSON'ın tasarım hedefleri basitlik, insan tarafından okunabilirlik ve programlama dilleri arasında kolay uygulanabilirliktir. Bugün her büyük programlama dili yerleşik JSON desteği içerir.

JSON altı veri türünü destekler: dizeler (çift tırnak), sayılar (tamsayı ve kayan nokta), boolean değerler (true ve false), null değeri, nesneler (sırasız anahtar-değer koleksiyonları) ve diziler (sıralı listeler). Yorumları, tarihleri, ikili verileri veya undefined değerleri doğal olarak desteklemez.

JSON Sözdizimi Kuralları

JSON'ın kesinlikle uyulması gereken bir sözdizimi vardır. Tek bir karakter hatası bile tüm belgenin ayrıştırılamamasına neden olabilir. Bu kuralları anlamak en yaygın formatlama hatalarını önler.

Dizeler Çift Tırnak Kullanmalıdır

Tüm dize değerleri ve nesne anahtarları çift tırnak içine alınmalıdır. Tek tırnak geçerli bir JSON dize sınırlayıcısı değildir. Bu, JavaScript'ten gelen ve tek ve çift tırnağın birbirinin yerine kullanılabildiği geliştiricilerin en yaygın hatalarından biridir.

// Invalid - single quotes
{'name': 'Alice', 'age': 30}

// Valid - double quotes
{"name": "Alice", "age": 30}

Nesne Anahtarları Tırnak İçinde Olmalıdır

JavaScript nesne literallerinden farklı olarak, JSON tüm nesne anahtarlarının çift tırnak içine alınmasını gerektirir. Tırnaksız anahtarlar sözdizimi hatasıdır.

// Invalid - unquoted keys
{name: "Alice", age: 30}

// Valid - quoted keys
{"name": "Alice", "age": 30}

Sondaki Virgül Yasaktır

JSON, bir nesne veya dizinin son öğesinden sonra virgüle izin vermez. Bu, JavaScript'te sondaki virgüle izin verilen (hatta bazı stil kılavuzlarında teşvik edilen) JavaScript geliştiricilerinin bir başka yaygın hatasıdır.

// Invalid - trailing comma
{
  "name": "Alice",
  "age": 30,
}

// Valid - no trailing comma
{
  "name": "Alice",
  "age": 30
}

Yorumlar Desteklenmez

JSON yorumları desteklemez. // tek satırlı yorumlar ve /* */ çok satırlı yorumlar JSON'da geçersizdir. Belgeleme eklemeniz gerekiyorsa, ayrı belgeleme dosyaları veya bazı araçlar tarafından desteklenen JSONC (Yorumlu JSON) formatını kullanmayı düşünün.

Katı Değer Türleri

JSON değerleri altı desteklenen türden biri olmalıdır. undefined, NaN, Infinity ve -Infinity geçerli JSON değerleri değildir. Bunlardan herhangi birini içermek ayrıştırma hatalarına neden olur veya birçok ayrıştırıcının reddedeceği standart dışı JSON üretir.

Yaygın Formatlama Hataları

Sözdizimi hatalarının ötesinde, teknik olarak geçerli ancak sorunlu JSON üreten birkaç formatlama hatası vardır:

• Tutarsız girinti: Sekme ve boşlukları karıştırmak veya farklı girinti derinlikleri kullanmak, JSON'ı kod incelemelerinde ve diff'lerde okumayı zorlaştırır. En yaygın kural olan 2 boşluk girintisini standartlaştırın.
• Derin iç içe yapılar: 4-5 seviyeden fazla iç içe yerleştirilmiş JSON'ı okumak ve hata ayıklamak zorlaşır. Yapıları düzleştirmeyi veya ayrı belgelere bölmeyi düşünün.
• Tutarsız anahtar sıralaması: JSON nesneleri teknik olarak sırasız olsa da, tutarlı bir anahtar sıralaması (alfabetik veya önem sırasına göre) diff'leri daha anlamlı hale getirir ve sürüm kontrolünde birleştirme çakışmalarını azaltır.
• Aşırı uzun satırlar: Tek satırda birçok öğe bulunan dizileri taramak zordur. Okunabilirliği artırmak için uzun dizileri her satırda bir öğe olacak şekilde birden çok satıra bölün.
• Eksik veya tutarsız null işleme: null değerlerini tamamen atlamaya mı yoksa açıkça dahil etmeye mi karar verin ve bu kararı API genelinde tutarlı bir şekilde uygulayın.

Pretty Print ve Sıkıştırma

JSON'ın iki ana formatlama modu farklı amaçlara hizmet eder ve doğru bağlamda doğru formatı kullanmak önemlidir.

Pretty Print JSON

Pretty print, JSON'ı insan tarafından okunabilir hale getirmek için girinti ve satır sonları ekler. Bu, geliştirme, hata ayıklama ve belgeleme sırasında çok önemlidir. Çoğu JSON formatlayıcı varsayılan olarak 2 boşluk girintisi kullanır:

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com"
    },
    {
      "id": 2,
      "name": "Bob",
      "email": "bob@example.com"
    }
  ]
}

Sıkıştırılmış JSON

Sıkıştırma, mümkün olan en küçük geçerli JSON'ı üretmek için tüm gereksiz boşlukları kaldırır. Bu, her baytın önemli olduğu üretim API'leri için çok önemlidir:

{"users":[{"id":1,"name":"Alice","email":"alice@example.com"},{"id":2,"name":"Bob","email":"bob@example.com"}]}

Hangisi Ne Zaman Kullanılır

JSON Schema Doğrulaması

JSON sözdizimi doğrulaması bir belgenin iyi formatlanmış olup olmadığını kontrol ederken, verilerin beklenen yapıya, türlere veya değerlere sahip olup olmadığını doğrulamaz. JSON Schema, JSON verilerinin beklenen şeklini tanımlayan bir kelime dağarcığı sağlayarak bu boşluğu doldurur.

JSON Schema Nedir?

JSON Schema, diğer JSON belgelerinin yapısını tanımlayan bir JSON belgesidir. Zorunlu alanları, beklenen türleri, değer aralıklarını, dize desenlerini ve iç içe nesne yapılarını belirtmenize olanak tanır. Schema'ya uyan bir JSON belgesine geçerli örnek denir.

Yaygın Schema Özellikleri

• Tür kontrolü: Alanların dize, sayı, boolean, nesne veya dizi olduğundan emin olun.
• Zorunlu alanlar: Hangi özelliklerin bulunması gerektiğini belirtin.
• Dize doğrulaması: Desenleri (regex), minimum/maksimum uzunluğu ve formatı (e-posta, tarih-saat, URI) zorunlu kılın.
• Sayı doğrulaması: Minimum, maksimum, hariç sınırlar ve kat kısıtlamaları ayarlayın.
• Dizi doğrulaması: Öğe türlerini, minimum/maksimum öğe sayısını ve benzersizliği kontrol edin.
• Birleştirme: Karmaşık doğrulama mantığı için allOf, anyOf, oneOf ve not kullanın.

Schema Doğrulaması Ne Zaman Kullanılır

Dış kaynaklardan JSON aldığınızda her zaman JSON Schema doğrulaması kullanmalısınız: API istek gövdeleri, yapılandırma dosyaları, veri içe aktarmaları ve mesaj kuyruğu yükleri. Schema doğrulaması hataları erken yakalar, net hata mesajları sağlar ve veri formatları için canlı belgeleme görevi görür. Ajv (JavaScript), jsonschema (Python) ve json-schema-validator (Java) gibi kütüphaneler, Schema doğrulamasını herhangi bir uygulamaya entegre etmeyi kolaylaştırır.

JSON Boyutunun Performans Etkisi

JSON belgelerinin boyutu, uygulama performansını birden fazla boyutta doğrudan etkiler: ağ aktarım süresi, ayrıştırma süresi ve bellek tüketimi. Bu etkileri anlamak, JSON formatlama ve yapılandırma hakkında bilinçli kararlar vermenize yardımcı olur.

Ağ Aktarımı

JSON'ın her baytı ağ üzerinden sunucudan istemciye aktarılmalıdır. Hızlı bağlantılarda 10KB ile 100KB arasındaki fark önemsiz görünebilir, ancak mobil ağlarda veya daha yavaş internet bölgelerindeki kullanıcılar için etki önemlidir. Araştırmalar, her 100 ms'lik yükleme süresi artışının dönüşüm oranlarını yaklaşık %1 azalttığını göstermektedir. Sıkıştırma genellikle JSON boyutunu %30-50 azaltır, gzip sıkıştırması ek %70-85 azaltma sağlar. JSON API yanıtları için her zaman gzip veya Brotli sıkıştırmasını etkinleştirin.

Ayrıştırma Performansı

JSON ayrıştırma şaşırtıcı derecede maliyetlidir. Büyük belgeler için (1MB'ın üzerinde), mobil cihazlarda ayrıştırma yüzlerce milisaniye sürebilir. Maliyet, belge boyutuyla kabaca doğrusaldır. Ayrıştırma maliyetini azaltmak için temel stratejiler: yalnızca istemcinin ihtiyaç duyduğu verileri gönderme (alan filtreleme), büyük sonuç kümeleri için sayfalama ve insan tarafından okunabilirliğin gerekmediği dahili servis iletişiminde Protocol Buffers veya MessagePack gibi daha verimli serileştirme formatları kullanma.

Bellek Kullanımı

Ayrıştırılmış JSON, her değer kendi bellek tahsisine sahip bağımsız bir nesne haline geldiği için genellikle serileştirilmiş formundan 3-10 kat daha fazla bellek tüketir. 1MB'lık bir JSON dizesi ayrıştırıldıktan sonra 5-10MB RAM kullanabilir. Tarayıcıda çalışan ve sınırlı belleğe sahip JavaScript uygulamaları için bu, düşük kaliteli cihazlarda performans düşüşüne veya çökmelere yol açabilir.

JSON ve JSONL

JSON Lines (JSONL veya NDJSON), JSON'ın önemli bir sınırlamasını ele alan ilgili bir formattır: tüm belgenin tek bir birim olarak ayrıştırılması gerekliliği. JSONL'de, dosyanın her satırı tam, bağımsız bir JSON nesnesidir.

JSONL Ne Zaman Kullanılır

• Günlük dosyaları: Her günlük kaydı, bağımsız bir satırda kendi kendine yeten bir JSON nesnesidir. Mevcut verileri değiştirmeden yeni kayıtlar ekleyebilir ve herhangi bir satırı bağımsız olarak okuyabilirsiniz.
• Veri akışları: Tam veri kümesini beklemeden kayıtları geldikçe işleyin. Her satır tam bir mesajdır.
• Büyük veri kümeleri: Tüm dosyayı belleğe yüklemeden kayıtları tek tek ayrıştırın ve işleyin. Bu, mevcut RAM'i aşan veri kümeleri için çok önemlidir.
• Paralel işleme: JSONL dosyalarını satır sınırlarında bölün ve parçaları farklı iş parçacıklarına dağıtın. Bu, rastgele bayt konumlarında bölmenin yapıyı bozacağı standart JSON için mümkün değildir.

Ne Zaman Standart JSON Kullanılır

• API yanıtları: Standart JSON, REST API'ler için beklenen formattır. Sonuçları bir dizi veya nesne içinde sarmak geleneksel ve beklenen bir durumdur.
• Yapılandırma dosyaları: Yapılandırma genellikle tek seferde yüklenmesi gerektiğinden, JSONL'nin akış avantajı önemsizdir.
• İç içe veri yapıları: Verileriniz kolayca bağımsız kayıtlara düzleştirilemeyen karmaşık iç içe yapıya sahipse, standart JSON daha doğaldır.

Büyük JSON Dosyalarını İşleme

Büyük JSON dosyaları (10MB'ın üzerinde), özel işleme gerektiren benzersiz zorluklar sunar. Standart ayrıştırma yöntemleri bu ölçekte başarısız olabilir veya düşük performans gösterebilir.

Akış Ayrıştırıcıları

Akış (veya SAX tarzı) ayrıştırıcılar, tüm belgeyi belleğe yüklemeden JSON'ı artımlı olarak işler. Nesne başlangıcı, anahtar-değer çiftleri ve dizi öğeleri gibi yapısal öğelerle karşılaştıkça olaylar yayarlar. Bu yaklaşım, dosya boyutundan bağımsız olarak sabit bellek kullanır. oboe.js (JavaScript), ijson (Python) ve Jackson Streaming API (Java) gibi kütüphaneler akış JSON ayrıştırma sağlar.

Büyük Dosyalar için Pratik İpuçları

• Önce JSONL'ye dönüştürün: Büyük bir JSON diziniz varsa, onu JSONL'ye dönüştürmek (her satırda bir nesne), grep, awk ve jq gibi standart araçlarla satır satır işleme olanağı sağlar.
• Komut satırı araçlarını kullanın: jq, komut satırından JSON işlemek için standart araçtır. Büyük dosyaları verimli bir şekilde işleyebilir ve çok büyük girdiler için akış modunu destekler.
• Böl ve paralelleştir: Büyük JSONL dosyalarını daha küçük parçalara bölün ve paralel olarak işleyin. Her satır kendi kendine yettiği için her parça bağımsız olarak işlenebilir.
• Belleğe yüklemekten kaçının: Mevcut RAM'den büyük dosyalar için asla JSON.parse() kullanmayın. Akış ayrıştırıcıları kullanın veya dosyayı satır satır işleyin.
• Sıkıştırılmış depolama: Büyük JSON dosyaları gzip sıkıştırmasıyla son derece iyi sıkışır (genellikle %80-90 azalma). Depolama için sıkıştırılmış kopyaları saklayın, işleme sırasında anında açın.

JSON Güvenlik Hususları

JSON bir veri formatıdır ve kendisi güvensiz değildir, ancak uygulamaların JSON'ı işleme şekli güvenlik açıklarına yol açabilir. Bu riskleri anlamak, güvenli sistemler inşa etmek için çok önemlidir.

JSON Ayrıştırmak için Asla eval() Kullanmayın

En kritik güvenlik kuralı: JSON ayrıştırmak için asla JavaScript'in eval() fonksiyonunu kullanmayın. eval() rastgele JavaScript kodu çalıştırır, yani kötü amaçlı JSON yükleri kullanıcının makinesinde kod çalıştırabilir. Her zaman yalnızca geçerli JSON'ı ayrıştıran ve çalıştırılabilir kodu reddeden JSON.parse() kullanın. Bu tartışılamaz.

JSONP ve Siteler Arası Riskler

JSONP (Paddingli JSON), CORS yaygın olarak desteklenmeden önce aynı köken politikası kısıtlamalarını aşmak için kullanılan bir teknikti. JSON verilerini script olarak çalıştırılan bir fonksiyon çağrısına sararak çalışır. Bu, üçüncü taraf sunuculardan rastgele JavaScript çalıştırdığı için doğası gereği tehlikelidir. Hem istemciyi hem de sunucuyu kontrol ediyorsanız, JSONP yerine CORS kullanın. JSONP eski bir teknoloji olarak kabul edilmeli ve yeni uygulamalarda kaçınılmalıdır.

Prototip Kirliliği

JavaScript'te JSON nesnelerini birleştirirken veya derin kopyalarken, __proto__, constructor ve prototype gibi anahtarlara dikkat edin. Kullanıcı tarafından sağlanan JSON bu anahtarlar temizlenmeden mevcut bir nesneye özyinelemeli olarak birleştirilirse, uygulamadaki tüm nesnelerin prototipini değiştirerek yetki yükseltmesine veya hizmet reddine yol açabilir. Birleştirmeden önce her zaman nesne anahtarlarını temizleyin.

Derin İç İçe Yerleştirme ile Hizmet Reddi

Aşırı iç içe yerleştirme derinliğine (binlerce seviye) sahip özel olarak hazırlanmış JSON belgeleri, özyinelemeli ayrıştırıcılarda yığın taşması hatalarına neden olabilir. Ayrıştırıcıda maksimum iç içe yerleştirme derinliği ayarlayarak bunu azaltın. Çoğu üretim JSON ayrıştırıcısı bu sınırı yapılandırmanıza izin verir.

Girdi Doğrulaması

Dış kaynaklardan gelen JSON verilerine asla güvenmeyin. Kullanmadan önce her zaman gelen JSON'ın yapısını, türlerini ve değer aralıklarını doğrulayın. JSON Schema doğrulaması en sağlam yaklaşımdır, ancak zorunlu alanlar ve tür kontrolleri için basit kontroller bile hatalı biçimlendirilmiş veya kötü amaçlı girdilere karşı önemli koruma sağlar.