105 Cara Mengatur gqlgen.yml untuk Kustomisasi

Golang telah lama jadi primadona backend berkat performanya yang kencang dan ekosistem tooling-nya yang terus berkembang. Salah satunya, untuk membuat GraphQL server di Go, kita punya gqlgen — framework yang powerful dan banyak digunakan. Tapi tahukah kamu, kekuatan sebenarnya dari gqlgen justru ada dalam file konfigurasinya, gqlgen.yml?

Pada artikel ini, saya akan membedah 105 cara untuk mengatur gqlgen.yml, mulai dari yang paling esensial sampai hacky tweaks untuk production-ready GraphQL API-mu. Lengkap dengan contoh kode, mini-simulasi, hingga diagram flow dengan Mermaid. Siap? Mari kita eksplorasi gqlgen.yml seperti engineer profesional!

Apa Itu gqlgen.yml?

Sebelum ke 105 customizations, kita refresh dulu apa itu file config ini:

• letak: biasanya di root project.
• fungsi: mendefinisikan schema path, tempat resolver, mapping type, hooks, plugins, dan berbagai tweak lain.

Contoh paling dasar gqlgen.yml:

# gqlgen.yml
schema:
  - graph/schema.graphqls

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

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

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

Mengatur schema dan Directory Structure

Cara #1-#5

1. Schema Path Tunggal
   Langsung tunjuk file master schema:

   schema:
     - graph/schema.graphqls
   

2. Multiple Schema Files
   Pisah per modul/microservice:

   schema:
     - graph/user/schema.graphqls
     - graph/product/schema.graphqls
   

3. Globbing Schema Files
   Otomasi load seluruh schema di folder:

   schema:
     - "graph/**/*.graphqls"
   

4. Schema dengan Preprocessing
   Bisa diubah manual sebelum generate.

5. Versioning Schema
   Pisahkan per versi jika API-mu versioned.

Custom File dan Package Output

Cara #6-#15

Kamu juga bisa custom package name agar lebih idiomatic.

exec:
  filename: internal/graph/gen.go
  package: graphgen

model:
  filename: internal/graph/model.go
  package: graphmodel

Type Mapping (models dan bindings)

Cara #16-#25

Ini bagian paling powerful!

Mapping Tipe GraphQL ke Struct Go

Misal, schema:

scalar DateTime
type User {
  id: ID!
  createdAt: DateTime!
}

Mappingnya:

models:
  DateTime:
    model:
      - github.com/yourapp/pkg/datetime.Time

Beberapa opsi mapping:

• model: ganti type yang digunakan
• bind: map ke type yang diimport saat scan input
• field: mapping per field

Opsional: Kamu juga bisa set kustom untuk array/matrix type.

Custom Unmarshal/Marshal untuk Scalar

Cara #26-#30

Default scalar hanya diproses otomatis. Untuk scalar custom, wajib buat Marshaller-Unmarshaller.

Misal mapping ke time.Time:

models:
  DateTime:
    model: time.Time
    marshal: github.com/yourapp/pkg/datetime.MarshalDateTime
    unmarshal: github.com/yourapp/pkg/datetime.UnmarshalDateTime

Menentukan Resolver Layouts

Cara #31-#35

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

Opsi layout:

• follow-schema: Per-type per-file (paling populer)
• single-file: Semua resolver dalam satu file
• custom: Path bebas yang kamu tentukan sendiri

Memakai Plugin Custom

Cara #36-#40

gqlgen mendukung plugin third-party untuk enhance kode yang dihasilkan:
Misalnya, plugin untuk open-tracing, error-wrapping, atau codegen yang kompatibel GraphQL Federation.

plugins:
  - name: github.com/99designs/gqlgen/plugin/federation

Scalar dan Directive Hooks

Cara #41-#55

Tambahkan hooks custom saat proses parsing:

directives:
  upper:
    implementation: github.com/yourapp/graph/directives.UpperCase
    location: FIELD_DEFINITION

Custom scalar hooks juga bisa tambahkan validator atau sanitizer ke custom scalar.

Tag Struct kustom (JSON/DB/CustomTag)

Cara #56-#65

Kadang, field pada GraphQL butuh tag struct berbeda di Go.
Tambahkan mapping tag lewat config:

# Membuat custom tag JSON
models:
  User:
    fields:
      email:
        tag: json:"email,omitempty" db:"email_column"

Tag Yang Sama untuk Semua Model

Cara #66-#69

struct_tag: json

atau:

struct_tag: json,db

Generate Interfaces

Cara #70-#75

Untuk schema Polymorphic, gunakan mapping ke Go interface:

models:
  Animal:
    model: github.com/yourapp/graph/model.Animal

Opsi Kustom Null

Cara #76-#80

Default gqlgen pakai pointer *T untuk nullables. Bisa diubah ke null.String, dsb:

models:
  String:
    model: github.com/guregu/null.String

Field Mapping ke Field Berbeda

Cara #81-#90

Misal schema:

type Product {
  id: ID!
  productName: String!
}

Struct Go berbeda nama field:

type Product struct {
  ID          string
  NameOfProduct string
}

Konfigurasikan mapping-nya:

models:
  Product:
    fields:
      productName:
        resolver: true
        goField: NameOfProduct

Disable/Enable Output Artifacts

Cara #91-#95

Atur artifact apa saja yang di-generate lewat flag/konfigurasi file:

omit_getters: true
omit_resolver_interface: false

Enable Resolver Methods Only

Cara #96-#99

Mengurangi kode, generate hanya bagian resolver:

resolver:
  only: true

Testing: Generate Mock

Cara #100-#102

Gqlgen bisa generate mock untuk resolver, sangat handy saat unit test!

generate:
  mocks: true

Environment dan Path Relatif

Cara #103-#104

Bisa pakai env var (misal saat CI/CD):

schema:
  - ${SCHEMA_PATH}

Watch Mode Auto Reload

Cara #105

Aktifkan live watch untuk ui atau service development:

gqlgen generate --watch

Simulasi — Pipeline Codegen

Di bawah, contoh flow codegen dengan diagram Mermaid:

flowchart TD
    A[Update gqlgen.yml]
    B[Schema diubah]
    C[Run gqlgen generate]
    D[Generated Go Code Update]
    A-->C
    B-->C
    C-->D

Rangkuman

Seperti yang kamu bisa lihat, gqlgen.yml bukan cuma file template biasa.
Dari mapping custom type, scalar, plugins, rapid testing, hingga custom kode layout, semuanya dibikin flexible.

Dengan 105 metode di atas, kamu bisa kustomisasi GraphQL API-mu sesuai kebutuhan perusahaan, skala, bahkan cara kerja timmu sendiri. Jangan ragu eksperimen — dan eksplorasi lebih lanjut lewat dokumentasi.
Jika ada tips kustomisasi yang belum saya bahas, share di kolom komentar ya!

Menulis config dengan benar = menghasilkan kode backend yang bersih, terstruktur, dan hemat waktu.
#HappyCoding! 🚀

Referensi

• gqlgen Configuration Reference
• GraphQL Official Spec
• Go Documentation