Przewodnik Szybkiego Startu Go Resty

Go Resty to biblioteka języka Go służąca do budowania klientów interfejsu API RESTful. Dzięki Go Resty, programiści mogą szybciej i bardziej efektywnie budować niezawodnych klientów interfejsu API RESTful. Ten rozdział przedstawia, jak szybko rozpocząć pracę z Go Resty.

Instalacja

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

lub

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

Przykład użycia Resty

Poniższe przykłady pomogą Ci jak najbardziej komfortowo korzystać z biblioteki resty.

// Importuj resty do swojego kodu i odwołuj się do niego jako `resty`.
import "github.com/go-resty/resty/v2"

Proste żądanie GET

// Utwórz klienta Resty
client := resty.New()

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

// Eksploruj obiekt odpowiedzi
fmt.Println("Informacje o odpowiedzi:")
fmt.Println("  Błąd           :", err)
fmt.Println("  Kod stanu      :", resp.StatusCode())
fmt.Println("  Status         :", resp.Status())
fmt.Println("  Protokół       :", resp.Proto())
fmt.Println("  Czas           :", resp.Time())
fmt.Println("  Odebrane o     :", resp.ReceivedAt())
fmt.Println("  Treść          :\n", resp)
fmt.Println()

// Eksploruj informacje śledzenia
fmt.Println("Informacje śledzenia żądania:")
ti := resp.Request.TraceInfo()
fmt.Println("  Wyszukiwanie DNS       :", ti.DNSLookup)
fmt.Println("  Czas połączenia        :", ti.ConnTime)
fmt.Println("  Czas połączenia TCP    :", ti.TCPConnTime)
fmt.Println("  Ustalenie połączenia TLS:", ti.TLSHandshake)
fmt.Println("  Czas serwera           :", ti.ServerTime)
fmt.Println("  Czas odpowiedzi         :", ti.ResponseTime)
fmt.Println("  Całkowity czas          :", ti.TotalTime)
fmt.Println("  Czy połączenie było ponownie używane  :", ti.IsConnReused)
fmt.Println("  Połączenie było bezczynne  :", ti.IsConnWasIdle)
fmt.Println("  Czas bezczynności połączenia:", ti.ConnIdleTime)
fmt.Println("  Próba żądania         :", ti.RequestAttempt)
fmt.Println("  Adres zdalny          :", ti.RemoteAddr.String())

Output
Informacje o odpowiedzi:
  Błąd           : 
  Kod stanu      : 200
  Status         : 200 OK
  Protokół       : HTTP/2.0
  Czas           : 457.034718ms
  Odebrane o     : 2020-09-14 15:35:29.784681 -0700 PDT m=+0.458137045
  Treść          :
  {
    "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"
  }

Informacje śledzenia żądania:
  Wyszukiwanie DNS       : 4.074657ms
  Czas połączenia        : 381.709936ms
  Czas połączenia TCP    : 77.428048ms
  Ustalenie połączenia TLS: 299.623597ms
  Czas serwera           : 75.414703ms
  Czas odpowiedzi         : 79.337µs
  Całkowity czas          : 457.034718ms
  Czy połączenie było ponownie używane  : false
  Połączenie było bezczynne  : false
  Czas bezczynności połączenia: 0s
  Próba żądania         : 1
  Adres zdalny          : 3.221.81.55:443

Złożony żądanie GET

// Utwórz klienta Resty
client := resty.New()

// Ustaw parametry zapytania
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")


// Przykład użycia metody 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")


// Jeśli konieczne, wymuś określony typ zawartości odpowiedzi, aby Resty mógł sparsować odpowiedź JSON do twojej struktury
resp, err := client.R().
      SetResult(result).
      ForceContentType("application/json").
      Get("v2/alpine/manifests/latest")

Różne przykłady żądań POST

// Utwórz klienta Resty
client := resty.New()

// POST ciąg JSON
// Jeśli ustawiono ustawienia na poziomie klienta, typ zawartości nie musi być ustawiony
resp, err := client.R().
      SetHeader("Content-Type", "application/json").
      SetBody(`{"username":"testuser", "password":"testpass"}`).
      SetResult(&AuthSuccess{}).    // lub SetResult(AuthSuccess{}).
      Post("https://myapp.com/login")

// POST tablicę []byte
// Jeśli ustawiono ustawienia na poziomie klienta, typ zawartości nie musi być ustawiony
resp, err := client.R().
      SetHeader("Content-Type", "application/json").
      SetBody([]byte(`{"username":"testuser", "password":"testpass"}`)).
      SetResult(&AuthSuccess{}).    // lub SetResult(AuthSuccess{}).
      Post("https://myapp.com/login")

// POST strukturę, domyślnie typ zawartości JSON, nie ma potrzeby ustawiania
resp, err := client.R().
      SetBody(User{Username: "testuser", Password: "testpass"}).
      SetResult(&AuthSuccess{}).    // lub SetResult(AuthSuccess{}).
      SetError(&AuthError{}).       // lub SetError(AuthError{}).
      Post("https://myapp.com/login")

// POST mapę, domyślnie typ zawartości JSON, nie ma potrzeby ustawiania
resp, err := client.R().
      SetBody(map[string]interface{}{"username": "testuser", "password": "testpass"}).
      SetResult(&AuthSuccess{}).    // lub SetResult(AuthSuccess{}).
      SetError(&AuthError{}).       // lub SetError(AuthError{}).
      Post("https://myapp.com/login")

// Prześlij plik jako surową tablicę bajtów. Przykład: Prześlij plik do Dropbox
fileBytes, _ := os.ReadFile("/Users/jeeva/mydocument.pdf")

// Zauważ, że nie ustawiamy nagłówka typu zawartości, ponieważ go-resty automatycznie wykryje Content-Type
resp, err := client.R().
      SetBody(fileBytes).
      SetContentLength(true).          // Dropbox wymaga tego wartości
      SetAuthToken("").
      SetError(&DropboxError{}).       // lub SetError(DropboxError{}).
      Post("https://content.dropboxapi.com/1/files_put/auto/resty/mydocument.pdf") // Dropbox obsługuje również przesyłanie metodą PUT

// Uwaga: Jeśli nagłówek typu zawartości nie jest ustawiony, resty wykryje Content-Type ciała żądania
//   * Dla typów danych struct i map, domyślnie jest to 'application/json'
//   * Następnie jest to normalny typ zawartości tekstowej

Żądanie PUT

Możesz użyć różnych kombinacji wywołania metody PUT tak jak pokazano dla POST.

// Uwaga: Jest to przykład użycia metody PUT, dla większej liczby kombinacji proszę odnosić się do POST

// Utwórz klienta Resty
client := resty.New()

// Wyślij żądanie z typem zawartości JSON
// Jeżeli istnieją ustawienia na poziomie klienta, token uwierzytelniający może zostać pominięty, błąd
resp, err := client.R().
      SetBody(Article{
        Title: "go-resty",
        Content: "To jest treść mojego artykułu, oh yeah!",
        Author: "Jeevanandam M",
        Tags: []string{"artykuł", "przykład", "resty"},
      }).
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      SetError(&Error{}).       // Lub SetError(Error{}).
      Put("https://myapp.com/article/1234")

Żądanie PATCH

Możesz użyć różnych kombinacji wywołania metody PATCH tak jak pokazano dla POST.

// Uwaga: Jest to przykład użycia metody PATCH, dla większej liczby kombinacji proszę odnosić się do POST

// Utwórz klienta Resty
client := resty.New()

// Wyślij żądanie z typem zawartości JSON
// Jeżeli istnieją ustawienia na poziomie klienta, token uwierzytelniający może zostać pominięty, błąd
resp, err := client.R().
      SetBody(Article{
        Tags: []string{"nowy tag 1", "nowy tag 2"},
      }).
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      SetError(&Error{}).       // Lub SetError(Error{}).
      Patch("https://myapp.com/articles/1234")

Żądanie DELETE, HEAD, OPTIONS

// Utwórz klienta Resty
client := resty.New()

// Usuń artykuł
// Jeżeli istnieją ustawienia na poziomie klienta, token uwierzytelniający może zostać pominięty, błąd
resp, err := client.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      SetError(&Error{}).       // Lub SetError(Error{}).
      Delete("https://myapp.com/articles/1234")

// Usuń wiele artykułów z ładunkiem/zawartością JSON jako ciąg znaków
// Jeżeli istnieją ustawienia na poziomie klienta, token uwierzytelniający może zostać pominięty, błąd
resp, err := client.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      SetError(&Error{}).       // Lub SetError(Error{}).
      SetHeader("Content-Type", "application/json").
      SetBody(`{article_ids: [1002, 1006, 1007, 87683, 45432] }`).
      Delete("https://myapp.com/articles")

// Pobierz informacje o nagłówku zasobu
// Jeżeli istnieją ustawienia na poziomie klienta, token uwierzytelniający może zostać pominięty
resp, err := client.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      Head("https://myapp.com/videos/hi-res-video")

// Pobierz informacje o opcjach zasobu
// Jeżeli istnieją ustawienia na poziomie klienta, token uwierzytelniający może zostać pominięty
resp, err := client.R().
      SetAuthToken("C6A79608-782F-4ED0-A11D-BD82FAD829CD").
      Options("https://myapp.com/servers/nyc-dc-01")

Konfiguracja operacji serializacji/deserializacji JSON i XML

Użytkownicy mogą zarejestrować wybrane biblioteki JSON/XML w Resty lub napisać własne biblioteki. Domyślnie Resty rejestruje standardowe biblioteki encoding/json i encoding/xml.

// Przykład rejestracji json-iterator
import jsoniter "github.com/json-iterator/go"

json := jsoniter.ConfigCompatibleWithStandardLibrary

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

// Podobnie, użytkownicy mogą skonfigurować XML w następujący sposób -
client.SetXMLMarshaler(xml.Marshal).
    SetXMLUnmarshaler(xml.Unmarshal)