Servidor HTTP em Golang: rotas com net/http, JSON e códigos de status

Um servidor em poucas linhas

Um handler é uma função que recebe a requisição e escreve a resposta. O ServeMux encaminha as requisições para os 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))
}

O editor não consegue aceitar conexões vindas do seu navegador, então os exemplos desta página iniciam o servidor com httptest.NewServer e o chamam a partir do mesmo programa. Em um programa real, a última parte é substituída por uma linha que bloqueia e serve para sempre:

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

Aí curl localhost:8080/hello/gopher imprime Hello, gopher!. O ListenAndServe só retorna em caso de erro (a porta já está em uso, por exemplo), e é por isso que ele fica dentro de um log.Fatal.

Cada requisição executa na sua própria goroutine. Tudo o que os seus handlers compartilham, como um map ou um contador, precisa de um mutex.

Handlers

Qualquer coisa com um método ServeHTTP(http.ResponseWriter, *http.Request) é um http.Handler. O http.HandlerFunc adapta uma função comum a essa interface, e o mux.HandleFunc faz a conversão por você. Um handler do tipo struct é prático quando os handlers precisam de dependências:

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)

O *http.Request oferece:

Padrões de rota (Go 1.22)

Desde o Go 1.22, os padrões do ServeMux têm a forma [MÉTODO ][HOST]/[CAMINHO], e os caminhos podem conter wildcards.

Quando dois padrões casam, o mais específico vence, então /items/new ganha de /items/{id}. Se nenhum for mais específico, por exemplo /items/{id} e /{kind}/new (os dois casam com /items/new), registrar o segundo causa panic com uma mensagem que nomeia os dois padrões. Se um caminho casa mas o método não, o mux responde 405 Method Not Allowed com um header Allow, sem nenhum código seu.

O padrão "/" pega tudo. Isso surpreende quem registra uma página inicial com "/" e descobre que ela responde 200 para toda URL desconhecida. Use "GET /{$}" para a página inicial.

Esses padrões exigem go 1.22 ou mais no go.mod. Com uma linha de versão mais antiga, o mux volta ao comportamento antigo: ele lê "GET /items" como um nome de host seguido de um caminho, então a rota nunca casa e toda requisição para /items recebe 404.

Uma pequena API 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()
	}
}

A última requisição usa DELETE, que nenhuma rota aceita, e o mux responde 405 com Allow: GET, HEAD sozinho: esses são os métodos registrados para aquele caminho (uma rota GET também aceita HEAD).

Códigos de status e a ordem das escritas

Uma resposta tem três partes, e elas precisam ser escritas em ordem: headers, status, corpo.

1. w.Header().Set(...) altera os headers. Só tem efeito até o status ser enviado.
2. w.WriteHeader(code) envia a linha de status e os headers.
3. w.Write(...) (ou fmt.Fprint(w, ...), ou um encoder) envia o corpo. Se WriteHeader não foi chamado, o primeiro Write envia 200 OK antes.

Consequências:

• Definir um header depois que o corpo começou não faz nada.
• Chamar WriteHeader duas vezes registra http: superfluous response.WriteHeader call e mantém o primeiro status.
• Depois de uma resposta de erro, faça return. O http.Error não interrompe o seu handler, e o código depois dele continua escrevendo na mesma resposta.

Use as constantes com nome (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) em vez de números puros. http.StatusText(404) devolve "Not Found".

Middleware

Um middleware é uma função que recebe um handler e devolve um handler, fazendo algo antes ou depois de chamar o próximo:

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

A linha log: sempre aparece antes de client got: para a mesma requisição. A goroutine do handler a imprime antes de retornar, e o servidor só conclui a resposta quando o handler retorna.

O statusRecorder embute o ResponseWriter real e sobrescreve só o WriteHeader, que é o jeito padrão de observar o código de status em um middleware.

Configurações de produção

O http.ListenAndServe usa um servidor sem timeouts, então um cliente lento pode manter uma conexão aberta indefinidamente. Configure um http.Server explicitamente para qualquer coisa exposta à internet, e desligue-o de forma graciosa:

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

O Shutdown para de aceitar conexões novas e espera as requisições ativas terminarem, até o prazo do context. O ListenAndServe devolve http.ErrServerClosed assim que o Shutdown começa, e é por isso que esse erro não é tratado como falha. Para handlers de longa duração, passe r.Context() adiante para que eles parem quando o cliente for embora.

Servir arquivos estáticos é uma linha: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

Erros comuns

• Não retornar depois de http.Error. O handler continua executando e escreve mais coisas na resposta.
• Definir headers depois de escrever o corpo. Eles são descartados em silêncio.
• Registrar a página inicial em "/". Ela vira a rota que pega todo caminho desconhecido. Use "/{$}".
• Compartilhar estado entre handlers sem lock. As requisições executam de forma concorrente.
• Usar o servidor padrão em produção. Ele não tem timeouts; defina-os em um http.Server.
• Padrões de rota ignorados. Se "GET /x/{id}" nunca casa, confira se o go.mod diz go 1.22 ou mais.