Golang HTTP Sunucusu: net/http Yönlendirme, JSON ve Durum Kodları

Birkaç satırda bir sunucu

Handler, isteği alıp yanıtı yazan bir fonksiyondur. ServeMux istekleri handler'lara yönlendirir.

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

Editör tarayıcınızdan bağlantı kabul edemez, bu yüzden bu sayfadaki örnekler sunucuyu httptest.NewServer ile başlatır ve aynı programdan çağırır. Gerçek bir programda son kısmın yerini, bloklanıp sonsuza kadar hizmet veren tek bir satır alır:

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

Sonra curl localhost:8080/hello/gopher, Hello, gopher! yazdırır. ListenAndServe yalnızca bir hatada (örneğin port kullanılıyorsa) döner; log.Fatal ile sarılmasının nedeni budur.

Her istek kendi goroutine'inde çalışır. Handler'larınızın paylaştığı bir map ya da sayaç gibi her şey bir mutex gerektirir.

Handler'lar

ServeHTTP(http.ResponseWriter, *http.Request) metodu olan her şey bir http.Handler'dır. http.HandlerFunc düz bir fonksiyonu bu interface'e uyarlar ve mux.HandleFunc dönüşümü sizin yerinize yapar. Handler'ların bağımlılıklara ihtiyacı olduğunda struct handler kullanışlıdır:

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 size şunları verir:

Yönlendirme desenleri (Go 1.22)

Go 1.22'den beri ServeMux desenleri [METHOD ][HOST]/[PATH] biçimindedir ve yollar joker karakterler içerebilir.

İki desen eşleştiğinde daha belirli olan kazanır, bu yüzden /items/new, /items/{id}'yi yener. Hiçbiri daha belirli değilse, örneğin /items/{id} ve /{kind}/new (ikisi de /items/new ile eşleşir), ikincisini kaydetmek iki deseni de adlandıran bir mesajla panic olur. Bir yol eşleşip metot eşleşmezse mux, sizden hiçbir kod gerektirmeden bir Allow header'ıyla 405 Method Not Allowed yanıtı verir.

"/" deseni her şeyi yakalar. Bu, bir ana sayfayı "/" ile kaydedip onun bilinmeyen her URL'e 200 ile yanıt verdiğini görenleri şaşırtır. Ana sayfa için "GET /{$}" kullanın.

Bu desenler go.mod içinde go 1.22 ya da sonrasını gerektirir. Daha eski bir sürüm satırıyla mux eski davranışa döner: "GET /items"'ı bir host adı ardından bir yol olarak okur, bu yüzden rota hiç eşleşmez ve /items'a gelen her istek 404 alır.

Küçük bir JSON API'si

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

Son istek hiçbir rotanın kabul etmediği DELETE'i kullanır ve mux kendiliğinden Allow: GET, HEAD ile 405 yanıtı verir: bunlar o yol için kaydedilmiş metotlardır (bir GET rotası HEAD'i de kabul eder).

Durum kodları ve yazma sırası

Bir yanıtın üç parçası vardır ve sırayla yazılmaları gerekir: header'lar, durum, gövde.

1. w.Header().Set(...) header'ları değiştirir. Yalnızca durum gönderilene kadar etkisi vardır.
2. w.WriteHeader(code) durum satırını ve header'ları gönderir.
3. w.Write(...) (ya da fmt.Fprint(w, ...) veya bir encoder) gövdeyi gönderir. WriteHeader çağrılmamışsa ilk Write önce 200 OK gönderir.

Sonuçları:

• Gövde başladıktan sonra bir header ayarlamak hiçbir şey yapmaz.
• WriteHeader'ı iki kez çağırmak http: superfluous response.WriteHeader call loglar ve ilk durumu tutar.
• Bir hata yanıtından sonra return edin. http.Error handler'ınızı durdurmaz ve ondan sonraki kod aynı yanıta yazmaya devam eder.

Düz sayılar yerine adlandırılmış sabitleri (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) kullanın. http.StatusText(404), "Not Found" döndürür.

Middleware

Middleware, bir handler alıp bir handler döndüren ve bir sonrakini çağırmadan önce ya da sonra bir şey yapan bir fonksiyondur:

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

Aynı istek için log: satırı her zaman client got:'tan önce görünür. Handler goroutine'i onu dönmeden önce yazdırır ve sunucu handler dönene kadar yanıtı bitirmez.

statusRecorder gerçek ResponseWriter'ı gömer ve yalnızca WriteHeader'ı geçersiz kılar; bu, middleware'den durum kodunu gözlemlemenin standart yoludur.

Production ayarları

http.ListenAndServe timeout'u olmayan bir sunucu kullanır, bu yüzden yavaş bir istemci bir bağlantıyı süresiz açık tutabilir. İnternete açık her şey için bir http.Server'ı açıkça yapılandırın ve onu düzgün biçimde kapatı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 yeni bağlantıları kabul etmeyi bırakır ve context'in deadline'ına kadar aktif isteklerin bitmesini bekler. ListenAndServe, Shutdown başlar başlamaz http.ErrServerClosed döndürür; bu hatanın başarısızlık sayılmamasının nedeni budur. Uzun süren handler'lar için r.Context()'i aşağıya aktarın ki istemci gidince dursunlar.

Statik dosya sunmak tek satırdır: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

Sık yapılan hatalar

• http.Error'dan sonra return etmemek. Handler çalışmaya devam eder ve yanıta daha fazlasını yazar.
• Gövdeyi yazdıktan sonra header ayarlamak. Sessizce atılırlar.
• Ana sayfayı "/" üzerine kaydetmek. Bilinmeyen her yol için her şeyi yakalayan rota olur. "/{$}" kullanın.
• Handler'lar arasında kilit olmadan durum paylaşmak. İstekler eşzamanlı çalışır.
• Production'da varsayılan sunucuyu kullanmak. Timeout'u yoktur; onları bir http.Server üzerinde ayarlayın.
• Yok sayılan yönlendirme desenleri. "GET /x/{id}" hiç eşleşmiyorsa go.mod'un go 1.22 ya da sonrasını belirttiğini kontrol edin.