Исполняемые доки Go: HTTP-клиент

Q: Как сделать GET-запрос в Go?

resp, err := http.Get(url), проверьте err, затем defer resp.Body.Close() и прочитайте тело через io.ReadAll(resp.Body) или декодируйте его через json.NewDecoder(resp.Body).Decode(&v). Проверяйте и resp.StatusCode: 404 или 500 для http.Get не ошибка.

Q: Как задать таймаут HTTP-запроса в Go?

Создайте клиент с таймаутом, client := &http.Client{Timeout: 10 * time.Second}, и используйте его вместо http.Get или http.DefaultClient, у которых нет общего таймаута: сервер, который принял соединение и так и не ответил, блокирует вызов навсегда. Для ограничения на отдельный запрос создайте его через http.NewRequestWithContext с контекстом из context.WithTimeout.

Q: Как отправить POST-запрос с телом JSON в Go?

Закодируйте значение и отправьте его: body, _ := json.Marshal(v) и http.Post(url, "application/json", bytes.NewReader(body)). Чтобы добавить заголовки вроде Authorization, создайте запрос через http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), задайте req.Header.Set("Content-Type", "application/json") и отправьте через client.Do(req).

Q: Зачем закрывать resp.Body в Go?

Тело это поток на открытом соединении. Закрытие возвращает соединение в пул для повторного использования; если забыть, соединения и файловые дескрипторы утекают, пока программа не упрётся в лимит. Закрывайте тело, даже если не читаете его, и дочитывайте до конца, если хотите, чтобы соединение переиспользовалось.

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

Каждый пример на этой странице запускает свой сервер через httptest.NewServer и обращается к нему через настоящее TCP-соединение на localhost. Замените srv.URL на настоящий адрес вроде https://api.example.com, и клиентский код не изменится.

Три правила, которые здесь видны:

Сначала проверяйте err. Он сообщает о том, что не удалось получить вообще никакого ответа: ошибки DNS, отказ в соединении, таймауты, проблемы с TLS.
defer resp.Body.Close() сразу после проверки ошибки. Тело держит соединение открытым. Незакрытое тело приводит к утечке соединения.
Читайте или декодируйте тело. io.ReadAll для текста, json.NewDecoder(resp.Body).Decode(&v) для JSON.

Коды статуса не ошибки

http.Get возвращает err == nil для любого ответа, который прислал сервер, включая 404 и 500. Статус нужно проверять самому:

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 ограничивает, сколько тела ошибки вы прочитаете, чтобы неисправный сервер не заставил вас загрузить мегабайты в сообщение об ошибке. Многие API возвращают при успехе 201, 202 или 204; если подходит любой 2xx, проверяйте resp.StatusCode >= 200 && resp.StatusCode < 300.

Таймауты: не используйте клиент по умолчанию для реального трафика

У http.Get, http.Post и http.DefaultClient нет общего таймаута (транспорт по умолчанию ограничивает только установку соединения и TLS-рукопожатие). Сервер, который принял соединение и так и не ответил, блокирует вашу горутину навсегда. Создайте свой клиент:

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 покрывает весь обмен: соединение, редиректы и чтение тела. Возвращаемая ошибка это *url.Error, у которой Timeout() == true, и errors.As находит её через интерфейс net.Error. Создайте один клиент и используйте его везде; http.Client безопасен для конкурентного использования. Пул соединений живёт в его Transport, а не в Client: новый http.Client{} на каждый запрос всё равно делит http.DefaultTransport и его пул, а вот новый http.Transport на каждый запрос каждый раз начинает с пустым пулом.

Запросы с контекстом и заголовками

http.NewRequestWithContext создаёт запрос, который можно настроить перед отправкой через client.Do. Контекст даёт дедлайн или отмену для отдельного запроса поверх таймаута клиента и привязывает исходящие вызовы к времени жизни входящего запроса на сервере.

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

Если склеивать пользовательский ввод с URL ("?q=" + q), всё ломается на &, # и пробелах. url.Values и его метод Encode делают экранирование и сортируют ключи. Для сегментов пути используйте 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) это сокращение для запроса с таким заголовком Content-Type. Для всего остального (заголовок аутентификации, PUT, PATCH, DELETE) используйте http.NewRequestWithContext с нужным методом и client.Do. Для отправки форм client.PostForm(url, url.Values{...}) кодирует значения и задаёт application/x-www-form-urlencoded.

Повторное использование соединений

Клиент переиспользует TCP-соединение, только когда вы дочитали предыдущее тело до конца и закрыли его. Если вы перестали читать раньше (например, после статуса с ошибкой), а запросов к одному хосту много, вычитайте тело перед закрытием:

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

Для тел, которые могут быть огромными, вычитывайте через io.LimitReader или смиритесь с потерей соединения.

Редиректы

Клиент автоматически следует до 10 редиректов, а resp.Request.URL говорит, где вы в итоге оказались. Чтобы остановиться на первом редиректе, например чтобы прочитать заголовок Location, задайте 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
	},
}

Частые ошибки

http.Get или http.DefaultClient в продакшене. Нет таймаута. Сделайте http.Client с Timeout.
Забытый resp.Body.Close(). Соединения утекают, пока запросы не начнут падать.
Закрытие тела до проверки err. Когда err не nil, resp равен nil, и resp.Body.Close() вызывает панику.
err == nil как признак успеха. Проверяйте resp.StatusCode.
Новый http.Transport на каждый запрос. У каждого транспорта свой пул соединений, поэтому каждый запрос открывает новое соединение (и заново проходит TLS-рукопожатие). Делите один транспорт, обычно через один общий http.Client.
Ручная сборка строки запроса. Используйте url.Values.

Часто задаваемые вопросы

Как сделать GET-запрос в Go?

resp, err := http.Get(url), проверьте err, затем defer resp.Body.Close() и прочитайте тело через io.ReadAll(resp.Body) или декодируйте его через json.NewDecoder(resp.Body).Decode(&v). Проверяйте и resp.StatusCode: 404 или 500 для http.Get не ошибка.

Как задать таймаут HTTP-запроса в Go?

Создайте клиент с таймаутом, client := &http.Client{Timeout: 10 * time.Second}, и используйте его вместо http.Get или http.DefaultClient, у которых нет общего таймаута: сервер, который принял соединение и так и не ответил, блокирует вызов навсегда. Для ограничения на отдельный запрос создайте его через http.NewRequestWithContext с контекстом из context.WithTimeout.

Как отправить POST-запрос с телом JSON в Go?

Закодируйте значение и отправьте его: body, _ := json.Marshal(v) и http.Post(url, "application/json", bytes.NewReader(body)). Чтобы добавить заголовки вроде Authorization, создайте запрос через http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), задайте req.Header.Set("Content-Type", "application/json") и отправьте через client.Do(req).

Зачем закрывать resp.Body в Go?

Тело это поток на открытом соединении. Закрытие возвращает соединение в пул для повторного использования; если забыть, соединения и файловые дескрипторы утекают, пока программа не упрётся в лимит. Закрывайте тело, даже если не читаете его, и дочитывайте до конца, если хотите, чтобы соединение переиспользовалось.

Связанные концепции