Documentation ¶
Overview ¶
Package gorequest inspired by Nodejs SuperAgent provides easy-way to write http client
Index ¶
- Constants
- Variables
- type File
- type Logger
- type Request
- type Response
- type SuperAgent
- func (s *SuperAgent) AddCookie(c *http.Cookie) *SuperAgent
- func (s *SuperAgent) AddCookies(cookies []*http.Cookie) *SuperAgent
- func (s *SuperAgent) AppendHeader(param string, value string) *SuperAgent
- func (s *SuperAgent) AsCurlCommand() (string, error)
- func (s *SuperAgent) ClearSuperAgent()
- func (s *SuperAgent) CustomMethod(method, targetUrl string) *SuperAgent
- func (s *SuperAgent) Delete(targetUrl string) *SuperAgent
- func (s *SuperAgent) End(callback ...func(response Response, body string, errs []error)) (Response, string, []error)
- func (s *SuperAgent) EndBytes(callback ...func(response Response, body []byte, errs []error)) (Response, []byte, []error)
- func (s *SuperAgent) EndStruct(v interface{}, ...) (Response, []byte, []error)
- func (s *SuperAgent) Get(targetUrl string) *SuperAgent
- func (s *SuperAgent) Head(targetUrl string) *SuperAgent
- func (s *SuperAgent) MakeRequest() (*http.Request, error)
- func (s *SuperAgent) Options(targetUrl string) *SuperAgent
- func (s *SuperAgent) Param(key string, value string) *SuperAgent
- func (s *SuperAgent) Patch(targetUrl string) *SuperAgent
- func (s *SuperAgent) Post(targetUrl string) *SuperAgent
- func (s *SuperAgent) Proxy(proxyUrl string) *SuperAgent
- func (s *SuperAgent) Put(targetUrl string) *SuperAgent
- func (s *SuperAgent) Query(content interface{}) *SuperAgent
- func (s *SuperAgent) RedirectPolicy(policy func(req Request, via []Request) error) *SuperAgent
- func (s *SuperAgent) Retry(retryerCount int, retryerTime time.Duration, statusCode ...int) *SuperAgent
- func (s *SuperAgent) Send(content interface{}) *SuperAgent
- func (s *SuperAgent) SendFile(file interface{}, args ...string) *SuperAgent
- func (s *SuperAgent) SendMap(content interface{}) *SuperAgent
- func (s *SuperAgent) SendSlice(content []interface{}) *SuperAgent
- func (s *SuperAgent) SendString(content string) *SuperAgent
- func (s *SuperAgent) SendStruct(content interface{}) *SuperAgent
- func (s *SuperAgent) Set(param string, value string) *SuperAgent
- func (s *SuperAgent) SetBasicAuth(username string, password string) *SuperAgent
- func (s *SuperAgent) SetCurlCommand(enable bool) *SuperAgent
- func (s *SuperAgent) SetDebug(enable bool) *SuperAgent
- func (s *SuperAgent) SetDoNotClearSuperAgent(enable bool) *SuperAgent
- func (s *SuperAgent) SetLogger(logger Logger) *SuperAgent
- func (s *SuperAgent) TLSClientConfig(config *tls.Config) *SuperAgent
- func (s *SuperAgent) Timeout(timeout time.Duration) *SuperAgent
- func (s *SuperAgent) Type(typeStr string) *SuperAgent
Constants ¶
const ( POST = "POST" GET = "GET" HEAD = "HEAD" PUT = "PUT" DELETE = "DELETE" PATCH = "PATCH" OPTIONS = "OPTIONS" )
HTTP methods we support
const ( TypeJSON = "json" TypeXML = "xml" TypeUrlencoded = "urlencoded" TypeForm = "form" TypeFormData = "form-data" TypeHTML = "html" TypeText = "text" TypeMultipart = "multipart" )
Types we support.
Variables ¶
var DisableTransportSwap = false
var Types = map[string]string{ TypeJSON: "application/json", TypeXML: "application/xml", TypeForm: "application/x-www-form-urlencoded", TypeFormData: "application/x-www-form-urlencoded", TypeUrlencoded: "application/x-www-form-urlencoded", TypeHTML: "text/html", TypeText: "text/plain", TypeMultipart: "multipart/form-data", }
Functions ¶
This section is empty.
Types ¶
type SuperAgent ¶
type SuperAgent struct { Url string Method string Header http.Header TargetType string ForceType string Data map[string]interface{} SliceData []interface{} FormData url.Values QueryData url.Values FileData []File BounceToRawString bool RawString string Client *http.Client Transport *http.Transport Cookies []*http.Cookie Errors []error BasicAuth struct{ Username, Password string } Debug bool CurlCommand bool Retryable struct { RetryableStatus []int RetryerTime time.Duration RetryerCount int Attempt int Enable bool } SpanContext opentracing.SpanContext //If true prevents clearing Superagent data and makes it possible to reuse it for the next requests DoNotClearSuperAgent bool // contains filtered or unexported fields }
A SuperAgent is a object storing all request data for client.
func (*SuperAgent) AddCookie ¶ added in v0.2.2
func (s *SuperAgent) AddCookie(c *http.Cookie) *SuperAgent
AddCookie adds a cookie to the request. The behavior is the same as AddCookie on Request from net/http
func (*SuperAgent) AddCookies ¶ added in v0.2.9
func (s *SuperAgent) AddCookies(cookies []*http.Cookie) *SuperAgent
AddCookies is a convenient method to add multiple cookies
func (*SuperAgent) AppendHeader ¶ added in v1.0.0
func (s *SuperAgent) AppendHeader(param string, value string) *SuperAgent
AppendHeader is used for setting header fileds with multiple values, Example. To set `Accept` as `application/json, text/plain`
gorequest.New(). Post("/gamelist"). AppendHeader("Accept", "application/json"). AppendHeader("Accept", "text/plain"). End()
func (*SuperAgent) AsCurlCommand ¶ added in v0.2.14
func (s *SuperAgent) AsCurlCommand() (string, error)
AsCurlCommand returns a string representing the runnable `curl' command version of the request.
func (*SuperAgent) ClearSuperAgent ¶
func (s *SuperAgent) ClearSuperAgent()
Clear SuperAgent data for another new request.
func (*SuperAgent) CustomMethod ¶ added in v0.2.14
func (s *SuperAgent) CustomMethod(method, targetUrl string) *SuperAgent
Just a wrapper to initialize SuperAgent instance by method string
func (*SuperAgent) Delete ¶ added in v0.2.0
func (s *SuperAgent) Delete(targetUrl string) *SuperAgent
func (*SuperAgent) End ¶
func (s *SuperAgent) End(callback ...func(response Response, body string, errs []error)) (Response, string, []error)
End is the most important function that you need to call when ending the chain. The request won't proceed without calling it. End function returns Response which matchs the structure of Response type in Golang's http package (but without Body data). The body data itself returns as a string in a 2nd return value. Lastly but worth noticing, error array (NOTE: not just single error value) is returned as a 3rd value and nil otherwise.
For example:
resp, body, errs := gorequest.New().Get("http://www.google.com").End() if errs != nil { fmt.Println(errs) } fmt.Println(resp, body)
Moreover, End function also supports callback which you can put as a parameter. This extends the flexibility and makes GoRequest fun and clean! You can use GoRequest in whatever style you love!
For example:
func printBody(resp gorequest.Response, body string, errs []error){ fmt.Println(resp.Status) } gorequest.New().Get("http://www..google.com").End(printBody)
func (*SuperAgent) EndBytes ¶ added in v0.2.6
func (s *SuperAgent) EndBytes(callback ...func(response Response, body []byte, errs []error)) (Response, []byte, []error)
EndBytes should be used when you want the body as bytes. The callbacks work the same way as with `End`, except that a byte array is used instead of a string.
func (*SuperAgent) EndStruct ¶ added in v0.2.14
func (s *SuperAgent) EndStruct(v interface{}, callback ...func(response Response, v interface{}, body []byte, errs []error)) (Response, []byte, []error)
EndStruct should be used when you want the body as a struct. The callbacks work the same way as with `End`, except that a struct is used instead of a string.
func (*SuperAgent) Get ¶
func (s *SuperAgent) Get(targetUrl string) *SuperAgent
func (*SuperAgent) Head ¶ added in v0.2.0
func (s *SuperAgent) Head(targetUrl string) *SuperAgent
func (*SuperAgent) MakeRequest ¶ added in v0.2.14
func (s *SuperAgent) MakeRequest() (*http.Request, error)
func (*SuperAgent) Options ¶ added in v0.2.14
func (s *SuperAgent) Options(targetUrl string) *SuperAgent
func (*SuperAgent) Param ¶ added in v0.2.9
func (s *SuperAgent) Param(key string, value string) *SuperAgent
As Go conventions accepts ; as a synonym for &. (https://github.com/golang/go/issues/2210) Thus, Query won't accept ; in a querystring if we provide something like fields=f1;f2;f3 This Param is then created as an alternative method to solve this.
func (*SuperAgent) Patch ¶ added in v0.2.3
func (s *SuperAgent) Patch(targetUrl string) *SuperAgent
func (*SuperAgent) Post ¶
func (s *SuperAgent) Post(targetUrl string) *SuperAgent
func (*SuperAgent) Proxy ¶ added in v0.2.0
func (s *SuperAgent) Proxy(proxyUrl string) *SuperAgent
Proxy function accepts a proxy url string to setup proxy url for any request. It provides a convenience way to setup proxy which have advantages over usual old ways. One example is you might try to set `http_proxy` environment. This means you are setting proxy up for all the requests. You will not be able to send different request with different proxy unless you change your `http_proxy` environment again. Another example is using Golang proxy setting. This is normal prefer way to do but too verbase compared to GoRequest's Proxy:
gorequest.New().Proxy("http://myproxy:9999"). Post("http://www.google.com"). End()
To set no_proxy, just put empty string to Proxy func:
gorequest.New().Proxy(""). Post("http://www.google.com"). End()
func (*SuperAgent) Put ¶ added in v0.2.0
func (s *SuperAgent) Put(targetUrl string) *SuperAgent
func (*SuperAgent) Query ¶
func (s *SuperAgent) Query(content interface{}) *SuperAgent
Query function accepts either json string or strings which will form a query-string in url of GET method or body of POST method. For example, making "/search?query=bicycle&size=50x50&weight=20kg" using GET method:
gorequest.New(). Get("/search"). Query(`{ query: 'bicycle' }`). Query(`{ size: '50x50' }`). Query(`{ weight: '20kg' }`). End()
Or you can put multiple json values:
gorequest.New(). Get("/search"). Query(`{ query: 'bicycle', size: '50x50', weight: '20kg' }`). End()
Strings are also acceptable:
gorequest.New(). Get("/search"). Query("query=bicycle&size=50x50"). Query("weight=20kg"). End()
Or even Mixed! :)
gorequest.New(). Get("/search"). Query("query=bicycle"). Query(`{ size: '50x50', weight:'20kg' }`). End()
func (*SuperAgent) RedirectPolicy ¶
func (s *SuperAgent) RedirectPolicy(policy func(req Request, via []Request) error) *SuperAgent
RedirectPolicy accepts a function to define how to handle redirects. If the policy function returns an error, the next Request is not made and the previous request is returned.
The policy function's arguments are the Request about to be made and the past requests in order of oldest first.
func (*SuperAgent) Retry ¶ added in v0.2.15
func (s *SuperAgent) Retry(retryerCount int, retryerTime time.Duration, statusCode ...int) *SuperAgent
gorequest.New().
Post("/gamelist"). Retry(3, 5 * time.seconds, http.StatusBadRequest, http.StatusInternalServerError). End()
func (*SuperAgent) Send ¶
func (s *SuperAgent) Send(content interface{}) *SuperAgent
Send function accepts either json string or query strings which is usually used to assign data to POST or PUT method. Without specifying any type, if you give Send with json data, you are doing requesting in json format:
gorequest.New(). Post("/search"). Send(`{ query: 'sushi' }`). End()
While if you use at least one of querystring, GoRequest understands and automatically set the Content-Type to `application/x-www-form-urlencoded`
gorequest.New(). Post("/search"). Send("query=tonkatsu"). End()
So, if you want to strictly send json format, you need to use Type func to set it as `json` (Please see more details in Type function). You can also do multiple chain of Send:
gorequest.New(). Post("/search"). Send("query=bicycle&size=50x50"). Send(`{ wheel: '4'}`). End()
From v0.2.0, Send function provide another convenience way to work with Struct type. You can mix and match it with json and query string:
type BrowserVersionSupport struct { Chrome string Firefox string } ver := BrowserVersionSupport{ Chrome: "37.0.2041.6", Firefox: "30.0" } gorequest.New(). Post("/update_version"). Send(ver). Send(`{"Safari":"5.1.10"}`). End()
If you have set Type to text or Content-Type to text/plain, content will be sent as raw string in body instead of form
gorequest.New(). Post("/greet"). Type("text"). Send("hello world"). End()
func (*SuperAgent) SendFile ¶ added in v0.2.14
func (s *SuperAgent) SendFile(file interface{}, args ...string) *SuperAgent
SendFile function works only with type "multipart". The function accepts one mandatory and up to two optional arguments. The mandatory (first) argument is the file. The function accepts a path to a file as string:
gorequest.New(). Post("http://example.com"). Type("multipart"). SendFile("./example_file.ext"). End()
File can also be a []byte slice of a already file read by eg. ioutil.ReadFile:
b, _ := ioutil.ReadFile("./example_file.ext") gorequest.New(). Post("http://example.com"). Type("multipart"). SendFile(b). End()
Furthermore file can also be a os.File:
f, _ := os.Open("./example_file.ext") gorequest.New(). Post("http://example.com"). Type("multipart"). SendFile(f). End()
The first optional argument (second argument overall) is the filename, which will be automatically determined when file is a string (path) or a os.File. When file is a []byte slice, filename defaults to "filename". In all cases the automatically determined filename can be overwritten:
b, _ := ioutil.ReadFile("./example_file.ext") gorequest.New(). Post("http://example.com"). Type("multipart"). SendFile(b, "my_custom_filename"). End()
The second optional argument (third argument overall) is the fieldname in the multipart/form-data request. It defaults to fileNUMBER (eg. file1), where number is ascending and starts counting at 1. So if you send multiple files, the fieldnames will be file1, file2, ... unless it is overwritten. If fieldname is set to "file" it will be automatically set to fileNUMBER, where number is the greatest exsiting number+1.
b, _ := ioutil.ReadFile("./example_file.ext") gorequest.New(). Post("http://example.com"). Type("multipart"). SendFile(b, "", "my_custom_fieldname"). // filename left blank, will become "example_file.ext" End()
func (*SuperAgent) SendMap ¶ added in v0.2.15
func (s *SuperAgent) SendMap(content interface{}) *SuperAgent
func (*SuperAgent) SendSlice ¶ added in v0.2.11
func (s *SuperAgent) SendSlice(content []interface{}) *SuperAgent
SendSlice (similar to SendString) returns SuperAgent's itself for any next chain and takes content []interface{} as a parameter. Its duty is to append slice of interface{} into s.SliceData ([]interface{}) which later changes into json array in the End() func.
func (*SuperAgent) SendString ¶ added in v0.2.0
func (s *SuperAgent) SendString(content string) *SuperAgent
SendString returns SuperAgent's itself for any next chain and takes content string as a parameter. Its duty is to transform String into s.Data (map[string]interface{}) which later changes into appropriate format such as json, form, text, etc. in the End func. Send implicitly uses SendString and you should use Send instead of this.
func (*SuperAgent) SendStruct ¶ added in v0.2.11
func (s *SuperAgent) SendStruct(content interface{}) *SuperAgent
SendStruct (similar to SendString) returns SuperAgent's itself for any next chain and takes content interface{} as a parameter. Its duty is to transfrom interface{} (implicitly always a struct) into s.Data (map[string]interface{}) which later changes into appropriate format such as json, form, text, etc. in the End() func.
func (*SuperAgent) Set ¶
func (s *SuperAgent) Set(param string, value string) *SuperAgent
Set is used for setting header fields, this will overwrite the existed values of Header through AppendHeader(). Example. To set `Accept` as `application/json`
gorequest.New(). Post("/gamelist"). Set("Accept", "application/json"). End()
func (*SuperAgent) SetBasicAuth ¶ added in v0.2.5
func (s *SuperAgent) SetBasicAuth(username string, password string) *SuperAgent
SetBasicAuth sets the basic authentication header Example. To set the header for username "myuser" and password "mypass"
gorequest.New() Post("/gamelist"). SetBasicAuth("myuser", "mypass"). End()
func (*SuperAgent) SetCurlCommand ¶ added in v0.2.12
func (s *SuperAgent) SetCurlCommand(enable bool) *SuperAgent
Enable the curlcommand mode which display a CURL command line
func (*SuperAgent) SetDebug ¶ added in v0.2.8
func (s *SuperAgent) SetDebug(enable bool) *SuperAgent
Enable the debug mode which logs request/response detail
func (*SuperAgent) SetDoNotClearSuperAgent ¶ added in v1.0.0
func (s *SuperAgent) SetDoNotClearSuperAgent(enable bool) *SuperAgent
Enable the DoNotClear mode for not clearing super agent and reuse for the next request
func (*SuperAgent) SetLogger ¶ added in v0.2.8
func (s *SuperAgent) SetLogger(logger Logger) *SuperAgent
func (*SuperAgent) TLSClientConfig ¶ added in v0.2.2
func (s *SuperAgent) TLSClientConfig(config *tls.Config) *SuperAgent
Set TLSClientConfig for underling Transport. One example is you can use it to disable security check (https):
gorequest.New().TLSClientConfig(&tls.Config{ InsecureSkipVerify: true}). Get("https://disable-security-check.com"). End()
func (*SuperAgent) Timeout ¶ added in v0.2.0
func (s *SuperAgent) Timeout(timeout time.Duration) *SuperAgent
func (*SuperAgent) Type ¶
func (s *SuperAgent) Type(typeStr string) *SuperAgent
Type is a convenience function to specify the data type to send. For example, to send data as `application/x-www-form-urlencoded` :
gorequest.New(). Post("/recipe"). Type("form"). Send(`{ "name": "egg benedict", "category": "brunch" }`). End()
This will POST the body "name=egg benedict&category=brunch" to url /recipe
GoRequest supports
"text/html" uses "html" "application/json" uses "json" "application/xml" uses "xml" "text/plain" uses "text" "application/x-www-form-urlencoded" uses "urlencoded", "form" or "form-data"