תיעוד Go עם דוגמאות להרצה: HTTP Client

Q: איך שולחים בקשת GET ב-Go?

resp, err := http.Get(url), בודקים את err, אחר כך defer resp.Body.Close() וקוראים את ה-body עם io.ReadAll(resp.Body) או מפענחים אותו עם json.NewDecoder(resp.Body).Decode(&v). בדקו גם את resp.StatusCode: 404 או 500 הם לא שגיאה מבחינת http.Get.

Q: איך מגדירים timeout לבקשת HTTP ב-Go?

צרו client עם timeout, client := &http.Client{Timeout: 10 * time.Second}, והשתמשו בו במקום http.Get או http.DefaultClient, שאין להם timeout כולל: שרת שמקבל את החיבור ולא עונה אף פעם חוסם את הקריאה לנצח. למגבלה לכל בקשה בנפרד, בנו את הבקשה עם http.NewRequestWithContext ועם context מ-context.WithTimeout.

Q: איך שולחים בקשת POST עם body של JSON ב-Go?

עשו marshal לערך ואז שלחו אותו: body, _ := json.Marshal(v) ו-http.Post(url, "application/json", bytes.NewReader(body)). כדי להוסיף headers כמו Authorization, בנו את הבקשה עם http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), הגדירו req.Header.Set("Content-Type", "application/json") ושלחו אותה עם client.Do(req).

Q: למה צריך לסגור את resp.Body ב-Go?

ה-body הוא stream על חיבור פתוח. סגירה שלו מחזירה את החיבור ל-pool לשימוש חוזר; אם שוכחים, חיבורים ו-file descriptors דולפים עד שהתוכנית מגיעה למגבלה שלה. סגרו אותו גם כשאתם לא קוראים אותו, וקראו אותו עד הסוף אם אתם רוצים שהחיבור ישמש שוב.

בקשת 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 וקוד ה-client לא ישתנה.

שלושת הכללים שרואים כאן:

בדקו קודם את err. הוא מדווח על כישלון לקבל תשובה כלשהי: שגיאות DNS, חיבורים שנדחו, timeouts, בעיות TLS.
defer resp.Body.Close() מיד אחרי בדיקת השגיאה. ה-body מחזיק את החיבור פתוח. body שלא נסגר מדליף את החיבור.
קראו או פענחו את ה-body. 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 מגביל כמה מה-body של שגיאה אתם קוראים, כך ששרת שמתנהג לא כראוי לא יוכל לגרום לכם לטעון מגהבייטים לתוך הודעת שגיאה. הרבה APIs מחזירים 201, 202 או 204 כהצלחה; בדקו resp.StatusCode >= 200 && resp.StatusCode < 300 כשכל 2xx מתאים לכם.

Timeouts: אף פעם לא להשתמש ב-client ברירת המחדל לתעבורה אמיתית

ל-http.Get, ל-http.Post ול-http.DefaultClient אין timeout כולל (ה-transport ברירת המחדל מגביל רק את יצירת החיבור ואת ה-TLS handshake). שרת שמקבל את החיבור ולא עונה אף פעם חוסם את ה-goroutine שלכם לנצח. צרו 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 מכסה את כל חילופי הדברים: התחברות, redirects וקריאת ה-body. השגיאה שהוא מחזיר היא *url.Error שמדווחת Timeout() == true, ו-errors.As מוצאת אותה דרך ה-interface net.Error. צרו client אחד והשתמשו בו בכל מקום; http.Client בטוח לשימוש מקבילי. ה-pool של החיבורים נמצא ב-Transport שלו, לא ב-Client: http.Client{} חדש לכל בקשה עדיין חולק את http.DefaultTransport ואת ה-pool שלו, אבל http.Transport חדש לכל בקשה מתחיל כל פעם עם pool ריק.

בקשות עם context ו-headers

http.NewRequestWithContext בונה בקשה שאפשר להתאים לפני ששולחים אותה עם client.Do. ה-context נותן deadline או ביטול לכל בקשה, מעבר ל-timeout של ה-client, וקושר קריאות יוצאות למשך החיים של בקשה נכנסת בשרת.

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 שלו מבצעים את ה-escaping וממיינים את המפתחות. לחלקים של ה-path, השתמשו ב-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) הוא קיצור לבקשה עם ה-header Content-Type הזה. לכל דבר אחר (header של הרשאה, PUT, PATCH, DELETE) השתמשו ב-http.NewRequestWithContext עם המתודה וב-client.Do. לשליחת טפסים, client.PostForm(url, url.Values{...}) מקודד את הערכים ומגדיר application/x-www-form-urlencoded.

שימוש חוזר בחיבורים

ה-client משתמש שוב בחיבור TCP רק כשקוראים את ה-body הקודם עד הסוף וסוגרים אותו. אם מפסיקים לקרוא מוקדם (למשל אחרי סטטוס של שגיאה), רוקנו אותו לפני הסגירה כששולחים הרבה בקשות לאותו host:

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

ל-bodies שעלולים להיות ענקיים, רוקנו דרך io.LimitReader, או השלימו עם אובדן החיבור.

Redirects

ה-client עוקב אוטומטית אחרי עד 10 redirects, ו-resp.Request.URL אומר לכם לאן הגעתם בסוף. כדי לעצור ב-redirect הראשון, למשל כדי לקרוא header של 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 ב-production. אין timeout. צרו http.Client עם Timeout.
לשכוח את resp.Body.Close(). חיבורים דולפים עד שבקשות מתחילות להיכשל.
סגירת ה-body לפני בדיקת err. כש-err הוא לא nil, resp הוא nil ו-resp.Body.Close() נכנס ל-panic.
להתייחס ל-err == nil כהצלחה. בדקו את resp.StatusCode.
יצירת http.Transport חדש לכל בקשה. לכל transport יש pool חיבורים משלו, ולכן כל בקשה פותחת חיבור חדש (ו-TLS handshake חדש). שתפו transport אחד, בדרך כלל דרך http.Client משותף אחד.
בניית query strings ביד. השתמשו ב-url.Values.

שאלות נפוצות

איך שולחים בקשת GET ב-Go?

resp, err := http.Get(url), בודקים את err, אחר כך defer resp.Body.Close() וקוראים את ה-body עם io.ReadAll(resp.Body) או מפענחים אותו עם json.NewDecoder(resp.Body).Decode(&v). בדקו גם את resp.StatusCode: 404 או 500 הם לא שגיאה מבחינת http.Get.

איך מגדירים timeout לבקשת HTTP ב-Go?

צרו client עם timeout, client := &http.Client{Timeout: 10 * time.Second}, והשתמשו בו במקום http.Get או http.DefaultClient, שאין להם timeout כולל: שרת שמקבל את החיבור ולא עונה אף פעם חוסם את הקריאה לנצח. למגבלה לכל בקשה בנפרד, בנו את הבקשה עם http.NewRequestWithContext ועם context מ-context.WithTimeout.

איך שולחים בקשת POST עם body של JSON ב-Go?

עשו marshal לערך ואז שלחו אותו: body, _ := json.Marshal(v) ו-http.Post(url, "application/json", bytes.NewReader(body)). כדי להוסיף headers כמו Authorization, בנו את הבקשה עם http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), הגדירו req.Header.Set("Content-Type", "application/json") ושלחו אותה עם client.Do(req).

למה צריך לסגור את resp.Body ב-Go?

ה-body הוא stream על חיבור פתוח. סגירה שלו מחזירה את החיבור ל-pool לשימוש חוזר; אם שוכחים, חיבורים ו-file descriptors דולפים עד שהתוכנית מגיעה למגבלה שלה. סגרו אותו גם כשאתם לא קוראים אותו, וקראו אותו עד הסוף אם אתם רוצים שהחיבור ישמש שוב.

מושגים קשורים