106 Menulis Skema .graphqls untuk gqlgen: Panduan Praktis

Menggunakan gqlgen untuk membangun API GraphQL di lingkungan Go tidak hanya memberikan kinerja tinggi dan fleksibilitas, tetapi juga mendekatkan kita pada pola-pola best practice dalam arsitektur modern. Salah satu pondasi utama ketika menggunakan gqlgen adalah menulis skema GraphQL (.graphqls). Artikel ini memandu Anda tahap demi tahap dalam mendesain file .graphqls yang robust, scalable, dan dioptimalkan untuk pengembangan berkelanjutan.

Apa Itu Skema .graphqls?

File .graphqls adalah tempat kita mendefinisikan bentuk data, query, mutation, relationship, dan aturan-aturan terkait API. Secara analogi, .graphqls adalah “kontrak” antara frontend dan backend — mendefinisikan tipe data, endpoint query, mutation, hingga subscription.

Menggunakan file .graphqls berarti menjadi schema-first developer. Anda mendesain API layer sebelum berinteraksi dengan logika bisnis atau database.

Anatomy Dasar .graphqls

Mari kita mulai dengan skema sederhana yang bisa kita gunakan sebagai referensi.

# schema.graphqls

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

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
}

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

Penjelasan:

• Kita mendefinisikan dua tipe utama (User dan Post) beserta relationship-nya.
• Ada tipe Query yang mendefinisikan endpoint/output yang dapat diambil oleh klien.

Extended: Menambah Mutasi dan Enum

GraphQL tidak hanya sekadar membaca data, tetapi juga memungkinkan modifikasi data melalui mutation, serta tipe data khusus seperti Enum.

enum Role {
  ADMIN
  USER
  GUEST
}

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

type Mutation {
  createUser(name: String!, email: String!, role: Role!): User!
  createPost(title: String!, content: String!, authorId: ID!): Post!
}

Simulasi Query:

mutation {
  createUser(name: "Bob", email: "bob@example.com", role: ADMIN) {
    id
    name
  }
}

Bagaimana gqlgen Menggunakan Skema .graphqls?

Jika Anda menjalankan perintah go run github.com/99designs/gqlgen generate, gqlgen akan:

1. Membaca semua file .graphqls
2. Membuat mapping struktur Go berdasarkan tipe-tipe di skema
3. Menghasilkan scaffolding resolver yang harus Anda implementasikan (untuk Query, Mutation, dsb.)

Diagram Alur (Mermaid)

graph TD
    A[Start] --> B[Edit schema.graphqls]
    B --> C[gqlgen generate]
    C --> D[Generate types.go & resolvers.go]
    D --> E[Implement resolver logic]
    E --> F[API Siap Digunakan]

Taktik Modularisasi Skema

Dalam tim besar atau aplikasi kompleks, pemecahan file .graphqls sangat membantu manajemen. Misalnya:

Folder Anda akan terlihat seperti:

- graph/
    - schema.graphqls
    - user.graphqls
    - post.graphqls

Gqlgen akan otomatis menggabungkan semua file .graphqls di folder yang sama.

Best Practices Menulis Skema

1. Gunakan Scalar yang Tepat:
   Jangan asal gunakan String untuk semua tipe data. Gunakan Int, Float, Boolean, dan custom scalar seperti DateTime.

2. Dokumentasikan Setiap Field:
   Komentar baris dengan """ untuk memberikan intellisense pada tools seperti GraphQL Playground.

   """
   Tipe ini mewakili artikel blog post pengguna.
   """
   type Post {
     title: String!
     ...
   }
   

3. Gunakan Enum bila Tipe Terbatas:
   Hindari typo dan validasi manual dengan enum pada tipe seperti status, role, dsb.

4. Modular & DRY:
   Ekstrak input type dan payload bila query/mutation Anda mulai kompleks.

   input CreatePostInput {
     title: String!
     content: String!
     authorId: ID!
   }
   
   type Mutation {
     createPost(input: CreatePostInput!): Post!
   }
   

5. Backward Compatibility:
   Status GraphQL breaking change-nya adalah jika Anda menghapus field — selalu konsultasikan skema baru sebelum rilis.

Simulasi Kasus Nyata

Misalkan Anda membutuhkan fitur berikut di aplikasi:

• Melihat daftar user dan post (dengan relasi user ke post)
• Membuat user baru
• Membuat post baru untuk user tertentu

Skemanya bisa seperti ini:

# user.graphqls

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

input NewUserInput {
  name: String!
  email: String!
}

type Mutation {
  createUser(input: NewUserInput!): User!
}

# post.graphqls

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
}

input NewPostInput {
  title: String!
  content: String!
  authorId: ID!
}

type Mutation {
  createPost(input: NewPostInput!): Post!
}

Penutup

Skema .graphqls adalah blueprint utama dalam siklus hidup pengembangan API GraphQL dengan gqlgen. Dengan penulisan skema yang rapi, mendokumentasikan seluruh usecase bisnis, serta memanfaatkan modularisasi, Anda akan memudahkan proses scaling, maintenance, hingga handover antar engineer. Lebih dari sekadar file, skema .graphqls adalah jantung API contract Anda.

Jika ada tips atau skema favorit yang ingin Anda bagikan, silakan diskusikan di kolom komentar.
Happy coding, engineer! 🚀