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.

 1# schema.graphqls
 2
 3type User {
 4  id: ID!
 5  name: String!
 6  email: String!
 7  posts: [Post!]!
 8}
 9
10type Post {
11  id: ID!
12  title: String!
13  content: String!
14  author: User!
15}
16
17type Query {
18  users: [User!]!
19  posts: [Post!]!
20  user(id: ID!): User
21  post(id: ID!): Post
22}

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.

 1enum Role {
 2  ADMIN
 3  USER
 4  GUEST
 5}
 6
 7type User {
 8  id: ID!
 9  name: String!
10  email: String!
11  role: Role!
12  posts: [Post!]!
13}
14
15type Mutation {
16  createUser(name: String!, email: String!, role: Role!): User!
17  createPost(title: String!, content: String!, authorId: ID!): Post!
18}

1mutation {
2  createUser(name: "Bob", email: "bob@example.com", role: ADMIN) {
3    id
4    name
5  }
6}

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]

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:

1- graph/
2    - schema.graphqls
3    - user.graphqls
4    - 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.

   graphql

   Salin

   1"""
   2Tipe ini mewakili artikel blog post pengguna.
   3"""
   4type Post {
   5  title: String!
   6  ...
   7}

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.

   graphql

   Salin

   1input CreatePostInput {
   2  title: String!
   3  content: String!
   4  authorId: ID!
   5}
   6
   7type Mutation {
   8  createPost(input: CreatePostInput!): Post!
   9}

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:

 1# user.graphqls
 2
 3type User {
 4  id: ID!
 5  name: String!
 6  email: String!
 7  posts: [Post!]!
 8}
 9
10input NewUserInput {
11  name: String!
12  email: String!
13}
14
15type Mutation {
16  createUser(input: NewUserInput!): User!
17}

 1# post.graphqls
 2
 3type Post {
 4  id: ID!
 5  title: String!
 6  content: String!
 7  author: User!
 8}
 9
10input NewPostInput {
11  title: String!
12  content: String!
13  authorId: ID!
14}
15
16type Mutation {
17  createPost(input: NewPostInput!): Post!
18}

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! 🚀