README
¶
req
A golang http request library for humans
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
Document
Install
go get github.com/imroc/req
Overview
req implements a friendly API over Go's existing net/http library.
Req and Resp are two most important struct, you can think of Req as a client that initiate HTTP requests, Resp as a information container for the request and response. They all provide simple and convenient APIs that allows you to do a lot of things.
func (r *Req) Post(url string, v ...interface{}) (*Resp, error)
In most cases, only url is required, others are optional, like headers, params, files or body etc.
There is a default Req object, all of its' public methods are wrapped by the req package, so you can also think of req package as a Req object
// use Req object to initiate requests.
r := req.New()
r.Get(url)
// use req package to initiate reqeust.
req.Get(url)
You can use req.New() to create lots of *Req as client with independent configuration
Examples
Basic
Set Header
Set Param
Set Body
Debug
Output Format
ToJSON & ToXML
Get *http.Response
Upload
Download
Cookie
Set Timeout
Set Proxy
Customize 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 (it is actually a map[string]string)
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")
req.Get("https://www.baidu.com", header)
Set Param
Use req.Param (it is actually a map[string]string)
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 (it is also actually a map[string]string)
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 object as xml or json body (add Content-Type header automatically)
req.Post(url, req.BodyJSON(&foo))
req.Post(url, req.BodyXML(&bar))
Debug
Set global variable req.Debug to true, it will print detail infomation for every request.
req.Debug = true
req.Post("http://localhost/test" "hi")
Output Format
You can use different kind of output format to log the request and response infomation in your log file in defferent scenarios. For example, use %+v output format in the development phase, it allows you to observe the details. Use %v or %-v output format in production phase, just log the information necessarily.
%+v or %+s
Output in detail
r, _ := req.Post(url, header, param)
log.Printf("%+v", r) // output the same format as Debug is enabled
%v or %s
Output in simple way (default format)
r, _ := req.Get(url, param)
log.Printf("%v\n", r) // GET http://foo.bar/api?name=roc&cmd=add {"code":"0","msg":"success"}
log.Prinln(r) // smae as above
%-v or %-s
Output in simple way and keep all in one line (request body or response body may have multiple lines, this format will replace "\r" or "\n" with " ", it's useful when doing some search in your log file)
Flag
You can call SetFlags to control the output content, decide which pieces can be output.
const (
LreqHead = 1 << iota // output request head (request line and request header)
LreqBody // output request body
LrespHead // output response head (response line and response header)
LrespBody // output response body
Lcost // output time costed by the request
LstdFlags = LreqHead | LreqBody | LrespHead | LrespBody
)
req.SetFlags(req.LreqHead | req.LreqBody | req.LrespHead)
Monitoring time consuming
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)
}
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", // FieldName is form field name
FileName: "avatar.png", //Filename is the name of the file that you wish to upload. We use this to guess the mimetype as well as pass it onto the server
})
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)
Specify independent http client for some requests
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}
Documentation
¶
Index ¶
- Constants
- Variables
- func BodyJSON(v interface{}) *bodyJson
- func BodyXML(v interface{}) *bodyXml
- func Client() *http.Client
- func EnableCookie(enable bool)
- func EnableInsecureTLS(enable bool)
- func File(patterns ...string) interface{}
- func Flags() int
- func SetClient(client *http.Client)
- func SetFlags(flags int)
- func SetJSONEscapeHTML(escape bool)
- func SetJSONIndent(prefix, indent string)
- func SetProxy(proxy func(*http.Request) (*url.URL, error)) error
- func SetProxyUrl(rawurl string) error
- func SetTimeout(d time.Duration)
- func SetXMLIndent(prefix, indent string)
- type FileUpload
- type Header
- type Host
- type Param
- type QueryParam
- type Req
- func (r *Req) Client() *http.Client
- func (r *Req) Delete(url string, v ...interface{}) (*Resp, error)
- func (r *Req) Do(method, rawurl string, v ...interface{}) (resp *Resp, err error)
- func (r *Req) EnableCookie(enable bool)
- func (r *Req) EnableInsecureTLS(enable bool)
- func (r *Req) Flags() int
- func (r *Req) Get(url string, v ...interface{}) (*Resp, error)
- func (r *Req) Head(url string, v ...interface{}) (*Resp, error)
- func (r *Req) Options(url string, v ...interface{}) (*Resp, error)
- func (r *Req) Patch(url string, v ...interface{}) (*Resp, error)
- func (r *Req) Post(url string, v ...interface{}) (*Resp, error)
- func (r *Req) Put(url string, v ...interface{}) (*Resp, error)
- func (r *Req) SetClient(client *http.Client)
- func (r *Req) SetFlags(flags int)
- func (r *Req) SetJSONEscapeHTML(escape bool)
- func (r *Req) SetJSONIndent(prefix, indent string)
- func (r *Req) SetProxy(proxy func(*http.Request) (*url.URL, error)) error
- func (r *Req) SetProxyUrl(rawurl string) error
- func (r *Req) SetTimeout(d time.Duration)
- func (r *Req) SetXMLIndent(prefix, indent string)
- type Resp
- func Delete(url string, v ...interface{}) (*Resp, error)
- func Do(method, url string, v ...interface{}) (*Resp, error)
- func Get(url string, v ...interface{}) (*Resp, error)
- func Head(url string, v ...interface{}) (*Resp, error)
- func Options(url string, v ...interface{}) (*Resp, error)
- func Patch(url string, v ...interface{}) (*Resp, error)
- func Post(url string, v ...interface{}) (*Resp, error)
- func Put(url string, v ...interface{}) (*Resp, error)
- func (r *Resp) Bytes() []byte
- func (r *Resp) Cost() time.Duration
- func (r *Resp) Format(s fmt.State, verb rune)
- func (r *Resp) Request() *http.Request
- func (r *Resp) Response() *http.Response
- func (r *Resp) String() string
- func (r *Resp) ToFile(name string) error
- func (r *Resp) ToJSON(v interface{}) error
- func (r *Resp) ToXML(v interface{}) error
Constants ¶
const ( LreqHead = 1 << iota // output request head (request line and request header) LreqBody // output request body LrespHead // output response head (response line and response header) LrespBody // output response body Lcost // output time costed by the request LstdFlags = LreqHead | LreqBody | LrespHead | LrespBody )
Variables ¶
var Debug bool
Debug enable debug mode if set to true
Functions ¶
func BodyJSON ¶
func BodyJSON(v interface{}) *bodyJson
BodyJSON make the object be encoded in json format and set it to the request body
func BodyXML ¶
func BodyXML(v interface{}) *bodyXml
BodyXML make the object be encoded in xml format and set it to the request body
func EnableInsecureTLS ¶
func EnableInsecureTLS(enable bool)
func File ¶
func File(patterns ...string) interface{}
File upload files matching the name pattern such as /usr/*/bin/go* (assuming the Separator is '/')
func SetJSONEscapeHTML ¶
func SetJSONEscapeHTML(escape bool)
SetJSONEscapeHTML specifies whether problematic HTML characters should be escaped inside JSON quoted strings. The default behavior is to escape &, <, and > to \u0026, \u003c, and \u003e to avoid certain safety problems that can arise when embedding JSON in HTML.
In non-HTML settings where the escaping interferes with the readability of the output, SetEscapeHTML(false) disables this behavior.
func SetJSONIndent ¶
func SetJSONIndent(prefix, indent string)
SetJSONIndent instructs the encoder to format each subsequent encoded value as if indented by the package-level function Indent(dst, src, prefix, indent). Calling SetIndent("", "") disables indentation.
func SetProxyUrl ¶
SetProxyUrl set the simple proxy with fixed proxy url
func SetXMLIndent ¶
func SetXMLIndent(prefix, indent string)
SetXMLIndent sets the encoder to generate XML in which each element begins on a new indented line that starts with prefix and is followed by one or more copies of indent according to the nesting depth.
Types ¶
type FileUpload ¶
type FileUpload struct {
// filename in multipart form.
FileName string
// form field name
FieldName string
// file to uplaod, required
File io.ReadCloser
}
represents a file to upload
type QueryParam ¶
used to force append http request param to the uri
type Req ¶
type Req struct {
// contains filtered or unexported fields
}
func (*Req) EnableCookie ¶
EnableCookieenable or disable cookie manager
func (*Req) EnableInsecureTLS ¶
EnableInsecureTLS allows insecure https
func (*Req) SetJSONEscapeHTML ¶
SetJSONEscapeHTML specifies whether problematic HTML characters should be escaped inside JSON quoted strings. The default behavior is to escape &, <, and > to \u0026, \u003c, and \u003e to avoid certain safety problems that can arise when embedding JSON in HTML.
In non-HTML settings where the escaping interferes with the readability of the output, SetEscapeHTML(false) disables this behavior.
func (*Req) SetJSONIndent ¶
SetJSONIndent instructs the encoder to format each subsequent encoded value as if indented by the package-level function Indent(dst, src, prefix, indent). Calling SetIndent("", "") disables indentation.
func (*Req) SetProxyUrl ¶
SetProxyUrl set the simple proxy with fixed proxy url
func (*Req) SetTimeout ¶
SetTimeout sets the timeout for every request
func (*Req) SetXMLIndent ¶
SetXMLIndent sets the encoder to generate XML in which each element begins on a new indented line that starts with prefix and is followed by one or more copies of indent according to the nesting depth.
type Resp ¶
type Resp struct {
// contains filtered or unexported fields
}
Req represents a request with it's response
Source Files