HTTP server trong Golang: định tuyến net/http và JSON

Một máy chủ trong vài dòng

Handler là một hàm nhận request và ghi response. ServeMux định tuyến các request đến handler.

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))
}

Trình soạn thảo không thể nhận kết nối từ trình duyệt của bạn, nên các ví dụ trên trang này khởi động máy chủ bằng httptest.NewServer và gọi nó từ chính chương trình đó. Trong một chương trình thật, phần cuối được thay bằng một dòng chặn lại và phục vụ mãi mãi:

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

Khi đó curl localhost:8080/hello/gopher in ra Hello, gopher!. ListenAndServe chỉ trả về khi có lỗi (ví dụ cổng đã bị chiếm), vì vậy nó được bọc trong log.Fatal.

Mỗi request chạy trong goroutine riêng. Bất cứ thứ gì các handler dùng chung, như một map hay một bộ đếm, đều cần một mutex.

Handler

Bất cứ thứ gì có phương thức ServeHTTP(http.ResponseWriter, *http.Request) đều là một http.Handler. http.HandlerFunc chuyển một hàm thường thành interface đó, và mux.HandleFunc làm việc chuyển đổi này giúp bạn. Handler dạng struct tiện khi handler cần các phụ thuộc:

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 cho bạn:

Pattern định tuyến (Go 1.22)

Từ Go 1.22, pattern của ServeMux có dạng [METHOD ][HOST]/[PATH], và đường dẫn có thể chứa wildcard.

Khi hai pattern cùng khớp, pattern cụ thể hơn sẽ thắng, nên /items/new thắng /items/{id}. Nếu không pattern nào cụ thể hơn, ví dụ /items/{id} và /{kind}/new (cả hai đều khớp /items/new), việc đăng ký pattern thứ hai sẽ panic với một thông báo nêu tên cả hai pattern. Nếu đường dẫn khớp nhưng phương thức thì không, mux trả lời 405 Method Not Allowed kèm header Allow, mà bạn không cần viết dòng code nào.

Pattern "/" là pattern bắt tất cả. Điều đó làm nhiều người bất ngờ khi họ đăng ký trang chủ bằng "/" rồi thấy nó trả lời 200 cho mọi URL không xác định. Hãy dùng "GET /{$}" cho trang chủ.

Các pattern này cần go 1.22 trở lên trong go.mod. Với dòng phiên bản cũ hơn, mux quay về hành vi cũ: nó đọc "GET /items" như một tên host theo sau là một đường dẫn, nên route không bao giờ khớp và mọi request đến /items đều nhận 404.

Một JSON API nhỏ

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 cuối cùng dùng DELETE, phương thức không route nào chấp nhận, và mux tự trả lời 405 với Allow: GET, HEAD: đó là các phương thức đã đăng ký cho đường dẫn đó (một route GET cũng chấp nhận HEAD).

Mã trạng thái và thứ tự ghi

Một response có ba phần, và chúng phải được ghi theo thứ tự: header, trạng thái, body.

1. w.Header().Set(...) thay đổi header. Nó chỉ có tác dụng cho đến khi trạng thái được gửi đi.
2. w.WriteHeader(code) gửi dòng trạng thái và các header.
3. w.Write(...) (hoặc fmt.Fprint(w, ...), hoặc một encoder) gửi body. Nếu chưa gọi WriteHeader, lần Write đầu tiên sẽ gửi 200 OK trước.

Hệ quả:

• Đặt header sau khi body đã bắt đầu thì không có tác dụng gì.
• Gọi WriteHeader hai lần sẽ ghi log http: superfluous response.WriteHeader call và giữ trạng thái đầu tiên.
• Sau một response lỗi, hãy return. http.Error không dừng handler của bạn, và code phía sau vẫn tiếp tục ghi vào cùng response đó.

Hãy dùng các hằng số có tên (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) thay vì số trần. http.StatusText(404) trả về "Not Found".

Middleware

Middleware là một hàm nhận một handler và trả về một handler, làm gì đó trước hoặc sau khi gọi handler tiếp theo:

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)
	}
}

Dòng log: luôn xuất hiện trước client got: với cùng một request. Goroutine của handler in nó ra trước khi trả về, và máy chủ không hoàn tất response cho đến khi handler trả về.

statusRecorder nhúng ResponseWriter thật và chỉ ghi đè WriteHeader, đây là cách chuẩn để quan sát mã trạng thái từ middleware.

Cấu hình cho production

http.ListenAndServe dùng một máy chủ không có timeout, nên một client chậm có thể giữ kết nối mở vô thời hạn. Hãy cấu hình rõ ràng một http.Server cho bất cứ thứ gì đưa ra internet, và tắt nó một cách an toàn:

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 ngừng nhận kết nối mới và chờ các request đang chạy hoàn tất, tối đa đến hạn chót của context. ListenAndServe trả về http.ErrServerClosed ngay khi Shutdown bắt đầu, vì vậy lỗi đó không bị coi là thất bại. Với những handler chạy lâu, hãy truyền r.Context() xuống để chúng dừng khi client rời đi.

Phục vụ tệp tĩnh chỉ cần một dòng: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

Lỗi thường gặp

• Không return sau http.Error. Handler tiếp tục chạy và ghi thêm vào response.
• Đặt header sau khi đã ghi body. Chúng bị bỏ đi mà không có cảnh báo nào.
• Đăng ký trang chủ trên "/". Nó trở thành pattern bắt mọi đường dẫn không xác định. Hãy dùng "/{$}".
• Chia sẻ trạng thái giữa các handler mà không có khóa. Các request chạy đồng thời.
• Dùng máy chủ mặc định trên production. Nó không có timeout; hãy đặt timeout trên một http.Server.
• Pattern định tuyến bị bỏ qua. Nếu "GET /x/{id}" không bao giờ khớp, hãy kiểm tra go.mod có ghi go 1.22 trở lên không.