Category: Tutorial

Di Belajar Golang dari Nol #18 kita sudah merapikan logging dan error handling di API produk. Sekarang API kita sudah bisa cerita sendiri lewat log ketika ada yang salah. Kalau kamu baru bergabung di tengah jalan, cek dulu daftar lengkap seri Belajar Golang supaya urutannya tidak lompat.

Kali ini kita bahas dua pola yang hampir pasti kamu butuhkan begitu API dipakai orang sungguhan: worker dan job terjadwal.

Dua jenis pekerjaan yang tidak cocok di handler

Coba perhatikan dua situasi ini.

Pertama, ada pekerjaan yang tidak boleh membuat request menunggu. Contohnya kirim email notifikasi atau generate laporan PDF. Kirim email bisa makan dua sampai lima detik. Kalau dikerjakan di dalam handler, user harus menatap loading selama itu. Padahal user tidak peduli emailnya sudah terkirim atau belum. Dia cuma mau tahu transaksinya berhasil.

Kedua, ada pekerjaan yang harus jalan rutin tanpa disuruh siapa pun. Rekap penjualan harian, bersih-bersih data lama, cek stok yang menipis. Tidak ada request yang memicu pekerjaan ini. Dia harus jalan sendiri sesuai jadwal.

Untuk masalah pertama kita pakai worker. Untuk masalah kedua kita pakai job terjadwal. Dua-duanya bisa dibangun dengan bahan yang sudah kamu pelajari di seri ini: goroutine, channel, dan context.

Worker pool: channel sebagai antrian

Di bagian 10 kamu sudah kenal goroutine dan channel. Waktu itu contohnya masih abstrak. Sekarang kita pakai untuk kasus nyata.

Idenya sederhana. Channel jadi antrian pekerjaan. Beberapa goroutine jadi pekerja yang mengambil dari antrian itu. Handler cukup memasukkan pekerjaan ke channel, lalu lanjut membalas request.

Pertama kita definisikan bentuk pekerjaannya sebagai struct.

type EmailJob struct {
	Tujuan string
	Isi    string
}

Lalu kita buat channel antrian dan beberapa worker.

jobs := make(chan EmailJob, 100)

var wg sync.WaitGroup
for i := 1; i <= 3; i++ {
	wg.Add(1)
	go func(id int) {
		defer wg.Done()
		for job := range jobs {
			slog.Info("worker ambil job", "worker", id, "tujuan", job.Tujuan)
			kirimEmail(job)
		}
	}(i)
}

Perhatikan beberapa hal. Channel diberi buffer 100 supaya handler tidak ikut menunggu saat semua worker sedang sibuk. Tiga goroutine worker melakukan range di channel yang sama. Go otomatis membagi job ke worker yang sedang kosong. Kamu tidak perlu mengatur pembagiannya sendiri.

Bagian for job := range jobs juga yang membuat shutdown jadi rapi. Loop ini baru berhenti ketika channel ditutup dan isinya habis. Jadi urutan mematikannya jelas: panggil close(jobs), worker menghabiskan sisa antrian, lalu wg.Wait() menunggu semuanya selesai. Tidak ada job yang dibuang di tengah jalan.

close(jobs)
wg.Wait()
slog.Info("semua worker selesai")

Contoh nyata: notifikasi setelah transaksi

Sekarang kita sambungkan ke API. Misalkan setiap ada produk baru dibuat, admin harus dapat email. Tanpa worker, handlernya kira-kira begini.

mux.HandleFunc("POST /produk", func(w http.ResponseWriter, r *http.Request) {
	// ... simpan produk ...
	kirimEmail(EmailJob{Tujuan: "admin@toko.com", Isi: "Produk baru masuk"})
	w.WriteHeader(http.StatusCreated)
})

Kalau kirimEmail makan dua detik, request juga makan dua detik. Coba cek dengan curl -w "%{time_total}", hasilnya sekitar 2,01 detik.

Dengan worker, handler cukup melempar job ke channel lalu langsung membalas 201.

mux.HandleFunc("POST /produk", func(w http.ResponseWriter, r *http.Request) {
	// ... simpan produk ...
	jobs <- EmailJob{Tujuan: "admin@toko.com", Isi: "Produk baru masuk"}
	w.WriteHeader(http.StatusCreated)
})

Sekarang curl yang sama selesai dalam hitungan milidetik. Email tetap terkirim, tapi di belakang layar. User tidak perlu ikut menunggu pekerjaan yang bukan urusannya.

Job terjadwal dengan time.Ticker

Pola kedua: pekerjaan yang jalan rutin. Standard library sudah menyediakan time.Ticker, yaitu channel yang berdenyut setiap interval tertentu. Gabungkan dengan goroutine dan select, jadilah scheduler sederhana.

Ingat pelajaran context di bagian 17. Setiap goroutine yang hidup lama wajib punya cara berhenti. Di sinilah ctx.Done() masuk.

func jalankanRekap(ctx context.Context, interval time.Duration) {
	ticker := time.NewTicker(interval)
	defer ticker.Stop()

	for {
		select {
		case <-ctx.Done():
			slog.Info("job rekap berhenti")
			return
		case <-ticker.C:
			mu.Lock()
			jumlah := len(produk)
			mu.Unlock()
			slog.Info("rekap produk", "jumlah", jumlah)
		}
	}
}

Jalankan sebagai goroutine: go jalankanRekap(ctx, time.Minute). Setiap menit dia menghitung jumlah produk dan mencatatnya lewat slog. Ketika context dibatalkan, select memilih cabang ctx.Done() dan goroutine keluar dengan rapi. Jangan lupa defer ticker.Stop() supaya resource ticker dilepas.

Jalan pada jam tertentu

Ticker cocok untuk interval. Tapi bagaimana kalau job harus jalan tiap tengah malam? Polanya sedikit berbeda: hitung durasi sampai jadwal berikutnya dengan time.Until, tidur selama itu, kerjakan, lalu ulangi.

func jalankanTengahMalam(ctx context.Context, tugas func()) {
	for {
		sekarang := time.Now()
		besok := time.Date(sekarang.Year(), sekarang.Month(), sekarang.Day()+1,
			0, 0, 0, 0, sekarang.Location())
		timer := time.NewTimer(time.Until(besok))

		select {
		case <-ctx.Done():
			timer.Stop()
			return
		case <-timer.C:
			tugas()
		}
	}
}

time.Date dengan hari ditambah satu dan jam nol menghasilkan tengah malam berikutnya. time.Until menghitung sisa waktunya. Setelah tugas selesai, loop mengulang dan menghitung tengah malam berikutnya lagi.

Pola sederhana ini sering sudah cukup. Banyak orang buru-buru pasang library cron padahal jadwalnya cuma satu atau dua. Kalau kebutuhanmu masih bisa dijelaskan dalam satu kalimat, misalnya tiap jam atau tiap tengah malam, standard library sudah memadai. Lebih sedikit dependency, lebih mudah dipahami orang yang membaca kodenya nanti.

Kapan layak pakai robfig/cron

Kalau jadwalnya mulai ramai dan rumit, misalnya tiap hari kerja jam 8 pagi, tiap tanggal 1, plus tiap 15 menit di jam kantor, barulah library seperti robfig/cron layak dipakai. Dia menerima ekspresi cron yang sama dengan crontab di Linux.

c := cron.New()
c.AddFunc("0 0 * * *", rekapHarian)     // tiap tengah malam
c.AddFunc("*/15 8-17 * * 1-5", cekStok) // tiap 15 menit, jam kerja
c.Start()

Install dengan go get github.com/robfig/cron/v3. Aturannya sama seperti dependency lain di seri ini: pakai ketika kebutuhannya nyata, bukan karena terlihat keren.

Jebakan yang harus kamu tahu dari awal

Sebelum kamu pakai pola ini di production, ada tiga jebakan yang jujur harus dibahas.

Pertama, job hilang saat server restart. Antrian kita hidup di memori. Kalau server mati atau di-deploy ulang, semua job yang belum dikerjakan ikut lenyap. Untuk email notifikasi biasa, ini sering masih bisa diterima. Untuk job yang tidak boleh hilang, misalnya pemrosesan pembayaran, kamu butuh durable queue seperti Redis atau RabbitMQ. Job disimpan di luar proses aplikasi, jadi selamat dari restart. Kita tidak bedah itu sekarang, cukup tahu dulu batasnya di mana.

Kedua, dua instance server berarti job ganda. Kalau nanti aplikasimu jalan di dua server demi ketersediaan, job terjadwal ikut jalan di dua-duanya. Rekap harian terkirim dua kali. Solusinya macam-macam, dari lock di database sampai memisahkan scheduler jadi service sendiri. Yang penting sekarang: sadari bahwa pola ini mengasumsikan satu instance.

Ketiga, panic di worker mematikan goroutine diam-diam. Ini yang paling licik. Kalau kode di dalam worker panic, goroutine itu mati. Kamu punya tiga worker, satu panic, sisa dua. Panic lagi, sisa satu. Lama-lama antrian menumpuk dan tidak ada yang tahu kenapa. Ingat pelajaran bagian 18: panic yang tidak ditangani harus dicatat. Pasang recover di fungsi kerjanya.

func kirimEmail(job EmailJob) {
	defer func() {
		if r := recover(); r != nil {
			slog.Error("worker panic", "tujuan", job.Tujuan, "error", r)
		}
	}()

	time.Sleep(2 * time.Second) // simulasi kirim email
	slog.Info("email terkirim", "tujuan", job.Tujuan)
}

Dengan begini, job yang bermasalah tercatat di log dan workernya tetap hidup untuk job berikutnya.

Satu catatan lagi di level server. Untuk job yang benar-benar terpisah dari API, misalnya script backup, kamu tidak harus menjadwalkannya dari dalam Go. systemd yang kita pakai di bagian 15 untuk menjalankan aplikasi juga punya fitur timer. Kamu tulis unit timer, systemd yang menjalankan program Go kecil sesuai jadwal. Kelebihannya, jadwal terlihat oleh admin server lewat systemctl list-timers, bukan tersembunyi di dalam kode.

Latihan: API produk dengan worker dan rekap terjadwal

Sekarang kita rangkai semuanya jadi satu program utuh. API produk menerima POST, melempar job email ke worker, dan job rekap jalan tiap 30 detik. Shutdown ditangani lewat signal.NotifyContext, cara standar menangkap Ctrl+C atau sinyal stop dari systemd.

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"sync"
	"syscall"
	"time"
)

type Produk struct {
	ID    int    `json:"id"`
	Nama  string `json:"nama"`
	Harga int    `json:"harga"`
}

type EmailJob struct {
	Tujuan string
	Isi    string
}

var (
	mu     sync.Mutex
	produk = []Produk{{ID: 1, Nama: "Kopi Arabika", Harga: 85000}}
)

func kirimEmail(job EmailJob) {
	defer func() {
		if r := recover(); r != nil {
			slog.Error("worker panic", "tujuan", job.Tujuan, "error", r)
		}
	}()
	time.Sleep(2 * time.Second) // simulasi kirim email
	slog.Info("email terkirim", "tujuan", job.Tujuan, "isi", job.Isi)
}

func jalankanRekap(ctx context.Context, interval time.Duration) {
	ticker := time.NewTicker(interval)
	defer ticker.Stop()
	for {
		select {
		case <-ctx.Done():
			slog.Info("job rekap berhenti")
			return
		case <-ticker.C:
			mu.Lock()
			jumlah := len(produk)
			mu.Unlock()
			slog.Info("rekap produk", "jumlah", jumlah)
		}
	}
}

func main() {
	slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stdout, nil)))

	ctx, stop := signal.NotifyContext(context.Background(),
		os.Interrupt, syscall.SIGTERM)
	defer stop()

	jobs := make(chan EmailJob, 100)
	var wg sync.WaitGroup
	for i := 1; i <= 3; i++ {
		wg.Add(1)
		go func(id int) {
			defer wg.Done()
			for job := range jobs {
				slog.Info("worker ambil job", "worker", id, "tujuan", job.Tujuan)
				kirimEmail(job)
			}
		}(i)
	}

	go jalankanRekap(ctx, 30*time.Second)

	mux := http.NewServeMux()
	mux.HandleFunc("POST /produk", func(w http.ResponseWriter, r *http.Request) {
		var p Produk
		if err := json.NewDecoder(r.Body).Decode(&p); err != nil {
			http.Error(w, `{"error":"body tidak valid"}`, http.StatusBadRequest)
			return
		}
		mu.Lock()
		p.ID = len(produk) + 1
		produk = append(produk, p)
		mu.Unlock()

		jobs <- EmailJob{
			Tujuan: "admin@toko.com",
			Isi:    fmt.Sprintf("Produk baru: %s", p.Nama),
		}

		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(http.StatusCreated)
		json.NewEncoder(w).Encode(p)
	})

	server := &http.Server{Addr: ":8080", Handler: mux}
	go func() {
		slog.Info("server jalan", "addr", ":8080")
		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
			slog.Error("server gagal", "error", err)
			os.Exit(1)
		}
	}()

	<-ctx.Done()
	slog.Info("sinyal berhenti diterima")

	shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	server.Shutdown(shutdownCtx)

	close(jobs)
	wg.Wait()
	slog.Info("semua worker selesai, aplikasi berhenti")
}

Jalankan dengan go run main.go, lalu kirim beberapa request.

curl -X POST localhost:8080/produk \
  -d '{"nama":"Teh Hijau","harga":45000}'

Perhatikan lognya. Respons 201 datang seketika, log worker ambil job muncul, dua detik kemudian email terkirim. Tiap 30 detik muncul rekap produk dengan jumlah terbaru. Dua pola jalan berdampingan tanpa saling ganggu.

Sekarang tekan Ctrl+C. Urutan lognya bercerita sendiri: sinyal diterima, server berhenti menerima request, job rekap berhenti, worker menghabiskan sisa antrian, baru aplikasi benar-benar mati. Itulah shutdown yang rapi. Tidak ada email yang setengah terkirim, tidak ada goroutine yang dipaksa mati.

Selanjutnya

API kita sekarang bisa mengerjakan tugas di belakang layar dan punya jadwal sendiri. Di bagian 20 kita bahas kebutuhan yang hampir pasti muncul di aplikasi nyata: Upload dan Menyimpan File di API Go.

Kalau kamu sedang membangun sistem dengan kebutuhan background job dan penjadwalan seperti ini untuk bisnismu, tim kami di Arrazy juga mengerjakan pengembangan sistem aplikasi custom dari perancangan sampai deploy.

Di Belajar Golang dari Nol #17 kita memasang context di seluruh alur handler, service, dan repository. Sekarang setiap request punya batas waktu dan bisa dibatalkan. Bagus. Tapi ada satu hal yang belum kita urus: apa yang terjadi kalau alur itu gagal di server, jam dua pagi, saat tidak ada yang menonton.

Bagian ini soal itu. Kita rapikan cara aplikasi bercerita tentang dirinya sendiri lewat log, dan cara error dibawa naik dari lapisan bawah tanpa kehilangan konteks.

Masalahnya: log adalah satu-satunya mata kita

Saat aplikasi jalan di laptop, kita bisa pasang breakpoint, cetak variabel, ulangi request sesuka hati. Di server tidak begitu. Aplikasi berjalan di balik systemd, request datang dari pengguna asli, dan kejadiannya sudah lewat saat kita baru membuka journalctl.

Yang tersisa cuma log. Kalau log kita begini:

2026/07/26 02:14:33 error
2026/07/26 02:14:35 error
2026/07/26 02:17:02 gagal

maka kita tidak punya apa-apa. Error apa? Request yang mana? Pengguna mana? Endpoint mana? Baris seperti itu hanya memberi tahu bahwa ada masalah, dan itu sudah kita tahu dari keluhan pelanggan.

Ada satu kebiasaan lain yang lebih berbahaya: error yang ditelan diam-diam.

data, _ := json.Marshal(produk)
w.Write(data)

Underscore itu berarti “saya tidak peduli”. Kalau suatu hari marshal gagal, aplikasi tetap jalan, pengguna dapat balasan kosong, dan tidak ada satu baris pun di log. Bug seperti ini bisa duduk diam berbulan-bulan sampai akhirnya meledak di waktu yang paling tidak enak.

Aturan sederhananya: setiap error diperiksa, dan setiap error yang tidak ditangani harus dicatat.

Error wrapping dengan %w

Di bagian 3 kita sudah kenal pola if err != nil. Masalahnya, kalau error hanya diteruskan apa adanya, kita kehilangan jejak. Pesan sql: no rows in result set muncul di handler tanpa memberi tahu tabel apa, id berapa, dan fungsi mana yang memanggilnya.

Solusinya adalah membungkus error. Gunakan fmt.Errorf dengan kata kunci %w. Kata kunci ini menambah konteks di depan, tapi menyimpan error aslinya di dalam.

Mulai dari repository:

func (r *ProdukRepo) Ambil(ctx context.Context, id int64) (Produk, error) {
	var p Produk
	query := "SELECT id, nama, harga FROM produk WHERE id = ?"
	err := r.db.QueryRowContext(ctx, query, id).Scan(&p.ID, &p.Nama, &p.Harga)
	if err != nil {
		return Produk{}, fmt.Errorf("repo ambil produk id %d: %w", id, err)
	}
	return p, nil
}

Naik ke service:

func (s *ProdukService) Detail(ctx context.Context, id int64) (Produk, error) {
	p, err := s.repo.Ambil(ctx, id)
	if err != nil {
		return Produk{}, fmt.Errorf("service detail produk: %w", err)
	}
	return p, nil
}

Saat handler mencatat error itu, isinya jadi seperti ini:

service detail produk: repo ambil produk id 42: sql: no rows in result set

Satu baris, tiga lapis cerita. Kita tahu alurnya lewat mana, id yang dicari berapa, dan akar masalahnya apa. Itulah yang kita cari saat jam dua pagi.

Dua hal yang perlu dijaga. Pertama, jangan menulis kata “error” atau “gagal” berulang di setiap lapis, nanti pesannya jadi “gagal: gagal: gagal”. Sebut nama operasinya saja. Kedua, cukup bungkus sekali per lapis. Membungkus dua kali di fungsi yang sama hanya menambah panjang tanpa menambah informasi.

errors.Is untuk mengenali error tertentu

Error yang dibungkus %w tetap bisa dikenali. Di sinilah errors.Is berguna. Fungsi ini membongkar lapisan pembungkus sampai menemukan error yang kita cari.

Ingat sql.ErrNoRows dari bagian 12? Itu bukan kerusakan sistem, itu cuma data tidak ada. Balasan yang benar adalah 404, bukan 500.

if errors.Is(err, sql.ErrNoRows) {
	balasJSON(w, http.StatusNotFound, map[string]string{
		"pesan": "Produk tidak ditemukan",
	})
	return
}

Perhatikan bahwa ini tetap bekerja walau error sudah dibungkus dua kali. Kalau kita pakai err == sql.ErrNoRows, perbandingan itu gagal begitu error dibungkus. Jadi biasakan pakai errors.Is.

Pola yang sama berlaku untuk context.DeadlineExceeded dari bagian 17. Request yang kehabisan waktu layak dibalas 504, bukan 500 generik.

errors.As untuk mengambil tipe error custom

errors.Is membandingkan nilai. Kalau kita butuh isinya, gunakan errors.As. Fungsi ini mencari error dengan tipe tertentu di dalam rantai, lalu menyalinnya ke variabel kita supaya field-nya bisa dibaca.

Error custom sederhana

Di bagian 9 kita belajar interface. error sendiri sebenarnya interface biasa dengan satu method:

type error interface {
	Error() string
}

Artinya struct apa pun bisa jadi error asal punya method Error() string. Ini berguna saat error perlu membawa data, bukan cuma kalimat.

type ErrValidasi struct {
	Field string
	Pesan string
}

func (e *ErrValidasi) Error() string {
	return fmt.Sprintf("validasi gagal pada field %s: %s", e.Field, e.Pesan)
}

Service memakainya begini:

func (s *ProdukService) Simpan(ctx context.Context, p Produk) error {
	if p.Harga <= 0 {
		return &ErrValidasi{Field: "harga", Pesan: "Harga harus lebih dari nol"}
	}
	if err := s.repo.Simpan(ctx, p); err != nil {
		return fmt.Errorf("service simpan produk: %w", err)
	}
	return nil
}

Handler mengambilnya kembali dengan errors.As:

var errValidasi *ErrValidasi
if errors.As(err, &errValidasi) {
	balasJSON(w, http.StatusBadRequest, map[string]string{
		"field": errValidasi.Field,
		"pesan": errValidasi.Pesan,
	})
	return
}

Kapan ini berguna? Saat handler perlu memutuskan sesuatu berdasarkan isi error, misalnya menentukan status code atau memberi tahu field mana yang salah di form. Kalau error cuma perlu dicatat lalu dibalas 500, tipe custom itu berlebihan. Cukup bungkus dengan fmt.Errorf.

Pisahkan pesan untuk pengguna dan detail untuk developer

Ini kesalahan yang sering saya temukan saat mengaudit backend orang lain: pesan error mentah dikirim langsung ke browser.

// jangan begini
http.Error(w, err.Error(), http.StatusInternalServerError)

Pengguna jadi melihat kalimat seperti dial tcp 10.0.0.5:3306: connect: connection refused. Bagi pengguna itu tidak berguna. Bagi penyerang itu hadiah: nama tabel, IP database, port, versi driver, semuanya bocor gratis.

Aturannya dua arah. Pengguna dapat kalimat sopan dan umum. Log menyimpan detail teknis lengkap.

log.Error("gagal mengambil produk",
	"produk_id", id,
	"error", err.Error(),
)
balasJSON(w, http.StatusInternalServerError, map[string]string{
	"pesan": "Terjadi kesalahan di server, coba beberapa saat lagi",
})

Kalau ingin pengguna bisa melapor dengan jelas, sisipkan request id ke balasan. Detailnya tetap di log, tapi pengguna punya nomor tiket untuk disebut ke tim support.

log/slog: logging terstruktur dari standard library

Sejak Go 1.21, standard library punya log/slog. Dibanding log biasa, bedanya jauh.

• Log punya level: Debug, Info, Warn, Error. Kita bisa menyaring saat produksi.
• Data ditulis sebagai pasangan key value, bukan kalimat panjang yang harus diurai ulang.
• Bisa keluar sebagai JSON, jadi mudah dibaca mesin dan dicari lewat tool log.

Siapkan logger sekali di main.go, lalu pasang jadi default:

func siapkanLogger(env string) *slog.Logger {
	opts := &slog.HandlerOptions{Level: slog.LevelInfo}

	var handler slog.Handler
	if env == "production" {
		handler = slog.NewJSONHandler(os.Stdout, opts)
	} else {
		opts.Level = slog.LevelDebug
		handler = slog.NewTextHandler(os.Stdout, opts)
	}

	logger := slog.New(handler)
	slog.SetDefault(logger)
	return logger
}

Di lokal, text handler lebih enak dibaca mata. Di server, JSON handler lebih enak dibaca alat. Level Debug menyala saat ngoding, dan mati saat produksi supaya log tidak penuh sampah.

Cara pakainya:

slog.Info("server berjalan", "port", 8080, "env", env)
slog.Error("koneksi database putus", "host", cfg.DBHost, "error", err.Error())

Perhatikan polanya: pesan pendek dulu, lalu data menyusul sebagai pasangan key value. Jangan menempel nilai ke dalam pesan pakai fmt.Sprintf, karena nanti sulit dicari dan difilter.

Menyisipkan request id lewat middleware dan context

Satu request bisa menghasilkan lima baris log. Kalau ada seratus request per menit, semua baris itu bercampur. Tanpa penanda, kita tidak tahu baris mana milik request mana.

Solusinya request id. Dibuat di middleware (nyambung bagian 13), disimpan di context (nyambung bagian 17), lalu diambil lagi saat logging. Ini justru contoh sah pemakaian context.WithValue: data lintas lapisan yang sifatnya metadata request, bukan parameter bisnis.

type kunciCtx string

const kunciRequestID kunciCtx = "request_id"

func RequestID(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		id := r.Header.Get("X-Request-ID")
		if id == "" {
			id = acakID()
		}

		ctx := context.WithValue(r.Context(), kunciRequestID, id)
		w.Header().Set("X-Request-ID", id)
		next.ServeHTTP(w, r.WithContext(ctx))
	})
}

func acakID() string {
	b := make([]byte, 8)
	if _, err := rand.Read(b); err != nil {
		return "id-gagal"
	}
	return hex.EncodeToString(b)
}

Lalu dua helper kecil untuk mengambilnya kembali:

func RequestIDDari(ctx context.Context) string {
	if id, ok := ctx.Value(kunciRequestID).(string); ok {
		return id
	}
	return "tanpa-id"
}

func LogDari(ctx context.Context) *slog.Logger {
	return slog.Default().With("request_id", RequestIDDari(ctx))
}

Sekarang semua lapisan tinggal panggil LogDari(ctx) dan setiap baris otomatis membawa request id yang sama. Saat pelanggan lapor, kita minta nilai header X-Request-ID, lalu cari di server dengan cara yang sudah kita pelajari di bagian 15:

journalctl -u aplikasi.service | grep 9f2c1ab7d3e5f004

Yang wajib dan yang jangan dicatat

Wajib ada di setiap baris log request:

• waktu kejadian
• level (info, warn, error)
• request id
• method dan path
• durasi proses
• pesan error yang sudah berkonteks, bukan cuma kata “error”

Jangan pernah masuk log:

• password, walau sudah salah ketik
• token, session, API key, isi header Authorization
• nomor kartu, CVV, data pembayaran
• NIK, alamat lengkap, dan data pribadi yang tidak dibutuhkan untuk debug
• seluruh body request mentah, karena isinya sering mengandung semua hal di atas

Log itu disimpan lama, dikirim ke layanan pihak ketiga, dan sering bisa dibaca lebih banyak orang daripada database. Perlakukan seperti dokumen publik internal.

Panic dan recover

Panic berbeda dengan error. Error itu keadaan yang kita perkirakan. Panic itu keadaan yang tidak kita perkirakan, misalnya nil pointer atau index di luar batas.

Masalahnya, panic di satu goroutine handler bisa menjatuhkan seluruh proses. Satu request bermasalah membuat semua pengguna lain ikut kena. Karena itu kita pasang middleware recovery.

func Recovery(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			if rec := recover(); rec != nil {
				slog.Error("panic tertangkap",
					"request_id", RequestIDDari(r.Context()),
					"path", r.URL.Path,
					"panic", fmt.Sprint(rec),
					"stack", string(debug.Stack()),
				)
				balasJSON(w, http.StatusInternalServerError, map[string]string{
					"pesan": "Terjadi kesalahan di server",
				})
			}
		}()
		next.ServeHTTP(w, r)
	})
}

Pasang paling luar, sebelum middleware lain, supaya panic dari mana pun tertangkap. Stack trace masuk log, pengguna dapat 500 yang sopan, server tetap hidup.

Recover bukan alasan untuk malas menangani error. Anggap setiap baris “panic tertangkap” di log sebagai bug yang wajib diperbaiki minggu itu juga.

Latihan: rapikan satu endpoint sampai tuntas

Gabungkan semuanya di handler detail produk.

func (h *ProdukHandler) Detail(w http.ResponseWriter, r *http.Request) {
	mulai := time.Now()
	ctx := r.Context()
	log := LogDari(ctx).With("method", r.Method, "path", r.URL.Path)

	id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
	if err != nil {
		log.Warn("id tidak valid", "nilai", r.PathValue("id"))
		balasJSON(w, http.StatusBadRequest, map[string]string{
			"pesan": "ID produk tidak valid",
		})
		return
	}

	produk, err := h.service.Detail(ctx, id)
	if err != nil {
		var errValidasi *ErrValidasi
		switch {
		case errors.Is(err, sql.ErrNoRows):
			log.Info("produk tidak ditemukan", "produk_id", id)
			balasJSON(w, http.StatusNotFound, map[string]string{
				"pesan": "Produk tidak ditemukan",
			})
		case errors.As(err, &errValidasi):
			log.Warn("validasi gagal", "field", errValidasi.Field)
			balasJSON(w, http.StatusBadRequest, map[string]string{
				"pesan": errValidasi.Pesan,
			})
		default:
			log.Error("gagal mengambil produk",
				"produk_id", id,
				"error", err.Error(),
				"durasi_ms", time.Since(mulai).Milliseconds(),
			)
			balasJSON(w, http.StatusInternalServerError, map[string]string{
				"pesan": "Terjadi kesalahan di server",
			})
		}
		return
	}

	log.Info("produk terkirim",
		"produk_id", id,
		"durasi_ms", time.Since(mulai).Milliseconds(),
	)
	balasJSON(w, http.StatusOK, produk)
}

Rangkai middleware-nya di main.go, recovery di lapis paling luar:

mux := http.NewServeMux()
mux.HandleFunc("GET /produk/{id}", produkHandler.Detail)

handler := Recovery(RequestID(mux))
slog.Info("server berjalan", "port", 8080)
http.ListenAndServe(":8080", handler)

Saat request berhasil, log produksi terlihat seperti ini:

{"time":"2026-07-26T02:14:33.481+07:00","level":"INFO","msg":"produk terkirim","request_id":"9f2c1ab7d3e5f004","method":"GET","path":"/produk/42","produk_id":42,"durasi_ms":6}

Saat database mati, log yang sama berubah jadi:

{"time":"2026-07-26T02:14:35.902+07:00","level":"ERROR","msg":"gagal mengambil produk","request_id":"a71b0c94ee3d2185","method":"GET","path":"/produk/42","produk_id":42,"error":"service detail produk: repo ambil produk id 42: dial tcp 10.0.0.5:3306: connect: connection refused","durasi_ms":2041}

Bandingkan dengan baris “error” polos di awal artikel. Sekarang kita tahu endpoint mana, id berapa, akar masalahnya di koneksi database, dan proses menggantung dua detik sebelum menyerah. Pengguna sendiri hanya melihat kalimat sopan tanpa satu pun detail internal.

Rangkuman

• Bungkus error dengan %w di setiap lapis supaya konteksnya menumpuk.
• Pakai errors.Is untuk mengenali error tertentu, errors.As untuk mengambil isinya.
• Buat error custom hanya saat error perlu membawa data.
• Pengguna dapat kalimat sopan, log dapat detail teknis.
• Pakai log/slog dengan atribut key value, JSON di server, text di lokal.
• Sisipkan request id lewat middleware dan context supaya satu request bisa dirunut.
• Pasang middleware recovery, dan perlakukan setiap panic sebagai bug yang harus diperbaiki.

Di bagian 19 kita bahas Worker dan Job Terjadwal di Go, untuk pekerjaan yang jalan di belakang layar tanpa menunggu request.

Kalau tim Anda butuh bantuan membangun backend yang rapi sejak awal, silakan lihat layanan sistem aplikasi dari Arrazy Inovasi.

Di Belajar Golang dari Nol #16 kita merapikan project jadi tiga lapis: handler, service, repository. Alurnya sudah jelas. Request masuk lewat handler, logika dikerjakan service, data diambil repository.

Tapi ada satu hal yang belum kita urus. Semua fungsi di tiga lapis itu masih berjalan tanpa rem. Sekali query jalan, dia jalan terus sampai selesai. Tidak peduli siapa pun yang menunggunya sudah pergi.

Bagian ini membahas remnya. Namanya context.

Masalah yang Baru Kelihatan Saat Aplikasi Ramai

Bayangkan endpoint laporan penjualan di aplikasi Anda. Query-nya berat, butuh 8 detik. Pengguna klik menu laporan, menunggu 3 detik, lalu bosan dan menutup tab browser.

Apa yang terjadi di server? Query itu tetap jalan. Lima detik sisanya database tetap bekerja keras untuk hasil yang tidak akan pernah dibaca siapa pun. Koneksi database tetap dipegang. Memori tetap terpakai.

Satu pengguna tidak masalah. Tapi kalau 50 orang melakukan hal yang sama dalam satu menit, server Anda sibuk mengerjakan pekerjaan hantu.

Kasus kedua lebih menyakitkan. Aplikasi Anda memanggil API pihak ketiga, misalnya cek ongkir atau payment gateway. Server mereka sedang bermasalah dan tidak menjawab apa-apa. Bukan error, hanya diam. Koneksi Anda menggantung. Satu per satu request menumpuk sampai aplikasi berhenti melayani siapa pun.

Go menyediakan satu mekanisme untuk dua masalah ini. Context adalah cara Go menyampaikan pesan “sudah tidak usah dilanjut” ke semua bagian program yang sedang mengerjakan satu permintaan.

Analogi: Pesan Estafet ke Semua Petugas

Anggap satu request HTTP itu satu pesanan di dapur restoran. Pesanan masuk, lalu dibagi ke banyak orang. Ada yang menyiapkan nasi, ada yang menggoreng ayam, ada yang menyeduh minuman.

Context adalah selembar catatan kecil yang ikut ke setiap orang itu. Isinya dua hal: kabar pembatalan dan batas waktu.

Kalau pelanggan tiba-tiba pergi, pelayan menandai catatan itu sebagai batal. Semua orang yang memegang salinan catatan langsung tahu dan berhenti memasak. Kalau ada aturan “pesanan harus jadi dalam 10 menit”, batas itu juga tertulis di catatan yang sama.

Yang penting dipahami: context tidak memaksa siapa pun berhenti. Dia hanya menyampaikan kabar. Kode Andalah yang harus rajin mengecek catatan itu dan berhenti dengan sukarela.

context.Background dan context.TODO

Setiap context punya induk. Di ujung paling atas ada context kosong yang tidak pernah dibatalkan dan tidak punya batas waktu. Ada dua pilihan untuk itu.

• context.Background() dipakai di titik paling awal program. Di dalam main(), saat inisialisasi, atau di test. Ini pilihan default Anda.
• context.TODO() dipakai saat Anda belum tahu context yang benar harus datang dari mana. Fungsinya sama persis, bedanya cuma penanda untuk diri sendiri bahwa bagian ini masih perlu dirapikan.

Aturan praktisnya sederhana. Kalau ragu, pakai context.Background(). Pakai context.TODO() hanya saat Anda sedang menambal kode lama dan belum sempat mengalirkan context dari atas.

context.WithTimeout: Memberi Batas Waktu

Ini fungsi yang paling sering Anda pakai. Coba jalankan kode berikut.

package main

import (
	"context"
	"fmt"
	"time"
)

func ambilDataLambat(ctx context.Context) (string, error) {
	hasil := make(chan string, 1)

	go func() {
		time.Sleep(5 * time.Second)
		hasil <- "data dari server tetangga"
	}()

	select {
	case data := <-hasil:
		return data, nil
	case <-ctx.Done():
		return "", ctx.Err()
	}
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancel()

	mulai := time.Now()
	data, err := ambilDataLambat(ctx)
	if err != nil {
		fmt.Println("gagal setelah", time.Since(mulai).Round(time.Second), ":", err)
		return
	}
	fmt.Println("berhasil:", data)
}

Outputnya:

gagal setelah 2s : context deadline exceeded

Fungsinya butuh 5 detik, batas kita 2 detik. Setelah 2 detik, channel ctx.Done() tertutup dan select memilih cabang itu. Kita tidak menunggu 3 detik sisanya.

Dua hal yang perlu Anda ingat dari kode di atas:

• ctx.Done() adalah channel. Selama context masih hidup, channel ini diam. Begitu batas waktu lewat atau ada pembatalan, channel ini tertutup dan semua yang menunggu langsung jalan.
• ctx.Err() memberi tahu alasannya. Nilainya context.DeadlineExceeded kalau kehabisan waktu, atau context.Canceled kalau dibatalkan manual.

Kenapa defer cancel() Wajib

context.WithTimeout mengembalikan dua nilai. Yang kedua adalah fungsi cancel. Banyak pemula mengabaikannya karena kodenya tetap jalan tanpa itu. Ini kebiasaan yang mahal.

Saat Anda memanggil WithTimeout, Go diam-diam membuat timer di belakang layar dan mendaftarkan context baru ke induknya. Selama cancel belum dipanggil, timer dan pendaftaran itu masih nyangkut di memori.

Kalau fungsi Anda selesai dalam 100 milidetik tapi timeout-nya 5 detik, tanpa cancel ada sampah yang menganggur 4,9 detik. Di endpoint yang dipanggil ribuan kali per menit, sampah ini menumpuk. Itu yang disebut kebocoran resource.

Memanggil cancel dua kali aman, dan memanggilnya setelah timeout lewat juga aman. Jadi tidak ada alasan untuk melewatkannya. Tulis defer cancel() tepat di baris setelah WithTimeout, selalu.

context.WithCancel: Pembatalan Manual

Kadang yang Anda butuhkan bukan batas waktu, tapi tombol stop. Di bagian 10 kita membuat goroutine pekerja yang jalan terus. Waktu itu kita belum punya cara rapi untuk menghentikannya. Sekarang punya.

package main

import (
	"context"
	"fmt"
	"time"
)

func pekerja(ctx context.Context, nama string) {
	for {
		select {
		case <-ctx.Done():
			fmt.Println(nama, "berhenti karena", ctx.Err())
			return
		default:
			fmt.Println(nama, "sedang memproses antrean")
			time.Sleep(700 * time.Millisecond)
		}
	}
}

func main() {
	ctx, cancel := context.WithCancel(context.Background())

	go pekerja(ctx, "pekerja-1")
	go pekerja(ctx, "pekerja-2")

	time.Sleep(2 * time.Second)
	fmt.Println("perintah berhenti dikirim")
	cancel()

	time.Sleep(300 * time.Millisecond)
	fmt.Println("aplikasi ditutup")
}

Contoh output:

pekerja-1 sedang memproses antrean
pekerja-2 sedang memproses antrean
pekerja-1 sedang memproses antrean
pekerja-2 sedang memproses antrean
pekerja-1 sedang memproses antrean
pekerja-2 sedang memproses antrean
perintah berhenti dikirim
pekerja-1 berhenti karena context canceled
pekerja-2 berhenti karena context canceled
aplikasi ditutup

Satu kali panggil cancel(), dua goroutine berhenti. Ini bedanya dengan cara lama memakai channel stop buatan sendiri. Context menyebar ke bawah secara otomatis, jadi cucu dari context ini ikut dibatalkan tanpa Anda urus satu per satu.

Context di HTTP Handler

Kabar baiknya, untuk aplikasi web Anda tidak perlu membuat context dari nol. Paket net/http sudah menyiapkannya di setiap request.

r.Context() mengembalikan context yang otomatis dibatalkan ketika klien memutus koneksi. Tutup tab, tekan tombol batal, atau koneksi internet putus, semuanya memicu pembatalan yang sama.

func laporanHandler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()

	for i := 1; i <= 5; i++ {
		select {
		case <-ctx.Done():
			log.Println("klien pergi di langkah", i, "alasan:", ctx.Err())
			return
		case <-time.After(1 * time.Second):
			log.Println("selesai memproses langkah", i)
		}
	}

	w.Write([]byte("laporan selesai"))
}

Jalankan server, panggil endpoint itu dengan curl, lalu tekan Ctrl+C sebelum 5 detik. Di log server Anda akan lihat prosesnya berhenti di tengah jalan. Tanpa pengecekan ctx.Done(), server tetap menghitung sampai langkah kelima untuk pengguna yang sudah tidak ada.

Mengalirkan Context ke Database

Di bagian 12 kita memakai db.Query dan db.Exec. Keduanya punya versi yang menerima context: QueryContext dan ExecContext.

Perubahannya kecil. Tambah parameter ctx di depan, ganti nama method. Begini repository produk kita setelah dirapikan.

package repository

import (
	"context"
	"database/sql"

	"nama-project/internal/entity"
)

type ProdukRepository struct {
	db *sql.DB
}

func NewProdukRepository(db *sql.DB) *ProdukRepository {
	return &ProdukRepository{db: db}
}

func (r *ProdukRepository) FindAll(ctx context.Context) ([]entity.Produk, error) {
	query := "SELECT id, nama, harga FROM produk ORDER BY id"

	rows, err := r.db.QueryContext(ctx, query)
	if err != nil {
		return nil, err
	}
	defer rows.Close()

	var daftar []entity.Produk
	for rows.Next() {
		var p entity.Produk
		if err := rows.Scan(&p.ID, &p.Nama, &p.Harga); err != nil {
			return nil, err
		}
		daftar = append(daftar, p)
	}

	return daftar, rows.Err()
}

func (r *ProdukRepository) Create(ctx context.Context, p entity.Produk) error {
	_, err := r.db.ExecContext(ctx,
		"INSERT INTO produk (nama, harga) VALUES (?, ?)",
		p.Nama, p.Harga,
	)
	return err
}

Efeknya nyata, bukan sekadar kosmetik. Driver database seperti MySQL dan PostgreSQL akan mengirim sinyal pembatalan ke server database saat context mati. Query yang sedang berjalan benar-benar dihentikan di sisi database, lalu koneksi dikembalikan ke pool.

Tanpa ini, koneksi baru bebas setelah query selesai dengan caranya sendiri.

Aturan Idiomatik yang Perlu Dihafal

Tim Go menetapkan beberapa konvensi. Ikuti saja, karena seluruh ekosistem library Go mengikutinya.

• Context selalu parameter pertama, namanya ctx. Tulis func Ambil(ctx context.Context, id int) error, bukan sebaliknya. Ini bukan selera, ini standar yang bikin kode Anda terbaca oleh siapa pun.
• Jangan simpan context di dalam struct. Context itu milik satu request, sementara struct repository hidup selama aplikasi jalan. Menyimpannya di struct berarti satu request bisa membatalkan request orang lain. Oper lewat parameter.
• Jangan kirim nil. Kalau benar benar belum tahu mau isi apa, pakai context.TODO(). Mengirim nil akan bikin panic saat ada yang memanggil ctx.Done().
• Context aman dipakai banyak goroutine sekaligus. Anda boleh mengoper satu ctx yang sama ke lima goroutine tanpa mutex.

Sekilas tentang context.WithValue

Context juga bisa membawa data. Bentuknya seperti ini.

type kunciRequestID struct{}

ctx = context.WithValue(ctx, kunciRequestID{}, "req-8842")

if id, ok := ctx.Value(kunciRequestID{}).(string); ok {
	log.Println("request id:", id)
}

Pakai ini secukupnya saja. WithValue ditujukan untuk data yang menempel pada satu request dan menembus banyak lapisan tanpa jadi urusan bisnis, misalnya request ID, trace ID, atau identitas user hasil middleware autentikasi dari bagian 13.

Peringatannya: jangan pakai WithValue untuk mengoper parameter fungsi. Kalau service Anda butuh produkID, jadikan itu parameter biasa. Menaruhnya di context bikin signature fungsi berbohong, tipe datanya tidak dicek compiler, dan orang berikutnya harus membaca seluruh isi project untuk tahu apa yang ada di dalam ctx.

Satu catatan teknis: pakai tipe kunci buatan sendiri seperti kunciRequestID di atas, jangan string biasa, supaya kunci Anda tidak bentrok dengan kunci milik library lain.

Latihan: Endpoint Produk dari Ujung ke Ujung

Sekarang kita gabungkan semuanya. Target kita: request masuk ke handler, context-nya mengalir ke service, service memberi batas 3 detik, lalu diteruskan ke query database.

Lapisan service:

package service

import (
	"context"
	"time"

	"nama-project/internal/entity"
	"nama-project/internal/repository"
)

type ProdukService struct {
	repo *repository.ProdukRepository
}

func NewProdukService(repo *repository.ProdukRepository) *ProdukService {
	return &ProdukService{repo: repo}
}

func (s *ProdukService) ListProduk(ctx context.Context) ([]entity.Produk, error) {
	ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
	defer cancel()

	return s.repo.FindAll(ctx)
}

Perhatikan baris context.WithTimeout(ctx, ...). Induknya adalah ctx dari request, bukan context.Background(). Jadi ada dua pemicu berhenti sekaligus: klien pergi, atau waktu 3 detik habis. Mana pun yang lebih dulu, query berhenti.

Lapisan handler:

package handler

import (
	"context"
	"encoding/json"
	"errors"
	"log"
	"net/http"

	"nama-project/internal/service"
)

type ProdukHandler struct {
	service *service.ProdukService
}

func NewProdukHandler(s *service.ProdukService) *ProdukHandler {
	return &ProdukHandler{service: s}
}

func (h *ProdukHandler) List(w http.ResponseWriter, r *http.Request) {
	daftar, err := h.service.ListProduk(r.Context())
	if err != nil {
		switch {
		case errors.Is(err, context.DeadlineExceeded):
			log.Println("query produk melebihi batas waktu")
			http.Error(w, "permintaan terlalu lama diproses", http.StatusGatewayTimeout)
		case errors.Is(err, context.Canceled):
			log.Println("klien membatalkan permintaan produk")
		default:
			log.Println("gagal mengambil produk:", err)
			http.Error(w, "terjadi kesalahan di server", http.StatusInternalServerError)
		}
		return
	}

	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(daftar)
}

Saat context batal karena klien pergi, kita hanya menulis log tanpa mengirim response. Wajar, karena tidak ada lagi yang menerimanya.

Menguji Kondisi Normal

$ curl -i http://localhost:8080/api/produk

HTTP/1.1 200 OK
Content-Type: application/json

[{"id":1,"nama":"Kopi Gayo 250g","harga":85000},
 {"id":2,"nama":"Kopi Toraja 250g","harga":92000}]

Cepat dan tidak ada yang aneh. Timeout 3 detik tidak pernah tersentuh.

Menguji Kondisi Timeout

Untuk membuktikan timeout bekerja, sisipkan query lambat sementara di FindAll. Di MySQL pakai SELECT SLEEP(6), di PostgreSQL pakai SELECT pg_sleep(6).

query := "SELECT SLEEP(6)"

Lalu panggil lagi endpointnya.

$ curl -i -w "\nwaktu total: %{time_total}s\n" http://localhost:8080/api/produk

HTTP/1.1 504 Gateway Timeout
Content-Type: text/plain; charset=utf-8

permintaan terlalu lama diproses
waktu total: 3.012s

Log servernya:

2026/07/26 10:14:22 query produk melebihi batas waktu

Tiga detik, bukan enam. Pengguna dapat jawaban yang jelas, koneksi database kembali ke pool, dan server Anda tidak menahan pekerjaan yang tidak berguna. Setelah selesai mencoba, kembalikan query aslinya.

Rangkuman

Context itu kontrak kecil dengan efek besar. Isinya cuma kabar batal dan batas waktu, tapi dia yang menjaga aplikasi Anda tetap waras saat trafik naik.

Tiga hal yang layak Anda bawa pulang. Selalu tulis defer cancel(). Selalu taruh ctx sebagai parameter pertama. Selalu alirkan context sampai ke query database, jangan berhenti di service.

Kalau Anda sudah sampai sini, aplikasi Go Anda sudah punya struktur rapi dan kontrol waktu yang jelas. Yang belum, cara mencatat apa yang terjadi saat ada masalah. Itu bahasan bagian 18: Logging dan Error Handling yang Rapi di Aplikasi Go.

Kalau Anda butuh partner untuk membangun aplikasi backend yang siap dipakai banyak pengguna, tim kami siap bantu lewat layanan pengembangan sistem aplikasi.

Di Belajar Golang dari Nol #15 kita sudah menaruh API produk di server. Binary sudah jalan sebagai service. Domain sudah dipasang. Secara fungsi, aplikasinya hidup dan bisa dipakai orang lain.

Tapi coba buka lagi folder projectnya. Kemungkinan besar isinya masih sedikit file yang gemuk. Satu main.go yang menampung hampir semua hal. Selama masih dikerjakan sendiri, itu belum terasa mengganggu. Masalah baru muncul saat aplikasinya tumbuh atau ada orang kedua yang ikut menyentuh kodenya.

Bagian ini membahas cara merapikan project Go supaya tetap enak dipakai jangka panjang. Kita tidak menambah fitur baru. Kita memindahkan kode yang sudah ada ke tempat yang lebih masuk akal.

Tanda project Go mulai berantakan

Sebelum merapikan, kenali dulu gejalanya. Kalau salah satu tanda di bawah ini terasa familiar, project Anda sudah waktunya ditata.

• File main.go tembus ratusan baris. Setiap kali ingin mengubah satu hal kecil, Anda harus scroll jauh untuk menemukannya.
• Handler menempel langsung ke query database. Fungsi yang tugasnya membalas HTTP juga menulis SELECT dan INSERT di dalamnya.
• Susah dites. Untuk menguji satu aturan sederhana seperti “harga tidak boleh nol”, Anda terpaksa menyalakan database dulu.
• Dua orang mengedit file yang sama. Setiap pull request berakhir dengan konflik di file yang itu-itu saja.
• Aturan bisnis tercecer. Validasi nama produk ada di handler, validasi stok ada di tempat lain, dan tidak ada yang tahu mana yang benar.

Inti masalahnya satu. Terlalu banyak tanggung jawab dijejalkan ke satu tempat.

Prinsip: pisahkan berdasarkan tanggung jawab

Banyak pemula memisahkan file berdasarkan jenisnya. Semua struct masuk folder models. Semua fungsi HTTP masuk folder handlers. Semua query masuk folder database. Kelihatan rapi di awal, tapi setiap kali menambah satu fitur Anda harus membuka tiga folder berbeda.

Cara yang lebih tahan lama adalah memisahkan berdasarkan tanggung jawab, lalu mengelompokkannya per fitur. Untuk aplikasi web biasa, tiga lapis sudah cukup.

Lapis 1: handler

Tugasnya menerima request dan membalas response. Dia membaca body JSON, mengambil parameter dari URL, memanggil lapis di bawahnya, lalu menulis hasilnya kembali sebagai JSON. Handler tidak boleh tahu soal SQL. Handler juga tidak memutuskan apakah sebuah harga valid.

Lapis 2: service

Tempat aturan bisnis tinggal. Nama produk wajib diisi. Harga harus lebih dari nol. Stok minus dianggap nol. Service tidak tahu apa-apa soal HTTP. Dia tidak tahu status code, tidak tahu header, tidak tahu request. Karena itu, service bisa dipakai ulang dari mana saja, termasuk dari CLI atau worker.

Lapis 3: repository

Satu-satunya bagian yang bicara ke database. Query SQL hanya boleh ada di sini. Kalau suatu hari Anda ganti dari PostgreSQL ke MySQL, atau menambah cache, yang berubah cuma lapis ini.

Arah panggilannya selalu satu arah: handler memanggil service, service memanggil repository. Tidak pernah sebaliknya. Aturan sederhana ini yang menjaga project tetap waras.

Struktur folder yang disarankan

Untuk API produk yang kita bangun sejak bagian 11, struktur folder yang saya sarankan seperti ini.

tokoapi/
├── cmd/
│   └── api/
│       └── main.go
├── internal/
│   ├── config/
│   │   └── config.go
│   ├── middleware/
│   │   ├── log.go
│   │   └── recover.go
│   └── produk/
│       ├── handler.go
│       ├── model.go
│       ├── repository.go
│       ├── service.go
│       └── service_test.go
├── go.mod
└── go.sum

Kenapa ada folder cmd

Folder cmd berisi titik masuk program. Satu subfolder untuk satu binary. Sekarang isinya baru cmd/api. Nanti kalau Anda butuh program tambahan, misalnya pengirim laporan harian, tinggal buat cmd/worker/main.go tanpa mengganggu API. Keduanya berbagi kode yang sama di internal.

Perintah build dan run jadi sedikit lebih panjang, tapi masih sederhana.

go run ./cmd/api
go build -o bin/api ./cmd/api

Kenapa ada folder internal

Ini bukan sekadar kebiasaan penamaan. internal adalah fitur bawaan Go. Package yang ada di dalam folder bernama internal hanya bisa diimport oleh kode yang berada di dalam module yang sama. Project lain yang mengimport module Anda akan langsung ditolak oleh compiler.

Manfaatnya jelas. Anda bebas mengubah isi internal/produk kapan saja tanpa takut merusak project orang. Kalau suatu saat Anda memang ingin membagikan sebagian kode ke publik, pindahkan package itu keluar dari internal, misalnya ke folder pkg. Selama belum yakin, taruh saja semuanya di internal.

Refactor bertahap dari kode bagian 12 dan 13

Jangan bongkar semuanya sekaligus. Pindahkan satu lapis, jalankan aplikasinya, pastikan masih normal, baru lanjut ke lapis berikutnya.

Urutan yang paling aman adalah dari bawah ke atas. Mulai dari model, lalu repository, lalu service, terakhir handler. Alasannya sederhana. Lapis bawah tidak bergantung pada lapis atas, jadi memindahkannya tidak akan membuat kode lain rusak. Kalau Anda mulai dari handler, semua yang dipanggilnya masih berserakan dan Anda akan terjebak memindahkan banyak hal sekaligus.

Satu file berisi konfigurasi juga sebaiknya ikut dipindah ke internal/config. Isinya membaca environment variable yang sudah kita siapkan waktu deploy di bagian 15, lalu mengembalikannya sebagai struct. Dengan begitu, tidak ada lagi os.Getenv yang tersebar di tengah kode.

model.go

Mulai dari yang paling gampang. Pindahkan struct produk ke filenya sendiri.

package produk

import "time"

type Produk struct {
	ID         int64     `json:"id"`
	Nama       string    `json:"nama"`
	Harga      int64     `json:"harga"`
	Stok       int       `json:"stok"`
	DibuatPada time.Time `json:"dibuat_pada"`
}

Perhatikan nama packagenya: produk, bukan models. Karena package sudah bernama produk, penulisan dari luar jadi produk.Produk. Tidak perlu menambah awalan atau akhiran apa pun pada nama struct.

repository.go

Sekarang pindahkan semua query yang tadinya menempel di handler. Repository menyimpan *sql.DB sebagai field, bukan mengambilnya dari variabel global.

package produk

import (
	"context"
	"database/sql"
)

type Repository struct {
	db *sql.DB
}

func NewRepository(db *sql.DB) *Repository {
	return &Repository{db: db}
}

func (r *Repository) Ambil(ctx context.Context, id int64) (Produk, error) {
	query := `SELECT id, nama, harga, stok, dibuat_pada FROM produk WHERE id = $1`

	var p Produk
	err := r.db.QueryRowContext(ctx, query, id).
		Scan(&p.ID, &p.Nama, &p.Harga, &p.Stok, &p.DibuatPada)
	if err != nil {
		return Produk{}, err
	}

	return p, nil
}

func (r *Repository) Simpan(ctx context.Context, p Produk) (Produk, error) {
	query := `INSERT INTO produk (nama, harga, stok)
		VALUES ($1, $2, $3)
		RETURNING id, dibuat_pada`

	err := r.db.QueryRowContext(ctx, query, p.Nama, p.Harga, p.Stok).
		Scan(&p.ID, &p.DibuatPada)
	if err != nil {
		return Produk{}, err
	}

	return p, nil
}

service.go

Semua if validasi yang tadinya berserakan di handler kita kumpulkan di sini. Errornya dibuat sebagai variabel supaya bisa dicek dari luar.

package produk

import (
	"context"
	"errors"
	"strings"
)

var (
	ErrNamaKosong = errors.New("nama produk tidak boleh kosong")
	ErrHargaSalah = errors.New("harga produk harus lebih dari nol")
)

type PenyimpanProduk interface {
	Ambil(ctx context.Context, id int64) (Produk, error)
	Simpan(ctx context.Context, p Produk) (Produk, error)
}

type Service struct {
	repo PenyimpanProduk
}

func NewService(repo PenyimpanProduk) *Service {
	return &Service{repo: repo}
}

func (s *Service) Buat(ctx context.Context, p Produk) (Produk, error) {
	p.Nama = strings.TrimSpace(p.Nama)

	if p.Nama == "" {
		return Produk{}, ErrNamaKosong
	}
	if p.Harga <= 0 {
		return Produk{}, ErrHargaSalah
	}
	if p.Stok < 0 {
		p.Stok = 0
	}

	return s.repo.Simpan(ctx, p)
}

func (s *Service) Detail(ctx context.Context, id int64) (Produk, error) {
	return s.repo.Ambil(ctx, id)
}

Ada satu hal penting di sini. Field repo bertipe PenyimpanProduk, bukan *Repository. Alasannya kita bahas sebentar lagi di bagian testing.

handler.go

Sisa tugas handler tinggal tiga: baca request, panggil service, tulis JSON.

package produk

import (
	"encoding/json"
	"net/http"
	"strconv"
)

type Handler struct {
	svc *Service
}

func NewHandler(svc *Service) *Handler {
	return &Handler{svc: svc}
}

func (h *Handler) Buat(w http.ResponseWriter, r *http.Request) {
	var body Produk
	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
		tulisJSON(w, http.StatusBadRequest, map[string]string{"error": "body tidak valid"})
		return
	}

	hasil, err := h.svc.Buat(r.Context(), body)
	if err != nil {
		tulisJSON(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
		return
	}

	tulisJSON(w, http.StatusCreated, hasil)
}

func (h *Handler) Detail(w http.ResponseWriter, r *http.Request) {
	id, err := strconv.ParseInt(r.PathValue("id"), 10, 64)
	if err != nil {
		tulisJSON(w, http.StatusBadRequest, map[string]string{"error": "id tidak valid"})
		return
	}

	hasil, err := h.svc.Detail(r.Context(), id)
	if err != nil {
		tulisJSON(w, http.StatusNotFound, map[string]string{"error": "produk tidak ditemukan"})
		return
	}

	tulisJSON(w, http.StatusOK, hasil)
}

func tulisJSON(w http.ResponseWriter, status int, data any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	json.NewEncoder(w).Encode(data)
}

Handler ini jadi jauh lebih pendek daripada versi bagian 12. Tidak ada SQL, tidak ada validasi. Kalau ada bug di aturan harga, Anda tahu persis harus membuka file mana.

Merangkai dependensi tanpa framework

Di bahasa lain, urusan seperti ini sering diserahkan ke library dependency injection. Di Go, caranya jauh lebih sederhana dan tidak butuh library sama sekali.

Polanya cuma dua langkah. Pertama, simpan dependensi sebagai field di dalam struct. Kedua, buat fungsi constructor yang menerimanya dari luar. Itu yang sudah kita lakukan lewat NewRepository, NewService, dan NewHandler.

Semua rangkaiannya dipasang di satu tempat: main.go.

package main

import (
	"log"
	"net/http"

	"github.com/vandy/tokoapi/internal/config"
	"github.com/vandy/tokoapi/internal/middleware"
	"github.com/vandy/tokoapi/internal/produk"
)

func main() {
	cfg := config.Muat()

	db, err := config.BukaDB(cfg.DatabaseURL)
	if err != nil {
		log.Fatalf("gagal konek database: %v", err)
	}
	defer db.Close()

	repo := produk.NewRepository(db)
	svc := produk.NewService(repo)
	h := produk.NewHandler(svc)

	mux := http.NewServeMux()
	mux.HandleFunc("POST /produk", h.Buat)
	mux.HandleFunc("GET /produk/{id}", h.Detail)

	handler := middleware.Log(middleware.Recover(mux))

	log.Printf("server jalan di %s", cfg.Alamat)
	if err := http.ListenAndServe(cfg.Alamat, handler); err != nil {
		log.Fatal(err)
	}
}

Sekarang main.go bisa dibaca dalam satu tarikan napas. Baca config, buka database, rangkai tiga lapis, daftarkan route, pasang middleware dari bagian 13, nyalakan server. Orang baru yang bergabung ke tim bisa memahami alur aplikasi hanya dari file ini.

Kenapa struktur ini bikin testing gampang

Di bagian 14 kita menulis test dan sempat repot karena kodenya menempel ke database. Struktur baru ini menyelesaikan masalah itu.

Kuncinya ada di interface PenyimpanProduk tadi. Karena Service menyimpan interface, bukan struct konkret, kita bisa memberinya repository palsu saat testing. Ini pemakaian nyata dari interface yang kita pelajari di bagian 9.

package produk

import (
	"context"
	"errors"
	"testing"
)

type repoPalsu struct {
	tersimpan Produk
}

func (r *repoPalsu) Ambil(ctx context.Context, id int64) (Produk, error) {
	return Produk{ID: id, Nama: "Kopi Susu", Harga: 18000}, nil
}

func (r *repoPalsu) Simpan(ctx context.Context, p Produk) (Produk, error) {
	p.ID = 1
	r.tersimpan = p
	return p, nil
}

func TestBuatMenolakNamaKosong(t *testing.T) {
	svc := NewService(&repoPalsu{})

	_, err := svc.Buat(context.Background(), Produk{Nama: "   ", Harga: 18000})

	if !errors.Is(err, ErrNamaKosong) {
		t.Fatalf("harusnya ErrNamaKosong, dapat: %v", err)
	}
}

Test ini jalan dalam hitungan milidetik. Tidak ada database yang perlu dinyalakan, tidak ada tabel yang perlu dibersihkan. Anda bisa menjalankannya di laptop maupun di CI tanpa setup tambahan.

Perhatikan juga bahwa repoPalsu tidak perlu mengimplementasikan seluruh method Repository. Cukup method yang ada di interface. Semakin kecil interfacenya, semakin mudah dipalsukan.

Kapan struktur ini tidak perlu

Bagian ini sering dilewatkan orang, padahal penting.

Kalau program Anda cuma 200 baris, satu file main.go itu sah. Script yang mengubah CSV jadi JSON tidak butuh folder internal. Tool kecil yang memanggil satu API tidak butuh lapis service. Membuat lima lapis untuk kode sependek itu justru bikin Anda lebih lama menemukan sesuatu.

Pegangan yang saya pakai kira-kira begini:

• Di bawah 300 baris, satu file. Belum ada yang perlu dipisah.
• Mulai ada dua atau tiga fitur. Pecah per fitur dulu, belum perlu tiga lapis penuh.
• Sudah ada database, aturan bisnis, dan lebih dari satu orang yang mengerjakan. Baru pakai struktur tiga lapis seperti di atas.

Struktur mengikuti kebutuhan, bukan gengsi. Kalau Anda tidak bisa menjelaskan kenapa sebuah folder ada, kemungkinan folder itu memang belum perlu ada.

Konvensi penamaan file dan folder

Go punya beberapa kebiasaan yang sebaiknya diikuti supaya kode Anda terasa familiar bagi programmer Go lain.

• Nama folder dan package huruf kecil semua. Tanpa underscore, tanpa strip, tanpa huruf besar. Tulis produk, bukan Produk atau produk_service.
• Nama package sebaiknya kata tunggal. config, middleware, produk. Hindari nama kosong makna seperti utils, helpers, atau common, karena isinya cepat berubah jadi tempat sampah.
• Nama file boleh pakai underscore. Contohnya produk_handler.go. Tapi karena packagenya sudah bernama produk, cukup handler.go.
• Akhiran _test.go wajib untuk file test. Ini aturan compiler, bukan selera.
• Jangan mengulang nama package di nama tipe. Cukup produk.Service, jangan produk.ProdukService.

Satu catatan jujur soal struktur folder. Tim Go tidak pernah merilis struktur project resmi. Repository populer bernama golang-standards/project-layout sering dikutip sebagai standar, padahal itu proyek komunitas dan banyak developer Go senior menganggapnya kelewat rumit untuk aplikasi biasa.

Jadi jangan bingung kalau Anda menemukan lima tutorial dengan lima struktur berbeda. Yang penting bukan meniru persis, melainkan konsisten di dalam satu project dan punya alasan untuk setiap folder yang Anda buat.

Rangkuman

Merapikan project bukan soal estetika. Tujuannya supaya perubahan berikutnya lebih murah. Tiga hal yang perlu Anda bawa dari bagian ini: pisahkan berdasarkan tanggung jawab, rangkai dependensi lewat constructor di main.go, dan pakai interface supaya service bisa dites tanpa database.

Coba refactor project Anda sendiri sekarang. Pindahkan satu lapis dulu, jalankan, baru lanjut.

Di bagian 17 kita masuk ke topik yang selalu muncul begitu aplikasi dipakai banyak orang: Context di Go: Timeout, Pembatalan, dan Request yang Sehat. Parameter ctx yang sejak tadi kita bawa ke mana-mana akhirnya akan terpakai sungguhan di sana.

Kalau Anda butuh bantuan menata ulang aplikasi Go yang sudah terlanjur besar atau ingin membangun sistem baru dengan fondasi yang benar sejak awal, tim kami siap membantu lewat layanan pengembangan sistem dan aplikasi.

Di Belajar Golang dari Nol #14 kita menutup API produk dengan testing. Database sudah jalan, middleware auth sudah pasang, dan test-nya hijau semua. Tapi API itu masih hidup di satu tempat: laptop kamu.

Bagian ini kita pindahkan ke server. Target akhirnya jelas. API bisa diakses dari internet lewat domain, pakai HTTPS, tetap hidup walau SSH ditutup, dan otomatis nyala lagi kalau server reboot.

Saya tulis langkahnya berurutan. Ikuti pelan-pelan. Setiap langkah ada cara mengeceknya sebelum lanjut ke langkah berikutnya.

Kenapa deploy aplikasi Go itu jauh lebih santai

Ingat bagian 1 waktu kita bahas kenapa Go dipilih? Salah satu alasannya muncul persis di titik ini. Go itu bahasa yang dikompilasi jadi satu file binary. Bukan script yang butuh interpreter, bukan bytecode yang butuh virtual machine.

Artinya di server kamu tidak perlu install Go. Tidak perlu install runtime apa pun. Tidak ada folder vendor yang harus ikut diupload. Tidak ada perintah install dependency di server yang bisa gagal karena versi beda.

Bandingkan dengan aplikasi PHP atau Node.js. Di sana kamu perlu install PHP dengan ekstensi yang cocok, atau Node dengan versi yang cocok, lalu jalankan composer install atau npm install di server. Setiap komponen itu satu kemungkinan gagal.

Di Go, yang kamu kirim ke server cuma satu file. Itu saja. Sisanya tinggal mengatur cara menjalankannya.

Build binary untuk server Linux

Server kamu hampir pasti pakai Linux dengan arsitektur amd64. Laptop kamu mungkin macOS, mungkin Windows, mungkin Linux juga. Tidak masalah. Go bisa membuat binary untuk sistem lain langsung dari laptop kamu. Ini namanya cross compile.

Caranya cukup mengatur dua variabel sebelum perintah build:

GOOS=linux GOARCH=amd64 go build -o api-produk

GOOS menentukan sistem operasi target, GOARCH menentukan arsitektur prosesornya. Hasilnya file bernama api-produk yang siap jalan di server Linux, walaupun kamu build dari MacBook.

Kalau server kamu pakai prosesor ARM, misalnya beberapa VPS murah sekarang, ganti jadi GOARCH=arm64. Cek dulu di server dengan perintah uname -m. Kalau hasilnya x86_64 berarti amd64. Kalau aarch64 berarti arm64.

Di Windows PowerShell sintaksnya sedikit berbeda:

$env:GOOS="linux"; $env:GOARCH="amd64"; go build -o api-produk

Mengecilkan ukuran binary

Binary Go biasanya berukuran belasan sampai puluhan megabyte. Itu wajar karena semua yang dibutuhkan sudah ikut di dalamnya. Kalau mau lebih ramping, buang informasi debug:

GOOS=linux GOARCH=amd64 go build -ldflags "-s -w" -o api-produk

Flag -s membuang tabel simbol, -w membuang informasi DWARF. Ukuran biasanya turun sekitar 25 sampai 30 persen. Ini opsional. Efek sampingnya, stack trace saat panic jadi kurang detail. Untuk API kecil yang lognya sudah rapi, ini pertukaran yang masuk akal.

Siapkan kode untuk production

Sebelum diupload, ada satu hal yang harus dibereskan di kode. Selama 14 bagian sebelumnya kita menulis port dan koneksi database langsung di dalam kode. Untuk belajar itu tidak apa-apa. Untuk production itu masalah.

Kenapa? Karena kredensial database production tidak boleh masuk ke Git. Dan karena port di server bisa saja berbeda dengan di laptop. Kalau nilai-nilai ini di-hardcode, kamu harus edit kode dan build ulang setiap kali konfigurasinya berubah.

Solusinya pakai environment variable. Bikin satu helper kecil yang membaca env dengan nilai cadangan:

func getEnv(key, fallback string) string {
	if value := os.Getenv(key); value != "" {
		return value
	}
	return fallback
}

Lalu pakai di fungsi main:

func main() {
	port := getEnv("PORT", "8080")
	dsn := getEnv("DB_DSN", "root:@tcp(127.0.0.1:3306)/toko?parseTime=true")

	db, err := sql.Open("mysql", dsn)
	if err != nil {
		log.Fatal("gagal koneksi database: ", err)
	}
	defer db.Close()

	if err := db.Ping(); err != nil {
		log.Fatal("database tidak merespons: ", err)
	}

	log.Printf("server jalan di port %s", port)
	log.Fatal(http.ListenAndServe(":"+port, router(db)))
}

Sekarang di laptop kamu tetap bisa jalan tanpa set apa-apa karena ada nilai default. Di server, nilai aslinya nanti diisi lewat file environment yang kita buat sebentar lagi.

Satu catatan penting. Jangan lupa db.Ping(). Fungsi sql.Open tidak benar-benar menyambung ke database, dia cuma menyiapkan koneksi. Tanpa Ping, aplikasi kamu akan terlihat sukses jalan padahal kredensialnya salah.

Kirim binary ke server

Sekarang upload. Pakai scp dari folder tempat binary tadi dibuat:

scp api-produk deploy@103.10.20.30:/home/deploy/

Ganti deploy dengan user di server kamu dan IP-nya dengan IP VPS kamu. Setelah selesai, masuk ke server:

ssh deploy@103.10.20.30

Beri izin eksekusi, lalu jalankan langsung untuk tes pertama:

chmod +x /home/deploy/api-produk
DB_DSN="user:password@tcp(127.0.0.1:3306)/toko?parseTime=true" ./api-produk

Kalau muncul log “server jalan di port 8080”, berarti binary-nya sehat. Biarkan terminal itu terbuka. Buka terminal baru di laptop kamu dan tes dari luar:

curl http://103.10.20.30:8080/produk

Kalau balasannya JSON produk, selamat, API kamu sudah hidup di internet. Kalau timeout, kemungkinan besar firewall server belum membuka port 8080. Tidak perlu dibuka permanen, karena sebentar lagi Nginx yang akan menangani lalu lintas dari luar.

Sekarang tekan Ctrl+C di server untuk mematikannya. Kita akan jalankan dengan cara yang benar.

Bikin API tetap hidup dengan systemd

Masalah dari ./api-produk tadi jelas. Begitu SSH ditutup, prosesnya ikut mati. Kalau aplikasi crash, tidak ada yang menghidupkan lagi. Kalau server reboot, API kamu diam saja.

Jawabannya systemd. Ini pengelola service bawaan hampir semua Linux modern. Dia yang akan menyalakan, mengawasi, dan menghidupkan ulang aplikasi kamu.

Pertama, simpan kredensial di file environment terpisah:

sudo nano /etc/api-produk.env

Isinya begini, satu baris satu variabel, tanpa spasi di sekitar tanda sama dengan dan tanpa tanda kutip:

PORT=8080
DB_DSN=user:password@tcp(127.0.0.1:3306)/toko?parseTime=true

Kunci filenya supaya tidak bisa dibaca user lain:

sudo chmod 640 /etc/api-produk.env
sudo chown root:deploy /etc/api-produk.env

Sekarang buat file unit systemd:

sudo nano /etc/systemd/system/api-produk.service

Isi lengkapnya:

[Unit]
Description=API Produk Go
After=network.target mysql.service

[Service]
Type=simple
User=deploy
Group=deploy
WorkingDirectory=/home/deploy
EnvironmentFile=/etc/api-produk.env
ExecStart=/home/deploy/api-produk
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Mari bedah bagian yang penting.

• After=network.target menunda start sampai jaringan siap.
• User=deploy menjalankan aplikasi sebagai user biasa, bukan root. Ini penting untuk keamanan. Kalau aplikasi kamu dibobol, penyerang tidak langsung dapat akses root.
• WorkingDirectory menentukan folder kerja. Berguna kalau aplikasi kamu membaca file relatif, misalnya template atau file migrasi.
• EnvironmentFile menyuntikkan isi file env tadi ke proses.
• ExecStart harus pakai path absolut. Systemd tidak mengenal path relatif.
• Restart=always menghidupkan ulang aplikasi kalau mati karena alasan apa pun. RestartSec=5 memberi jeda 5 detik supaya tidak restart membabi buta saat database sedang bermasalah.
• WantedBy=multi-user.target yang membuat service ikut nyala saat server boot.

Muat ulang konfigurasi, aktifkan, lalu jalankan:

sudo systemctl daemon-reload
sudo systemctl enable api-produk
sudo systemctl start api-produk
sudo systemctl status api-produk

Perintah status harus menampilkan active (running) berwarna hijau. Kalau merah, jangan panik. Baca lognya:

sudo journalctl -u api-produk -n 50 --no-pager

Tambahkan -f kalau mau memantau log secara langsung sambil mengetes API:

sudo journalctl -u api-produk -f

Semua yang kamu tulis dengan log.Printf di kode Go akan muncul di sini. Ini yang menggantikan terminal yang biasa kamu lihat waktu development.

Nginx di depan sebagai reverse proxy

API kamu sekarang jalan di port 8080. Tapi orang tidak mau mengetik nomor port. Mereka mau mengetik nama domain.

Di sini Nginx masuk. Dia duduk di depan, menerima permintaan di port 80 dan 443, lalu meneruskannya ke aplikasi Go di port 8080. Ada tiga alasan kenapa ini layak:

• Port 80 dan 443 butuh hak root. Aplikasi Go kamu jalan sebagai user biasa, jadi tidak boleh memakainya langsung.
• Nginx yang mengurus sertifikat TLS. Kode Go kamu tidak perlu tahu soal HTTPS sama sekali.
• Satu server bisa menampung banyak domain dan banyak aplikasi sekaligus.

Buat konfigurasinya:

sudo nano /etc/nginx/sites-available/api-produk

Isi dengan server block sederhana:

server {
    listen 80;
    server_name api.domainkamu.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Empat header itu bukan formalitas. Tanpa X-Real-IP dan X-Forwarded-For, aplikasi Go kamu akan melihat semua pengunjung datang dari 127.0.0.1. Rate limiting dan log akses jadi tidak berguna.

Aktifkan konfigurasinya, cek dulu sintaksnya, baru muat ulang:

sudo ln -s /etc/nginx/sites-available/api-produk /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Selalu jalankan nginx -t sebelum reload. Kalau ada typo, dia akan bilang di baris berapa, dan Nginx yang sedang jalan tidak ikut tumbang.

Pastikan domain kamu sudah diarahkan ke IP server lewat DNS record tipe A sebelum lanjut. Tes dengan curl http://api.domainkamu.com/produk.

Pasang HTTPS gratis dengan Certbot

API tanpa HTTPS itu tidak layak dipakai. Token auth yang kita buat di bagian 13 akan melintas dalam bentuk teks polos. Untungnya sertifikat gratis dari Let’s Encrypt cuma butuh dua perintah.

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d api.domainkamu.com

Certbot akan minta email, minta persetujuan, lalu menawarkan redirect otomatis dari HTTP ke HTTPS. Pilih ya. Setelah selesai, dia mengedit sendiri file Nginx tadi dan menambahkan blok listen 443 lengkap dengan path sertifikat.

Sertifikat Let’s Encrypt berlaku 90 hari. Certbot sudah memasang timer perpanjangan otomatis saat instalasi, jadi kamu tidak perlu mengingat tanggalnya. Kalau mau memastikan mekanismenya jalan:

sudo certbot renew --dry-run

Update versi tanpa drama

Aplikasi kamu akan berubah. Alurnya cuma tiga langkah dan selalu sama:

GOOS=linux GOARCH=amd64 go build -ldflags "-s -w" -o api-produk
scp api-produk deploy@103.10.20.30:/home/deploy/
ssh deploy@103.10.20.30 "sudo systemctl restart api-produk"

Downtime-nya sangat pendek, biasanya di bawah satu detik. Alasannya kembali ke sifat Go tadi. Systemd cuma perlu mematikan satu proses dan menyalakan satu binary. Tidak ada kompilasi di server, tidak ada cache yang harus dihangatkan, tidak ada dependency yang diunduh ulang.

Satu tips kecil. Kalau scp gagal karena file sedang dipakai, matikan service dulu sebelum upload, atau upload dengan nama sementara lalu ganti nama setelah service berhenti.

Kamu mungkin pernah dengar Docker sebagai alternatif. Docker memang jalan lain yang valid, terutama kalau aplikasi kamu butuh banyak layanan pendamping atau kamu berencana pindah ke Kubernetes. Tapi untuk satu API Go di satu VPS, systemd sudah cukup dan jauh lebih sedikit bagian yang harus dipelajari. Simpan Docker untuk saat kebutuhannya benar-benar muncul.

Checklist sebelum bilang selesai

Lima hal ini yang sering terlewat. Cek satu per satu:

• Environment variable terpasang. Jalankan sudo systemctl show api-produk -p Environment atau cek langsung apakah aplikasi berhasil konek ke database production, bukan ke default.
• Log terbaca. Pastikan journalctl -u api-produk memunculkan sesuatu saat kamu mengirim request. Kalau log kosong, kamu buta saat ada masalah.
• Service nyala saat reboot. Jangan cuma percaya. Uji dengan sudo reboot, tunggu sebentar, lalu cek statusnya lagi. Kalau lupa systemctl enable, di sinilah ketahuannya.
• Backup database berjalan. Minimal cron harian yang menjalankan mysqldump ke folder terpisah. Backup yang belum pernah dicoba direstore itu belum bisa disebut backup.
• Firewall rapat. Buka hanya port 22, 80, dan 443. Port 8080 dan port database tidak boleh terlihat dari internet. Cek dengan sudo ufw status.

Sejauh mana tutorial ini berlaku

Saya perlu jujur soal batasnya. Cara di atas cocok untuk API kecil sampai menengah yang jalan di satu VPS. Itu mencakup sebagian besar aplikasi internal, dashboard perusahaan, dan produk yang baru mulai. Banyak sistem berjalan bertahun-tahun dengan setup persis seperti ini.

Yang tidak dibahas di sini adalah situasi skala besar. Kalau kamu butuh beberapa server di belakang load balancer, deploy tanpa downtime sama sekali, rollback otomatis saat error rate naik, atau pipeline CI yang build dan deploy sendiri setiap kali kode di-merge, itu topik lain dengan alat lain. Silakan pindah ke sana kalau memang trafiknya sudah menuntut, bukan sebelum itu.

Sekarang API produk kamu sudah hidup di server dengan domain dan HTTPS. Di bagian 16 kita kembali ke kode: Struktur Project Go yang Rapi untuk Aplikasi Nyata. Semua file yang selama ini menumpuk di satu folder akan kita tata supaya masih enak dibaca enam bulan lagi.

Kalau kamu butuh bantuan membangun dan mengelola API produksi untuk kebutuhan bisnis, tim Arrazy Inovasi mengerjakan pengembangan sistem dan aplikasi dari perencanaan sampai deploy di server.