req

package module
v0.3.2 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2021 License: Apache-2.0 Imports: 24 Imported by: 761

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 information 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 information 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 added in v0.3.0

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 added in v0.1.6

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 added in v0.3.0

func HeaderFromStruct(v interface{}) Header

HeaderFromStruct init header from struct

func ParseStruct added in v0.3.0

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

ParseStruct parse struct into header

func (Header) Clone added in v0.1.6

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 added in v0.3.0

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 ReservedHeader added in v0.3.2

type ReservedHeader map[string]string

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 added in v0.1.3

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 added in v0.1.4

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

ToBytes returns response body as []byte, return error if error happened 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 added in v0.1.4

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

ToString returns response body as string, return error if error happened 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 added in v0.1.3

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

type UploadProgress added in v0.1.6

type UploadProgress func(current, total int64)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL