HTTP-сервер на Golang: маршрутизация net/http, JSON и статусы

Сервер в несколько строк

Обработчик это функция, которая получает запрос и пишет ответ. 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.

Каждый запрос выполняется в своей горутине. Всё, что обработчики делят между собой, например мапа или счётчик, нуждается в мьютексе.

Обработчики

Всё, у чего есть метод 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), регистрация второго вызывает панику с сообщением, где названы оба шаблона. Если путь совпал, а метод нет, мультиплексор отвечает 405 Method Not Allowed с заголовком Allow, без всякого кода с вашей стороны.

Шаблон "/" ловит всё. Это удивляет тех, кто регистрирует главную страницу на "/" и обнаруживает, что она отвечает 200 на любой неизвестный URL. Для главной страницы используйте "GET /{$}".

Этим шаблонам нужно go 1.22 или новее в go.mod. При более старой строке версии мультиплексор возвращается к старому поведению: он читает "GET /items" как имя хоста, за которым идёт путь, так что маршрут никогда не совпадает, и каждый запрос к /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, который не принимает ни один маршрут, и мультиплексор сам отвечает 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

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:. Горутина обработчика печатает её до возврата, а сервер не завершает ответ, пока обработчик не вернётся.

statusRecorder встраивает настоящий ResponseWriter и переопределяет только WriteHeader; это стандартный способ узнать код статуса из middleware.

Настройки для продакшена

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")))).

Частые ошибки

• Нет return после http.Error. Обработчик продолжает работать и дописывает в ответ.
• Заголовки после записи тела. Они молча отбрасываются.
• Главная страница на "/". Она ловит все неизвестные пути. Используйте "/{$}".
• Общее состояние обработчиков без блокировки. Запросы выполняются конкурентно.
• Сервер по умолчанию в продакшене. У него нет таймаутов; задайте их в http.Server.
• Шаблоны маршрутов игнорируются. Если "GET /x/{id}" никогда не совпадает, проверьте, что в go.mod указано go 1.22 или новее.