خادم HTTP في Golang: التوجيه في net/http وJSON ورموز الحالة

خادم في بضعة أسطر

المعالج (handler) دالة تتلقّى الطلب وتكتب الردّ. ويوجّه ServeMux الطلبات إلى المعالجات.

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 خاصة به. أي شيء تتشاركه معالجاتك، مثل خريطة أو عدّاد، يحتاج mutex.

المعالجات

أي شيء له تابع ServeHTTP(http.ResponseWriter, *http.Request) هو http.Handler. يكيّف http.HandlerFunc دالة عادية مع هذه الواجهة، ويجري mux.HandleFunc التحويل نيابة عنك. والمعالج على شكل بنية مفيد عندما تحتاج المعالجات إلى اعتماديات:

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]، ويمكن أن تحتوي المسارات على متغيّرات.

عندما يتطابق نمطان يفوز الأكثر تحديدًا، فيتقدّم /items/new على /items/{id}. وإذا لم يكن أي منهما أكثر تحديدًا، مثل /items/{id} و/{kind}/new (كلاهما يطابق /items/new)، فإن تسجيل الثاني يسبّب panic برسالة تسمّي النمطين. إذا طابق المسار ولم تطابق الطريقة، يجيب الموجّه بـ 405 Method Not Allowed مع ترويسة Allow، دون أي شيفرة منك.

النمط "/" يلتقط كل شيء. وهذا يفاجئ من يسجّل الصفحة الرئيسية بـ "/" فيجدها تجيب كل عنوان مجهول بـ 200. استخدم "GET /{$}" للصفحة الرئيسية.

تحتاج هذه الأنماط إلى go 1.22 أو أحدث في go.mod. مع سطر إصدار أقدم يرجع الموجّه إلى السلوك القديم: يقرأ "GET /items" كاسم مضيف يليه مسار، فلا يطابق المسار أبدًا ويحصل كل طلب إلى /items على 404.

واجهة JSON صغيرة

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، التي لا يقبلها أي مسار، فيجيب الموجّه بنفسه بـ 405 مع Allow: GET, HEAD: هذه هي الطرق المسجّلة لذلك المسار (مسار GET يقبل HEAD أيضًا).

رموز الحالة وترتيب الكتابة

للردّ ثلاثة أجزاء، ويجب كتابتها بالترتيب: الترويسات، ثم الحالة، ثم الجسم.

1. يغيّر w.Header().Set(...) الترويسات. ويكون له أثر فقط حتى تُرسل الحالة.
2. يرسل w.WriteHeader(code) سطر الحالة والترويسات.
3. يرسل w.Write(...) (أو fmt.Fprint(w, ...) أو مرمّز) الجسم. إذا لم تُستدعَ WriteHeader، يرسل أول Write الحالة 200 OK أولًا.

العواقب:

• ضبط ترويسة بعد بدء الجسم لا يفعل شيئًا.
• استدعاء WriteHeader مرتين يسجّل http: superfluous response.WriteHeader call ويحتفظ بالحالة الأولى.
• بعد ردّ خطأ، نفّذ return. لا توقف http.Error معالجك، والشيفرة التي بعدها تستمر في الكتابة في الردّ نفسه.

استخدم الثوابت المسمّاة (http.StatusOK وhttp.StatusCreated وhttp.StatusBadRequest وhttp.StatusUnauthorized وhttp.StatusNotFound وhttp.StatusInternalServerError) بدل الأرقام المجرّدة. تعيد http.StatusText(404) النص "Not Found".

الطبقات الوسيطة (Middleware)

الطبقة الوسيطة دالة تأخذ معالجًا وتعيد معالجًا، وتفعل شيئًا قبل استدعاء التالي أو بعده:

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 المعالج قبل أن تعود، ولا ينهي الخادم الردّ حتى يعود المعالج.

تضمّن statusRecorder الـ ResponseWriter الحقيقي وتعيد تعريف WriteHeader وحدها، وهذه الطريقة المعتادة لمراقبة رمز الحالة من طبقة وسيطة.

إعدادات الإنتاج

تستخدم http.ListenAndServe خادمًا بلا مهل، فيستطيع عميل بطيء إبقاء اتصال مفتوحًا بلا حد. اضبط 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 عن قبول اتصالات جديدة وينتظر انتهاء الطلبات النشطة، حتى الموعد النهائي للسياق. تعيد ListenAndServe الخطأ http.ErrServerClosed فور بدء Shutdown، ولهذا لا يُعامل ذلك الخطأ كفشل. للمعالجات طويلة التشغيل مرّر r.Context() إلى الأسفل لتتوقّف عندما يغادر العميل.

خدمة الملفات الثابتة سطر واحد: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

أخطاء شائعة

• عدم العودة بعد http.Error. يستمر المعالج في العمل ويكتب المزيد في الردّ.
• ضبط الترويسات بعد كتابة الجسم. تُهمل بصمت.
• تسجيل الصفحة الرئيسية على "/". تصبح ملتقطة كل مسار مجهول. استخدم "/{$}".
• مشاركة الحالة بين المعالجات دون قفل. الطلبات تعمل بالتزامن.
• استخدام الخادم الافتراضي في الإنتاج. لا مهل له؛ اضبطها على http.Server.
• تجاهل أنماط التوجيه. إذا لم يطابق "GET /x/{id}" أبدًا، فتحقّق من أن go.mod يذكر go 1.22 أو أحدث.