Servidor HTTP en Golang: rutas net/http, JSON y códigos de estado

Un servidor en unas pocas líneas

Un handler es una función que recibe la petición y escribe la respuesta. ServeMux enruta las peticiones a los 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))
}

El editor no puede aceptar conexiones desde tu navegador, así que los ejemplos de esta página arrancan el servidor con httptest.NewServer y lo llaman desde el mismo programa. En un programa real, la última parte se sustituye por una línea que se bloquea y sirve para siempre:

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

Entonces curl localhost:8080/hello/gopher imprime Hello, gopher!. ListenAndServe solo retorna ante un error (el puerto está ocupado, por ejemplo), y por eso va envuelto en log.Fatal.

Cada petición se ejecuta en su propia goroutine. Todo lo que compartan tus handlers, como un map o un contador, necesita un mutex.

Handlers

Cualquier cosa con un método ServeHTTP(http.ResponseWriter, *http.Request) es un http.Handler. http.HandlerFunc adapta una función normal a esa interfaz, y mux.HandleFunc hace la conversión por ti. Un handler basado en struct viene bien cuando los handlers necesitan dependencias:

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)

El *http.Request te da:

Patrones de ruta (Go 1.22)

Desde Go 1.22, los patrones de ServeMux tienen la forma [METHOD ][HOST]/[PATH], y las rutas pueden contener comodines.

Cuando coinciden dos patrones, gana el más específico, así que /items/new gana a /items/{id}. Si ninguno es más específico, por ejemplo /items/{id} y /{kind}/new (los dos coinciden con /items/new), registrar el segundo provoca un panic con un mensaje que nombra ambos patrones. Si una ruta coincide pero el método no, el mux responde 405 Method Not Allowed con una cabecera Allow, sin código tuyo.

El patrón "/" es el comodín general. Eso sorprende a quien registra una página de inicio con "/" y ve que responde a cualquier URL desconocida con un 200. Usa "GET /{$}" para la página de inicio.

Estos patrones necesitan go 1.22 o posterior en go.mod. Con una línea de versión más antigua, el mux vuelve al comportamiento antiguo: lee "GET /items" como un nombre de host seguido de una ruta, así que la ruta nunca coincide y todas las peticiones a /items reciben un 404.

Una pequeña 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()
	}
}

La última petición usa DELETE, que ninguna ruta acepta, y el mux responde 405 con Allow: GET, HEAD por su cuenta: esos son los métodos registrados para esa ruta (una ruta GET también acepta HEAD).

Códigos de estado y el orden de las escrituras

Una respuesta tiene tres partes, y deben escribirse en orden: cabeceras, estado, body.

1. w.Header().Set(...) cambia las cabeceras. Solo tiene efecto hasta que se envía el estado.
2. w.WriteHeader(code) envía la línea de estado y las cabeceras.
3. w.Write(...) (o fmt.Fprint(w, ...), o un encoder) envía el body. Si no se ha llamado a WriteHeader, el primer Write envía antes 200 OK.

Consecuencias:

• Poner una cabecera después de que haya empezado el body no hace nada.
• Llamar dos veces a WriteHeader registra http: superfluous response.WriteHeader call y mantiene el primer estado.
• Después de una respuesta de error, haz return. http.Error no detiene tu handler, y el código que va detrás sigue escribiendo en la misma respuesta.

Usa las constantes con nombre (http.StatusOK, http.StatusCreated, http.StatusBadRequest, http.StatusUnauthorized, http.StatusNotFound, http.StatusInternalServerError) en lugar de números a secas. http.StatusText(404) devuelve "Not Found".

Middleware

Un middleware es una función que recibe un handler y devuelve un handler, y hace algo antes o después de llamar al siguiente:

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

La línea log: siempre aparece antes que client got: para la misma petición. La goroutine del handler la imprime antes de retornar, y el servidor no termina la respuesta hasta que el handler retorna.

El statusRecorder incrusta el ResponseWriter real y sobrescribe solo WriteHeader, que es la forma estándar de observar el código de estado desde un middleware.

Ajustes de producción

http.ListenAndServe usa un servidor sin timeouts, así que un cliente lento puede mantener una conexión abierta indefinidamente. Configura un http.Server explícitamente para todo lo que esté expuesto a internet, y apágalo de forma ordenada:

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 deja de aceptar conexiones nuevas y espera a que terminen las peticiones activas, hasta el deadline del context. ListenAndServe devuelve http.ErrServerClosed en cuanto empieza Shutdown, y por eso ese error no se trata como un fallo. Para handlers de larga duración, pasa r.Context() hacia abajo para que se detengan cuando el cliente se va.

Servir archivos estáticos es una línea: mux.Handle("GET /static/", http.StripPrefix("/static/", http.FileServer(http.Dir("public")))).

Errores comunes

• No retornar después de http.Error. El handler sigue ejecutándose y escribe más en la respuesta.
• Poner cabeceras después de escribir el body. Se descartan en silencio.
• Registrar la página de inicio en "/". Se convierte en el comodín de todas las rutas desconocidas. Usa "/{$}".
• Compartir estado entre handlers sin un lock. Las peticiones se ejecutan de forma concurrente.
• Usar el servidor por defecto en producción. No tiene timeouts; ponlos en un http.Server.
• Patrones de ruta ignorados. Si "GET /x/{id}" nunca coincide, comprueba que go.mod diga go 1.22 o posterior.