HTTP client trong Golang: GET, POST JSON, timeout và header

Một 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))
}

Mỗi ví dụ trên trang này tự khởi động máy chủ riêng bằng httptest.NewServer và gọi nó qua một kết nối TCP thật trên localhost. Đổi srv.URL thành một địa chỉ thật như https://api.example.com thì code phía client vẫn giữ nguyên.

Ba quy tắc thấy được ở đây:

1. Kiểm tra err trước tiên. Nó báo những lần không nhận được response nào cả: lỗi DNS, kết nối bị từ chối, timeout, sự cố TLS.
2. defer resp.Body.Close() ngay sau khi kiểm tra lỗi. Body giữ kết nối mở. Một body không được đóng sẽ làm rò rỉ kết nối.
3. Đọc hoặc giải mã body. io.ReadAll cho văn bản, json.NewDecoder(resp.Body).Decode(&v) cho JSON.

Mã trạng thái không phải là lỗi

http.Get trả về err == nil với mọi response mà máy chủ gửi, kể cả 404 và 500. Bạn phải tự kiểm tra mã trạng thái:

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 giới hạn lượng dữ liệu bạn đọc từ body lỗi, để một máy chủ hoạt động bất thường không thể bắt bạn nạp hàng megabyte vào một thông báo lỗi. Nhiều API trả về 201, 202 hoặc 204 khi thành công; hãy kiểm tra resp.StatusCode >= 200 && resp.StatusCode < 300 khi mã 2xx nào cũng chấp nhận được.

Timeout: đừng bao giờ dùng client mặc định cho lưu lượng thật

http.Get, http.Post và http.DefaultClient không có timeout tổng (transport mặc định chỉ giới hạn bước quay số kết nối và bắt tay TLS). Một máy chủ chấp nhận kết nối rồi không bao giờ trả lời sẽ chặn goroutine của bạn mãi mãi. Hãy tạo client riêng:

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 bao trùm toàn bộ quá trình trao đổi: kết nối, chuyển hướng và đọc body. Lỗi nó trả về là một *url.Error báo Timeout() == true, mà errors.As tìm ra được qua interface net.Error. Hãy tạo một client và dùng lại ở mọi nơi; http.Client an toàn khi dùng đồng thời. Pool kết nối nằm trong Transport của nó, không nằm trong Client: một http.Client{} mới cho mỗi request vẫn dùng chung http.DefaultTransport và pool của nó, nhưng một http.Transport mới cho mỗi request thì lần nào cũng bắt đầu với pool trống.

Request kèm context và header

http.NewRequestWithContext tạo một request mà bạn có thể tùy chỉnh trước khi gửi bằng client.Do. Context cho thêm hạn chót hoặc việc hủy riêng cho từng request, bên trên timeout của client, và gắn các lời gọi đi ra với vòng đời của một request đi vào trong máy chủ.

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

Nối dữ liệu người dùng nhập vào URL ("?q=" + q) sẽ hỏng khi gặp &, # và khoảng trắng. url.Values cùng phương thức Encode của nó lo việc escape, và sắp xếp các khóa. Với các đoạn của đường dẫn, dùng 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) là lối tắt cho một request có header Content-Type đó. Với mọi trường hợp khác (header xác thực, PUT, PATCH, DELETE), dùng http.NewRequestWithContext với phương thức tương ứng và client.Do. Để gửi form, client.PostForm(url, url.Values{...}) mã hóa các giá trị và đặt application/x-www-form-urlencoded.

Dùng lại kết nối

Client chỉ dùng lại một kết nối TCP khi bạn đã đọc body trước đó đến hết và đóng nó. Nếu bạn dừng đọc sớm (ví dụ sau một mã trạng thái lỗi), hãy đọc nốt phần còn lại trước khi đóng khi bạn gửi nhiều request đến cùng một host:

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

Với những body có thể rất lớn, hãy đọc nốt qua io.LimitReader, hoặc chấp nhận mất kết nối đó.

Chuyển hướng

Client tự động đi theo tối đa 10 lần chuyển hướng, và resp.Request.URL cho bạn biết cuối cùng mình đến đâu. Để dừng ở lần chuyển hướng đầu tiên, chẳng hạn để đọc header Location, đặt 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
	},
}

Lỗi thường gặp

• Dùng http.Get hoặc http.DefaultClient trên production. Không có timeout. Hãy tạo một http.Client có Timeout.
• Quên resp.Body.Close(). Kết nối bị rò rỉ cho đến khi request bắt đầu thất bại.
• Đóng body trước khi kiểm tra err. Khi err khác nil, resp là nil và resp.Body.Close() gây panic.
• Coi err == nil là thành công. Hãy kiểm tra resp.StatusCode.
• Tạo http.Transport mới cho mỗi request. Mỗi transport có pool kết nối riêng, nên request nào cũng mở một kết nối mới (và một lần bắt tay TLS mới). Hãy dùng chung một transport, thường là qua một http.Client dùng chung.
• Tự tay ghép query string. Hãy dùng url.Values.