Pengenalan dan Tujuan Artikel

Go Fiber v3 masih menjadi pilihan populer untuk membangun API yang cepat, ringan, dan mudah diskalakan. Artikel ini menjelaskan langkah demi langkah memulai dari nol, mulai dari setup project dan struktur folder yang terorganisir hingga routing modern, middleware inti, serta perhatian saat migrasi dari versi sebelumnya. Fokusnya adalah praktik nyata yang bisa langsung diterapkan oleh tim engineering.

Kita juga akan membahas konfigurasi environment, handler error, validasi request dasar, serta contoh API minimal yang siap dikembangkan, sehingga Anda mendapatkan panduan komprehensif untuk memulai aplikasi backend yang terstruktur.

1. Setup Proyek Go Fiber v3 dari Nol

Inisialisasi modul dan instalasi dependensi

Langkah pertama adalah membuat direktori proyek lalu inisialisasi go.mod. Pastikan menggunakan Go versi yang kompatibel (Go 1.21+ disarankan untuk berjalan dengan baik). Berikut perintah dasar:

mkdir myfiberapp && cd myfiberapp
go mod init github.com/organisasi/myfiberapp
go get github.com/gofiber/fiber/v3
go get github.com/gofiber/fiber/v3/middleware/logger
go get github.com/gofiber/fiber/v3/middleware/recover

Pendekatan ini memastikan semua middleware inti tersedia sejak awal. Fiber v3 tetap menggunakan path modul github.com/gofiber/fiber/v3, jadi pastikan modul versi 3 direferensikan secara eksplisit.

Struktur folder awal

Organisasi folder memengaruhi kemudahan pengembangan dan pemeliharaan. Struktur minimal berikut cukup modular untuk tim kecil sampai menengah:

myfiberapp/
├── cmd/
│   └── server/
│       └── main.go
├── internal/
│   ├── config/
│   │   └── config.go
│   ├── handler/
│   │   └── user.go
│   ├── router/
│   │   └── router.go
│   ├── middleware/
│   │   └── mw.go
│   └── service/
│       └── user.go
├── pkg/
│   └── response/
│       └── response.go
└── .env

Klasifikasi internal menjaga kode hanya bisa digunakan dalam modul utama. Tempatkan konfigurasi, middleware, dan handler di folder terpisah agar setiap lapisan punya tanggung jawab jelas.

2. Struktur dan Konfigurasi Dasar

Konfigurasi environment

Gunakan file .env plus pembacaan memakai paket seperti github.com/joho/godotenv atau envconfig. Contoh file:

APP_PORT=8080
APP_ENV=development
LOG_LEVEL=debug

Di internal/config/config.go buat loader yang validasi nilai default dan fallback bila tidak diset:

package config

import (
    "log"
    "os"
)

type Config struct {
    Port string
}

func Load() Config {
    if port := os.Getenv("APP_PORT"); port != "" {
        return Config{Port: port}
    }
    log.Println("APP_PORT tidak diset, menggunakan 8080")
    return Config{Port: "8080"}
}

Teknik ini memungkinkan pengujian lokal dan lingkungan produksi memakai nilai yang berbeda tanpa mengubah kode.

App fiber dengan konfigurasi eksplisit

Fiber menerima konfigurasi saat inisialisasi. Gunakan opsi seperti Prefork, DisableStartupMessage, atau AppName jika diperlukan. Contoh:

func NewApp() *fiber.App {
    cfg := fiber.Config{
        AppName:               "myfiberapp",
        DisableStartupMessage: true,
        BodyLimit:             4 * 1024 * 1024,
    }
    app := fiber.New(cfg)
    app.Use(recover.New())
    app.Use(logger.New(logger.Config{Format: "${time} ${status} - ${method} ${path}\n"}))
    return app
}

Memasukkan middleware recovery dan logging di awal menjaga aplikasi tetap tahan terhadap panic dan mempermudah debugging.

3. Routing Modern dan Route Grouping

Grouping dengan tujuan modular

Fiber mendukung route grouping yang memudahkan pemisahan domain fungsional. Gunakan fiber.Group untuk memetakan versi API dan middleware spesifik:

func RegisterRoutes(app *fiber.App, handler *handler.UserHandler) {
    api := app.Group("/api")
    v1 := api.Group("/v1")
    v1.Group("/users", func(group fiber.Router) {
        group.Get("/", handler.List)
        group.Post("/", handler.Create)
    })
}

Dalam modul ini, handler memegang logika bisnis, sedangkan router hanya mengatur endpoint. Strategi ini memudahkan penambahan versi baru tanpa merusak rute lama.

Middleware per route

Selain middleware global, sering kali tiap grup memerlukan middleware tersendiri, misalnya autentikasi JWT atau rate limiter. Fiber memfasilitasi dengan method Use pada objek group.

Contoh: Anda bisa menambahkan middleware validasi header atau rate limit sebelum rute tertentu tidak perlu memeriksa secara manual di handler.

4. Contoh API Minimal Siap Dikembangkan

Berikut contoh handler dan response sederhana:

package handler

import (
    "github.com/gofiber/fiber/v3"
    "github.com/organisasi/myfiberapp/pkg/response"
)

type UserHandler struct{}

func (h *UserHandler) List(c *fiber.Ctx) error {
    users := []map[string]string{{"id": "1", "name": "Fiona"}}
    return c.Status(fiber.StatusOK).JSON(response.Success(users))
}

func (h *UserHandler) Create(c *fiber.Ctx) error {
    var payload struct { Name string `json:"name"` }
    if err := c.BodyParser(&payload); err != nil {
        return response.BadRequest(c, "Payload tidak valid", err)
    }
    if payload.Name == "" {
        return response.BadRequest(c, "Nama wajib diisi", nil)
    }
    created := map[string]string{"id": "2", "name": payload.Name}
    return c.Status(fiber.StatusCreated).JSON(response.Success(created))
}

Struktur response membantu menjaga format output konsisten untuk semua handler.

5. Praktik Terbaik: Environment Config, Error Handler, dan Validasi

Konfigurasi environment yang aman

Gunakan paket seperti godotenv hanya saat development. Untuk production, baca variabel langsung dari environment runtime (misalnya container). Pisahkan konfigurasi sensitif (database, API key) di file terpisah dan jangan commit ke VCS.

Custom error handler

Fiber memungkinkan override error handler global untuk log lebih baik dan mengontrol format response error:

app := fiber.New(fiber.Config{
    ErrorHandler: func(c *fiber.Ctx, err error) error {
        code := fiber.StatusInternalServerError
        if e, ok := err.(*fiber.Error); ok {
            code = e.Code
        }
        return c.Status(code).JSON(response.Error("Terjadi kesalahan", err.Error()))
    },
})

Dengan custom handler, Anda bisa menerapkan logging terpusat, menghindari kebocoran stack trace di production, dan menyertakan kode error standar.

Validasi request dasar

Gunakan BodyParser dan cek field secara eksplisit, atau integrasikan dengan paket validasi seperti github.com/go-playground/validator/v10. Pastikan cek dilakukan sebelum logika bisnis lain dijalankan.

Contoh:

payload := new(CreateUserRequest)
if err := c.BodyParser(payload); err != nil {
    return response.BadRequest(c, "Payload tidak valid", err)
}
if err := validator.New().Struct(payload); err != nil {
    return response.BadRequest(c, "Validasi gagal", err)
}

Dengan memisahkan layer tersebut, Anda meminimalkan bug akibat data tidak valid.

6. Perbedaan Penting dibanding Fiber v2 dan Tips Migrasi

Fiber v3 memperbarui beberapa dependency internal dan menambahkan perbaikan kompatibilitas Go terbaru. Perbedaan utama yang perlu dicatat saat migrasi:

  • Modul path wajib github.com/gofiber/fiber/v3: perbarui go.mod agar pakai major terbaru.
  • Handler error lebih konsisten: Fiber v3 memperkenalkan error handler yang lebih terstruktur, sehingga gunakan fiber.New(fiber.Config{ErrorHandler: ...}) daripada override global lama.
  • Middleware dan API tetap stabil, tetapi pastikan tidak menggunakan method yang deprecated seperti app.ListenV2.

Tips migrasi singkat:

  1. Perbarui go.mod ke v3 lalu jalankan go mod tidy.
  2. Cari penggunaan lama seperti fiber.New().Error() lalu adaptasi ke handler baru.
  3. Jalankan tes integrasi untuk memastikan middleware dan route grouping baru berjalan.

Selalu baca release note resmi Fiber jika ada fitur baru yang memerlukan penyesuaian.

7. Tips Debugging dan Common Mistakes

Beberapa jebakan umum saat memulai Fiber:

  • Lupa menambahkan fiber.New sebelum register route: menyebabkan panic saat route dipanggil.
  • Middleware hanya terdaftar di level global saat harusnya per grup: pastikan middleware yang hanya perlu grup tertentu tidak ditambahkan ke app.Use global.
  • BodyParser tidak dijaga kesalahan: dapat menyebabkan data parsial atau panic bila payload tidak valid.

Gunakan log middleware dan error handler untuk melihat alur request. Fiber menyediakan logger bawaan yang bisa dikonfigurasi formatnya untuk mencakup trace ID atau request ID.

Kesimpulan

Dengan struktur folder modular, konfigurasi yang jelas, route grouping, serta middleware inti seperti logger dan recover, Anda sudah bisa membangun service berbasis Go Fiber v3 yang terstruktur. Tambahan praktis seperti handler response konsisten, custom error handler, serta validasi request membantu memelihara kode dalam jangka panjang.

Penting untuk memperlakukan environment config dengan hati-hati, memahami perbedaan minor dari Fiber v2 saat migrasi, dan selalu menambahkan middleware spesifik pada tingkat yang sesuai. Ikuti pendekatan ini agar proyek fiber Anda siap untuk nilai production dan mudah diperluas di masa depan.