JSON’dan TypeScript’e: arayüz ve tip oluşturma (2026 rehberi)
JSON’dan TypeScript’e geçmenin en hızlı yolu, payload’unuzu bir JSON’dan TypeScript’e dönüştürücüye yapıştırıp ürettiği arayüzü kopyalamaktır — kurulum yok, yükleme yok, tarayıcınızda anında biter. Bu, “tiplere hemen ihtiyacım var” durumunu çözer.
Ancak tip üretmek ile iyi tip üretmek iki ayrı şeydir. Bir dönüştürücü tahmin yürütmek zorundadır: Bu alan isteğe bağlı mı, yoksa yalnızca tek bir örnekte mi eksik? Şu array her zaman string mi tutuyor, yoksa bazen sayı da mı? Tarih string’i bir Date’e mi dönüşmeli? Bu rehber, çıkarımın gerçekte nasıl çalıştığını, ne zaman interface ne zaman type kullanmanız gerektiğini ve canlı API yanıtlarını güvenebileceğiniz tiplere çevirmenin gerçek tuzaklarını adım adım anlatıyor.
JSON’u TypeScript’e nasıl dönüştürürsünüz
JSON’u TypeScript’e dönüştürmek üç adım sürer:
- JSON’unuzu yapıştırın. Bir nesneyi, array’i veya ham API yanıtını giriş kutusuna bırakın. Dönüştürme anında ve tamamen istemci tarafında çalışır.
- Çıktıyı ayarlayın.
interfaceveyatypeseçin,Userya daApiResponsegibi bir kök ad belirleyin,exportanahtar sözcüğünü açıp kapatın ve isteğe bağlı alanlar için?:ya da| nulltercih edin. - Kopyalayın veya indirin. Üretilen TypeScript’i tek tıkla alın ve doğrudan kod tabanınıza yapıştırın.
İşlemsel yol için hepsi bu. JSON’dan TypeScript’e dönüştürücü girişi okur, bir tip ağacı çıkarır ve tanımları sağ tarafta yazdırır — sayfadan hiçbir şey ayrılmaz. Rehberin geri kalanı, dönüştürücünün tahmin edemediği durumları düzeltebilmeniz için ürettiği şeyi anlamakla ilgili.
JSON tipleri TypeScript’e nasıl eşlenir
Her JSON değerinin bir TypeScript karşılığı vardır. Eşleme çoğunlukla birebirdir:
| JSON değeri | TypeScript tipi |
|---|---|
"text" | string |
42, 3.14 | number |
true / false | boolean |
null | null |
[1, 2, 3] | number[] |
{ ... } | interface veya type |
İşin asıl yoğunlaştığı yer nesnelerdir. Tipik bir REST kullanıcı payload’unu ele alalım:
{
"id": 101,
"name": "Ada Lovelace",
"email": "ada@example.com",
"active": true,
"roles": ["admin", "user"]
}Bir dönüştürücü, bu JSON’dan şu TypeScript arayüzünü üretir:
export interface User {
id: number;
name: string;
email: string;
active: boolean;
roles: string[];
}Her skaler kendi ilkel tipine eşlenir ve roles array’i string[] olur. Bunu API istemcinize koyduğunuzda otomatik tamamlama ve derleme zamanı denetimleri de beraberinde gelir.
Dönüştürücü tipleri nasıl çıkarır
Asıl iş çıkarım algoritmasındadır. Dört kural, ona vereceğiniz neredeyse her şeyi kapsar.
Yapısal çıkarım: nesne başına bir adlandırılmış arayüz
Her belirgin nesne şekli kendi adlandırılmış arayüzü olur. İç içe nesneler satır içi tiplere indirgenmez — ayrı, referans verilen tanımlara taşınırlar:
{
"order": {
"id": "A-1",
"total": 42.5,
"customer": { "name": "Sam", "vip": false }
}
}export interface Root {
order: Order;
}
export interface Order {
id: string;
total: number;
customer: Customer;
}
export interface Customer {
name: string;
vip: boolean;
}Aynı şekiller tekilleştirilir; böylece aynı yapıya sahip iki alan, kopyalar üretmek yerine tek bir arayüzü paylaşır.
Array birleştirme: isteğe bağlı alanları çıkarma
Bir nesne array’i ilettiğinizde, dönüştürücü onları anahtar anahtar birleştirir. Bir anahtar bazı elemanlarda görünüp bazılarında görünmüyorsa, isteğe bağlı olarak işaretlenir:
{
"users": [
{ "id": 1, "nick": "x" },
{ "id": 2 }
]
}export interface Root {
users: User[];
}
export interface User {
id: number;
nick?: string;
}id her elemanda bulunur, bu yüzden zorunlu kalır. nick ikinci kullanıcıda eksiktir, bu yüzden nick?: string olur. Tek bir örnek neden nadiren yeterli olur, onu aşağıdaki tuzaklar bölümünde görebilirsiniz.
Karışık array’ler için birleşim tipleri
Array’lerin türdeş olması gerekmez. Elemanlar farklı tiplere sahip olduğunda, dönüştürücü onları bir birleşim içinde toplar:
{
"tags": ["a", "b"],
"meta": [1, "two"]
}export interface Root {
tags: string[];
meta: (string | number)[];
}tags türdeş biçimde string’tir, dolayısıyla string[]. meta bir sayı ile bir string’i karıştırır ve (string | number)[] üretir. Boş bir array hiç çıkarılamaz ve unknown[]’a düşer — sıfır elemandan öğrenecek bir şey olmadığından bu dürüst bir davranıştır.
İsteğe bağlı mı, null mı: ?: mı | null mı
Bunlar benzer görünür ama farklı şeyler ifade eder. ?: ile işaretlenmiş bir alan nesneden tamamen yok olabilir. | null ile tiplenen bir alan her zaman vardır ama null değerini tutabilir:
{ "score": null }export interface Root {
score: number | null;
}Burada score açık bir null ile birlikte vardır, bu yüzden number | null olarak tiplenir — değer mevcuttur, yalnızca null’dur. Bunu array örneğindeki nick?: string ile karşılaştırın; orada anahtarın kendisi tümüyle eksik olabilir. API anahtarı atlayabildiğinde ?:, anahtarı null değeriyle gönderdiğinde | null kullanın. Çoğu dönüştürücü, bunun nasıl çıktılanacağını bir anahtarla denetlemenize izin verir.
interface vs type: hangisini kullanmalısınız?
İkisi de bir nesne şeklini tanımlayabilir. Karar verme yöntemi şöyle:
| İhtiyaç | Kullanın |
|---|---|
| JSON’dan gelen düz nesne şekli | interface |
Birleşim (A | B) veya kesişim (A & C) | type |
| Dosyalar arası bildirim birleştirme / genişletme | interface |
| Eşlemeli veya koşullu tipler | type |
| Biraz daha temiz editör hata mesajları | interface |
Bir JSON nesnesinden çıkmış veriler için interface geleneksel tercihtir ve marjinal olarak daha güzel derleyici hataları üretir. Bir birleşime ihtiyaç duyduğunuz an — diyelim ki ya başarı ya da hata olan bir Result — bir type’a geçmek zorunda kalırsınız, çünkü arayüzler birleşimleri ifade edemez:
type ApiResult =
| { status: "ok"; data: User }
| { status: "error"; message: string };İyi bir varsayılan: düz JSON nesneleri için bir interface üretin ve şekil bir birleşime ya da kesişime ihtiyaç duyduğunda bir type’a dönüştürün. Tam karşılaştırmayı istiyorsanız TypeScript Handbook uç durumları kapsar. Bir arayüz yerine bir json to typescript type takma adına ihtiyaç duyduğunuzda, çoğu dönüştürücü tüm çıktıyı çevirmek için tek bir anahtar sunar.
quicktype vs json-to-ts vs çevrim içi araçlar vs el ile
TypeScript tipleri üretmenin tek bir en iyi yolu yok; doğru seçim, JSON’un nerede durduğuna ve ne sıklıkla değiştiğine bağlı.
| Yaklaşım | En uygun olduğu durum | Ödünleşim |
|---|---|---|
| quicktype | Çok dilli çıktı, çalışma zamanı doğrulama kodu üretme | Daha ağır; çoğu zaman gerektiğinden fazla çıktı |
| json-to-ts (kütüphane) | Bir betiğe veya pipeline’a bağlı derleme zamanı kod üretimi | Kurulum ve bir Node araç zinciri gerektirir |
| Tarayıcı tabanlı çevrim içi araç | Tek seferlik dönüştürmeler, hassas payload’lar, sıfır kurulum | Her seferinde el ile yapıştırma |
| Tipleri el ile yazma | Küçük nesneler, tip sistemini öğrenme | Ölçekte sıkıcı ve hataya açık |
Birden çok dilde tiplere ihtiyaç duyduğunuzda ya da tiplerle birlikte doğrulayıcılar yaymasını istediğinizde quicktype’ı seçin. Dönüştürme bir derleme adımına ait olduğunda json-to-ts kütüphanesini seçin. Hızlı bir dönüştürme için — özellikle token, müşteri kimliği ya da uzak bir hizmete yapıştırmamayı tercih edeceğiniz herhangi bir şey içeren bir payload için — bir tarayıcı aracı gizlilik ve hızda kazanır. Bizim JSON’dan TypeScript’e dönüştürücümüz tamamen istemci tarafında çalışır: JSON sayfadan asla ayrılmaz ve kurulacak ya da güncellenecek bir şey yoktur.
Tipler doğrulama değildir: çalışma zamanı denetimlerine köprü
Bu birçok ekibi yanıltır, o yüzden açıkça söylemekte fayda var: TypeScript tipleri derleme zamanında silinir ve çalışma zamanında hiçbir şey yapmaz. Üretilmiş bir interface User, gerçek bir API yanıtının ona uyup uymadığını denetlemez. Sunucu id’yi sayı yerine string olarak gönderirse, TypeScript sizin tip ek açıklamanıza mutlu mesut inanırken gerçek veri yalan söyler.
generate typescript types yapıp aynı zamanda bunları canlı veri üzerinde zorlamak için, tipleri bir çalışma zamanı doğrulayıcısıyla eşleştirin:
- zod — şemayı bir kez tanımlayın, statik tipi ondan çıkarın ve yanıtları çalışma zamanında ayrıştırın.
- io-ts — codec tabanlı doğrulama, işlevsel kod tabanlarında popülerdir.
- JSON Schema + Ajv — çalışma zamanında doğrulanan dilden bağımsız şemalar; sözleşme hizmetler arasında paylaşıldığında işe yarar.
Yaygın bir desen, editör desteği için arayüzü üretmek, ardından gerçek sınır denetimi olarak eşleşen bir zod şeması yazmaktır:
import { z } from "zod";
const UserSchema = z.object({
id: z.number(),
name: z.string(),
email: z.string().email(),
active: z.boolean(),
roles: z.array(z.string()),
});
type User = z.infer<typeof UserSchema>;
// Gerçek yanıt şemaya uymuyorsa hata fırlatır.
const user = UserSchema.parse(await res.json());Şema yolunu izliyorsanız, JSON Schema doğrulama rehberimiz şema yazmayı ve zorlamayı baştan sona anlatıyor.
JSON’u tiplerken sık görülen tuzaklar
Üretilen tipler bir başlangıç noktasıdır, bitmiş bir ürün değil. Şunlara dikkat edin.
snake_case vs camelCase. Dönüştürücüler anahtarları olduğu gibi korur. public_repos içeren GitHub tarzı bir payload, publicRepos değil public_repos: number üretir. Kod tabanınız camelCase tercih ediyorsa, ya snake_case tiplerle yaşarsınız ya da alanları girerken yeniden adlandıran bir eşleme katmanı eklersiniz.
Tarih string’leri string kalır. "2026-06-01T00:00:00Z" gibi bir alan Date değil, string olarak tiplenir. Bu bilinçlidir — JSON’un tarih tipi yoktur ve yanlış tahmin etmek dürüst olmaktan beterdir. String’den Date’e dönüştürme, denetimin sizde olduğu ayrıştırma katmanınıza aittir.
any ve unknown sızıntısı. Boş array’ler unknown[] olur ve derinlemesine karışık yapılar gevşek tiplere bozulabilir. Bunlar hata değil; dönüştürücünün yetersiz veriden çıkarım yapamadığının işaretidir. Gerçek şekli öğrendiğinizde bunları el ile sıkılaştırın.
Derin iç içe geçme patlaması. Yoğun biçimde iç içe geçmiş bir payload, uzun bir küçük arayüzler zinciri üretir. Bu genellikle sorunsuzdur ve tek bir devasa satır içi tipten daha okunaklıdır, ancak kendi adını hak etmeyen şekilleri düzleştirmeye değer.
Tek örnek tuzağı. En sık takılınan yer burası. İsteğe bağlı alanlar yalnızca birden çok array elemanından çıkarılabilir — tek bir nesne, hangi anahtarların bazen eksik olduğunu dönüştürücüye söyleyemez. Önce temsili bir yanıt array’i toplayın. Dönüştürmeden önce birkaç örneği yan yana yapıştırıp incelemek için bir JSON biçimlendirici elverişlidir ve JSONC gibi standart dışı girişler besliyorsanız JSON5 ve JSONC rehberimizi okuyun — dönüştürücünün tam anlamıyla geçerli JSON’a ihtiyacı vardır.
Sıkça sorulan sorular
JSON’u bir TypeScript arayüzüne nasıl dönüştürürüm?
JSON’unuzu bir JSON’dan TypeScript’e dönüştürücüye yapıştırın. Girişi tarayıcınızda okur ve anında bir TypeScript arayüzü üretir. Sonucu almak için Kopyala’ya tıklayın — yükleme yok, hesap yok, kurulacak eklenti yok.
JSON verisi için interface mı type mı kullanmalıyım?
JSON’dan gelen düz nesne şekilleri için interface kullanın — geleneksel olandır ve biraz daha net editör hataları verir. Bir birleşime ya da kesişime ihtiyaç duyduğunuzda type’a geçin, çünkü arayüzler bunları ifade edemez.
İç içe nesneler ve array’ler nasıl işlenir?
İç içe nesneler ayrı, adlandırılmış arayüzler olur (bir address alanı bir Address arayüzü verir). Nesne array’leri anahtar anahtar tek bir eleman arayüzünde birleştirilir; ilkel array’ler ise string[] gibi tiplenmiş array’lere dönüşür.
İsteğe bağlı ve null alanlar nasıl tiplenir?
Bazı array elemanlarında eksik olan bir anahtar isteğe bağlı olarak işaretlenir (nick?: string). Her zaman var olan ama null tutan bir anahtar | null ile tiplenir (score: number | null). İkisi farklı durumları tanımlar: yok olan ile var-ama-null olan.
TypeScript tipleri JSON’u çalışma zamanında doğrular mı?
Hayır. TypeScript tipleri derleme zamanında silinir ve veriyi çalışma zamanında denetlemez. Gerçek bir API yanıtını doğrulamak için, üretilen tipleri zod, io-ts ya da Ajv ile JSON Schema gibi bir çalışma zamanı doğrulayıcısıyla eşleştirin.
quicktype vs json-to-ts vs çevrim içi bir dönüştürücü — hangisi en iyisi?
quicktype çok dilli çıktıya ve çalışma zamanı doğrulayıcılarına uygundur; json-to-ts kütüphanesi derleme zamanı kod üretimine uygundur; çevrim içi bir dönüştürücü hızlı, gizli, sıfır kurulumlu tek seferlik dönüştürmelere uygundur. Hassas payload’lar için, istemci tarafı bir tarayıcı aracı veriyi her türlü sunucudan uzak tutar.
Tarih string’leri neden Date yerine string olarak tiplenir?
JSON’un tarih tipi yoktur, dolayısıyla bir tarih hatta yalnızca bir string’tir. Bunu string olarak tiplemek dürüst ve istikrarlıdır; Date’e dönüştürmek, biçim ve hata işlemenin denetimini elinizde tuttuğunuz ayrıştırma katmanınıza ait bir karardır.
Çevrim içi bir dönüştürücü kullanırken JSON verim gizli kalır mı?
İstemci tarafı bir araçla, evet. Dönüştürme tamamen tarayıcınızda JavaScript kullanılarak çalışır; bu yüzden JSON — token’lar, kimlikler ve müşteri verisi dâhil — sayfadan asla ayrılmaz ve hiçbir zaman bir sunucuya gönderilmez.