Awesome
goreq
A Simplified Http Client. Its initial codes are cloned from HttpRequest. I have refactored the codes and make it more friendly to programmers. And some bugs are fixed and new features are added.
Major changes include:
- can send any string or bytes in body
- can set a shared client for concurrency
- won't clear setting actively
- ......
You can see the release notes for details.
Installation
$ go get github.com/smallnest/goreq
Usage
why you should use goreq
goreq comes from gorequest but it added some new features and fixed some bugs. The initial functions and major functions are from gorequest. Thanks to @parnurzeal and other contributors. Why have I not created pull requests to gorequest and created a new repository? I want to refactor it a lot and add features quickly.
GoReq makes http thing more simple for you, using fluent styles to make http client more awesome. You can control headers, timeout, query parameters, binding response and others in one line:
Before
client := &http.Client{
CheckRedirect: redirectPolicyFunc,
}
req, err := http.NewRequest("GET", "http://example.com", nil)
req.Header.Add("If-None-Match", `W/"wyzzy"`)
resp, err := client.Do(req)
Using GoReq
resp, body, errs := goreq.New().Get("http://example.com").
RedirectPolicy(redirectPolicyFunc).
SetHeader("If-None-Match", `W/"wyzzy"`).
End()
Http Methods
GET
resp, body, err := goreq.New().Get("http://httpbin.org/get").End()
DELETE
q := `{"Name":"Jerry"}`
resp, _, err := goreq.New().Delete("http://httpbin.org/delete").ContentType("json").SendMapString(q).End()
HEAD
resp, body, err := goreq.New().Head("http://httpbin.org/headers").SendRawString("hello world").End()
POST
resp, body, err := goreq.New().Post("http://httpbin.org/post").SendRawString("hello world").End()
PUT
q := `{"Name":"Jerry"}`
resp, body, err := goreq.New().Put("http://httpbin.org/put").ContentType("json").SendMapString(q).End()
PATCH
q := `{"Name":"Jerry"}`
resp, body, err := goreq.New().Patch("http://httpbin.org/patch").ContentType("json").SendMapString(q).End()
Header
You can set one Header by:
or set some headers by json:
or set some headers by struct:
Proxy
In the case when you are behind proxy, GoRequest can handle it easily with Proxy func:
request := goreq.New().Proxy("http://proxy:999")
resp, body, errs := request.Get("http://example-proxy.com").End()
Socks5 will be supported in future.
Timeout
Timeout can be set in any time duration using time package:
request := goreq.New().Timeout(2*time.Millisecond)
resp, body, errs:= request.Get("http://example.com").End()
Timeout func defines both dial + read/write timeout to the specified time parameter.
SSL
Basic Auth
To add a basic authentication header:
request := goreq.New().SetBasicAuth("username", "password") resp, body, errs := request.Get("http://example-proxy.com").End(.End())
Query Parameter
Query function accepts either json string or query 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:
goreq.New().
Get("/search").
Query(`{ "query": "bicycle" }`).
Query(`{ "size": "50x50" }`).
Query(`{ "weight": "20kg" }`).
End()
It also support query string:
goreq.New().
Get("/search").
Query("query=bicycle&size=50x50").
Query("weight=20kg").
End()
even you can pass a struct:
qq := struct {
Query1 string `json:"query1"`
Query2 string `json:"query2"`
}{
Query1: "test1",
Query2: "test2",
}
goreq.New().
Get("/search").
Query(qq).
End()
Param can be used to set query value that contains ";" like fields=f1;f2;f3
Request Body
For POST, PUT, PATCH, you can set content of request BODY.. It is convenient to BODY content.
JSON
You can use SendMapString or SendStruct to set JSON content. You should set content type to "application/json" by:
goreq.New().Post("/user").ContentType("json")
or
goreq.New().Post("/user").SetHeader("application/json")
GoReq will parse struct, json string or query string and rebuild the json content:
type BrowserVersionSupport struct {
Chrome string
Firefox string
}
ver := BrowserVersionSupport{ Chrome: "37.0.2041.6", Firefox: "30.0" }
goreq.New().
Post("/update_version").
SendStruct(ver).
SendStruct(`{"Safari":"5.1.10"}`).
End()
or
goreq.New().
Post("/search").
SendMapString("query=bicycle&size=50x50").
SendMapString(`{ "wheel": "4"}`).
End()
Form
If you set Content-Type as "application/x-www-form-urlencoded", GoReq rebuilds the below data into form style:
goreq.New().
Post("/search").
ContentType("form").
SendMapString("query=bicycle&size=50x50").
SendMapString(`{ "wheel": "4"}`).
End()
Raw String
If you want upload XML or other plain text, you can use this method:
goreq.New().
Post("/search").
ContentType("text").
SendRawString("hello world").
End()
Raw Bytes
Even you can upload raw bytes:
goreq.New().
Post("/search").
ContentType("stream").
SendRawBytes([]byte("hello world")).
End()
Bind Response Body
You can bind response body to a struct:
type Person struct {
Name string
}
var friend Person
_, _, err := goreq.New().Get(ts.URL).
BindBody(&friend).
End()
Callback
GoReqalso supports callback function to handle response:
func printStatus(resp goreq.Response, body string, errs []error){
fmt.Println(resp.Status)
}
goreq.New().Get("http://example.com").End(printStatus)
Debug
For deugging, GoReq leverages httputil to dump details of every request/response. You can just use SetDebug to enable/disable debug mode and SetLogger to set your own choice of logger.
Share Client
For concurrency, you can use a shared client in multiple GoReq instances:
sa := New().Get(ts.URL + case1_empty)
sa.End()
client := sa.Client;
goreq.New().Get(ts.URL+case2_set_header).
SetHeader("API-Key", "fookey").
SetClient(client).
End()
Reset
You can reset GoReq and use it send another request. It only keep the client and reset other fields.
goreq.New().Get("http://example.com").Reset()
Retry
You can set a retry value and GoReq will retry until the value if it fails. So goreq sends request at most retry + 1 times.
_, _, err := New().Get(ts.URL).
Retry(3, 100, nil).
End()
License
goreq is MIT License.