102 Menyiapkan Proyek gqlgen Pertama Anda

Membangun aplikasi GraphQL yang efektif dari nol kini terasa semakin mudah berkat berbagai tool yang tersedia di ekosistem Go. Salah satu yang cukup populer dan powerful adalah gqlgen. Library ini menawarkan cara praktis, performatif, dan idiomatik untuk membangun API GraphQL di Golang. Dalam artikel ini, saya akan membimbing Anda—in the style of hands-on engineer—untuk menyiapkan proyek gqlgen pertama mulai dari inisialisasi hingga menjalankan query sederhana.

Kenapa gqlgen?

Tak perlu panjang lebar, berikut beberapa alasan utama saya memilih gqlgen:

• Type-safe. Schema GraphQL akan di-generate sebagai kode Go statis.
• Performance. Zero reflection, sehingga eksekusi lebih cepat.
• Extendable. Bisa disesuaikan sesuai kebutuhan bisnis Anda.

Prasyarat

Pastikan Anda sudah menginstal:

• Go 1.18+
• Git (untuk versioning dan clone repo library)
• Node.js dan npm hanya jika ingin playground GUI, opsional

Step 1: Bootstrapping Proyek

Mulai dari level paling dasar. Buat folder proyek dan inisialisasi modul Go.

$ mkdir gqlgen-demo
$ cd gqlgen-demo
$ go mod init github.com/username/gqlgen-demo

Lalu, install gqlgen:

$ go get github.com/99designs/gqlgen

Step 2: Create Schema GraphQL

Seperti best-practice pada GraphQL, kita mulai dengan mendefinisikan schema (.graphqls). Buat folder graph dan file schema:

$ mkdir graph
$ touch graph/schema.graphqls

Contoh schema sederhana:

# graph/schema.graphqls
type Query {
    hello: String!
    todos: [Todo!]!
}

type Todo {
    id: ID!
    text: String!
    done: Boolean!
}

Step 3: Generate Boilerplate gqlgen

Agar tidak menulis kode struct dan resolver manual, kita pakai codegen dari gqlgen.

$ go run github.com/99designs/gqlgen generate

Perintah di atas menghasilkan beberapa file otomatis (:rocket:), contoh:

• graph/model/models_gen.go: struct berdasarkan schema
• graph/schema.resolvers.go: resolver stub, area logic bisnis kita
• gqlgen.yml: config generator

Struktur direktori:

gqlgen-demo/
  ├── go.mod
  ├── gqlgen.yml
  └── graph/
      ├── model/
      │   └── models_gen.go
      ├── schema.graphqls
      └── schema.resolvers.go

Step 4: Implement Resolver

Mari kita isi logic untuk resolver yang tadi sudah di-generate. Dua buah resolver: Query.hello dan Query.todos.

// graph/schema.resolvers.go
package graph

import (
    "context"
    "github.com/username/gqlgen-demo/graph/model"
)

var todos = []*model.Todo{
    {ID: "1", Text: "Belajar gqlgen", Done: false},
    {ID: "2", Text: "Implementasi GraphQL", Done: true},
}

func (r *queryResolver) Hello(ctx context.Context) (string, error) {
    return "Halo developer!", nil
}

func (r *queryResolver) Todos(ctx context.Context) ([]*model.Todo, error) {
    return todos, nil
}

Jika Anda perhatikan, jenis struct dan fungsi resolver sudah auto-generate. Kemudian, logic aslinya mudah diisi sesuai spesifikasi Anda.

Step 5: Setup Entry Point (main.go)

Kita butuh server HTTP untuk expose API GraphQL. Gunakan net/http dan handler graph.NewExecutableSchema.

package main

import (
    "log"
    "net/http"
    "github.com/99designs/gqlgen/graphql/handler"
    "github.com/99designs/gqlgen/graphql/playground"
    "github.com/username/gqlgen-demo/graph"
    "github.com/username/gqlgen-demo/graph/generated"
)

func main() {
    srv := handler.NewDefaultServer(generated.NewExecutableSchema(generated.Config{Resolvers: &graph.Resolver{}}))

    http.Handle("/", playground.Handler("GraphQL playground", "/query"))
    http.Handle("/query", srv)

    log.Println("connect to http://localhost:8080/ for GraphQL playground")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Step 6: Run & Uji Query

Jalankan server:

$ go run .

Buka http://localhost:8080 pada browser. Anda akan melihat playground antarmuka Query GUI. Sekarang jalankan query berikut:

query {
  hello
  todos {
    id
    text
    done
  }
}

Hasilnya seharusnya seperti berikut:

{
  "data": {
    "hello": "Halo developer!",
    "todos": [
      {
        "id": "1",
        "text": "Belajar gqlgen",
        "done": false
      },
      {
        "id": "2",
        "text": "Implementasi GraphQL",
        "done": true
      }
    ]
  }
}

Diagram Alur request GraphQL (Mermaid)

Mari visualisasikan bagaimana request diproses dari client ke resolver:

sequenceDiagram
    participant Client
    participant Server
    participant Resolver

    Client->>Server: Kirim GraphQL Query
    Server->>Resolver: Delegasi ke resolver (misal: Query.todos)
    Resolver-->>Server: Return hasil data
    Server-->>Client: Kirim response JSON

Tabel: Perbandingan gqlgen vs Library GraphQL lain di Go

Troubleshooting & Best Practices

• Perubahan schema
  Setelah mengubah schema.graphqls, jangan lupa regenerate:

  $ go run github.com/99designs/gqlgen generate
  

• Protobuf/Custom Model
  Anda bisa mapping custom model (misal, dari Protobuf/Ent).

• Scaffolding
  Untuk proyek baru, gunakan juga CLI init:

  $ go run github.com/99designs/gqlgen init
  

Penutup

Dengan mengikuti langkah-langkah sederhana di atas, Anda telah berhasil menyiapkan proyek gqlgen pertama Anda, siap sebagai fondasi sistem GraphQL production-grade di Go.
Setelah paham dasar-dasarnya, Anda bisa eksplorasi fitur lanjut seperti middleware, pagination, subscriptions, integration ke DB, dan testing resolver.

Bagaimana pengalaman Anda menggunakan gqlgen? Jika ada kendala atau insight, silakan share di kolom komentar. Selamat mencoba, happy hacking! 🚀

Referensi:

• gqlgen Official Documentation
• GraphQL Specification