Cliente HTTP en Golang: GET, POST JSON, timeouts y cabeceras

Una petición GET

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
)

func main() {
	// A local test server stands in for a real API (the editor has no internet access).
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "you asked for %s", r.URL.Path)
	}))
	defer srv.Close()

	resp, err := http.Get(srv.URL + "/status")
	if err != nil {
		fmt.Println("request failed:", err)
		return
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("reading body:", err)
		return
	}
	fmt.Println(resp.StatusCode, resp.Header.Get("Content-Type"))
	fmt.Println(string(body))
}

Cada ejemplo de esta página arranca su propio servidor con httptest.NewServer y lo llama a través de una conexión TCP real en localhost. Cambia srv.URL por una dirección real como https://api.example.com y el código del cliente no cambia.

Las tres reglas que se ven aquí:

1. Comprueba primero err. Informa de los fallos al obtener cualquier respuesta: errores de DNS, conexiones rechazadas, timeouts, problemas de TLS.
2. defer resp.Body.Close() justo después de comprobar el error. El body mantiene abierta la conexión. Un body sin cerrar fuga la conexión.
3. Lee o decodifica el body. io.ReadAll para texto, json.NewDecoder(resp.Body).Decode(&v) para JSON.

Los códigos de estado no son errores

http.Get devuelve err == nil para cualquier respuesta que envíe el servidor, incluidos 404 y 500. El estado lo tienes que comprobar tú:

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
)

type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

func getUser(baseURL string, id int) (User, error) {
	resp, err := http.Get(fmt.Sprintf("%s/users/%d", baseURL, id))
	if err != nil {
		return User{}, err
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		// Read a little of the body: APIs usually explain the error there.
		msg, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
		return User{}, fmt.Errorf("get user %d: %s: %s", id, resp.Status, bytes.TrimSpace(msg))
	}

	var u User
	if err := json.NewDecoder(resp.Body).Decode(&u); err != nil {
		return User{}, fmt.Errorf("decode user %d: %w", id, err)
	}
	return u, nil
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
		if r.PathValue("id") != "1" {
			http.Error(w, "no such user", http.StatusNotFound)
			return
		}
		w.Header().Set("Content-Type", "application/json")
		fmt.Fprint(w, `{"id": 1, "name": "Grace"}`)
	})
	srv := httptest.NewServer(mux)
	defer srv.Close()

	fmt.Println(getUser(srv.URL, 1))
	fmt.Println(getUser(srv.URL, 2))
}

io.LimitReader limita cuánto lees de un body de error, para que un servidor que se porta mal no te haga cargar megabytes en un mensaje de error. Muchas APIs devuelven 201, 202 o 204 como éxito; comprueba resp.StatusCode >= 200 && resp.StatusCode < 300 cuando te valga cualquier 2xx.

Timeouts: nunca uses el cliente por defecto para tráfico real

http.Get, http.Post y http.DefaultClient no tienen timeout global (el transporte por defecto solo limita la conexión y el handshake TLS). Un servidor que acepta la conexión y nunca responde bloquea tu goroutine para siempre. Crea tu propio cliente:

package main

import (
	"errors"
	"fmt"
	"net"
	"net/http"
	"net/http/httptest"
	"time"
)

func main() {
	slow := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		select {
		case <-time.After(2 * time.Second):
		case <-r.Context().Done(): // stop when the client gives up
		}
	}))
	defer slow.Close()

	client := &http.Client{Timeout: 100 * time.Millisecond}

	start := time.Now()
	_, err := client.Get(slow.URL)
	fmt.Println("gave up quickly:", time.Since(start) < time.Second)

	var netErr net.Error
	if errors.As(err, &netErr) && netErr.Timeout() {
		fmt.Println("timeout error:", netErr.Timeout())
	}
}

Client.Timeout cubre todo el intercambio: la conexión, las redirecciones y la lectura del body. El error que devuelve es un *url.Error que informa Timeout() == true, y errors.As lo encuentra a través de la interfaz net.Error. Crea un solo cliente y reutilízalo en todas partes; un http.Client es seguro para uso concurrente. El pool de conexiones vive en su Transport, no en el Client: un http.Client{} nuevo por petición sigue compartiendo http.DefaultTransport y su pool, pero un http.Transport nuevo por petición empieza cada vez con el pool vacío.

Peticiones con context y cabeceras

http.NewRequestWithContext construye una petición que puedes personalizar antes de enviarla con client.Do. El context da un deadline o una cancelación por petición, además del timeout del cliente, y ata las llamadas salientes a la vida de una petición entrante en un servidor.

package main

import (
	"context"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"net/url"
	"time"
)

func main() {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "auth=%q agent=%q q=%q page=%q",
			r.Header.Get("Authorization"), r.Header.Get("User-Agent"),
			r.URL.Query().Get("q"), r.URL.Query().Get("page"))
	}))
	defer srv.Close()

	client := &http.Client{Timeout: 10 * time.Second}

	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancel()

	// Build the query string safely: url.Values escapes spaces and symbols.
	params := url.Values{}
	params.Set("q", "go & rust")
	params.Set("page", "2")
	target := srv.URL + "/search?" + params.Encode()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil)
	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Set("Authorization", "Bearer token123")
	req.Header.Set("User-Agent", "docs-example/1.0")

	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
	fmt.Println("encoded query:", params.Encode())
}

Concatenar la entrada del usuario en una URL ("?q=" + q) se rompe con &, # y los espacios. url.Values y su método Encode hacen el escapado, y ordenan las claves. Para segmentos de la ruta, usa url.PathEscape.

POST con JSON

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"time"
)

type Order struct {
	Item     string `json:"item"`
	Quantity int    `json:"quantity"`
}

type Created struct {
	ID     int    `json:"id"`
	Status string `json:"status"`
}

func main() {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		var o Order
		if r.Header.Get("Content-Type") != "application/json" {
			http.Error(w, "want JSON", http.StatusUnsupportedMediaType)
			return
		}
		if err := json.NewDecoder(r.Body).Decode(&o); err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(http.StatusCreated)
		json.NewEncoder(w).Encode(Created{ID: 101, Status: fmt.Sprintf("%d x %s", o.Quantity, o.Item)})
	}))
	defer srv.Close()

	client := &http.Client{Timeout: 5 * time.Second}

	payload, err := json.Marshal(Order{Item: "coffee", Quantity: 2})
	if err != nil {
		fmt.Println(err)
		return
	}

	resp, err := client.Post(srv.URL+"/orders", "application/json", bytes.NewReader(payload))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusCreated {
		msg, _ := io.ReadAll(resp.Body)
		fmt.Println("unexpected status:", resp.Status, string(msg))
		return
	}
	var c Created
	if err := json.NewDecoder(resp.Body).Decode(&c); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("%d %+v\n", resp.StatusCode, c)
}

client.Post(url, contentType, body) es un atajo para una petición con esa cabecera Content-Type. Para cualquier otra cosa (una cabecera de autenticación, PUT, PATCH, DELETE) usa http.NewRequestWithContext con el método y client.Do. Para enviar formularios, client.PostForm(url, url.Values{...}) codifica los valores y pone application/x-www-form-urlencoded.

Reutilización de conexiones

El cliente reutiliza una conexión TCP solo cuando lees el body anterior hasta el final y lo cierras. Si dejas de leer antes (por ejemplo, tras un estado de error), vacíalo antes de cerrarlo cuando hagas muchas peticiones al mismo host:

defer func() {
	io.Copy(io.Discard, resp.Body)
	resp.Body.Close()
}()

Para bodies que podrían ser enormes, vacíalos a través de io.LimitReader, o acepta perder la conexión.

Redirecciones

El cliente sigue automáticamente hasta 10 redirecciones, y resp.Request.URL te dice dónde acabaste. Para detenerte en la primera redirección, por ejemplo para leer una cabecera Location, define CheckRedirect:

client := &http.Client{
	Timeout: 10 * time.Second,
	CheckRedirect: func(req *http.Request, via []*http.Request) error {
		return http.ErrUseLastResponse // return the 3xx response itself
	},
}

Errores comunes

• Usar http.Get o http.DefaultClient en producción. Sin timeout. Crea un http.Client con Timeout.
• Olvidar resp.Body.Close(). Las conexiones se fugan hasta que las peticiones empiezan a fallar.
• Cerrar el body antes de comprobar err. Cuando err no es nil, resp es nil y resp.Body.Close() provoca un panic.
• Tomar err == nil como éxito. Comprueba resp.StatusCode.
• Crear un http.Transport nuevo por petición. Cada transporte tiene su propio pool de conexiones, así que cada petición abre una conexión nueva (y un handshake TLS nuevo). Comparte un solo transporte, normalmente a través de un único http.Client compartido.
• Construir las query strings a mano. Usa url.Values.