req

package module
v0.0.0-...-10b1ce3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 27, 2021 License: Apache-2.0 Imports: 24 Imported by: 0

README

req

GoDoc

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 request.
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 Set context.Context

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)

You can also set header from struct, use HeaderFromStruct func to parse your struct

type HeaderStruct struct {
	UserAgent     string `json:"User-Agent"`
	Authorization string `json:"Authorization"`
}

func main(){
	h := HeaderStruct{
		"V1.0.0",
		"roc",
	}

	authHeader := req.HeaderFromStruct(h) 
	req.Get("https://www.baidu.com", authHeader, req.Header{"User-Agent": "V1.1"})
}

Note: Please add tag 'json' to your argument in struct to let you customize the key name of your header

Set Param

Use req.Param (it is actually a map[string]interface{})

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]interface{})

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")

post

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)         // same 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
})

Use req.UploadProgress to listen upload progress

progress := func(current, total int64) {
	fmt.Println(float32(current)/float32(total)*100, "%")
}
req.Post(url, req.File("/Users/roc/Pictures/*.png"), req.UploadProgress(progress))
fmt.Println("upload complete")

Download

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

Use req.DownloadProgress to listen download progress

progress := func(current, total int64) {
	fmt.Println(float32(current)/float32(total)*100, "%")
}
r, _ := req.Get(url, req.DownloadProgress(progress))
r.ToFile("hello.mp4")
fmt.Println("download complete")

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")

Set context.Context

You can pass context.Context in simple way:

r, _ := req.Get(url, context.Background())

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

View Source 
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
)

flags to decide which part can be outputed

Variables

View Source 
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 Client 

func Client() *http.Client

Client return the default underlying http client

func EnableCookie 

func EnableCookie(enable bool)

EnableCookieenable or disable cookie manager

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 Flags 

func Flags() int

Flags return output format for the *Resp

func SetClient 

func SetClient(client *http.Client)

SetClient sets the default http.Client for requests.

func SetFlags 

func SetFlags(flags int)

SetFlags control display format of *Resp

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 SetProgressInterval 

func SetProgressInterval(interval time.Duration)

SetProgressInterval sets the progress reporting interval of both UploadProgress and DownloadProgress handler for the default client

func SetProxy 

func SetProxy(proxy func(*http.Request) (*url.URL, error)) error

SetProxy sets the proxy for every request

func SetProxyUrl 

func SetProxyUrl(rawurl string) error

SetProxyUrl set the simple proxy with fixed proxy url

func SetTimeout 

func SetTimeout(d time.Duration)

SetTimeout sets the timeout for every request

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 DownloadProgress 

type DownloadProgress func(current, total int64)

type FileUpload 

type FileUpload struct {
	// filename in multipart form.
	FileName string
	// form field name
	FieldName string
	// file to uplaod, required
	File io.ReadCloser
}

FileUpload represents a file to upload 

type Header map[string]string

Header represents http request header

func HeaderFromStruct 

func HeaderFromStruct(v interface{}) Header

HeaderFromStruct init header from struct

func ParseStruct 

func ParseStruct(h Header, v interface{}) Header

ParseStruct parse struct into header

func (Header) Clone 

func (h Header) Clone() Header

type Host 

type Host string

Host is used for set request's Host

type Param 

type Param map[string]interface{}

Param represents http request param

type QueryParam 

type QueryParam map[string]interface{}

QueryParam is used to force append http request param to the uri

type Req 

type Req struct {
	// contains filtered or unexported fields
}

Req is a convenient client for initiating requests

func New 

func New() *Req

New create a new *Req

func (*Req) Client 

func (r *Req) Client() *http.Client

Client return the default underlying http client

func (*Req) Delete 

func (r *Req) Delete(url string, v ...interface{}) (*Resp, error)

Delete execute a http DELETE request

func (*Req) Do 

func (r *Req) Do(method, rawurl string, vs ...interface{}) (resp *Resp, err error)

Do execute a http request with sepecify method and url, and it can also have some optional params, depending on your needs.

func (*Req) EnableCookie 

func (r *Req) EnableCookie(enable bool)

EnableCookieenable or disable cookie manager

func (*Req) EnableInsecureTLS 

func (r *Req) EnableInsecureTLS(enable bool)

EnableInsecureTLS allows insecure https

func (*Req) Flags 

func (r *Req) Flags() int

Flags return output format for the *Resp

func (*Req) Get 

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

Get execute a http GET request

func (*Req) Head 

func (r *Req) Head(url string, v ...interface{}) (*Resp, error)

Head execute a http HEAD request

func (*Req) Options 

func (r *Req) Options(url string, v ...interface{}) (*Resp, error)

Options execute a http OPTIONS request

func (*Req) Patch 

func (r *Req) Patch(url string, v ...interface{}) (*Resp, error)

Patch execute a http PATCH request

func (*Req) Post 

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

Post execute a http POST request

func (*Req) Put 

func (r *Req) Put(url string, v ...interface{}) (*Resp, error)

Put execute a http PUT request

func (*Req) SetClient 

func (r *Req) SetClient(client *http.Client)

SetClient sets the underlying http.Client.

func (*Req) SetFlags 

func (r *Req) SetFlags(flags int)

SetFlags control display format of *Resp

func (*Req) SetJSONEscapeHTML 

func (r *Req) 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 (*Req) SetJSONIndent 

func (r *Req) 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 (*Req) SetProgressInterval 

func (r *Req) SetProgressInterval(interval time.Duration)

SetProgressInterval sets the progress reporting interval of both UploadProgress and DownloadProgress handler

func (*Req) SetProxy 

func (r *Req) SetProxy(proxy func(*http.Request) (*url.URL, error)) error

SetProxy sets the proxy for every request

func (*Req) SetProxyUrl 

func (r *Req) SetProxyUrl(rawurl string) error

SetProxyUrl set the simple proxy with fixed proxy url

func (*Req) SetTimeout 

func (r *Req) SetTimeout(d time.Duration)

SetTimeout sets the timeout for every request

func (*Req) SetXMLIndent 

func (r *Req) 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.

type Resp 

type Resp struct {
	// contains filtered or unexported fields
}

Resp represents a request with it's response

func Delete 

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

Delete execute a http DELETE request

func Do 

func Do(method, url string, v ...interface{}) (*Resp, error)

Do execute request.

func Get 

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

Get execute a http GET request 

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

Head execute a http HEAD request

func Options 

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

Options execute a http OPTIONS request

func Patch 

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

Patch execute a http PATCH request

func Post 

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

Post execute a http POST request

func Put 

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

Put execute a http PUT request

func (*Resp) Bytes 

func (r *Resp) Bytes() []byte

Bytes returns response body as []byte

func (*Resp) Cost 

func (r *Resp) Cost() time.Duration

Cost return the time cost of the request

func (*Resp) Dump 

func (r *Resp) Dump() string

Dump dump the request

func (*Resp) Format 

func (r *Resp) Format(s fmt.State, verb rune)

Format fort the response

func (*Resp) Request 

func (r *Resp) Request() *http.Request

Request returns *http.Request

func (*Resp) Response 

func (r *Resp) Response() *http.Response

Response returns *http.Response

func (*Resp) String 

func (r *Resp) String() string

String returns response body as string

func (*Resp) ToBytes 

func (r *Resp) ToBytes() ([]byte, error)

ToBytes returns response body as []byte, return error if error happend when reading the response body

func (*Resp) ToFile 

func (r *Resp) ToFile(name string) error

ToFile download the response body to file with optional download callback

func (*Resp) ToJSON 

func (r *Resp) ToJSON(v interface{}) error

ToJSON convert json response body to struct or map

func (*Resp) ToString 

func (r *Resp) ToString() (string, error)

ToString returns response body as string, return error if error happend when reading the response body

func (*Resp) ToXML 

func (r *Resp) ToXML(v interface{}) error

ToXML convert xml response body to struct or map

func (Resp) Upload 

func (m Resp) Upload(req *http.Request)

type UploadProgress 

type UploadProgress func(current, total int64)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.