104 Struktur File gqlgen dan Cara Kerjanya

Jika Anda pernah membangun backend GraphQL di Golang, pasti tidak asing dengan gqlgen. Library ini menawarkan generator schema first untuk GraphQL dengan workflow yang strongly typed dan terintegrasi langsung dengan idiom Go. Artikel ini akan membedah struktur file standar pada projek gqlgen, mekanisme kerja tiap komponennya, serta contoh dan simulasi request sederhana. Mari kita mulai dengan pemahaman fondasi gqlgen.

Mengapa gqlgen?

Gqlgen menyederhanakan proses membangun API GraphQL di Golang dengan schema-first workflow. Anda merancang schema terlebih dahulu, lalu gqlgen secara otomatis mengenerate kode stub, sehingga Anda bisa fokus pada logika business.

Workflow Schema-First secara Singkat

1. Buat schema GraphQL (*.graphql).
2. Jalankan go run github.com/99designs/gqlgen generate.
3. Implementasikan resolver yang di-stub oleh gqlgen.
4. Jalankan server, dan mulai develop API GraphQL secara robust.

Struktur File Gqlgen

Mari kita lihat struktur file projek gqlgen tipikal, lalu kita bedah satu persatu fungsinya.

.
├── go.mod
├── go.sum
├── gqlgen.yml
├── graph/
│   ├── generated/
│   │   ├── generated.go
│   │   └── models_gen.go
│   ├── model/
│   │   └── models.go
│   ├── resolver.go
│   ├── schema.graphqls
│   └── schema.resolvers.go
├── server.go
└── README.md

Penjelasan Struktur

Diagram Alur Kerja gqlgen

Untuk memahami integrasi antar file dan workflow request GraphQL, mari visualisasikan dengan diagram mermaid berikut:

flowchart TD
    A[Client] -->|Query/Mutation| B[HTTP Endpoint /graphql]
    B --> C[Server.go]
    C --> D[gqlgen Handler]
    D --> E[Generated Code (graph/generated)]
    E --> F[Resolver.go]
    F --> G[Business Logic di schema.resolvers.go / model/]
    G --> H[Data Source (DB/API)]
    H --> G
    G --> F
    F --> E
    E --> D
    D --> C
    C --> B
    B --> A

Deskripsi:
Client mengirim permintaan Query/Mutation ke endpoint /graphql, yang ditangani server dan diteruskan ke handler gqlgen. Handler ini memanfaatkan generated code untuk melakukan verifikasi dan pemetaan ke resolver yang sudah diimplementasikan. Resolver mengeksekusi logika bisnis dan mengambil/mengubah data dari data source sebelum mengembalikan response ke client.

1. Definisi Schema: schema.graphqls

File ini adalah pondasi utama. Semua entrypoint GraphQL, type, input, bahkan directive, ditulis di sini.

Contoh:

# graph/schema.graphqls

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

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

type User {
  id: ID!
  name: String!
  email: String!
}

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

2. Model Go: model/models.go

Optional – Anda dapat menyesuaikan model Go Anda sendiri agar terintegrasi dengan kode idiomatis Go. Jika model tidak ada, gqlgen akan mengenerate otomatis pada generated/models_gen.go.

// graph/model/models.go
package model

type User struct {
    ID    string `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

3. Konfigurasi gqlgen: gqlgen.yml

File ini menentukan referensi schema, output generate code, mapping model, dan lain-lain.

Contoh:

schema:
  - graph/schema.graphqls

exec:
  filename: graph/generated/generated.go
  package: generated

model:
  filename: graph/model/models.go
  package: model

resolver:
  layout: follow-schema
  dir: graph
  package: graph

models:
  User:
    model: graph/model.User
  NewUser:
    model: graph/model.NewUser

4. Generated Code: graph/generated/

Jangan modifikasi isi folder ini. Semua file di-generate setiap kali menjalankan gqlgen generate.
Di dalam sini terjadi binding antara GraphQL operation dan resolver Go, serta type-safety di compile time.

5. Resolver: graph/resolver.go & schema.resolvers.go

resolver.go berisi struct utama Resolver — biasanya diinject dependency (DB access, cache, dsb).

type Resolver struct{
    users []*model.User
}

Sementara, schema.resolvers.go adalah implementasi tiap resolver (otomatis maupun manual).

Contoh Resolver Sederhana:

func (r *queryResolver) Users(ctx context.Context) ([]*model.User, error) {
    return r.users, nil
}

func (r *mutationResolver) CreateUser(ctx context.Context, input model.NewUser) (*model.User, error) {
    user := &model.User{
        ID: fmt.Sprintf("%d", len(r.users)+1),
        Name: input.Name,
        Email: input.Email,
    }
    r.users = append(r.users, user)
    return user, nil
}

6. Server Entrypoint: server.go

Inisialisasi dan menjalankan GraphQL HTTP handler.

Contoh:

func main() {
    srv := handler.NewDefaultServer(generated.NewExecutableSchema(generated.Config{Resolvers: &graph.Resolver{users: []*model.User{}}}))
    http.Handle("/graphql", srv)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

Simulasi Request-Response

Misal: Create user baru di playground/batch GraphQL.

Request:

mutation {
  createUser(input: {name: "Alice", email: "alice@example.com"}) {
    id
    name
    email
  }
}

Response:

{
  "data": {
    "createUser": {
      "id": "1",
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}

Tips Praktis

• Jangan edit file di folder /generated, selalu modifikasi kode di /model dan resolver.
• Jalankan go run github.com/99designs/gqlgen generate setiap kali mengubah schema.
• Bagi resolver di beberapa file jika query/mutation semakin banyak.
• Manfaatkan dependency injection pada struct Resolver agar logic tidak tercampur.
• Gunakan tool seperti GraphQL Playground untuk testing.

Ringkasan

gqlgen mendesain struktur proyek yang sangat Go idiomatis & terpisah rapi:

• Schema -> Central contract API yang langsung di-generate ke Go code stub.
• Models -> Dapat dikustomisasi.
• Resolvers -> Letak logika utama.
• Generated Code -> “Jembatan” antara GraphQL dan Go, Anda tidak perlu sentuh.

Clusterisasi struktur file gqlgen ini membantu project tetap scalable dan maintainable. Anda pun tetap mendapatkan kepastian type safety dan kemudahan develop API GraphQL di ekosistem Go.

Selamat bereksplorasi dengan gqlgen—dengan arsitektur file yang padu seperti ini, membangun backend GraphQL Go tidak pernah semenyenangkan dan seaman ini! 🚀