HTTP Server ב-Golang: ניתוב ב-net/http, JSON וקודי סטטוס

שרת בכמה שורות

handler הוא פונקציה שמקבלת את הבקשה וכותבת את התשובה. ServeMux מנתב בקשות ל-handlers.

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

העורך לא יכול לקבל חיבורים מהדפדפן שלכם, ולכן הדוגמאות בעמוד הזה מפעילות את השרת עם httptest.NewServer וקוראות לו מאותה תוכנית. בתוכנית אמיתית, החלק האחרון מוחלף בשורה אחת שחוסמת ומגישה לנצח:

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

אחר כך curl localhost:8080/hello/gopher מדפיס Hello, gopher!. ListenAndServe חוזרת רק בשגיאה (למשל כשהפורט תפוס), ולכן היא עטופה ב-log.Fatal.

כל בקשה רצה ב-goroutine משלה. כל מה שה-handlers שלכם חולקים, כמו map או מונה, צריך mutex.

Handlers

כל דבר עם מתודה ServeHTTP(http.ResponseWriter, *http.Request) הוא http.Handler. http.HandlerFunc מתאים פונקציה רגילה ל-interface הזה, ו-mux.HandleFunc עושה את ההמרה בשבילכם. handler מסוג struct נוח כש-handlers צריכים תלויות:

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 נותן לכם:

תבניות ניתוב (Go 1.22)

מאז Go 1.22, לתבניות של ServeMux יש הצורה [METHOD ][HOST]/[PATH], ונתיבים יכולים להכיל wildcards.

כששתי תבניות מתאימות, המדויקת יותר מנצחת, ולכן /items/new גוברת על /items/{id}. אם אף אחת מהן לא מדויקת יותר, למשל /items/{id} ו-/{kind}/new (שתיהן מתאימות ל-/items/new), רישום השנייה נכנס ל-panic עם הודעה שמציינת את שתי התבניות. אם נתיב מתאים אבל המתודה לא, ה-mux עונה 405 Method Not Allowed עם header של Allow, בלי שום קוד מצדכם.

התבנית "/" היא ה-catch-all. זה מפתיע אנשים שרושמים דף בית עם "/" ומגלים שהוא עונה 200 לכל URL לא מוכר. השתמשו ב-"GET /{$}" לדף הבית.

התבניות האלה דורשות go 1.22 ומעלה ב-go.mod. עם שורת גרסה ישנה יותר, ה-mux חוזר להתנהגות הישנה: הוא קורא את "GET /items" כשם host ואחריו נתיב, ולכן הנתיב לא מתאים אף פעם וכל בקשה ל-/items מקבלת 404.

JSON API קטן

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

הבקשה האחרונה משתמשת ב-DELETE, שאף נתיב לא מקבל, וה-mux עונה 405 עם Allow: GET, HEAD בעצמו: אלה המתודות שרשומות לנתיב הזה (נתיב של GET מקבל גם HEAD).

קודי סטטוס וסדר הכתיבה

לתשובה יש שלושה חלקים, וצריך לכתוב אותם לפי הסדר: headers, סטטוס, body.

1. w.Header().Set(...) משנה headers. יש לזה השפעה רק עד שהסטטוס נשלח.
2. w.WriteHeader(code) שולח את שורת הסטטוס ואת ה-headers.
3. w.Write(...) (או fmt.Fprint(w, ...), או encoder) שולח את ה-body. אם לא קראו ל-WriteHeader, ה-Write הראשון שולח קודם 200 OK.

ההשלכות:

• הגדרת header אחרי שה-body כבר התחיל לא עושה כלום.
• קריאה ל-WriteHeader פעמיים כותבת ללוג http: superfluous response.WriteHeader call ושומרת את הסטטוס הראשון.
• אחרי תשובת שגיאה, return. http.Error לא עוצרת את ה-handler שלכם, וקוד שאחריה ממשיך לכתוב לאותה תשובה.

השתמשו בקבועים בעלי השם (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) ולא במספרים חשופים. http.StatusText(404) מחזירה "Not Found".

Middleware

middleware היא פונקציה שמקבלת handler ומחזירה handler, ועושה משהו לפני או אחרי הקריאה ל-handler הבא:

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

השורה log: תמיד מופיעה לפני client got: באותה בקשה. ה-goroutine של ה-handler מדפיסה אותה לפני שהיא חוזרת, והשרת לא מסיים את התשובה עד שה-handler חוזר.

ה-statusRecorder מטמיע את ה-ResponseWriter האמיתי ודורס רק את WriteHeader, וזו הדרך המקובלת לראות את קוד הסטטוס מתוך middleware.

הגדרות ל-production

http.ListenAndServe משתמשת בשרת בלי timeouts, כך שלקוח איטי יכול להחזיק חיבור פתוח ללא הגבלה. הגדירו http.Server במפורש לכל דבר שחשוף לאינטרנט, וכבו אותו בצורה מסודרת:

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 מפסיקה לקבל חיבורים חדשים ומחכה שבקשות פעילות יסתיימו, עד ה-deadline של ה-context. ListenAndServe מחזירה http.ErrServerClosed ברגע ש-Shutdown מתחילה, ולכן השגיאה הזאת לא נחשבת לכישלון. ל-handlers שרצים זמן רב, העבירו את r.Context() הלאה כדי שייעצרו כשהלקוח עוזב.

הגשת קבצים סטטיים היא שורה אחת: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

טעויות נפוצות

• לא לעשות return אחרי http.Error. ה-handler ממשיך לרוץ וכותב עוד לתוך התשובה.
• הגדרת headers אחרי כתיבת ה-body. הם נזרקים בשקט.
• רישום דף הבית על "/". הוא הופך ל-catch-all של כל נתיב לא מוכר. השתמשו ב-"/{$}".
• שיתוף state בין handlers בלי נעילה. בקשות רצות במקביל.
• שימוש בשרת ברירת המחדל ב-production. אין לו timeouts; הגדירו אותם ב-http.Server.
• תבניות ניתוב שמתעלמים מהן. אם "GET /x/{id}" אף פעם לא מתאימה, בדקו שב-go.mod כתוב go 1.22 ומעלה.