gcal

README

gcal

Advanced HTTP client for golang.

引入http client

import "github.com/layasugar/gcal"

Quick Start by trace

package main

import (
    "github.com/layasugar/gcal"
)

func main() {
	client := gcal.WithCommonHeader(genv.AppName(), "111").
		WithTrace(c, glogs.GetSpanContextKey(), url, glogs.Tracer).
		WithHeaders(map[string]string{"laya": "surprise"}).
		WithOption(gcal.OPT_TIMEOUT, 30)

	res, err := client.Get(url, map[string]string{"laya": data})
	if err != nil {
		log.Printf("BulkCourse http返回错误: err=%s", err.Error())
	}

	if res == nil {
		log.Printf("空响应")
		return
	}

	if res.StatusCode != http.StatusOK {
		log.Printf("BulkCourse: http状态码错误批量处理失败: %s", fmt.Sprintf("%d", res.StatusCode))
	}

	body1, err := res.ReadAll()
	log.Printf(string(body1))
}

Usage

Sending Request

// get
gcal.Get("http://httpbin.org/get", map[string]string{
"q": "news",
})

// get with url.Values
gcal.Get("http://httpbin.org/get", url.Values{
"q": []string{"news", "today"}
})

// post
gcal.Post("http://httpbin.org/post", map[string]string {
"name": "value"
})

// post file(multipart)
gcal.Post("http://httpbin.org/multipart", map[string]string {
"@file": "/tmp/hello.pdf",
})

// put json
gcal.PutJson("http://httpbin.org/put",
`{
    "name": "hello",
}`)

// delete
gcal.Delete("http://httpbin.org/delete")

Customize Request

Before you start a new HTTP request with Get or Post method, you can specify temporary options, headers or cookies for current request.

gcal.
WithHeader("User-Agent", "Super Robot").
WithHeader("custom-header", "value").
WithHeaders(map[string]string {
"another-header": "another-value",
"and-another-header": "another-value",
}).
WithOption(gcal.OPT_TIMEOUT, 60).
WithCookie(&http.Cookie{
Name: "uid",
Value: "123",
}).
Get("http://github.com")

Response

The gcal.Response is a thin wrap of http.Response.

// traditional
res, err := gcal.Get("http://google.com")
bodyBytes, err := ioutil.ReadAll(res.Body)
res.Body.Close()

// ToString
res, err = gcal.Get("http://google.com")
bodyString, err := res.ToString()

// ReadAll
res, err = gcal.Get("http://google.com")
bodyBytes, err := res.ReadAll()

Concurrent Safe

If you want to start many requests concurrently, remember to call the Begin method when you begin:

go func () {
gcal.
Begin().
WithHeader("Req-A", "a").
Get("http://google.com")
}()
go func () {
gcal.
Begin().
WithHeader("Req-B", "b").
Get("http://google.com")
}()

Error Checking

You can use gcal.IsTimeoutError to check for timeout error:

res, err := gcal.Get("http://google.com")
if gcal.IsTimeoutError(err) {
// do something
}

Options

Available options as below:

• OPT_FOLLOWLOCATION: TRUE to follow any "Location: " header that the server sends as part of the HTTP header. Default to true.
• OPT_CONNECTTIMEOUT: The number of seconds or interval (with time.Duration) to wait while trying to connect. Use 0 to wait indefinitely.
• OPT_CONNECTTIMEOUT_MS: The number of milliseconds to wait while trying to connect. Use 0 to wait indefinitely.
• OPT_MAXREDIRS: The maximum amount of HTTP redirections to follow. Use this option alongside OPT_FOLLOWLOCATION.
• OPT_PROXYTYPE: Specify the proxy type. Valid options are PROXY_HTTP, PROXY_SOCKS4, PROXY_SOCKS5 , PROXY_SOCKS4A. Only PROXY_HTTP is supported currently.
• OPT_TIMEOUT: The maximum number of seconds or interval (with time.Duration) to allow gcal functions to execute.
• OPT_TIMEOUT_MS: The maximum number of milliseconds to allow gcal functions to execute.
• OPT_COOKIEJAR: Set to true to enable the default cookiejar, or you can set to a http.CookieJar instance to use a customized jar. Default to true.
• OPT_INTERFACE: TODO
• OPT_PROXY: Proxy host and port(127.0.0.1:1080).
• OPT_REFERER: The Referer header of the request.
• OPT_USERAGENT: The User-Agent header of the request. Default to "gcal".
• OPT_REDIRECT_POLICY: Function to check redirect.
• OPT_PROXY_FUNC: Function to specify proxy.
• OPT_UNSAFE_TLS: Set to true to disable TLS certificate checking.
• OPT_DEBUG: Print request info.
• OPT_CONTEXT: Set context.context (can be used to cancel request).
• OPT_BEFORE_REQUEST_FUNC: Function to call before request is sent, option should be type func(*http.Client, *http.Request)

Documentation

Overview

Powerful and easy to use http client

Powerful and easy to use http client

Index

• Constants
• Variables
• func IsNil(obj interface{}) bool
• func IsRedirectError(err error) bool
• func IsTimeoutError(err error) bool
• func Md5(s string) string
• func Option(o map[string]interface{}) map[int]interface{}
• type Error
  • func (err Error) Error() string
• type HttpClient
  • func NewHttpClient() *HttpClient
  • func (client *HttpClient) Begin() *HttpClient
  • func (client *HttpClient) Defaults(defaults Map) *HttpClient
  • func (client *HttpClient) Delete(url string, params ...interface{}) (*Response, error)
  • func (client *HttpClient) Do(method string, url string, headers map[string]string, body io.Reader) (*Response, error)
  • func (client *HttpClient) Get(url string, params ...interface{}) (*Response, error)
  • func (client *HttpClient) Head(url string) (*Response, error)
  • func (client *HttpClient) Post(url string, params interface{}) (*Response, error)
  • func (client *HttpClient) PostJson(url string, data interface{}) (*Response, error)
  • func (client *HttpClient) PostMultipart(url string, params interface{}) (*Response, error)
  • func (client *HttpClient) Put(url string, body io.Reader) (*Response, error)
  • func (client *HttpClient) PutJson(url string, data interface{}) (*Response, error)
  • func (client *HttpClient) WithCommonHeader(appName, appSecretKey string) *HttpClient
  • func (client *HttpClient) WithHeader(k string, v string) *HttpClient
  • func (client *HttpClient) WithHeaders(m map[string]string) *HttpClient
  • func (client *HttpClient) WithOption(k int, v interface{}) *HttpClient
  • func (client *HttpClient) WithOptions(m Map) *HttpClient
  • func (client *HttpClient) WithTrace(ctx interface{}, spanContextKey, name string, trace *zipkin.Tracer) *HttpClient
• type Map
• type Response
  • func (client *Response) ReadAll() ([]byte, error)
  • func (client *Response) ToString() (string, error)

Constants

const (
	ErrDefault
	ErrTimeout
	ErrRedirectPolicy
)

Package errors

const (
	PROXY_HTTP int = iota
	PROXY_SOCKS4
	PROXY_SOCKS5
	PROXY_SOCKS4A

	// CURL like OPT
	OPT_AUTOREFERER
	OPT_FOLLOWLOCATION
	OPT_CONNECTTIMEOUT
	OPT_CONNECTTIMEOUT_MS
	OPT_MAXREDIRS
	OPT_PROXYTYPE
	OPT_TIMEOUT
	OPT_TIMEOUT_MS
	OPT_COOKIEJAR
	OPT_INTERFACE
	OPT_PROXY
	OPT_REFERER
	OPT_USERAGENT

	// Other OPT
	OPT_REDIRECT_POLICY
	OPT_PROXY_FUNC
	OPT_DEBUG
	OPT_UNSAFE_TLS

	OPT_CONTEXT

	OPT_BEFORE_REQUEST_FUNC
	OPT_AFTER_REQUEST_FUNC
)

const (
	USERAGENT = "gcal"
)

Constants definations CURL options, see https://github.com/bagder/curl/blob/169fedbdce93ecf14befb6e0e1ce6a2d480252a3/packages/OS400/curl.inc.in

Variables

var Begin = defaultClient.Begin

var Defaults = defaultClient.Defaults

var CONST = map[string]int{
	"OPT_AUTOREFERER":         OPT_AUTOREFERER,
	"OPT_FOLLOWLOCATION":      OPT_FOLLOWLOCATION,
	"OPT_CONNECTTIMEOUT":      OPT_CONNECTTIMEOUT,
	"OPT_CONNECTTIMEOUT_MS":   OPT_CONNECTTIMEOUT_MS,
	"OPT_MAXREDIRS":           OPT_MAXREDIRS,
	"OPT_PROXYTYPE":           OPT_PROXYTYPE,
	"OPT_TIMEOUT":             OPT_TIMEOUT,
	"OPT_TIMEOUT_MS":          OPT_TIMEOUT_MS,
	"OPT_COOKIEJAR":           OPT_COOKIEJAR,
	"OPT_INTERFACE":           OPT_INTERFACE,
	"OPT_PROXY":               OPT_PROXY,
	"OPT_REFERER":             OPT_REFERER,
	"OPT_USERAGENT":           OPT_USERAGENT,
	"OPT_REDIRECT_POLICY":     OPT_REDIRECT_POLICY,
	"OPT_PROXY_FUNC":          OPT_PROXY_FUNC,
	"OPT_DEBUG":               OPT_DEBUG,
	"OPT_UNSAFE_TLS":          OPT_UNSAFE_TLS,
	"OPT_CONTEXT":             OPT_CONTEXT,
	"OPT_BEFORE_REQUEST_FUNC": OPT_BEFORE_REQUEST_FUNC,
	"OPT_AFTER_REQUEST_FUNC":  OPT_AFTER_REQUEST_FUNC,
}

String map of options

var Delete = defaultClient.Delete

var Do = defaultClient.Do

var Get = defaultClient.Get

var Head = defaultClient.Head

var Post = defaultClient.Post

var PostJson = defaultClient.PostJson

var PostMultipart = defaultClient.PostMultipart

var Put = defaultClient.Put

var PutJson = defaultClient.PutJson

var WithCommonHeader = defaultClient.WithCommonHeader

var WithHeader = defaultClient.WithHeader

var WithHeaders = defaultClient.WithHeaders

var WithOption = defaultClient.WithOption

var WithOptions = defaultClient.WithOptions

var WithTrace = defaultClient.WithTrace

Functions

func IsNil

func IsNil(obj interface{}) bool

func IsRedirectError

func IsRedirectError(err error) bool

Check a redirect error

func IsTimeoutError

func IsTimeoutError(err error) bool

Check a timeout error.

func Md5

func Md5(s string) string

md5

func Option

func Option(o map[string]interface{}) map[int]interface{}

Convert options with string keys to desired format.

Types

type Error

type Error struct {
	Code    int
	Message string
}

Custom error

func (Error) Error

func (err Error) Error() string

Implement the error interface

type HttpClient

type HttpClient struct {
	// trace_span
	Span zipkin.Span

	// span context key
	SpanContextKey string

	// Default headers of client client.
	Headers map[string]string
	// contains filtered or unexported fields
}

Powerful and easy to use HTTP client.

func NewHttpClient

func NewHttpClient() *HttpClient

Create an HTTP client.

func (*HttpClient) Begin

func (client *HttpClient) Begin() *HttpClient

Begin marks the begining of a request, it's necessary for concurrent requests.

func (*HttpClient) Defaults

func (client *HttpClient) Defaults(defaults Map) *HttpClient

Set default options and headers.

func (*HttpClient) Delete

func (client *HttpClient) Delete(url string, params ...interface{}) (*Response, error)

The DELETE request

func (*HttpClient) Do

func (client *HttpClient) Do(method string, url string, headers map[string]string,
	body io.Reader) (*Response, error)

Start a request, and get the response.

Usually we just need the Get and Post method.

func (*HttpClient) Get

func (client *HttpClient) Get(url string, params ...interface{}) (*Response, error)

The GET request

func (*HttpClient) Head

func (client *HttpClient) Head(url string) (*Response, error)

The HEAD request

func (*HttpClient) Post

func (client *HttpClient) Post(url string, params interface{}) (*Response,
	error)

The POST request

With multipart set to true, the request will be encoded as "multipart/form-data".

If any of the params key starts with "@", it is considered as a form file (similar to CURL but different).

func (*HttpClient) PostJson

func (client *HttpClient) PostJson(url string, data interface{}) (*Response, error)

func (*HttpClient) PostMultipart

func (client *HttpClient) PostMultipart(url string, params interface{}) (
	*Response, error)

Post with the request encoded as "multipart/form-data".

func (*HttpClient) Put

func (client *HttpClient) Put(url string, body io.Reader) (*Response, error)

The PUT request

func (*HttpClient) PutJson

func (client *HttpClient) PutJson(url string, data interface{}) (*Response, error)

Put json data

func (*HttpClient) WithCommonHeader

func (client *HttpClient) WithCommonHeader(appName, appSecretKey string) *HttpClient

func (*HttpClient) WithHeader

func (client *HttpClient) WithHeader(k string, v string) *HttpClient

Temporarily specify a header of the current request.

func (*HttpClient) WithHeaders

func (client *HttpClient) WithHeaders(m map[string]string) *HttpClient

Temporarily specify multiple headers of the current request.

func (*HttpClient) WithOption

func (client *HttpClient) WithOption(k int, v interface{}) *HttpClient

Temporarily specify an option of the current request.

func (*HttpClient) WithOptions

func (client *HttpClient) WithOptions(m Map) *HttpClient

Temporarily specify multiple options of the current request.

func (*HttpClient) WithTrace

func (client *HttpClient) WithTrace(ctx interface{}, spanContextKey, name string, trace *zipkin.Tracer) *HttpClient

type Map

type Map map[interface{}]interface{}

Map is a mixed structure with options and headers

type Response

type Response struct {
	*http.Response
}

Thin wrapper of http.Response(can also be used as http.Response).

func (*Response) ReadAll

func (client *Response) ReadAll() ([]byte, error)

Read response body into a byte slice.

func (*Response) ToString

func (client *Response) ToString() (string, error)

Read response body into string.