HTTP Server di Golang: Routing net/http, JSON, dan Kode Status

Server dalam beberapa baris

Handler adalah fungsi yang menerima request dan menulis response. ServeMux meneruskan request ke handler yang tepat.

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /hello/{name}", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "Hello, %s!\n", r.PathValue("name"))
	})

	// httptest starts a real server on a random local port.
	srv := httptest.NewServer(mux)
	defer srv.Close()

	resp, err := http.Get(srv.URL + "/hello/gopher")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Print(resp.Status, " ", string(body))
}

Editor tidak bisa menerima koneksi dari browser-mu, jadi contoh di halaman ini menjalankan server dengan httptest.NewServer dan memanggilnya dari program yang sama. Di program sungguhan, bagian terakhir diganti dengan satu baris yang memblokir dan melayani request selamanya:

log.Fatal(http.ListenAndServe(":8080", mux))

Setelah itu curl localhost:8080/hello/gopher mencetak Hello, gopher!. ListenAndServe hanya kembali saat terjadi error (misalnya port sudah dipakai), karena itulah ia dibungkus dengan log.Fatal.

Setiap request berjalan di goroutine-nya sendiri. Apa pun yang dipakai bersama oleh handler-mu, seperti map atau counter, butuh mutex.

Handler

Apa pun yang punya method ServeHTTP(http.ResponseWriter, *http.Request) adalah http.Handler. http.HandlerFunc menyesuaikan fungsi biasa ke interface itu, dan mux.HandleFunc melakukan konversinya untukmu. Handler berupa struct berguna saat handler membutuhkan dependensi:

type API struct {
	db *sql.DB
}

func (a *API) listItems(w http.ResponseWriter, r *http.Request) { /* uses a.db */ }

mux.HandleFunc("GET /items", api.listItems)

*http.Request memberimu:

Pola routing (Go 1.22)

Sejak Go 1.22, pola ServeMux berbentuk [METHOD ][HOST]/[PATH], dan path boleh berisi wildcard.

Saat dua pola sama-sama cocok, pola yang lebih spesifik menang, jadi /items/new mengalahkan /items/{id}. Kalau tidak ada yang lebih spesifik, misalnya /items/{id} dan /{kind}/new (keduanya cocok dengan /items/new), mendaftarkan pola kedua akan panic dengan pesan yang menyebut kedua pola. Kalau path-nya cocok tapi method-nya tidak, mux menjawab 405 Method Not Allowed dengan header Allow, tanpa kode apa pun darimu.

Pola "/" adalah penangkap semua path. Ini mengejutkan orang yang mendaftarkan halaman beranda dengan "/" lalu mendapati halaman itu menjawab setiap URL tak dikenal dengan 200. Pakai "GET /{$}" untuk halaman beranda.

Pola-pola ini butuh go 1.22 atau lebih baru di go.mod. Dengan baris versi yang lebih lama, mux kembali ke perilaku lama: ia membaca "GET /items" sebagai nama host diikuti path, sehingga route-nya tidak pernah cocok dan setiap request ke /items mendapat 404.

API JSON kecil

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"strconv"
	"strings"
	"sync"
)

type Item struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

type Store struct {
	mu     sync.Mutex
	items  map[int]Item
	nextID int
}

func writeJSON(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json") // headers first
	w.WriteHeader(status)                              // then the status
	json.NewEncoder(w).Encode(v)                       // then the body
}

func (s *Store) getItem(w http.ResponseWriter, r *http.Request) {
	id, err := strconv.Atoi(r.PathValue("id"))
	if err != nil {
		http.Error(w, "id must be a number", http.StatusBadRequest)
		return
	}
	s.mu.Lock()
	item, ok := s.items[id]
	s.mu.Unlock()
	if !ok {
		http.Error(w, "item not found", http.StatusNotFound)
		return
	}
	writeJSON(w, http.StatusOK, item)
}

func (s *Store) createItem(w http.ResponseWriter, r *http.Request) {
	var in Item
	r.Body = http.MaxBytesReader(w, r.Body, 1<<20) // refuse bodies over 1 MB
	if err := json.NewDecoder(r.Body).Decode(&in); err != nil || in.Name == "" {
		http.Error(w, "invalid JSON body", http.StatusBadRequest)
		return
	}
	s.mu.Lock()
	s.nextID++
	in.ID = s.nextID
	s.items[in.ID] = in
	s.mu.Unlock()

	w.Header().Set("Location", fmt.Sprintf("/items/%d", in.ID))
	writeJSON(w, http.StatusCreated, in)
}

func main() {
	store := &Store{items: map[int]Item{}}
	mux := http.NewServeMux()
	mux.HandleFunc("GET /items/{id}", store.getItem)
	mux.HandleFunc("POST /items", store.createItem)

	srv := httptest.NewServer(mux)
	defer srv.Close()

	show := func(resp *http.Response, err error) {
		if err != nil {
			fmt.Println("error:", err)
			return
		}
		defer resp.Body.Close()
		body, _ := io.ReadAll(resp.Body)
		fmt.Printf("%d %s", resp.StatusCode, body)
		if loc := resp.Header.Get("Location"); loc != "" {
			fmt.Println("  Location:", loc)
		}
	}

	show(http.Post(srv.URL+"/items", "application/json", strings.NewReader(`{"name":"lamp"}`)))
	show(http.Get(srv.URL + "/items/1"))
	show(http.Get(srv.URL + "/items/99"))
	show(http.Get(srv.URL + "/items/abc"))
	show(http.Post(srv.URL+"/items", "application/json", strings.NewReader(`{bad json`)))

	req, _ := http.NewRequest(http.MethodDelete, srv.URL+"/items/1", nil)
	resp, err := http.DefaultClient.Do(req)
	if err == nil {
		fmt.Println(resp.StatusCode, "Allow:", resp.Header.Get("Allow"))
		resp.Body.Close()
	}
}

Request terakhir memakai DELETE, yang tidak diterima oleh route mana pun, dan mux dengan sendirinya menjawab 405 dengan Allow: GET, HEAD: itulah method yang terdaftar untuk path tersebut (route GET juga menerima HEAD).

Kode status dan urutan penulisan

Response punya tiga bagian, dan ketiganya harus ditulis berurutan: header, status, body.

1. w.Header().Set(...) mengubah header. Pengaruhnya hanya berlaku sampai status dikirim.
2. w.WriteHeader(code) mengirim baris status dan header.
3. w.Write(...) (atau fmt.Fprint(w, ...), atau sebuah encoder) mengirim body. Kalau WriteHeader belum dipanggil, Write pertama akan mengirim 200 OK lebih dulu.

Akibatnya:

• Mengatur header setelah body mulai dikirim tidak berpengaruh apa-apa.
• Memanggil WriteHeader dua kali mencatat http: superfluous response.WriteHeader call di log dan mempertahankan status pertama.
• Setelah response error, lakukan return. http.Error tidak menghentikan handler-mu, dan kode setelahnya tetap menulis ke response yang sama.

Pakai konstanta bernama (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) daripada angka polos. http.StatusText(404) mengembalikan "Not Found".

Middleware

Middleware adalah fungsi yang menerima handler dan mengembalikan handler, yang melakukan sesuatu sebelum atau sesudah memanggil handler berikutnya:

package main

import (
	"fmt"
	"net/http"
	"net/http/httptest"
)

func requireKey(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.Header.Get("X-API-Key") != "secret" {
			http.Error(w, "unauthorized", http.StatusUnauthorized)
			return
		}
		next.ServeHTTP(w, r)
	})
}

type statusRecorder struct {
	http.ResponseWriter
	status int
}

func (s *statusRecorder) WriteHeader(code int) {
	s.status = code
	s.ResponseWriter.WriteHeader(code)
}

func logRequests(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
		next.ServeHTTP(rec, r)
		fmt.Printf("log: %s %s -> %d\n", r.Method, r.URL.Path, rec.status)
	})
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /report", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintln(w, "the report")
	})

	handler := logRequests(requireKey(mux)) // outermost runs first
	srv := httptest.NewServer(handler)
	defer srv.Close()

	for _, key := range []string{"", "secret"} {
		req, _ := http.NewRequest(http.MethodGet, srv.URL+"/report", nil)
		req.Header.Set("X-API-Key", key)
		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			fmt.Println(err)
			return
		}
		resp.Body.Close()
		fmt.Println("client got:", resp.Status)
	}
}

Baris log: selalu muncul sebelum client got: untuk request yang sama. Goroutine handler mencetaknya sebelum kembali, dan server tidak menyelesaikan response sampai handler kembali.

statusRecorder menyematkan (embed) ResponseWriter yang asli dan hanya meng-override WriteHeader, yang merupakan cara standar untuk mengamati kode status dari middleware.

Pengaturan untuk production

http.ListenAndServe memakai server tanpa timeout, jadi client yang lambat bisa menahan koneksi terbuka tanpa batas waktu. Konfigurasikan http.Server secara eksplisit untuk apa pun yang terbuka ke internet, dan matikan dengan rapi (graceful):

srv := &http.Server{
	Addr:              ":8080",
	Handler:           mux,
	ReadHeaderTimeout: 5 * time.Second,
	ReadTimeout:       10 * time.Second,
	WriteTimeout:      30 * time.Second,
	IdleTimeout:       120 * time.Second,
}

go func() {
	if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
		log.Fatal(err)
	}
}()

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
<-ctx.Done() // wait for Ctrl+C or a SIGTERM from the orchestrator

shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil { // finish in-flight requests
	log.Println("shutdown:", err)
}

Shutdown berhenti menerima koneksi baru dan menunggu request yang sedang berjalan selesai, sampai batas deadline context. ListenAndServe mengembalikan http.ErrServerClosed begitu Shutdown dimulai, karena itulah error tersebut tidak dianggap sebagai kegagalan. Untuk handler yang berjalan lama, teruskan r.Context() ke bawah supaya handler berhenti saat client pergi.

Menyajikan file statis cukup satu baris: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

Kesalahan umum

• Tidak melakukan return setelah http.Error. Handler terus berjalan dan menulis lebih banyak ke response.
• Mengatur header setelah menulis body. Header itu dibuang diam-diam.
• Mendaftarkan halaman beranda di "/". Halaman itu menjadi penangkap semua path yang tidak dikenal. Pakai "/{$}".
• Berbagi state antar handler tanpa lock. Request berjalan secara concurrent.
• Memakai server default di production. Server itu tidak punya timeout; atur timeout-nya di http.Server.
• Pola routing diabaikan. Kalau "GET /x/{id}" tidak pernah cocok, pastikan go.mod menulis go 1.22 atau lebih baru.