Dokumentacja Go z przykładami: Klient HTTP

Q: Jak wysłać żądanie GET w Go?

resp, err := http.Get(url), sprawdź err, potem defer resp.Body.Close() i przeczytaj body przez io.ReadAll(resp.Body) albo zdekoduj je przez json.NewDecoder(resp.Body).Decode(&v). Sprawdź też resp.StatusCode: 404 czy 500 to nie jest błąd zwracany przez http.Get.

Q: Jak ustawić timeout żądania HTTP w Go?

Utwórz klienta z timeoutem, client := &http.Client{Timeout: 10 * time.Second}, i używaj go zamiast http.Get czy http.DefaultClient, które nie mają ogólnego timeoutu: serwer, który przyjmie połączenie i nigdy nie odpowie, zablokuje wywołanie na zawsze. Dla limitu na pojedyncze żądanie zbuduj je przez http.NewRequestWithContext z kontekstem z context.WithTimeout.

Q: Jak wysłać żądanie POST z body w JSON w Go?

Zserializuj wartość, a potem ją wyślij: body, _ := json.Marshal(v) i http.Post(url, "application/json", bytes.NewReader(body)). Aby dodać nagłówki, np. Authorization, zbuduj żądanie przez http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), ustaw req.Header.Set("Content-Type", "application/json") i wyślij je przez client.Do(req).

Q: Dlaczego w Go trzeba zamykać resp.Body?

Body to strumień na otwartym połączeniu. Zamknięcie go oddaje połączenie do puli do ponownego użycia; bez zamknięcia połączenia i deskryptory plików wyciekają, aż program osiągnie limit. Zamykaj body nawet wtedy, gdy go nie czytasz, i czytaj je do końca, jeśli połączenie ma zostać użyte ponownie.

Żądanie 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))
}

Każdy przykład na tej stronie uruchamia własny serwer przez httptest.NewServer i łączy się z nim prawdziwym połączeniem TCP na localhost. Zamień srv.URL na prawdziwy adres (np. https://api.example.com), a kod klienta pozostanie bez zmian.

Widać tu trzy zasady:

Najpierw sprawdź err. Zgłasza sytuacje, w których nie udało się dostać żadnej odpowiedzi: błędy DNS, odrzucone połączenia, timeouty, problemy z TLS.
defer resp.Body.Close() zaraz po sprawdzeniu błędu. Body trzyma otwarte połączenie. Niezamknięte body powoduje wyciek połączenia.
Przeczytaj lub zdekoduj body. io.ReadAll dla tekstu, json.NewDecoder(resp.Body).Decode(&v) dla JSON.

Kody statusu to nie błędy

http.Get zwraca err == nil dla każdej odpowiedzi, którą wyśle serwer, także 404 i 500. Status musisz sprawdzić sam:

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 ogranicza, ile body błędu przeczytasz, więc źle działający serwer nie zmusi cię do wczytania megabajtów do komunikatu błędu. Wiele API zwraca przy sukcesie 201, 202 albo 204; sprawdzaj resp.StatusCode >= 200 && resp.StatusCode < 300, gdy każdy kod 2xx jest w porządku.

Timeouty: nigdy nie używaj domyślnego klienta do prawdziwego ruchu

http.Get, http.Post i http.DefaultClient nie mają ogólnego timeoutu (domyślny transport ogranicza tylko nawiązywanie połączenia i handshake TLS). Serwer, który przyjmie połączenie i nigdy nie odpowie, zablokuje twoją gorutynę na zawsze. Utwórz własnego klienta:

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 obejmuje całą wymianę: łączenie, przekierowania i czytanie body. Zwracany błąd to *url.Error, który zgłasza Timeout() == true, a errors.As znajduje go przez interfejs net.Error. Utwórz jednego klienta i używaj go wszędzie; http.Client jest bezpieczny przy współbieżnym użyciu. Pula połączeń żyje w jego Transport, a nie w Client: nowy http.Client{} na każde żądanie nadal współdzieli http.DefaultTransport i jego pulę, ale nowy http.Transport na każde żądanie za każdym razem zaczyna z pustą pulą.

Żądania z kontekstem i nagłówkami

http.NewRequestWithContext buduje żądanie, które możesz dostosować przed wysłaniem przez client.Do. Kontekst daje termin lub anulowanie dla pojedynczego żądania, niezależnie od timeoutu klienta, i wiąże wywołania wychodzące z czasem życia przychodzącego żądania na serwerze.

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

Doklejanie danych od użytkownika do URL ("?q=" + q) psuje się na &, # i spacjach. url.Values i jego metoda Encode zajmują się escapowaniem i sortują klucze. Dla segmentów ścieżki użyj url.PathEscape.

POST 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) to skrót dla żądania z takim nagłówkiem Content-Type. Do wszystkiego innego (nagłówek autoryzacji, PUT, PATCH, DELETE) użyj http.NewRequestWithContext z metodą i client.Do. Przy wysyłaniu formularzy client.PostForm(url, url.Values{...}) koduje wartości i ustawia application/x-www-form-urlencoded.

Ponowne użycie połączeń

Klient ponownie używa połączenia TCP tylko wtedy, gdy przeczytasz poprzednie body do końca i je zamkniesz. Jeśli przerwiesz czytanie wcześniej (np. po statusie błędu), a wysyłasz wiele żądań do tego samego hosta, opróżnij body przed zamknięciem:

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

Przy body, które może być ogromne, opróżniaj je przez io.LimitReader albo pogódź się z utratą połączenia.

Przekierowania

Klient automatycznie wykonuje do 10 przekierowań, a resp.Request.URL mówi, pod jakim adresem kończy się ten łańcuch. Aby zatrzymać się na pierwszym przekierowaniu, np. żeby odczytać nagłówek Location, ustaw 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
	},
}

Częste błędy

Używanie http.Get lub http.DefaultClient na produkcji. Brak timeoutu. Utwórz http.Client z Timeout.
Brak resp.Body.Close(). Połączenia wyciekają, aż żądania zaczynają zawodzić.
Zamykanie body przed sprawdzeniem err. Gdy err nie jest nil, resp jest nil, a resp.Body.Close() wywołuje panikę.
Traktowanie err == nil jako sukcesu. Sprawdzaj resp.StatusCode.
Tworzenie nowego http.Transport na każde żądanie. Każdy transport ma własną pulę połączeń, więc każde żądanie otwiera nowe połączenie (i robi nowy handshake TLS). Współdziel jeden transport, zwykle przez jeden wspólny http.Client.
Ręczne budowanie query stringów. Użyj url.Values.

Najczęściej zadawane pytania

Jak wysłać żądanie GET w Go?

resp, err := http.Get(url), sprawdź err, potem defer resp.Body.Close() i przeczytaj body przez io.ReadAll(resp.Body) albo zdekoduj je przez json.NewDecoder(resp.Body).Decode(&v). Sprawdź też resp.StatusCode: 404 czy 500 to nie jest błąd zwracany przez http.Get.

Jak ustawić timeout żądania HTTP w Go?

Utwórz klienta z timeoutem, client := &http.Client{Timeout: 10 * time.Second}, i używaj go zamiast http.Get czy http.DefaultClient, które nie mają ogólnego timeoutu: serwer, który przyjmie połączenie i nigdy nie odpowie, zablokuje wywołanie na zawsze. Dla limitu na pojedyncze żądanie zbuduj je przez http.NewRequestWithContext z kontekstem z context.WithTimeout.

Jak wysłać żądanie POST z body w JSON w Go?

Zserializuj wartość, a potem ją wyślij: body, _ := json.Marshal(v) i http.Post(url, "application/json", bytes.NewReader(body)). Aby dodać nagłówki, np. Authorization, zbuduj żądanie przez http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), ustaw req.Header.Set("Content-Type", "application/json") i wyślij je przez client.Do(req).

Dlaczego w Go trzeba zamykać resp.Body?

Body to strumień na otwartym połączeniu. Zamknięcie go oddaje połączenie do puli do ponownego użycia; bez zamknięcia połączenia i deskryptory plików wyciekają, aż program osiągnie limit. Zamykaj body nawet wtedy, gdy go nie czytasz, i czytaj je do końca, jeśli połączenie ma zostać użyte ponownie.

Powiązane zagadnienia