Ausführbare Go-Docs: HTTP-Client

Q: Wie stelle ich in Go einen GET-Request?

resp, err := http.Get(url), err prüfen, dann defer resp.Body.Close() und den Body mit io.ReadAll(resp.Body) lesen oder mit json.NewDecoder(resp.Body).Decode(&v) dekodieren. Prüf außerdem resp.StatusCode: Ein 404 oder 500 ist für http.Get kein Fehler.

Q: Wie setze ich in Go einen Timeout für einen HTTP-Request?

Erzeuge einen Client mit Timeout, client := &http.Client{Timeout: 10 * time.Second}, und nutze ihn statt http.Get oder http.DefaultClient. Die haben keinen Gesamt-Timeout: Ein Server, der die Verbindung annimmt und nie antwortet, blockiert den Aufruf für immer. Für ein Limit pro Request baust du den Request mit http.NewRequestWithContext und einem Context aus context.WithTimeout.

Q: Wie sende ich in Go einen POST-Request mit JSON-Body?

Den Wert marshallen und dann senden: body, _ := json.Marshal(v) und http.Post(url, "application/json", bytes.NewReader(body)). Um Header wie Authorization hinzuzufügen, baust du den Request mit http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), setzt req.Header.Set("Content-Type", "application/json") und sendest ihn mit client.Do(req).

Q: Warum muss ich in Go resp.Body schließen?

Der Body ist ein Stream auf einer offenen Verbindung. Schließt du ihn, geht die Verbindung zur Wiederverwendung zurück in den Pool; vergisst du es, leaken Verbindungen und File Descriptors, bis das Programm sein Limit erreicht. Schließ ihn auch, wenn du ihn nicht liest, und lies ihn bis zum Ende, wenn die Verbindung wiederverwendet werden soll.

Ein GET-Request

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

Jedes Beispiel auf dieser Seite startet mit httptest.NewServer einen eigenen Server und ruft ihn über eine echte TCP-Verbindung auf localhost auf. Ersetz srv.URL durch eine echte Adresse wie https://api.example.com, und der Client-Code bleibt unverändert.

Die drei Regeln, die hier zu sehen sind:

Zuerst err prüfen. Es meldet Fehlschläge, bei denen gar keine Antwort ankommt: DNS-Fehler, abgelehnte Verbindungen, Timeouts, TLS-Probleme.
defer resp.Body.Close() direkt nach der Fehlerprüfung. Der Body hält die Verbindung offen. Ein nicht geschlossener Body leakt die Verbindung.
Den Body lesen oder dekodieren. io.ReadAll für Text, json.NewDecoder(resp.Body).Decode(&v) für JSON.

Statuscodes sind keine Fehler

http.Get gibt für jede Antwort, die der Server sendet, err == nil zurück, auch für 404 und 500. Den Status musst du selbst prüfen:

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 begrenzt, wie viel von einem Fehler-Body du liest, damit ein fehlerhafter Server dich nicht Megabytes in eine Fehlermeldung laden lässt. Viele APIs geben bei Erfolg 201, 202 oder 204 zurück; prüf resp.StatusCode >= 200 && resp.StatusCode < 300, wenn jeder 2xx-Code in Ordnung ist.

Timeouts: für echten Traffic nie den Standard-Client

http.Get, http.Post und http.DefaultClient haben keinen Gesamt-Timeout (der Standard-Transport begrenzt nur den Verbindungsaufbau und den TLS-Handshake). Ein Server, der die Verbindung annimmt und nie antwortet, blockiert deine Goroutine für immer. Erzeuge deinen eigenen Client:

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 deckt den ganzen Austausch ab: Verbindungsaufbau, Redirects und das Lesen des Bodys. Der zurückgegebene Fehler ist ein *url.Error, der Timeout() == true meldet, und errors.As findet ihn über das Interface net.Error. Erzeuge einen Client und verwende ihn überall wieder; ein http.Client ist sicher für nebenläufige Nutzung. Der Verbindungspool lebt in seinem Transport, nicht im Client: Ein neuer http.Client{} pro Request teilt sich weiterhin http.DefaultTransport und dessen Pool, aber ein neuer http.Transport pro Request startet jedes Mal mit einem leeren Pool.

Requests mit Context und Headern

http.NewRequestWithContext baut einen Request, den du anpassen kannst, bevor du ihn mit client.Do sendest. Der Context liefert zusätzlich zum Timeout des Clients eine Deadline oder einen Abbruch pro Request und koppelt ausgehende Aufrufe in einem Server an die Lebensdauer eines eingehenden Requests.

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

Nutzereingaben in eine URL zu verketten ("?q=" + q) bricht bei &, # und Leerzeichen. url.Values und seine Methode Encode übernehmen das Escaping und sortieren die Schlüssel. Für Pfadsegmente nimm url.PathEscape.

POST mit 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) ist eine Abkürzung für einen Request mit diesem Content-Type-Header. Für alles andere (einen Auth-Header, PUT, PATCH, DELETE) nimm http.NewRequestWithContext mit der Methode und client.Do. Für Formulare kodiert client.PostForm(url, url.Values{...}) die Werte und setzt application/x-www-form-urlencoded.

Wiederverwendung von Verbindungen

Der Client verwendet eine TCP-Verbindung nur wieder, wenn du den vorherigen Body bis zum Ende gelesen und geschlossen hast. Hörst du früher auf zu lesen (zum Beispiel nach einem Fehlerstatus), leere ihn vor dem Schließen, wenn du viele Requests an denselben Host stellst:

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

Bei Bodys, die riesig sein könnten, leerst du stattdessen über io.LimitReader oder nimmst den Verlust der Verbindung in Kauf.

Redirects

Der Client folgt automatisch bis zu 10 Redirects, und resp.Request.URL sagt dir, wo du gelandet bist. Um beim ersten Redirect anzuhalten, etwa um einen Location-Header zu lesen, setz 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
	},
}

Häufige Fehler

http.Get oder http.DefaultClient in Produktion verwenden. Kein Timeout. Erzeuge einen http.Client mit Timeout.
resp.Body.Close() vergessen. Verbindungen leaken, bis Requests fehlschlagen.
Den Body schließen, bevor err geprüft ist. Ist err nicht nil, ist resp nil, und resp.Body.Close() löst eine Panic aus.
err == nil als Erfolg werten. Prüf resp.StatusCode.
Einen neuen http.Transport pro Request erzeugen. Jeder Transport hat seinen eigenen Verbindungspool, also öffnet jeder Request eine neue Verbindung (samt neuem TLS-Handshake). Teile einen Transport, meist über einen gemeinsamen http.Client.
Query-Strings von Hand bauen. Nimm url.Values.

Häufig gestellte Fragen

Wie stelle ich in Go einen GET-Request?

resp, err := http.Get(url), err prüfen, dann defer resp.Body.Close() und den Body mit io.ReadAll(resp.Body) lesen oder mit json.NewDecoder(resp.Body).Decode(&v) dekodieren. Prüf außerdem resp.StatusCode: Ein 404 oder 500 ist für http.Get kein Fehler.

Wie setze ich in Go einen Timeout für einen HTTP-Request?

Erzeuge einen Client mit Timeout, client := &http.Client{Timeout: 10 * time.Second}, und nutze ihn statt http.Get oder http.DefaultClient. Die haben keinen Gesamt-Timeout: Ein Server, der die Verbindung annimmt und nie antwortet, blockiert den Aufruf für immer. Für ein Limit pro Request baust du den Request mit http.NewRequestWithContext und einem Context aus context.WithTimeout.

Wie sende ich in Go einen POST-Request mit JSON-Body?

Den Wert marshallen und dann senden: body, _ := json.Marshal(v) und http.Post(url, "application/json", bytes.NewReader(body)). Um Header wie Authorization hinzuzufügen, baust du den Request mit http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), setzt req.Header.Set("Content-Type", "application/json") und sendest ihn mit client.Do(req).

Warum muss ich in Go resp.Body schließen?

Der Body ist ein Stream auf einer offenen Verbindung. Schließt du ihn, geht die Verbindung zur Wiederverwendung zurück in den Pool; vergisst du es, leaken Verbindungen und File Descriptors, bis das Programm sein Limit erreicht. Schließ ihn auch, wenn du ihn nicht liest, und lies ihn bis zum Ende, wenn die Verbindung wiederverwendet werden soll.

Verwandte Konzepte