req

A golang http request library for human

Features

• Light weight
• Simple
• Easy play with JSON and XML
• Easy for debug and logging
• Easy file uploads and downloads
• Easy manage cookie
• Easy set up proxy
• Easy set timeout
• Easy customize http client

Install

go get github.com/imroc/req

Quick Start

Only url is required, others are optional, like headers, params, files or body etc

func Get(url string, v ...interface{}) (*Resp, error)
func Post(url string, v ...interface{}) (*Resp, error)
......

Examples

Basic
Set Header
Set Param
Set Body
Debug & Logging
ToJSON & ToXML
Get *http.Response
Upload
Download
Cookie
Set Timeout
Set Proxy
Customize Client
Multiple Client

Basic

header := req.Header{
	"Accept":        "application/json",
	"Authorization": "Basic YWRtaW46YWRtaW4=",
}
param := req.Param{
	"name": "imroc",
	"cmd":  "add",
}
// only url is required, others are optional.
r, err = req.Post("http://foo.bar/api", header, param)
if err != nil {
	log.Fatal(err)
}
r.ToJSON(&foo)       // response => struct/map
log.Printf("%+v", r) // print info (try it, you may surprise) 

Set Header

use req.Header

authHeader := req.Header{
	"Accept":        "application/json",
	"Authorization": "Basic YWRtaW46YWRtaW4=",
}
req.Get("https://www.baidu.com", authHeader, req.Header{"User-Agent": "V1.1"})

use http.Header

header := make(http.Header)
header.Set("Accept", "application/json")
r, err := req.Get("https://www.baidu.com", header)

Set Param

use req.Param

param := req.Param{
	"id":  "imroc",
	"pwd": "roc",
}
req.Get("http://foo.bar/api", param) // http://foo.bar/api?id=imroc&pwd=roc
req.Post(url, param)                  // body => id=imroc&pwd=roc

use req.QueryParam force to append params to the url

req.Post("http://foo.bar/api", req.Param{"name": "roc", "age": "22"}, req.QueryParam{"access_token": "fedledGF9Hg9ehTU"})
/*
POST /api?access_token=fedledGF9Hg9ehTU HTTP/1.1
Host: foo.bar
User-Agent: Go-http-client/1.1
Content-Length: 15
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Accept-Encoding: gzip

age=22&name=roc
*/

Set Body

put string, []byte and io.Reader as body directly.

req.Post(url, "id=roc&cmd=query")

put xml and json body

req.Post(url, req.BodyJSON(&foo))
req.Post(url, req.BodyXML(&bar))

Debug & Logging

Enable debug mode

req.Debug = true
req.Get(url)
/*
GET /test HTTP/1.1
Host: localhost
User-Agent: Go-http-client/1.1
Transfer-Encoding: chunked
Accept-Encoding: gzip

=================================

HTTP/1.1 200 OK
Content-Length: 9
Content-Type: text/plain; charset=UTF-8
Date: Thu, 25 May 2017 14:55:58 GMT

hello req
*/

Output format

req.SetFlags(req.LreqHead | req.LreqBody | req.LrespHead) // not output reponse body
req.Debug = true
req.Post(url, "hi roc")
/*
POST /test HTTP/1.1
Host: localhost
User-Agent: Go-http-client/1.1
Content-Length: 6
Accept-Encoding: gzip

hi roc

=================================

HTTP/1.1 200 OK
Content-Length: 9
Content-Type: text/plain; charset=UTF-8
Date: Thu, 25 May 2017 14:57:39 GMT
*/

Monitor speed

req.SetFlags(req.LstdFlags | req.Lcost) // output format add time costed by request
r,_ := req.Get(url)
log.Println(r) // http://foo.bar/api 3.260802ms {"code":0 "msg":"success"}
if r.Cost() > 3 * time.Second { // check cost
	log.Println("WARN: slow request:",r)
}

Use %+v format to print debug info

r, _ := req.Post(url, header, param)
log.Printf("%+v", r)

Use %v format to print info simple

r, _ := req.Get(url, param)
log.Printf("%v", r) // GET http://foo.bar/api?name=roc&cmd=add {"code":"0","msg":"success"}

and the %-v format is similar to %v, the only difference is that it always keep the content in one line, it is useful while logging.

ToJSON & ToXML

r, _ := req.Get(url)
r.ToJSON(&foo)
r, _ = req.Post(url, req.BodyXML(&bar))
r.ToXML(&baz)

Get *http.Response

// func (r *Req) Response() *http.Response
r, _ := req.Get(url)
resp := r.Response()
fmt.Println(resp.StatusCode)

Upload

Use req.File to match files

req.Post(url, req.File("imroc.png"), req.File("/Users/roc/Pictures/*.png"))

Use req.FileUpload to fully control

file, _ := os.Open("imroc.png")
req.Post(url, req.FileUpload{
	File:      file,
	FieldName: "file",
	FileName:  "avatar.png",
})

Download

r, _ := req.Get(url)
r.ToFile("imroc.png")

Cookie

By default, the underlying *http.Client will manage your cookie(send cookie header to server automatically if server has set a cookie for you), you can disable it by calling this function :

req.EnableCookie(false)

and you can set cookie in request just using *http.Cookie

cookie := new(http.Cookie)
......
req.Get(url, cookie)

Set Timeout

req.SetTimeout(50 * time.Second)

Set Proxy

By default, req use proxy from system environment if http_proxy or https_proxy is specified, you can set a custom proxy or disable it by set nil

req.SetProxy(func(r *http.Request) (*url.URL, error) {
	if strings.Contains(r.URL.Hostname(), "google") {
		return url.Parse("http://my.vpn.com:23456")
	}
	return nil, nil
})

Set a simple proxy (use fixed proxy url for every request)

req.SetProxyUrl("http://my.proxy.com:23456")

Customize Client

Use SetClient to change the default underlying *http.Client

req.SetClient(client)

Only specify client for some request

client := &http.Client{Timeout: 30 * time.Second}
req.Get(url, client)

Change some properties of default client you want

req.Client().Jar, _ = cookiejar.New(nil)
trans, _ := req.Client().Transport.(*http.Transport)
trans.MaxIdleConns = 20
trans.TLSHandshakeTimeout = 20 * time.Second
trans.DisableKeepAlives = true
trans.TLSClientConfig = &tls.Config{InsecureSkipVerify: true}

Multiple Client

Use New(*http.Client) method to create a new *Req, it has all of the method exported by the package

r := req.New(nil) // create *Req with default client config
r.SetTimeout(2 * time.Second)
r.Post(url, header, body)