GraphQL Bergaya: Bahasa Rahasia di Balik Query dan Skema yang Rapi

Dalam satu kalimat

Memformat GraphQL adalah seni menerapkan aturan gaya yang konsisten pada query, mutasi, dan skema, mengubah tumpukan kurung kurawal dan field yang berantakan menjadi sebuah mahakarya yang mudah dibaca dan dirawat.

Problem yang diselesaikan

Zaman dulu, kalau kamu mau ambil data dari server untuk aplikasi web barumu yang keren, kemungkinan besar kamu bakal pakai REST API. Kamu akan minta data pengguna dari endpoint seperti /users/123, dan postingan mereka dari /users/123/posts. Masalahnya? Kamu bisa jadi dapat data pengguna yang jauh lebih banyak dari yang kamu butuhkan (over-fetching), atau kamu harus bolak-balik beberapa kali untuk mendapatkan semua data yang memang kamu butuhkan (under-fetching).

Masuklah GraphQL, sebuah bahasa query untuk API yang dikembangkan oleh Facebook. GraphQL membalikkan keadaan. Alih-alih server yang menentukan data apa yang harus dikirim, client lah yang meminta persis apa yang dibutuhkannya, semuanya dalam satu permintaan. Ibaratnya seperti pesan a la carte, bukan dapat menu paket yang sudah ditentukan.

# Kasih aku nama user 42 dan judul dari 3 post pertamanya aja
query GetUserNameAndPosts {
  user(id: "42") {
    name
    posts(first: 3) {
      title
    }
  }
}

Ini adalah sebuah revolusi. Tapi, ini juga memunculkan masalah baru yang skalanya lebih kecil. Query GraphQL, dengan kurung kurawal bersarangnya, bisa jadi kompleks. Kompleks banget. Tanpa aturan apa pun, query yang ditulis oleh satu developer mungkin terlihat seperti satu baris teks panjang yang tidak terbaca. Developer lain mungkin menulis query yang sama dengan gaya indentasi yang sama sekali berbeda.

Saat kamu mencoba men-debug masalah jam 2 pagi atau saat anggota tim baru mencoba memahami struktur API-mu, inkonsistensi ini adalah mimpi buruk. Kode adalah komunikasi, dan GraphQL yang tidak diformat itu seperti mencoba membaca buku tanpa paragraf, tanda baca, atau font yang konsisten. Pemformatan memaksakan tata bahasa bersama, membuat maksud kode langsung lebih jelas bagi setiap manusia yang membacanya.

Cara kerjanya di balik layar

Sebuah GraphQL formatter tidak sekadar melakukan find-and-replace canggih. Ini adalah proses rumit yang melibatkan pemahaman struktur kode, penerapan seperangkat aturan, dan kemudian membangun kembali kode dari awal dengan cara yang indah dan dapat diprediksi.

Parsing: Dari Teks Menjadi Pohon (Tree)

Pertama, formatter harus membaca string mentah kode GraphQL dan memahami apa isinya. Ia tidak bisa hanya mencari { dan menambahkan baris baru. Ia perlu tahu apakah kurung kurawal itu membuka sebuah query, definisi tipe, atau objek input.

Proses ini disebut parsing. Formatter melakukan tokenisasi input (memecahnya menjadi potongan-potongan yang bermakna seperti query, user, (, id, :, "42", )), lalu membangun sebuah Abstract Syntax Tree (AST). AST adalah struktur data seperti pohon yang merepresentasikan struktur gramatikal dari kode tersebut.

Untuk query sederhana:

query { user { name } }

AST-nya mungkin terlihat seperti ini (secara konseptual dan disederhanakan):

- Document
  - Definition (OperationDefinition, type: query)
    - SelectionSet
      - Selection (Field)
        - name: "user"
        - SelectionSet
          - Selection (Field)
            - name: "name"

Teks tersebut bukan lagi sekadar teks; ia adalah objek terstruktur yang dapat dimanipulasi secara cerdas oleh program.

Aturan Main Soal Gaya

Setelah formatter memiliki AST, ia dapat menelusuri pohon tersebut dan menerapkan aturan gayanya. Aturan-aturan inilah inti dari pemformatan dan sering menjadi subjek debat kusir (yang kebanyakan sia-sia) di kalangan developer. Aturan umum meliputi:

Indentasi: Berapa banyak spasi (atau tab, kalau kamu memang monster) yang digunakan untuk setiap tingkat bersarang. Standar yang hampir universal adalah 2 spasi.
Pindah Baris (Line Breaks): Kapan harus menempatkan sesuatu di baris baru. Haruskah kurung kurawal pembuka { berada di baris yang sama dengan nama field atau di baris baru? (Kebanyakan formatter meletakkannya di baris yang sama.)
Spasi: Memastikan spasi yang konsisten di sekitar operator seperti titik dua dan di dalam tanda kurung.
Pengurutan Field: Untuk skema yang besar, beberapa formatter bahkan dapat mengurutkan field berdasarkan abjad agar lebih mudah ditemukan.

Tools seperti Prettier menjadi terkenal karena "opinionated"—mereka membuat pilihan ini untukmu, jadi kamu tidak perlu berdebat tentangnya. Tujuannya bukan untuk menemukan satu gaya "sempurna", tetapi untuk memilih satu gaya dan menerapkannya tanpa ampun.

Pretty-Printing: Dari Pohon (Tree) Kembali ke Teks

Setelah menerapkan aturan, tugas akhir formatter adalah mengambil AST yang telah dimodifikasi dan mengubahnya kembali menjadi string teks. Proses ini disebut pretty-printing. Formatter melintasi pohon, dan di setiap node (seperti Field atau SelectionSet), ia mencetak teks yang sesuai, menambahkan indentasi dan baris baru yang benar sesuai aturan.

Hasilnya adalah string GraphQL yang diformat dengan indah.

Konsep terkait adalah minifikasi atau pemadatan. Ini adalah kebalikan dari pretty-printing. Proses ini juga mem-parsing kode menjadi AST, tetapi kemudian mencetaknya kembali dengan semua spasi opsional dihilangkan. Ini menciptakan string satu baris yang padat, tidak terbaca oleh manusia tetapi sempurna untuk dikirim melalui jaringan, karena menghemat beberapa byte yang berharga.

Kisah dari dunia nyata

Kasus Sesi Debugging Tengah Malam

Jasmine, seorang backend engineer, sedang on-call. Pukul 1:30 pagi, sebuah peringatan berbunyi: mutasi GraphQL kritis gagal di produksi. Satu-satunya petunjuk adalah entri log yang berisi query persis yang dikirim oleh client—satu baris teks ngawur sepanjang 3000 karakter, hasil copy-paste dari bundel JavaScript yang sudah di-minify. Dia menatap dinding teks itu, ...customer{address{..., mencoba menemukan bagian yang salah. Matanya mulai nanar. Karena frustrasi, dia melemparkan seluruh string ke dalam GraphQL formatter. Seketika, query itu mekar menjadi struktur 70 baris yang terindentasi sempurna. Dan di sanalah, terlihat jelas di baris 47: salah ketik di nama field krusial, adress bukannya address. Perbaikannya sepele, tetapi dia bahkan tidak bisa melihat masalahnya sampai kode itu diformat.

Pelajaran: Keterbacaan adalah langkah pertama dan terpenting menuju kemudahan debugging. Formatter mengubah gumpalan teks yang tidak bisa ditembus menjadi sesuatu yang benar-benar dapat di-parse oleh manusia.

Pull Request yang Nggak Mau Di-merge

Sebuah tim kecil sedang membangun backend e-commerce baru dengan GraphQL. Dua developer, Liam dan Olivia, sedang mengerjakan sebuah fitur. Liam mengonfigurasi editornya untuk menggunakan indentasi 4 spasi. Olivia, penggemar indentasi 2 spasi, memiliki pengaturan yang berbeda. Ketika Liam mengirimkan pull request-nya, Olivia mereviewnya, membuat beberapa perubahan logika, dan mendorong commit-nya. "Diff" yang dihasilkan adalah lautan warna merah dan hijau. Hampir setiap baris ditandai sebagai berubah, hanya karena editor mereka bertengkar soal spasi. Perubahan yang sebenarnya dan bermakna benar-benar hilang dalam kebisingan itu. Tech lead harus menghabiskan satu jam untuk mengurai kekacauan itu. Keesokan harinya, dia menambahkan GraphQL formatter otomatis ke pre-commit hook mereka. Sekarang, semua kode diformat dengan standar yang sama persis sebelum di-commit.

Pelajaran: Pemformatan otomatis menghilangkan perdebatan gaya dan menjaga riwayat version control tetap bersih, memfokuskan review pada hal yang penting: logika.

Skema yang Mirip Spaghetti

Skema GraphQL sebuah startup telah tumbuh secara organik selama tiga tahun. Tipe data ditambahkan di mana saja, field tidak dalam urutan tertentu, dan komentar jarang ada. Bagi karyawan baru, mencoba memahami model data API itu seperti mencoba mengurai laci penuh kabel tua yang kusut. Mereka memutuskan untuk melakukan eksperimen: mereka memasukkan seluruh file schema.graphql ke dalam formatter. Alat itu tidak hanya mengindentasi semuanya dengan benar tetapi juga mengurutkan semua field di dalam setiap tipe berdasarkan abjad. Tiba-tiba, id selalu menjadi field pertama. Field yang sudah usang dikelompokkan bersama. Seluruh struktur menjadi fokus. Itu bukan hanya lebih cantik; sekarang menjadi bagian dokumentasi yang berguna.

Pelajaran: Skema yang diformat dengan baik berfungsi sebagai dokumentasi hidup. Ini mengungkapkan struktur dan tujuan API Anda, membuatnya lebih mudah didekati oleh semua orang.

Kesalahan dan jebakan umum

Debat soal gaya penulisan. Jebakan terbesar adalah membuang-buang waktu berdebat soal tab vs. spasi atau di mana kurung kurawal seharusnya diletakkan. Nilai dari pemformatan adalah konsistensi. Pilih tool yang populer dan opinionated seperti Prettier, setuju untuk menggunakannya, dan lanjutkan hidup.
Lupa memformat sebelum commit. Jika pemformatan adalah proses manual, orang akan lupa. Ini mengarah pada diff yang berantakan yang ingin kamu hindari. Integrasikan pemformatan ke dalam pre-commit hook (menggunakan tool seperti Husky dan lint-staged) untuk membuatnya otomatis dan tanpa usaha.
Mencampuradukkan formatting dengan linting. Formatter membuat kodemu terlihat konsisten. Linter (seperti eslint-plugin-graphql) memeriksa kodemu untuk potensi bug atau praktik buruk, seperti menggunakan field yang sudah usang atau menulis query yang tidak efisien. Kamu butuh keduanya. Formatter membersihkan dapur; linter mengecek apakah kompornya lupa kamu matikan.
Memformat kode yang di-generate. Beberapa alur kerja men-generate file skema atau query GraphQL dari sumber lain (seperti skema database atau bahasa pemrograman yang berbeda). Memformat output-nya seringkali sia-sia, karena perubahanmu akan ditimpa saat kode di-generate lagi. Formatlah sumber-nya.
Mengirim query cantik di production. Meskipun indentasi yang indah bagus untuk development, itu adalah byte yang terbuang sia-sia di jaringan. Proses build kamu harus melakukan minifikasi query GraphQL sebelum dikirim dari aplikasi client ke server.

Kenapa ini harus kamu perhatikan

Kamu harus mulai memikirkan format GraphQL sejak sebuah proyek melibatkan lebih dari satu orang, atau sejak query-mu menjadi lebih kompleks dari satu field bersarang.

Ini adalah alat dasar untuk pengembangan perangkat lunak profesional yang kebetulan berlaku sempurna untuk GraphQL. Ini bukan tentang membuat sesuatu menjadi "cantik" demi keindahan semata. Ini tentang:

Kejelasan: Membuat kode lebih mudah dibaca dan dipahami.
Kemudahan Perawatan (Maintainability): Membuat kode lebih mudah diubah dan di-debug.
Kolaborasi: Mengurangi gesekan antar anggota tim dengan mengotomatiskan pilihan gaya.

Jika kamu pernah mendapati dirimu menatap query GraphQL yang di-minify di file log, atau berdebat dengan rekan setim tentang indentasi, itu pertanda kamu membutuhkan formatter otomatis dalam hidupmu.

Pelajari lebih dalam

GraphQL Specification - Sumber resmi dan kanonis untuk bahasa GraphQL itu sendiri.
Prettier: GraphQL - Dokumentasi dukungan GraphQL untuk code formatter paling populer.
Exploring GraphQL APIs with Abstract Syntax Trees - Postingan keren dari Apollo tentang kekuatan AST.
GraphQL on Wikipedia - Untuk gambaran tingkat tinggi dan sejarahnya.
ESLint Plugin for GraphQL - Selami lebih dalam tentang linting, pendamping kuat untuk formatting.