Membangkitkan Tipe TypeScript dari JSON: Panduan Praktis

Cara kerja inferensi JSON-ke-TypeScript

Generator menelusuri pohon nilai JSON dan memetakan setiap tipe JavaScript ke padanan TypeScript-nya: string tetap string, number tetap number, boolean tetap boolean, null menjadi null (atau digabungkan ke union), array menjadi T[] dengan T diinferensi dari elemennya, dan object menjadi interface bersarang.

{
  "id": 42,
  "email": "ada@example.com",
  "isActive": true,
  "roles": ["admin", "editor"],
  "profile": {
    "displayName": "Ada",
    "avatarUrl": null
  }
}

interface Root {
  id: number;
  email: string;
  isActive: boolean;
  roles: string[];
  profile: {
    displayName: string;
    avatarUrl: string | null;
  };
}

Di mana inferensi harus menebak

Field opsional vs. selalu hadir: satu sampel JSON tak bisa memberi tahu generator apakah avatarUrl kadang hilang sepenuhnya (yang seharusnya avatarUrl?: string | null) atau selalu hadir tetapi kadang null. Beri generator beberapa sampel representatif, atau tandai field sebagai opsional secara manual setelah pembangkitan jika Anda tahu API menghilangkannya dalam kondisi tertentu.

Angka yang sebenarnya ID vs. kuantitas: JSON punya satu tipe number, tetapi TypeScript tak bisa membedakan ID integer dari harga floating-point tanpa konteks tambahan. Sebagian generator menawarkan branded types atau literal union untuk ini; kebanyakan sekadar menghasilkan number dan menyerahkan perbedaannya pada Anda.

Array kosong: array tanpa contoh di dalamnya ("tags": []) tidak memberi generator apa pun untuk menginferensi tipe elemennya — biasanya ia jatuh ke unknown[] atau any[]. Arahkan generator ke sampel yang array-nya terisi, atau anotasikan manual setelahnya.

Literal union string: field status yang selalu salah satu dari "pending" | "active" | "closed" akan diinferensi sebagai string polos kecuali generator melihat semua nilai yang mungkin dalam sampel — dan bahkan saat itu, kebanyakan generator memilih tipe string yang lebih luas kecuali Anda mengaktifkan inferensi literal-union secara eksplisit.

Tanggal: JSON tak punya tipe tanggal — timestamp selalu berupa string (ISO 8601) atau angka (Unix epoch). Generator akan mengetikkan field tanggal sebagai string atau number, bukan Date; Anda tetap perlu mem-parsenya sendiri setelah fetching.

Ide yang sama dalam bahasa lain

Logika inferensinya — telusuri pohonnya, petakan tipenya, beri nama object bersarang — sama saja apa pun bahasa targetnya; hanya sintaks keluarannya yang berubah. Struct Go mendapat pemetaan field yang sama dengan struct tag untuk nama key JSON; dataclass Python mendapat type hint dan pembungkus Optional[...] opsional; kelas Java atau C# mendapat field bertipe dan getter/setter atau records. Jika tim Anda bekerja lintas bahasa terhadap API yang sama, membangkitkan tipe untuk masing-masing dari sampel JSON yang sama menjaga mereka tetap jujur satu sama lain.

type Root struct {
	ID       int     `json:"id"`
	Email    string  `json:"email"`
	IsActive bool    `json:"isActive"`
	Roles    []string `json:"roles"`
	Profile  struct {
		DisplayName string  `json:"displayName"`
		AvatarURL   *string `json:"avatarUrl"`
	} `json:"profile"`
}

Sebelum memercayai tipe yang dibangkitkan

Tipe yang dibangkitkan adalah titik awal yang kuat, bukan kontrak final. Sebelum meng-commit: konfirmasikan field opsional terhadap dokumentasi API nyata (bukan satu sampel saja), ganti field string yang longgar namun sebenarnya enum dengan literal union, pastikan field array-kosong mendapat tipe elemen nyata dari sampel yang lebih baik, dan bangkitkan ulang setiap kali API upstream menambah atau mengganti nama field alih-alih menambal interface-nya secara manual.