دليل البدء السريع لـ Go Resty

Go Resty هي مكتبة لغة Go لبناء عملاء API RESTful. باستخدام Go Resty ، يمكن للمطورين بناء عملاء API RESTful موثوق بهم بشكلٍ أسرع وأكثر كفاءة. يُقدم هذا الفصل كيفية البدء بسرعة مع Go Resty.

التثبيت

require github.com/go-resty/resty/v2 v2.7.0

أو

go get github.com/go-resty/resty/v2

مثال Resty

الأمثلة التالية ستساعدك في استخدام مكتبة resty بأكبر قدر من الراحة.

// استيراد مكتبة resty إلى كودك والإشارة إليها باسم `resty`.
import "github.com/go-resty/resty/v2"

طلب GET بسيط

// انشاء عميل Resty
client := resty.New()

resp, err := client.R().
    EnableTrace().
    Get("https://httpbin.org/get")

// استكشاف كائن الاستجابة
fmt.Println("معلومات الاستجابة:")
fmt.Println("  الخطأ      :", err)
fmt.Println("  كود الحالة:", resp.StatusCode())
fmt.Println("  الحالة     :", resp.Status())
fmt.Println("  البروتوكول:", resp.Proto())
fmt.Println("  الوقت      :", resp.Time())
fmt.Println("  تم الاستلام في:", resp.ReceivedAt())
fmt.Println("  الجسم       :\n", resp)
fmt.Println()

// استكشاف معلومات التتبع
fmt.Println("معلومات تتبع الطلب:")
ti := resp.Request.TraceInfo()
fmt.Println("  البحث عن DNS  :", ti.DNSLookup)
fmt.Println("  وقت الاتصال    :", ti.ConnTime)
fmt.Println("  وقت الاتصال بـ TCP:", ti.TCPConnTime)
fmt.Println("  مصافحة TLS   :", ti.TLSHandshake)
fmt.Println("  وقت الخادم     :", ti.ServerTime)
fmt.Println("  وقت الاستجابة   :", ti.ResponseTime)
fmt.Println("  الوقت الإجمالي  :", ti.TotalTime)
fmt.Println("  هل تم إعادة الاتصال :", ti.IsConnReused)
fmt.Println("  كان الاتصال غير نشط :", ti.IsConnWasIdle)
fmt.Println("  وقت الخمول للاتصال :", ti.ConnIdleTime)
fmt.Println("  محاولة الطلب :", ti.RequestAttempt)
fmt.Println("  عنوان البعيد  :", ti.RemoteAddr.String())

النتيجة
معلومات الاستجابة:
  الخطأ      : 
  كود الحالة: 200
  الحالة     : 200 OK
  البروتوكول: HTTP/2.0
  الوقت      : 457.034718ms
  تم الاستلام في: 2020-09-14 15:35:29.784681 -0700 PDT m=+0.458137045
  الجسم       :
  {
    "args": {},
    "headers": {
      "Accept-Encoding": "gzip",
      "Host": "httpbin.org",
      "User-Agent": "go-resty/2.4.0 (https://github.com/go-resty/resty)",
      "X-Amzn-Trace-Id": "Root=1-5f5ff031-000ff6292204aa6898e4de49"
    },
    "origin": "0.0.0.0",
    "url": "https://httpbin.org/get"
  }

معلومات تتبع الطلب:
  البحث عن DNS  : 4.074657ms
  وقت الاتصال    : 381.709936ms
  وقت الاتصال بـ TCP: 77.428048ms
  مصافحة TLS   : 299.623597ms
  وقت الخادم     : 75.414703ms
  وقت الاستجابة   : 79.337µs
  الوقت الإجمالي  : 457.034718ms
  هل تم إعادة الاتصال : false
  كان الاتصال غير نشط : false
  وقت الخمول للاتصال : 0s
  محاولة الطلب : 1
  عنوان البعيد  : 3.221.81.55:443

طلب GET المعقد

// إنشاء عميل Resty
client := resty.New()

// تعيين معلمات الاستعلام
resp, err := client.R().
      SetQueryParams(map[string]string{
          "page_no": "1",
          "limit": "20",
          "sort":"name",
          "order": "asc",
          "random":strconv.FormatInt(time.Now().Unix(), 10),
      }).
      SetHeader("Accept", "application/json").
      SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F").
      Get("/search_result")

// Ex. استخدام طريقة Request.SetQueryString
resp, err := client.R().
      SetQueryString("productId=232&template=fresh-sample&cat=resty&source=google&kw=buy a lot more").
      SetHeader("Accept", "application/json").
      SetAuthToken("BC594900518B4F7EAC75BD37F019E08FBC594900518B4F7EAC75BD37F019E08F").
      Get("/show_product")

// إذا لزم الأمر، فقوم بتحديد نوع محتوى الاستجابة المحدد لإرشاد Resty لتحليل الاستجابة JSON إلى هيكل البيانات
resp, err := client.R().
      SetResult(result).
      ForceContentType("application/json").
      Get("v2/alpine/manifests/latest")

Beواقعات مختلفة لطلبات POST

// إنشاء عميل Resty
client := resty.New()

// POST السلسلة JSON
// إذا تم تعيين الإعدادات على مستوى العميل، لا يلزم تعيين نوع المحتوى
resp, err := client.R().
      SetHeader("Content-Type", "application/json").
      SetBody(`{"username":"testuser", "password":"testpass"}`).
      SetResult(&AuthSuccess{}).    // أو SetResult(AuthSuccess{}).
      Post("https://myapp.com/login")

// POST []byte مصفوفة
// إذا تم تعيين الإعدادات على مستوى العميل، لا يلزم تعيين نوع المحتوى
resp, err := client.R().
      SetHeader("Content-Type", "application/json").
      SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
      SetResult(&AuthSuccess{}).    // أو SetResult(AuthSuccess{}).
      Post("https://myapp.com/login")

// POST ستركت معتمد على نوع المحتوى JSON بشكل افتراضي، لا يلزم تعيينه
resp, err := client.R().
      SetBody(User{Username: "testuser", Password: "testpass"}).
      SetResult(&AuthSuccess{}).    // أو SetResult(AuthSuccess{}).
      SetError(&AuthError{}).       // أو SetError(AuthError{}).
      Post("https://myapp.com/login")

// POST خريطة معتمدة على نوع المحتوى JSON بشكل افتراضي، لا يلزم تعيينه
resp, err := client.R().
      SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
      SetResult(&AuthSuccess{}).    // أو SetResult(AuthSuccess{}).
      SetError(&AuthError{}).       // أو SetError(AuthError{}).
      Post("https://myapp.com/login")

// تحميل ملف كمصفوفة بايتات نقية. مثال: تحميل ملف إلى Dropbox
fileBytes, _ := os.ReadFile("/Users/jeeva/mydocument.pdf")

// لاحظ أننا لا نقوم بتعيين رأس نوع المحتوى لأن go-resty سيكتشف تلقائيًا نوع المحتوى
resp, err := client.R().
      SetBody(fileBytes).
      SetContentLength(true).          // Dropbox يتطلب هذا القيمة
      SetAuthToken("").
      SetError(&DropboxError{}).       // أو SetError(DropboxError{}).
      Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf") // تدعم DropBox أيضًا عمليات التحميل بطريقة PUT

// ملاحظة: إذا لم يتم تعيين رأس نوع المحتوى، سيكتشف resty نوع المحتوى لجسم الطلب تلقائيًا
//   * بالنسبة لأنواع البيانات struct و map، يعتمد افتراضيًا على 'application/json'
//   * ثم يتبع ذلك نوع المحتوى النصي العادي

طلب PUT

يمكنك استخدام مجموعة متنوعة من استدعاء طريقة PUT تمامًا كما هو موضح لـ POST.

// ملاحظة: هذا مثال على استخدام طريقة PUT، للمزيد من الاختلافات يُرجى الرجوع إلى POST

// إنشاء عميل Resty
client := resty.New()

// إرسال الطلب بنوع المحتوى JSON
// إذا كانت هناك إعدادات على مستوى العميل، فيمكن تجاهل رمز المصادقة، ويمكن أن يكون ذلك مصدر لخطأ
resp, err := client.R().
      SetBody(Article{
        Title: "go-resty",
        Content: "هذا محتوى مقالي، نعم!",
        Author: "جيفانندام إم",
        Tags: []string{"مقال", "مثال", "ريستي"},
      }).
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      SetError(&Error{}).       // أو SetError(Error{}).
      Put("https://myapp.com/article/1234")

طلب PATCH

يمكنك استخدام مجموعة متنوعة من استدعاء طريقة PATCH تمامًا كما هو موضح لـ POST.

// ملاحظة: هذا مثال على استخدام طريقة PATCH، للمزيد من الاختلافات يُرجى الرجوع إلى POST

// إنشاء عميل Resty
client := resty.New()

// إرسال الطلب بنوع المحتوى JSON
// إذا كانت هناك إعدادات على مستوى العميل، فيمكن تجاهل رمز المصادقة، ويمكن أن يكون ذلك مصدر لخطأ
resp, err := client.R().
      SetBody(Article{
        Tags: []string{"وسم جديد 1", "وسم جديد 2"},
      }).
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      SetError(&Error{}).       // أو SetError(Error{}).
      Patch("https://myapp.com/articles/1234")

طلبات DELETE، HEAD، OPTIONS

// إنشاء عميل Resty
client := resty.New()

// حذف مقال
// إذا كانت هناك إعدادات على مستوى العميل، فيمكن تجاهل رمز المصادقة، ويمكن أن يكون ذلك مصدر لخطأ
resp, err := client.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      SetError(&Error{}).       // أو SetError(Error{}).
      Delete("https://myapp.com/articles/1234")

// حذف مقالات متعددة باستخدام سلسلة JSON كمحتوى/بيانات
// إذا كانت هناك إعدادات على مستوى العميل، فيمكن تجاهل رمز المصادقة، ويمكن أن يكون ذلك مصدر لخطأ
resp, err := client.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      SetError(&Error{}).       // أو SetError(Error{}).
      SetHeader("Content-Type", "application/json").
      SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
      Delete("https://myapp.com/articles")

// الحصول على معلومات الرأس لمورد
// إذا كانت هناك إعدادات على مستوى العميل، فيمكن تجاهل رمز المصادقة
resp, err := client.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      Head("https://myapp.com/videos/hi-res-video")

// الحصول على معلومات الخيارات لمورد
// إذا كانت هناك إعدادات على مستوى العميل، فيمكن تجاهل رمز المصادقة
resp, err := client.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      Options("https://myapp.com/servers/nyc-dc-01")

إعداد عمليات التسلسل/التفسير للـ JSON و XML

يمكن للمستخدمين تسجيل مكتباتهم المفضلة للـ JSON/XML مع resty، أو كتابة مكتباتهم الخاصة. بشكل افتراضي، يقوم resty بتسجيل مكتبات encoding/json و encoding/xml القياسية.

// مثال على تسجيل json-iterator
import jsoniter "github.com/json-iterator/go"

json := jsoniter.ConfigCompatibleWithStandardLibrary

client := resty.New().
    SetJSONMarshaler(json.Marshal).
    SetJSONUnmarshaler(json.Unmarshal)

// بالمثل، يمكن للمستخدمين إعداد XML كما يلي -
client.SetXMLMarshaler(xml.Marshal).
    SetXMLUnmarshaler(xml.Unmarshal)