Skema GraphQL Tulis, Format, dan Pahami SDL Tanpa Kode Pengulangan

Jika Anda pernah bekerja dengan API REST dan kemudian membuka skema GraphQL untuk pertama kalinya, sintaksnya mungkin terasa familiar tetapi tidak bisa diproses. Itu normal. Bahasa Definisi Skema (SDL) singkat, tetapi mengandung banyak makna per baris. Artikel ini memecahkannya agar Anda bisa membaca dan menulis skema tanpa harus merujuk ke dokumen setiap lima menit.

Apa Sebenarnya Skema GraphQL?

Skema GraphQL adalah kontrak antara server API Anda dan setiap klien yang memanggilnya. Skema ini menentukan secara tepat apa data yang ada, operasi apa yang tersedia, dan bentuk respons yang dihasilkan. Berbeda dengan REST — di mana Anda menemukan endpoint melalui dokumentasi, percobaan, dan kesalahan — GraphQL membuat kontrak tersebut eksplisit dan dapat dibaca oleh mesin.

Setiap API GraphQL dimulai dengan skema yang ditulis dalam SDL. Server memvalidasi semua permintaan terhadap skema tersebut saat berjalan. Jika klien meminta field yang tidak ada dalam skema, permintaan ditolak sebelum resolver berjalan. Ini adalah nilai inti dari sistem tipe GraphQL: skema adalah sumber kebenaran untuk area permukaan API Anda.

Dasar SDL: Tipe, Kueri, dan Mutasi

Setiap file SDL dibangun dari definisi tipe. Berikut adalah skema terkecil yang berguna:

type Query {
  hello: String
}

Query adalah titik masuk untuk operasi baca. Setiap skema harus memiliki satu. Field hello mengembalikan sebuah String — salah satu dari lima tipe skalar bawaan.

Lima tipe skalar bawaan adalah:

• String — teks UTF-8
• Int — bilangan bulat tanda 32-bit
• Float — bilangan desimal dengan presisi ganda
• Boolean — benar atau salah
• ID — identifikasi unik, diserialisasi sebagai string

Skema yang lebih realistis menentukan tipe objek khusus. Berikut adalah pola yang lebih umum:

type User {
  id: ID!
  name: String!
  email: String!
  role: UserRole!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  body: String
  author: User!
  publishedAt: DateTime
}

type Query {
  user(id: ID!): User
  posts: [Post!]!
}

Ada banyak hal yang terjadi dalam 20 baris tersebut. Mari kita uraikan satu per satu.

Field Non-Null dan Daftar

Itu ! setelah tipe berarti field tersebut tidak nol — tidak akan mengembalikan null. Tanpa itu, field tersebut bersifat nullable dan klien harus menangani nilai yang hilang. Perbedaan ini penting saat berjalan: jika resolver field non-null melempar atau mengembalikan null, GraphQL akan menyebar null ke atas pohon, yang dapat menghilangkan field induk juga.

Daftar menggunakan tanda kurung siku: [Post] adalah daftar nullable dari post yang nullable. [Post!]! adalah daftar non-null dari post yang non-null. Itu adalah versi yang biasanya Anda inginkan — field yang selalu mengembalikan array (mungkin kosong), dan setiap elemennya selalu merupakan objek nyata, bukan null.

Keempat kombinasi, dijelaskan secara eksplisit:

• [Post] — daftar nullable, item nullable (sangat jarang berguna)
• [Post!] — daftar nullable, item non-null
• [Post]! — daftar non-null, item nullable
• [Post!]! — daftar non-null, item non-null (paling umum)

Mutasi: Menulis Data

Kueri bersifat hanya baca. Mutasi menangani penulisan. Tipe Mutation dibangun dengan cara yang sama seperti Query, tetapi secara konvensi field-field-nya memiliki efek samping:

type Mutation {
  createPost(input: CreatePostInput!): Post!
  deletePost(id: ID!): Boolean!
}

Melihat CreatePostInput! — itu adalah tipe input, yang langsung mengarah ke konsep berikutnya.

Tipe Input vs Tipe Output

Ini adalah salah satu titik kebingungan paling umum dalam skema GraphQL. Anda adalah: melindungi sub-subdomain. menggunakan tipe objek seperti Post sebagai argumen pada mutasi. SDL memiliki dua jenis tipe yang terpisah karena alasan tertentu:

• Tipe Objek (type) — digunakan dalam respons. Dapat mengandung resolver dan logika field kompleks.
• Tipe Input (input) — digunakan dalam argumen. Data sederhana, tidak ada resolver. Field hanya dapat merujuk pada skalar atau tipe input lainnya.

input CreatePostInput {
  title: String!
  body: String
  authorId: ID!
}

Pemisahan ini menjaga validasi argumen tetap bersih dan mencegah masalah referensi lingkaran yang muncul jika tipe output (yang dapat merujuk satu sama lain dalam grafik kompleks) digunakan secara langsung sebagai input.

Skalar Khusus

Lima skalar bawaan tidak mencakup semua hal. Sebuah string waktu, URL, atau blok JSON — ini membutuhkan skalar khusus. Anda mendeklarasikannya seperti ini:

scalar DateTime
scalar JSON
scalar URL

Pernyataan skalar memberi tahu SDL nama yang digunakan. Logika serialisasi, deserialisasi, dan validasi sebenarnya berada di implementasi server — bukan di file skema. Library seperti graphql-scalars memberikan implementasi siap pakai untuk tipe umum sehingga Anda tidak perlu menulisnya dari awal.

Gunakan skalar khusus ketika sebuah String secara teknis benar tetapi secara semantik salah. Field yang dityped sebagai DateTime mengomunikasikan niat; field yang dityped sebagai String mengharuskan klien untuk menebak formatnya.

Enum

Enum membatasi field untuk himpunan nilai string tetap. Mereka lebih andal daripada string biasa karena skema mengenali nilai yang diizinkan pada tingkat tipe:

enum UserRole {
  ADMIN
  EDITOR
  VIEWER
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

Field yang dityped sebagai UserRole tidak akan mengembalikan string yang tidak terduga. Field yang dityped sebagai String bisa mengembalikan apa saja. Gunakan enum ketika himpunan nilai diketahui, stabil, dan bermakna bagi klien — ini membuat inspeksi skema menjadi sangat lebih berguna.

Interface dan Union

Ketika field dapat mengembalikan tipe objek yang berbeda, GraphQL menawarkan dua mekanisme: interface dan union.

Interface mendefinisikan himpunan field yang sama. Tipe yang menerapkan interface harus mencakup field-field tersebut:

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
}

type Post implements Node {
  id: ID!
  title: String!
}

Union mengelompokkan tipe tanpa memerlukan field yang sama. Mereka berguna ketika tipe yang mungkin tidak memiliki struktur yang sama:

union SearchResult = User | Post | Comment

type Query {
  search(query: String!): [SearchResult!]!
}

Klien menggunakan fragmen inline untuk menangani setiap tipe dalam union atau interface: ... on User { name }. Jika Anda mengembalikan data polimorfik, pilih interface ketika tipe berbagi field, dan union ketika tidak.

Direktif

Direktif memodifikasi perilaku pada tingkat field atau tipe. Dua dari mereka terdapat dalam setiap implementasi GraphQL:

• @deprecated(reason: "Use newField instead") — menandai field sebagai dideprakasi dalam inspeksi
• @skip(if: Boolean) dan @include(if: Boolean) — kondisional di sisi klien dalam kueri

Anda juga dapat mendefinisikan direktif khusus untuk hal-hal seperti pengamanan autentikasi, petunjuk pembatasan kecepatan, atau annotasi penundaan. Mereka didefinisikan dalam skema dan diimplementasikan di server:

directive @auth(requires: UserRole = ADMIN) on FIELD_DEFINITION

type Mutation {
  deleteUser(id: ID!): Boolean! @auth(requires: ADMIN)
}

Perbedaan GraphQL dan REST: Kapan Harus Menggunakan Yang Mana

Pendekatan pertama skema GraphQL memberikan manfaat dalam situasi tertentu. Ini adalah pilihan yang tepat ketika:

• Banyak klien (web, mobile, pihak ketiga) membutuhkan subset data yang berbeda dari data yang sama
• Anda ingin mengembangkan API tanpa versi — tambahkan field secara bebas, dekati alihkan daripada menghapus
• Domain secara alami berbentuk graf dengan hubungan kompleks antar entitas
• Anda ingin API yang dapat dijelaskan sendiri yang dapat dieksplorasi oleh klien melalui inspeksi

REST masih merupakan pilihan yang lebih baik ketika:

• Anda membangun endpoint CRUD sederhana dengan payload yang dapat diprediksi dan datar
• Pengaturan cache HTTP sangat penting — permintaan POST GraphQL tidak dapat di-cache secara otomatis
• Tim Anda kecil dan permukaan API stabil — beban REST lebih rendah
• Anda menghadapi masalah N+1 dan tidak ingin mengatur DataLoader untuk memperbaikinya

Masalah N+1 perlu ditunda. Dalam resolver GraphQL yang mengambil posts dan setiap post's author, implementasi yang tidak canggih memicu satu query database per post untuk mengambil penulis. Dengan 50 post, itu berarti 51 query untuk satu permintaan. REST tidak mengalami masalah ini karena Anda mengontrol tepat apa SQL yang dijalankan per endpoint. Dalam GraphQL, Anda memperbaikinya dengan pembatching (DataLoader atau setara) — ini dapat diperbaiki, tetapi ini adalah satu lagi hal yang harus diatur dengan benar.

Format dan Validasi SDL Anda

File skema terkumpul dengan indentasi tidak konsisten, jarak spasi yang tidak cocok, dan pergeseran struktur saat tim tumbuh. Sebelum mengonfirmasi perubahan skema, jalankan melalui formatter untuk menormalisasi spasi, mengurutkan field, dan menangkap kesalahan sintaks sebelum mereka mencapai CI.

Itu Pemformat Skema GraphQL on iotools.cloud melakukan persis ini — salin SDL Anda, dapatkan output bersih dan terformat secara konsisten dengan kesalahan validasi yang ditampilkan secara langsung. Ini menangani skema multi-tipe, skalar khusus, direktif, dan kasus-kasus yang membingungkan saat format manual. Sangat berguna sebagai pengecekan akhir sebelum mengonfirmasi atau berbagi skema dengan tim lain.

Anda mungkin juga menyukai