実行できるGoドキュメント: HTTPクライアント

Q: GoでGETリクエストを送るには？

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: GoでHTTPリクエストにタイムアウトを設定するには？

タイムアウト付きのクライアント client := &http.Client{Timeout: 10 * time.Second} を作り、http.Get や http.DefaultClient の代わりに使います。これらには全体のタイムアウトがなく、接続を受け入れたまま応答しないサーバーは呼び出しを永遠にブロックします。リクエストごとの制限には、context.WithTimeout のコンテキストを使って http.NewRequestWithContext でリクエストを作ります。

Q: GoでJSONのボディを持つPOSTリクエストを送るには？

値をマーシャルしてからポストします：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: なぜGoではresp.Bodyを閉じる必要があるのですか？

ボディは開いた接続の上のストリームです。閉じると接続がプールに戻り、再利用されます。忘れると、プログラムが上限に達するまで接続とファイルディスクリプタがリークします。読まない場合でも閉じ、接続を再利用させたいなら最後まで読みます。

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 で独自のサーバーを開始し、localhostの本物のTCP接続を通して呼び出しています。srv.URL を https://api.example.com のような本物のアドレスに置き換えても、クライアントのコードは変わりません。

ここに表れている3つのルールは次のとおりです。

まず err をチェックする。 これは、そもそもレスポンスを得られなかった失敗を報告します。DNSのエラー、拒否された接続、タイムアウト、TLSの問題などです。
エラーチェックの直後に defer resp.Body.Close() とする。 ボディは接続を開いたまま保持しています。閉じられていないボディは接続をリークさせます。
ボディを読むかデコードする。 テキストには io.ReadAll、JSONには json.NewDecoder(resp.Body).Decode(&v) を使います。

ステータスコードはエラーではない

http.Get は、404 や 500 を含め、サーバーが送ったどんなレスポンスでも err == nil を返します。ステータスは自分でチェックしなければなりません。

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 は、接続、リダイレクト、ボディの読み込みを含むやり取り全体を対象にします。返されるエラーは Timeout() == true を報告する *url.Error で、errors.As が net.Error インターフェースを通してそれを見つけます。クライアントは1つ作ってどこでも再利用します。http.Client は並行して使っても安全です。接続プールは Client ではなく Transport にあります。リクエストごとに新しい 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 を使います。

JSONをPOSTする

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 を使う。 タイムアウトがありません。Timeout 付きの http.Client を作ります。
resp.Body.Close() を忘れる。 リクエストが失敗し始めるまで接続がリークします。
err をチェックする前にボディを閉じる。 err が nil でないとき resp は nil で、resp.Body.Close() はpanicします。
err == nil を成功とみなす。 resp.StatusCode をチェックします。
リクエストごとに新しい http.Transport を作る。 トランスポートはそれぞれ独自の接続プールを持つので、すべてのリクエストが新しい接続（と新しいTLSハンドシェイク）を開きます。1つのトランスポートを、たいていは共有の http.Client を通して共有します。
クエリ文字列を手で組み立てる。 url.Values を使います。

よくある質問

GoでGETリクエストを送るには？

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 のエラーにはなりません。

GoでHTTPリクエストにタイムアウトを設定するには？

タイムアウト付きのクライアント client := &http.Client{Timeout: 10 * time.Second} を作り、http.Get や http.DefaultClient の代わりに使います。これらには全体のタイムアウトがなく、接続を受け入れたまま応答しないサーバーは呼び出しを永遠にブロックします。リクエストごとの制限には、context.WithTimeout のコンテキストを使って http.NewRequestWithContext でリクエストを作ります。

GoでJSONのボディを持つPOSTリクエストを送るには？

値をマーシャルしてからポストします：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) で送ります。

なぜGoではresp.Bodyを閉じる必要があるのですか？

ボディは開いた接続の上のストリームです。閉じると接続がプールに戻り、再利用されます。忘れると、プログラムが上限に達するまで接続とファイルディスクリプタがリークします。読まない場合でも閉じ、接続を再利用させたいなら最後まで読みます。