وثائق 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 من مقدار ما تقرؤه من جسم الخطأ، فلا يستطيع خادم سيئ السلوك أن يجعلك تحمّل ميغابايتات في رسالة خطأ. كثير من الواجهات البرمجية تعيد 201 أو 202 أو 204 للنجاح؛ افحص resp.StatusCode >= 200 && resp.StatusCode < 300 عندما يكون أي رمز 2xx مقبولًا.

المهل: لا تستخدم العميل الافتراضي للحركة الحقيقية أبدًا

ليس لـ http.Get وhttp.Post وhttp.DefaultClient أي مهلة كلية (الناقل الافتراضي يحدّ فقط الاتصال ومصافحة TLS). الخادم الذي يقبل الاتصال ولا يجيب أبدًا يوقف الـ goroutine الخاصة بك إلى الأبد. أنشئ عميلك الخاص:

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() حالة panic.
اعتبار 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؟

الجسم تدفّق على اتصال مفتوح. إغلاقه يعيد الاتصال إلى المجمّع لإعادة استخدامه؛ ونسيانه يسرّب الاتصالات وواصفات الملفات حتى يبلغ البرنامج حدّه. أغلقه حتى عندما لا تقرؤه، واقرأه حتى النهاية إذا أردت إعادة استخدام الاتصال.

مفاهيم ذات صلة