Membangun HTTP Handler
dengan net/http

Sebelum chi, pahami kontrak HTTP bawaan Go

Kalau kamu pernah menulis Express.js, Laravel controller, atau Next.js route handler, konsep handler di Go punya tujuan yang sama: menerima request, memutuskan respons, lalu mengembalikannya ke client.

Di Express.js kamu biasa menulis fungsi seperti (req, res) => res.json(data). Di Go bentuknya mirip secara mental, tetapi berbeda secara kontrak: handler menerima http.ResponseWriter dan *http.Request, lalu menulis respons melalui writer.

Tujuan modul ini bukan membuat arsitektur final. Tujuannya adalah membuat kamu nyaman dengan bahan mentah yang akan dipakai lagi saat memakai chi, handler testing, middleware, context, dan repository PostgreSQL.

Kontrak paling kecil untuk menerima HTTP request

Di Go, server HTTP tidak peduli handler kamu berupa struct, function, atau router besar, selama nilainya memenuhi interface http.Handler.

Bentuk sederhananya seperti ini.

kontrak-handler.goSalin
type Handler interface {
	ServeHTTP(ResponseWriter, *Request)
}

Karena interface Go dipenuhi secara implicit, struct apa pun yang punya method ServeHTTP otomatis bisa menjadi handler.

internal/product/handler_struct.goSalin
type ProductHandler struct {
	// nanti diisi service atau repository
}

func (h ProductHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("product handler"))
}

Untuk kasus sederhana, kamu tidak perlu membuat struct. http.HandlerFunc adalah adapter yang mengubah fungsi biasa menjadi http.Handler.

handlerfunc.goSalin
func healthHandler(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("ok"))
}

mux.HandleFunc("GET /health", healthHandler)

Yang membuat kontrak ini kuat: http.ServeMux sendiri juga memenuhi http.Handler. Jadi router, middleware, dan handler kamu adalah jenis nilai yang sama, dan bisa saling dibungkus tanpa batas.

flowchart LR
  REQ([HTTP Request]) --> SRV["http.Server"]
  SRV --> MUX["ServeMux<br/>(juga http.Handler)"]
  MUX -->|cocokkan pattern route| H["HandlerFunc / struct<br/>ServeHTTP(w, r)"]
  H --> RESP([HTTP Response])

Gambar 1. Semua komponen di rantai ini adalah http.Handler, sehingga middleware nanti cukup membungkus handler dan mengembalikan handler lagi.

Dua objek utama dalam setiap handler

Semua handler Go berputar di sekitar dua parameter: w untuk menulis respons dan r untuk membaca request.

*http.Request menyimpan data yang datang dari client. Untuk backend API, bagian yang paling sering kamu baca adalah r.Method, r.URL.Path, r.URL.Query(), r.Header, r.Body, dan r.Context().

membaca-request.goSalin
func debugHandler(w http.ResponseWriter, r *http.Request) {
	method := r.Method
	path := r.URL.Path
	category := r.URL.Query().Get("category")
	requestID := r.Header.Get("X-Request-ID")

	_ = method
	_ = path
	_ = category
	_ = requestID

	w.WriteHeader(http.StatusNoContent)
}

http.ResponseWriter adalah interface dengan tiga method: Header() untuk mengubah header, WriteHeader(status) untuk mengirim status code, dan Write([]byte) untuk menulis body. Urutan yang aman adalah set header dulu, tulis status code, lalu tulis body.

menulis-response.goSalin
func helloHandler(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	w.WriteHeader(http.StatusOK)
	w.Write([]byte("hello from Go API"))
}

Diagram berikut menjelaskan kenapa urutan tadi penting. Begitu status terkirim, header membeku dan tidak bisa diubah lagi.

stateDiagram-v2
  [*] --> HeaderTerbuka
  HeaderTerbuka --> HeaderTerbuka: w.Header().Set(...)
  HeaderTerbuka --> StatusTerkirim: w.WriteHeader(status)
  StatusTerkirim --> BodyMengalir: w.Write(...)
  BodyMengalir --> BodyMengalir: w.Write(...) lagi
  BodyMengalir --> [*]
  note right of StatusTerkirim: Header beku di sini.<br/>Set header setelahnya diabaikan.

Gambar 2. Siklus menulis response. Set semua header sebelum WriteHeader, karena setelah status terkirim header tidak berpengaruh lagi.

Dalam proyek online shop skincare, handler produk akan membaca query seperti category=serum, header seperti Authorization, dan body JSON saat admin membuat produk baru.

Cara paling umum React frontend bicara dengan Go API

React frontend biasanya mengirim dan menerima JSON. Di Go, package encoding/json sudah cukup untuk tahap awal.

Untuk respons JSON, set Content-Type, status code, lalu pakai json.NewEncoder(w).Encode(payload).

json-response.goSalin
type ProductResponse struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	PriceRupiah int64  `json:"price"`
}

func productHandler(w http.ResponseWriter, r *http.Request) {
	product := ProductResponse{
		ID:          1,
		Name:        "Niacinamide Serum",
		PriceRupiah: 189000,
	}

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

Untuk request JSON, buat struct request, lalu decode dari r.Body.

json-request.goSalin
type CreateProductRequest struct {
	Name        string `json:"name"`
	Category    string `json:"category"`
	PriceRupiah int64  `json:"price"`
	Stock       int    `json:"stock"`
}

func createProductHandler(w http.ResponseWriter, r *http.Request) {
	var req CreateProductRequest
	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
		http.Error(w, "invalid JSON", http.StatusBadRequest)
		return
	}

	w.WriteHeader(http.StatusCreated)
}

Ada dua helper kecil yang hampir selalu kita buat agar handler tidak mengulang boilerplate.

response.goSalin
func writeJSON(w http.ResponseWriter, status int, payload any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	if err := json.NewEncoder(w).Encode(payload); err != nil {
		slog.Error("encode response", "error", err)
	}
}

func writeError(w http.ResponseWriter, status int, message string) {
	writeJSON(w, status, map[string]string{"error": message})
}

decode-dengan-batas.goSalin
r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // 1 MB

decoder := json.NewDecoder(r.Body)
decoder.DisallowUnknownFields()
if err := decoder.Decode(&req); err != nil {
	writeError(w, http.StatusBadRequest, "request body tidak valid")
	return
}

Client React bergantung pada status code yang konsisten

Status code bukan kosmetik. Ia adalah kontrak yang membuat frontend, mobile app, worker, dan payment provider tahu hasil request tanpa menebak isi body.

Di Go, status code dikirim dengan w.WriteHeader(code). Bila kamu langsung memanggil w.Write(...) tanpa WriteHeader, Go akan mengirim 200 OK secara implicit.

status-code.goSalin
func createProductHandler(w http.ResponseWriter, r *http.Request) {
	// setelah produk berhasil dibuat
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusCreated)
	json.NewEncoder(w).Encode(product)
}

Pola guard clause dari React sangat cocok di Go. Validasi error lebih baik return lebih awal.

guard-clause.goSalin
if err := decoder.Decode(&req); err != nil {
	writeError(w, http.StatusBadRequest, "JSON tidak valid")
	return
}

if req.PriceRupiah <= 0 {
	writeError(w, http.StatusUnprocessableEntity, "harga harus lebih dari 0")
	return
}

Satu file lengkap tanpa chi, fokus ke net/http

Contoh ini sengaja memakai in-memory store agar perhatian kita tetap pada handler HTTP, bukan database.

handler.goSalin
package main

import (
	"encoding/json"
	"errors"
	"log/slog"
	"net/http"
	"os"
	"sort"
	"strconv"
	"strings"
	"sync"
)

type Product struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	Category    string `json:"category"`
	PriceRupiah int64  `json:"price"`
	Stock       int    `json:"stock"`
	Description string `json:"description,omitempty"`
	Status      string `json:"status"`
}

type CreateProductRequest struct {
	Name        string `json:"name"`
	Category    string `json:"category"`
	PriceRupiah int64  `json:"price"`
	Stock       int    `json:"stock"`
	Description string `json:"description"`
}

type ErrorResponse struct {
	Error string `json:"error"`
}

type ProductStore struct {
	mu       sync.RWMutex
	nextID   int64
	products map[int64]Product
}

func main() {
	store := NewProductStore()

	mux := http.NewServeMux()
	mux.HandleFunc("GET /health", healthHandler)
	mux.HandleFunc("GET /v1/products", store.ListProducts)
	mux.HandleFunc("POST /v1/products", store.CreateProduct)
	mux.HandleFunc("GET /v1/products/{id}", store.GetProduct)

	addr := ":8080"
	slog.Info("server listening", "addr", addr)
	if err := http.ListenAndServe(addr, mux); err != nil {
		slog.Error("server stopped", "error", err)
		os.Exit(1)
	}
}

func NewProductStore() *ProductStore {
	return &ProductStore{
		nextID: 4,
		products: map[int64]Product{
			1: {ID: 1, Name: "Hydrating Cleanser", Category: "cleanser", PriceRupiah: 129000, Stock: 40, Status: "active"},
			2: {ID: 2, Name: "Niacinamide Serum", Category: "serum", PriceRupiah: 189000, Stock: 22, Status: "active"},
			3: {ID: 3, Name: "Daily Sunscreen SPF 50", Category: "sunscreen", PriceRupiah: 159000, Stock: 35, Status: "active"},
		},
	}
}

func healthHandler(w http.ResponseWriter, r *http.Request) {
	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
}

func (s *ProductStore) ListProducts(w http.ResponseWriter, r *http.Request) {
	category := strings.TrimSpace(r.URL.Query().Get("category"))
	keyword := strings.ToLower(strings.TrimSpace(r.URL.Query().Get("q")))

	s.mu.RLock()
	products := make([]Product, 0, len(s.products))
	for _, product := range s.products {
		if category != "" && product.Category != category {
			continue
		}
		if keyword != "" && !strings.Contains(strings.ToLower(product.Name), keyword) {
			continue
		}
		products = append(products, product)
	}
	s.mu.RUnlock()

	// Iterasi map di Go acak. Urutkan agar urutan list stabil untuk frontend.
	sort.Slice(products, func(i, j int) bool {
		return products[i].ID < products[j].ID
	})

	writeJSON(w, http.StatusOK, products)
}

func (s *ProductStore) GetProduct(w http.ResponseWriter, r *http.Request) {
	id, err := parseID(r.PathValue("id"))
	if err != nil {
		writeError(w, http.StatusBadRequest, "product id harus berupa angka positif")
		return
	}

	s.mu.RLock()
	product, ok := s.products[id]
	s.mu.RUnlock()
	if !ok {
		writeError(w, http.StatusNotFound, "produk tidak ditemukan")
		return
	}

	writeJSON(w, http.StatusOK, product)
}

func (s *ProductStore) CreateProduct(w http.ResponseWriter, r *http.Request) {
	r.Body = http.MaxBytesReader(w, r.Body, 1<<20)

	var req CreateProductRequest
	decoder := json.NewDecoder(r.Body)
	decoder.DisallowUnknownFields()
	if err := decoder.Decode(&req); err != nil {
		writeError(w, http.StatusBadRequest, "request body harus berupa JSON produk yang valid")
		return
	}
	if err := validateCreateProduct(req); err != nil {
		writeError(w, http.StatusUnprocessableEntity, err.Error())
		return
	}

	s.mu.Lock()
	product := Product{
		ID:          s.nextID,
		Name:        strings.TrimSpace(req.Name),
		Category:    strings.TrimSpace(req.Category),
		PriceRupiah: req.PriceRupiah,
		Stock:       req.Stock,
		Description: strings.TrimSpace(req.Description),
		Status:      "active",
	}
	s.products[product.ID] = product
	s.nextID++
	s.mu.Unlock()

	writeJSON(w, http.StatusCreated, product)
}

func validateCreateProduct(req CreateProductRequest) error {
	if strings.TrimSpace(req.Name) == "" {
		return errors.New("nama produk wajib diisi")
	}
	if strings.TrimSpace(req.Category) == "" {
		return errors.New("kategori produk wajib diisi")
	}
	if req.PriceRupiah <= 0 {
		return errors.New("harga produk harus lebih dari 0")
	}
	if req.Stock < 0 {
		return errors.New("stok produk tidak boleh negatif")
	}
	return nil
}

func parseID(raw string) (int64, error) {
	id, err := strconv.ParseInt(raw, 10, 64)
	if err != nil || id <= 0 {
		return 0, errors.New("invalid id")
	}
	return id, nil
}

func writeJSON(w http.ResponseWriter, status int, payload any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	if err := json.NewEncoder(w).Encode(payload); err != nil {
		slog.Error("encode response", "error", err)
	}
}

func writeError(w http.ResponseWriter, status int, message string) {
	writeJSON(w, status, ErrorResponse{Error: message})
}

Diagram berikut menunjukkan alur satu request dari React app sampai respons JSON kembali.

sequenceDiagram
  participant FE as React Frontend
  participant MUX as net/http ServeMux
  participant H as Product Handler
  participant S as In-memory Store
  FE->>MUX: POST /v1/products dengan JSON
  MUX->>H: Panggil CreateProduct(w, r)
  H->>H: Decode JSON dari r.Body
  H->>H: Validasi input produk
  H->>S: Simpan product baru
  S-->>H: Product dengan ID
  H-->>FE: 201 Created application/json

Gambar 3. Alur request di modul ini masih tanpa database. Di Roadmap 3, store akan diganti repository PostgreSQL dengan pgx.

Router minimal dan cara menjalankan server

http.ServeMux adalah router bawaan standard library. Ia menerima pattern route, lalu memilih handler yang sesuai.

Sejak Go 1.22, ServeMux mendukung pattern yang lebih ekspresif, termasuk method dan wildcard path. Itu sebabnya contoh kita bisa menulis route seperti ini.

routes.goSalin
mux := http.NewServeMux()
mux.HandleFunc("GET /health", healthHandler)
mux.HandleFunc("GET /v1/products", store.ListProducts)
mux.HandleFunc("POST /v1/products", store.CreateProduct)
mux.HandleFunc("GET /v1/products/{id}", store.GetProduct)

Nilai wildcard bisa dibaca dengan r.PathValue("id").

path-value.goSalin
func (s *ProductStore) GetProduct(w http.ResponseWriter, r *http.Request) {
	idRaw := r.PathValue("id")
	// parse idRaw ke int64
}

http.ListenAndServe menjalankan server pada address tertentu dan memakai handler yang kamu berikan.

listen.goSalin
addr := ":8080"
if err := http.ListenAndServe(addr, mux); err != nil {
	slog.Error("server stopped", "error", err)
	os.Exit(1)
}

Standard library cukup kuat, tetapi proyek nyata butuh ergonomi lebih

Pertanyaan bagus untuk Go modern: kalau ServeMux sudah punya method pattern dan wildcard, kenapa masih belajar chi?

Jawabannya bukan karena net/http buruk. Justru chi dibangun di atas kontrak http.Handler, sehingga kamu tetap memakai fondasi yang sama. chi membantu saat route makin banyak, middleware makin serius, dan struktur API perlu rapi.

Latihan cepat sebelum masuk router chi

Sekarang jalankan contoh handler produk dan coba request dari terminal.

TerminalSalin
mkdir skincare-api
cd skincare-api
go mod init github.com/kamu/skincare-backend
# salin handler.go ke folder ini
go run .

Coba health check.

TerminalSalin
curl -i http://localhost:8080/health

Coba daftar produk dengan filter query.

TerminalSalin
curl -i "http://localhost:8080/v1/products?category=serum"

Coba detail produk dengan path parameter.

TerminalSalin
curl -i http://localhost:8080/v1/products/2

Coba membuat produk baru.

TerminalSalin
curl -i -X POST http://localhost:8080/v1/products \
  -H "Content-Type: application/json" \
  -d '{"name":"Barrier Repair Moisturizer","category":"moisturizer","price":219000,"stock":18,"description":"Krim pelembap untuk skin barrier"}'

Kesalahan kecil yang sering bikin handler Go membingungkan

Sebagian bug handler bukan karena Go sulit, tetapi karena kebiasaan dari Express.js atau Laravel terbawa tanpa disesuaikan.

bentuk-middleware-go.goSalin
func logging(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		slog.Info("request", "method", r.Method, "path", r.URL.Path)
		next.ServeHTTP(w, r)
	})
}

Sekarang kamu sudah bisa membaca dan menulis HTTP request secara langsung dengan standard library Go.

Untuk proyek online shop skincare, modul ini adalah fondasi endpoint produk. Di modul berikutnya, kita akan mulai merapikan routing dengan chi, lalu lanjut ke middleware, request context, dan akhirnya repository PostgreSQL dengan pgx.