greq

package module
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Feb 19, 2026 License: MIT Imports: 22 Imported by: 0

Image README ¶

Greq

GitHub go.mod Go version GitHub tag (latest SemVer) GoDoc Go Report Card Unit-Tests Coverage Status

中文说明 | English

greq A simple HTTP client request builder and sender, with retry feature.

Features

  • Make HTTP requests, supports GET,POST,PUT,PATCH,DELETE,HEAD
  • Transform request and response data
  • Supports chain configuration request
  • Supports defining and adding middleware
  • Supports defining request body provider and response decoder
  • Supports request retry feature, with default retry checker DefaultRetryChecker
  • Built-In: fom, json request body provider
  • Built-In: xml, json response body decoder
  • Support for directly parsing and sending .http file format requests
  • Supports download and upload file(s)
  • Built-in command tool:
    • cmd/greq Lightweight HTTP request tool similar to curl and supports the IDEA .http file format
    • cmd/gbench Lightweight HTTP request load testing tool similar to ab testing tool

Install

go get github.com/gookit/greq
Install Tools
# HTTP request tool
go install github.com/gookit/greq/cmd/greq@latest
# HTTP request testing
go install github.com/gookit/greq/cmd/gbench@latest

Quick start

package main

import (
	"github.com/gookit/goutil/dump"
	"github.com/gookit/greq"
)

func main() {
	resp, err := greq.New("https://httpbin.org").
		JSONType().
		UserAgent("custom-client/1.0").
		PostDo("/post", `{"name": "inhere"}`)

	if err != nil {
		panic(err)
	}

	ret := make(map[string]any)
	err = resp.Decode(&ret)
	if err != nil {
		panic(err)
	}

	dump.P(ret)
}

Result:

PRINT AT github.com/gookit/greq_test.TestHReq_Send(greq_test.go:73)
map[string]interface {} { #len=4
  "args": map[string]interface {} { #len=0
  },
  "headers": map[string]interface {} { #len=4
    "Host": string("httpbin.org"), #len=11
    "User-Agent": string("custom-client/1.0"), #len=17
    "X-Amzn-Trace-Id": string("Root=1-61e4d41e-06e27ae12ff872a224373ca7"), #len=40
    "Accept-Encoding": string("gzip"), #len=4
  },
  "origin": string("222.210.59.218"), #len=14
  "url": string("https://httpbin.org/post"), #len=24
},

Request headers

greq.New("some.host/api").
	SetHeader("req-id", "a string")

Set multi at once:

greq.New("some.host/api").
	SetHeaders(map[string]string{
		"req-id": "a string",
	})
Set content type
greq.New("some.host/api").
    ContentType("text/html")

Built in JSONType() FromType() XMLType()

greq.New("some.host/api").JSONType()

Use middleware

	buf := &bytes.Buffer{}
	mid0 := greq.MiddleFunc(func(r *http.Request, next greq.HandleFunc) (*greq.Response, error) {
		buf.WriteString("MID0>>")
		w, err := next(r)
		buf.WriteString(">>MID0")
		return w, err
	})

	mid1 := greq.MiddleFunc(func(r *http.Request, next greq.HandleFunc) (*greq.Response, error) {
		buf.WriteString("MID1>>")
		w, err := next(r)
		buf.WriteString(">>MID1")
		return w, err
	})

	mid2 := greq.MiddleFunc(func(r *http.Request, next greq.HandleFunc) (*greq.Response, error) {
		buf.WriteString("MID2>>")
		w, err := next(r)
		buf.WriteString(">>MID2")
		return w, err
	})

	resp, err := greq.New("https://httpbin.org").
		Doer(httpreq.DoerFunc(func(req *http.Request) (*http.Response, error) {
			tw := httptest.NewRecorder()
			buf.WriteString("(CORE)")
			return tw.Result(), nil
		})).
		Middleware(mid0, mid1, mid2).
		GetDo("/get")

    fmt.Println(buf.String())

Output:

MID2>>MID1>>MID0>>(CORE)>>MID0>>MID1>>MID2

More usage

Check response
  • Response.IsOK() bool
  • Response.IsFail() bool
  • Response.IsEmptyBody() bool
  • Response.IsJSONType() bool
  • Response.IsContentType(prefix string) bool
Get response data
  • Response.ContentType() string
  • Response.Decode(ptr any) error
Request to string
    str := greq.New("https://httpbin.org").
		UserAgent("some-client/1.0").
		BasicAuth("inhere", "some string").
		JSONType().
		Body("hi, with body").
		Post("/post").
		String()

	fmt.Println(str)

Output:

POST https://httpbin.org/post/ HTTP/1.1
User-Agent: some-client/1.0
Authorization: Basic aW5oZXJlOnNvbWUgc3RyaW5n
Content-Type: application/json; charset=utf-8

hi, with body
Response to string

greq.Response.String() can convert response to string.

package main

import (
	"fmt"

	"github.com/gookit/goutil/dump"
	"github.com/gookit/greq"
)

func main() {
	resp, err := greq.New("https://httpbin.org").
		UserAgent("custom-client/1.0").
		Send("/get")

	if err != nil {
		panic(err)
	}

	fmt.Print(resp.String())
}

Output:

HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Date: Tue, 18 Jan 2022 04:52:39 GMT
Content-Type: application/json
Content-Length: 272
Server: gunicorn/19.9.0

{
  "args": {},
  "headers": {
    "Accept-Encoding": "gzip",
    "Host": "httpbin.org",
    "User-Agent": "custom-client/1.0",
    "X-Amzn-Trace-Id": "Root=1-61e64797-3e428a925f7709906a8b7c01"
  },
  "origin": "222.210.59.218",
  "url": "https://httpbin.org/get"
}

Command Tool Usage

greq Tool

cmd/greq Lightweight HTTP request tool similar to curl and supports the IDEA .http file format

Install tool:

go install github.com/gookit/greq/cmd/greq@latest

Show options:

greq -h

Usage examples:

greq https://httpbin.org/get
greq -X POST -d '{"name": "inhere"}' https://httpbin.org/post
gbench Tool

cmd/gbench Lightweight HTTP request load testing tool similar to ab testing tool

Install tool:

go install github.com/gookit/greq/cmd/gbench@latest

Show options:

gbench -h

Usage examples：

gbench -c 10 -n 100 https://httpbin.org/get
gbench -c 10 -n 100 -d '{"name": "inhere"}' https://httpbin.org/post

Refers

Image Documentation ¶

Overview ¶

Package greq is a simple http client request builder, support batch requests.

Index ¶

Constants ¶

View Source 
const (
	HeaderUAgent = "User-Agent"
	HeaderAuth   = "Authorization"

	AgentCURL = "CURL/7.64.1 greq/1.0.2"
)

Variables ¶

View Source 
var DefaultDoer = http.DefaultClient

DefaultDoer for request.

Functions ¶

func DefaultRetryChecker ¶ added in v0.5.0 

func DefaultRetryChecker(resp *Response, err error, attempt int) bool

DefaultRetryChecker is the default retry condition checker It retries on: - Network errors (err != nil) - 5xx server errors - 429 Too Many Requests

func NewTransport ¶ added in v0.5.0 

func NewTransport(onCreate func(ht *http.Transport)) *http.Transport

NewTransport create new http transport

Types ¶

type AfterSendFn ¶ added in v0.3.0 

type AfterSendFn func(resp *Response, err error)

AfterSendFn callback func

type BodyProvider ¶ 

type BodyProvider interface {
	// ContentType returns the Content-Type of the body.
	ContentType() string
	// Body returns the io.Reader body.
	Body() (io.Reader, error)
}

BodyProvider provides Body content for http.Request attachment.

type Builder ¶ added in v0.3.0 

type Builder struct {
	*Options
	// contains filtered or unexported fields
}

Builder is an http request builder.

func BuilderWithClient ¶ added in v0.3.0 

func BuilderWithClient(c *Client, optFns ...OptionFn) *Builder

BuilderWithClient create a new builder with client

func NewBuilder ¶ added in v0.3.0 

func NewBuilder(fns ...OptionFn) *Builder

NewBuilder for request

func (*Builder) AddHeader ¶ added in v0.3.0 

func (b *Builder) AddHeader(key, value string) *Builder

AddHeader adds the key, value pair in HeaderM, appending values for existing keys to the key's values. Header keys are canonicalized.

func (*Builder) AddHeaderMap ¶ added in v0.3.0 

func (b *Builder) AddHeaderMap(headers map[string]string) *Builder

AddHeaderMap sets all the http.Header values, appending values for existing keys to the key's values.

func (*Builder) AddHeaders ¶ added in v0.3.0 

func (b *Builder) AddHeaders(headers http.Header) *Builder

AddHeaders adds all the http.Header values, appending values for existing keys to the key's values. Header keys are canonicalized.

func (*Builder) AddQuery ¶ added in v0.3.0 

func (b *Builder) AddQuery(key string, value any) *Builder

AddQuery appends new k-v param to the Query string.

func (*Builder) AnyBody ¶ added in v0.3.0 

func (b *Builder) AnyBody(body any) *Builder

AnyBody with custom any type body

func (*Builder) BasicAuth ¶ added in v0.3.0 

func (b *Builder) BasicAuth(username, password string) *Builder

BasicAuth sets the Authorization header to use HTTP Basic Authentication with the provided username and password.

With HTTP Basic Authentication the provided username and password are not encrypted.

func (*Builder) BodyProvider ¶ added in v0.3.0 

func (b *Builder) BodyProvider(bp BodyProvider) *Builder

BodyProvider with custom body provider

func (*Builder) BodyReader ¶ added in v0.3.0 

func (b *Builder) BodyReader(r io.Reader) *Builder

BodyReader with custom io reader body

func (*Builder) Build ¶ added in v0.3.0 

func (b *Builder) Build(method, pathURL string) (*http.Request, error)

Build request

func (*Builder) BytesBody ¶ added in v0.3.0 

func (b *Builder) BytesBody(bs []byte) *Builder

BytesBody with custom string body

func (*Builder) Delete ¶ added in v0.3.0 

func (b *Builder) Delete(pathURL string, optFns ...OptionFn) *Builder

Delete sets the method to DELETE and sets the given pathURL

func (*Builder) DeleteDo ¶ added in v0.3.0 

func (b *Builder) DeleteDo(pathURL string, optFns ...OptionFn) (*Response, error)

DeleteDo sets the method to DELETE and sets the given pathURL, then send request and return response.

func (*Builder) Do ¶ added in v0.3.0 

func (b *Builder) Do(optFns ...OptionFn) (*Response, error)

Do send request and return response.

func (*Builder) FileContentsBody ¶ added in v0.3.0 

func (b *Builder) FileContentsBody(filePath string) *Builder

FileContentsBody read file contents as body

func (*Builder) FormBody ¶ added in v0.3.0 

func (b *Builder) FormBody(formData any) *Builder

FormBody with form data body

func (*Builder) FormType ¶ added in v0.3.0 

func (b *Builder) FormType() *Builder

FormType with from Content-Type header

func (*Builder) Get ¶ added in v0.3.0 

func (b *Builder) Get(pathURL string, optFns ...OptionFn) *Builder

Get sets the method to GET and sets the given pathURL

func (*Builder) GetDo ¶ added in v0.3.0 

func (b *Builder) GetDo(pathURL string, optFns ...OptionFn) (*Response, error)

GetDo sets the method to GET and sets the given pathURL, then send request and return response.

func (*Builder) JSONBody ¶ added in v0.3.0 

func (b *Builder) JSONBody(jsonData any) *Builder

JSONBody with JSON data body

func (*Builder) JSONType ¶ added in v0.3.0 

func (b *Builder) JSONType() *Builder

JSONType with json Content-Type header

func (*Builder) Multipart ¶ added in v0.3.0 

func (b *Builder) Multipart(key, value string) *Builder

Multipart with custom multipart body

func (*Builder) MultipartType ¶ added in v0.3.0 

func (b *Builder) MultipartType() *Builder

MultipartType with multipart/form-data Content-Type header

func (*Builder) Patch ¶ added in v0.3.0 

func (b *Builder) Patch(pathURL string, data any, optFns ...OptionFn) *Builder

Patch sets the method to PATCH and sets the given pathURL

func (*Builder) PatchDo ¶ added in v0.3.0 

func (b *Builder) PatchDo(pathURL string, data any, optFns ...OptionFn) (*Response, error)

PatchDo sets the method to PATCH and sets the given pathURL, then send request and return response.

func (*Builder) PathURL ¶ added in v0.3.0 

func (b *Builder) PathURL(pathURL string) *Builder

PathURL set path URL for current request

func (*Builder) Post ¶ added in v0.3.0 

func (b *Builder) Post(pathURL string, data any, optFns ...OptionFn) *Builder

Post sets the method to POST and sets the given pathURL

func (*Builder) PostDo ¶ added in v0.3.0 

func (b *Builder) PostDo(pathURL string, data any, optFns ...OptionFn) (*Response, error)

PostDo sets the method to POST and sets the given pathURL, then send request and return http response.

func (*Builder) Put ¶ added in v0.3.0 

func (b *Builder) Put(pathURL string, data any, optFns ...OptionFn) *Builder

Put sets the method to PUT and sets the given pathURL

func (*Builder) PutDo ¶ added in v0.3.0 

func (b *Builder) PutDo(pathURL string, data any, optFns ...OptionFn) (*Response, error)

PutDo sets the method to PUT and sets the given pathURL, then send request and return response.

func (*Builder) QueryParams ¶ added in v0.3.0 

func (b *Builder) QueryParams(ps any) *Builder

QueryParams appends url.Values/map[string]string to the Query string. The value will be encoded as url Query parameters on send requests (see Send()).

func (*Builder) QueryValues ¶ added in v0.3.0 

func (b *Builder) QueryValues(values gourl.Values) *Builder

QueryValues appends url.Values to the Query string. The value will be encoded as url Query parameters on new requests (see Send()).

func (*Builder) RemoveHeaders ¶ added in v0.5.0 

func (b *Builder) RemoveHeaders(keys ...string) *Builder

RemoveHeaders removes the keys from HeaderM.

func (*Builder) Send ¶ added in v0.3.0 

func (b *Builder) Send(method, url string, optFns ...OptionFn) (*Response, error)

Send request and return response, alias of Do()

func (*Builder) SetHeader ¶ added in v0.3.0 

func (b *Builder) SetHeader(key, value string) *Builder

SetHeader sets the key, value pair in HeaderM, replacing existing values associated with key. Header keys are canonicalized.

func (*Builder) SetHeaderMap ¶ added in v0.3.0 

func (b *Builder) SetHeaderMap(headers map[string]string) *Builder

SetHeaderMap sets all the http.Header values, replacing values for existing keys to the key's values.

func (*Builder) SetHeaders ¶ added in v0.3.0 

func (b *Builder) SetHeaders(headers http.Header) *Builder

SetHeaders sets all the http.Header values, replacing values for existing keys to the key's values. Header keys are canonicalized.

func (*Builder) String ¶ added in v0.3.0 

func (b *Builder) String() string

String request to string.

func (*Builder) StringBody ¶ added in v0.3.0 

func (b *Builder) StringBody(s string) *Builder

StringBody with custom string body

func (*Builder) UserAgent ¶ added in v0.3.0 

func (b *Builder) UserAgent(ua string) *Builder

UserAgent set User-Agent header

func (*Builder) UserAuth ¶ added in v0.3.0 

func (b *Builder) UserAuth(value string) *Builder

UserAuth with user auth header value.

func (*Builder) WithBody ¶ added in v0.3.0 

func (b *Builder) WithBody(body any) *Builder

WithBody with custom any type body

func (*Builder) WithClient ¶ added in v0.3.0 

func (b *Builder) WithClient(c *Client) *Builder

WithClient set cli to builder

func (*Builder) WithContentType ¶ added in v0.3.0 

func (b *Builder) WithContentType(value string) *Builder

WithContentType with custom ContentType header

func (*Builder) WithCookieString ¶ added in v0.3.0 

func (b *Builder) WithCookieString(value string) *Builder

WithCookieString set cookie header value.

Usage: 

h.NewOpt().
	WithCookieString("name=inhere;age=30").
	Do("/some/api", "GET")

func (*Builder) WithCookies ¶ added in v0.3.0 

func (b *Builder) WithCookies(hcs ...*http.Cookie) *Builder

WithCookies to request

func (*Builder) WithMethod ¶ added in v0.3.0 

func (b *Builder) WithMethod(method string) *Builder

WithMethod set request method name.

func (*Builder) WithOptionFn ¶ added in v0.3.0 

func (b *Builder) WithOptionFn(fns ...OptionFn) *Builder

WithOptionFn set option fns to builder

func (*Builder) WithOptionFns ¶ added in v0.3.0 

func (b *Builder) WithOptionFns(fns []OptionFn) *Builder

WithOptionFns set option fns to builder

func (*Builder) WithQuerySMap ¶ added in v0.3.0 

func (b *Builder) WithQuerySMap(smp map[string]string) *Builder

WithQuerySMap appends map[string]string to the Query string.

func (*Builder) WithType ¶ added in v0.3.0 

func (b *Builder) WithType(value string) *Builder

WithType with custom ContentType header

func (*Builder) XMLType ¶ added in v0.3.0 

func (b *Builder) XMLType() *Builder

XMLType with xml Content-Type header

type Client ¶ added in v0.3.0 

type Client struct {

	// Method default http method. default is GET
	Method string
	// Header default http header. default is nil
	Header http.Header
	// defalut content type
	ContentType string
	// BaseURL default base URL. default is ""
	BaseURL string
	// Timeout default timeout(ms) for each request. default 10s
	//
	//  - 0: not limit
	Timeout int
	// RespDecoder response data decoder.
	//  - use for create Response instance. default is JSON decoder
	RespDecoder RespDecoder

	// ReqVars template vars for request: URL, Header, Query, Body
	//
	// eg: http://example.com/${name}
	ReqVars map[string]string
	// BeforeSend callback on each request, can return error to deny request.
	BeforeSend func(r *http.Request) error
	// AfterSend callback on each request, can use for record request and response
	AfterSend AfterSendFn

	// MaxRetries max retry times. default is 0 (not retry)
	MaxRetries int
	// RetryDelay retry delay time (ms). default is 0 (no delay)
	RetryDelay int
	// RetryChecker retry condition checker. default is nil (not retry)
	RetryChecker RetryChecker
	// contains filtered or unexported fields
}

Client is an HTTP Request builder and sender.

func BaseURL ¶ 

func BaseURL(baseURL string) *Client

BaseURL set base URL for request

func New ¶ 

func New(baseURL ...string) *Client

New create a new http request client.

func NewClient ¶ added in v0.5.0 

func NewClient(baseURL ...string) *Client

NewClient create a new http request client. alias of New()

func Reset ¶ 

func Reset() *Client

Reset std default settings

func Std ¶ 

func Std() *Client

Std instance

func (*Client) AnyBody ¶ added in v0.3.0 

func (h *Client) AnyBody(body any) *Builder

AnyBody with custom any type body

func (*Client) BasicAuth ¶ added in v0.3.0 

func (h *Client) BasicAuth(username, password string) *Builder

BasicAuth sets the Authorization header to use HTTP Basic Authentication with the provided username and password.

With HTTP Basic Authentication the provided username and password are not encrypted.

func (*Client) Body ¶ added in v0.3.0 

func (h *Client) Body(body any) *Builder

Body with custom any type body

func (*Client) BodyProvider ¶ added in v0.3.0 

func (h *Client) BodyProvider(bp BodyProvider) *Builder

BodyProvider with custom body provider

func (*Client) BodyReader ¶ added in v0.3.0 

func (h *Client) BodyReader(r io.Reader) *Builder

BodyReader with custom io reader body

func (*Client) Builder ¶ added in v0.3.0 

func (h *Client) Builder(optFns ...OptionFn) *Builder

Builder create a new builder with current client.

func (*Client) Client ¶ added in v0.3.0 

func (h *Client) Client(doer httpreq.Doer) *Client

Client custom set http request doer

func (*Client) Config ¶ added in v0.3.0 

func (h *Client) Config(fn func(h *Client)) *Client

Config custom config for client.

Usage: 

h.Config(func(h *Client) {
	h.Method = http.MethodPost
})

func (*Client) ConfigDoer ¶ added in v0.5.0 

func (h *Client) ConfigDoer(fn func(doer httpreq.Doer)) *Client

ConfigDoer custom config http request doer

func (*Client) ConfigHClient ¶ added in v0.3.0 

func (h *Client) ConfigHClient(fn func(hClient *http.Client)) *Client

ConfigHClient custom config http client.

Usage: 

h.ConfigHClient(func(hClient *http.Client) {
	hClient.Timeout = 30 * time.Second
})

func (*Client) DefaultBasicAuth ¶ added in v0.3.0 

func (h *Client) DefaultBasicAuth(username, password string) *Client

DefaultBasicAuth sets the Authorization header to use HTTP Basic Authentication with the provided username and password. With HTTP Basic Authentication the provided username and password are not encrypted.

func (*Client) DefaultContentType ¶ added in v0.3.0 

func (h *Client) DefaultContentType(value string) *Client

DefaultContentType set default ContentType header, it will be used for all requests.

Usage: 

// json type
h.DefaultContentType(httpctype.JSON)
// form type
h.DefaultContentType(httpctype.Form)

func (*Client) DefaultHeader ¶ added in v0.3.0 

func (h *Client) DefaultHeader(key, value string) *Client

DefaultHeader sets the http.Header value, it will be used for all requests.

func (*Client) DefaultHeaders ¶ added in v0.3.0 

func (h *Client) DefaultHeaders(headers http.Header) *Client

DefaultHeaders sets all the http.Header values, it will be used for all requests.

func (*Client) DefaultMethod ¶ added in v0.3.0 

func (h *Client) DefaultMethod(method string) *Client

DefaultMethod set default method name. it will be used when the Get()/Post() method is empty.

func (*Client) DefaultTimeout ¶ added in v0.5.0 

func (h *Client) DefaultTimeout(timeoutMs int) *Client

DefaultTimeout set default timeout in milliseconds for requests. default is 0 (infinite)

func (*Client) DefaultUserAgent ¶ added in v0.3.0 

func (h *Client) DefaultUserAgent(value string) *Client

DefaultUserAgent with User-Agent header setting for all requests.

func (*Client) DefaultUserAuth ¶ added in v0.3.0 

func (h *Client) DefaultUserAuth(value string) *Client

DefaultUserAuth with user auth header value for all requests.

func (*Client) Delete ¶ added in v0.3.0 

func (h *Client) Delete(pathURL string) *Builder

Delete sets the method to DELETE and sets the given pathURL

func (*Client) DeleteDo ¶ added in v0.3.0 

func (h *Client) DeleteDo(pathURL string, optFns ...OptionFn) (*Response, error)

DeleteDo sets the method to DELETE and sets the given pathURL, then send request and return http response.

func (*Client) Do ¶ added in v0.3.0 

func (h *Client) Do(method, url string, optFns ...OptionFn) (*Response, error)

Do send request and return response

func (*Client) DoWithOption ¶ added in v0.3.0 

func (h *Client) DoWithOption(method, url string, optFns ...OptionFn) (*Response, error)

DoWithOption request with options, then return response

func (*Client) Doer ¶ added in v0.3.0 

func (h *Client) Doer(doer httpreq.Doer) *Client

Doer custom set http request doer. If a nil cli is given, the DefaultDoer will be used.

func (*Client) Download ¶ added in v0.5.0 

func (h *Client) Download(url, savePath string, optFns ...OptionFn) (int, error)

Download remote file from url and save to savePath.

func (*Client) FormType ¶ added in v0.3.0 

func (h *Client) FormType() *Builder

FormType with from Content-Type header

func (*Client) Get ¶ added in v0.3.0 

func (h *Client) Get(pathURL string) *Builder

Get sets the method to GET and sets the given pathURL

func (*Client) GetDo ¶ added in v0.3.0 

func (h *Client) GetDo(pathURL string, optFns ...OptionFn) (*Response, error)

GetDo sets the method to GET and sets the given pathURL, then send request and return response.

func (*Client) Head ¶ added in v0.3.0 

func (h *Client) Head(pathURL string) *Builder

Head sets the method to HEAD and request the pathURL, then send request and return response.

func (*Client) HeadDo ¶ added in v0.3.0 

func (h *Client) HeadDo(pathURL string, optFns ...OptionFn) (*Response, error)

HeadDo sets the method to HEAD and request the pathURL, then send request and return response.

func (*Client) HttpClient ¶ added in v0.3.0 

func (h *Client) HttpClient(hClient *http.Client) *Client

HttpClient custom set http cli as request doer

func (*Client) JSONType ¶ added in v0.3.0 

func (h *Client) JSONType() *Builder

JSONType with json Content-Type header

func (*Client) Middleware ¶ added in v0.3.0 

func (h *Client) Middleware(middles ...Middleware) *Client

Middleware add one or multi middlewares

func (*Client) Middlewares ¶ added in v0.3.0 

func (h *Client) Middlewares(middles ...Middleware) *Client

Middlewares add one or multi middlewares

func (*Client) MustSend ¶ added in v0.3.0 

func (h *Client) MustSend(method, url string, optFns ...OptionFn) *Response

MustSend send request and return response, will panic on error

func (*Client) NewRequest ¶ added in v0.3.0 

func (h *Client) NewRequest(method, url string, optFns ...OptionFn) (*http.Request, error)

NewRequest build new request

func (*Client) NewRequestWithOptions ¶ added in v0.3.0 

func (h *Client) NewRequestWithOptions(url string, opt *Options) (*http.Request, error)

NewRequestWithOptions build new request with Options

func (*Client) OnBeforeSend ¶ added in v0.3.0 

func (h *Client) OnBeforeSend(fn func(r *http.Request) error) *Client

OnBeforeSend for cli

func (*Client) Patch ¶ added in v0.3.0 

func (h *Client) Patch(pathURL string) *Builder

Patch sets the method to PATCH and sets the given pathURL

func (*Client) PatchDo ¶ added in v0.3.0 

func (h *Client) PatchDo(pathURL string, optFns ...OptionFn) (*Response, error)

PatchDo sets the method to PATCH and sets the given pathURL, then send request and return http response.

func (*Client) Post ¶ added in v0.3.0 

func (h *Client) Post(pathURL string) *Builder

Post sets the method to POST and sets the given pathURL

func (*Client) PostDo ¶ added in v0.3.0 

func (h *Client) PostDo(pathURL string, optFns ...OptionFn) (*Response, error)

PostDo sets the method to POST and sets the given pathURL, then send request and return http response.

func (*Client) Put ¶ added in v0.3.0 

func (h *Client) Put(pathURL string) *Builder

Put sets the method to PUT and sets the given pathURL

func (*Client) PutDo ¶ added in v0.3.0 

func (h *Client) PutDo(pathURL string, optFns ...OptionFn) (*Response, error)

PutDo sets the method to PUT and sets the given pathURL, then send request and return http response.

func (*Client) QueryParams ¶ added in v0.3.0 

func (h *Client) QueryParams(ps any) *Builder

QueryParams appends url.Values/map[string]string to the Query string. The value will be encoded as url Query parameters on send requests (see Send()).

func (*Client) Send ¶ added in v0.3.0 

func (h *Client) Send(method, url string, optFns ...OptionFn) (*Response, error)

Send request and return response, alias of Do()

func (*Client) SendRaw ¶ added in v0.3.0 

func (h *Client) SendRaw(raw string, varMp map[string]string) (*Response, error)

SendRaw http request text. like IDE .http file contents

Format: 

POST https://example.com/path?name=inhere
Content-Type: application/json
Accept: */*

<content>

func (*Client) SendRequest ¶ added in v0.3.0 

func (h *Client) SendRequest(req *http.Request) (*Response, error)

SendRequest send request

func (*Client) SendWithOpt ¶ added in v0.3.0 

func (h *Client) SendWithOpt(pathURL string, opt *Options) (*Response, error)

SendWithOpt send request with option, then return response

func (*Client) SendWithOption ¶ added in v0.3.0 

func (h *Client) SendWithOption(method, url string, optFns ...OptionFn) (*Response, error)

SendWithOption request with options, then return response

func (*Client) SetMaxIdleConns ¶ added in v0.5.0 

func (h *Client) SetMaxIdleConns(maxIdleConns, maxIdleConnsPerHost int) *Client

SetMaxIdleConns Set the maximum number of idle connections.

func (*Client) String ¶ added in v0.3.0 

func (h *Client) String() string

String request to string.

func (*Client) Sub ¶ added in v0.3.0 

func (h *Client) Sub() *Client

Sub create an instance from current. will inherit all options

func (*Client) UploadFile ¶ added in v0.5.0 

func (h *Client) UploadFile(pathURL, fieldName, filePath string, optFns ...OptionFn) (*Response, error)

UploadFile uploads a single file to the given URL.

func (*Client) UploadFiles ¶ added in v0.5.0 

func (h *Client) UploadFiles(pathURL string, files map[string]string, optFns ...OptionFn) (*Response, error)

UploadFiles uploads multiple files to the given URL.

func (*Client) UploadWithData ¶ added in v0.5.0 

func (h *Client) UploadWithData(pathURL string, files map[string]string, fields map[string]string, optFns ...OptionFn) (*Response, error)

UploadWithData uploads files with additional form fields.

func (*Client) Use ¶ added in v0.3.0 

func (h *Client) Use(middles ...Middleware) *Client

Use one or multi middlewares

func (*Client) UserAgent ¶ added in v0.3.0 

func (h *Client) UserAgent(value string) *Builder

UserAgent with User-Agent header setting for all requests.

func (*Client) UserAuth ¶ added in v0.3.0 

func (h *Client) UserAuth(value string) *Builder

UserAuth with user auth header value for all requests.

func (*Client) Uses ¶ added in v0.3.0 

func (h *Client) Uses(middles ...Middleware) *Client

Uses one or multi middlewares

func (*Client) WithBaseURL ¶ added in v0.5.0 

func (h *Client) WithBaseURL(baseURL string) *Client

WithBaseURL set default base URL for all request

func (*Client) WithContentType ¶ added in v0.3.0 

func (h *Client) WithContentType(value string) *Builder

WithContentType with custom Content-Type header

func (*Client) WithMaxRetries ¶ added in v0.5.0 

func (h *Client) WithMaxRetries(maxRetries int) *Client

WithMaxRetries set max retry times

func (*Client) WithRespDecoder ¶ added in v0.3.0 

func (h *Client) WithRespDecoder(respDecoder RespDecoder) *Client

WithRespDecoder for cli

func (*Client) WithRetryChecker ¶ added in v0.5.0 

func (h *Client) WithRetryChecker(checker RetryChecker) *Client

WithRetryChecker set custom retry checker function

func (*Client) WithRetryConfig ¶ added in v0.5.0 

func (h *Client) WithRetryConfig(maxRetries, retryDelay int, checker RetryChecker) *Client

WithRetryConfig set retry configuration

func (*Client) WithRetryDelay ¶ added in v0.5.0 

func (h *Client) WithRetryDelay(retryDelay int) *Client

WithRetryDelay set retry delay time in milliseconds

type HandleFunc ¶ 

type HandleFunc func(r *http.Request) (*Response, error)

HandleFunc for the Middleware

type MiddleFunc ¶ 

type MiddleFunc func(r *http.Request, next HandleFunc) (*Response, error)

MiddleFunc implements the Middleware interface

func (MiddleFunc) Handle ¶ 

func (mf MiddleFunc) Handle(r *http.Request, next HandleFunc) (*Response, error)

Handle request

type Middleware ¶ 

type Middleware interface {
	Handle(r *http.Request, next HandleFunc) (*Response, error)
}

Middleware interface for cli request.

type OptionFn ¶ added in v0.3.0 

type OptionFn func(opt *Options)

OptionFn for config request options

func WithBody ¶ added in v0.5.0 

func WithBody(body any) OptionFn

WithBody set body data

func WithContentType ¶ added in v0.3.0 

func WithContentType(contentType string) OptionFn

WithContentType set content-type

func WithData ¶ added in v0.5.0 

func WithData(data any) OptionFn

WithData set data for request

func WithHeader ¶ added in v0.5.0 

func WithHeader(key, value string) OptionFn

WithHeader set header

func WithMaxRetries ¶ added in v0.5.0 

func WithMaxRetries(maxRetries int) OptionFn

WithMaxRetries set max retry times for the request

func WithMethod ¶ added in v0.3.0 

func WithMethod(method string) OptionFn

WithMethod set method

func WithRetry ¶ added in v0.5.0 

func WithRetry(maxRetries, retryDelay int, checker RetryChecker) OptionFn

WithRetry set retry configuration for the request

func WithRetryChecker ¶ added in v0.5.0 

func WithRetryChecker(checker RetryChecker) OptionFn

WithRetryChecker set custom retry checker function for the request

func WithRetryDelay ¶ added in v0.5.0 

func WithRetryDelay(retryDelay int) OptionFn

WithRetryDelay set retry delay time in milliseconds for the request

func WithTimeout ¶ added in v0.5.0 

func WithTimeout(timeoutMs int) OptionFn

WithTimeout set timeout (ms)

func WithUserAgent ¶ added in v0.3.0 

func WithUserAgent(userAgent string) OptionFn

WithUserAgent set user-agent header

type Options ¶ added in v0.3.0 

type Options struct {

	// Method for request
	Method string
	// ContentType header
	ContentType string
	// Headers for request
	Header http.Header
	// HeaderM map string data.
	HeaderM map[string]string

	// Query params data.
	Query  gourl.Values
	QueryM map[string]any

	// Data for request. Will be encoded to query string or request body.
	//
	// type allow: string, []byte, io.Reader, io.ReadCloser, url.Values, map[string]string
	Data any
	// Body data for request, only for POST, PUT, PATCH
	//
	// type allow: string, []byte, io.Reader, io.ReadCloser, url.Values, map[string]string
	Body any
	// Provider body data provider, can with custom content-type
	Provider BodyProvider

	// EncodeJSON req body
	EncodeJSON bool
	// Timeout unit: ms
	Timeout int
	// TCancelFn will auto set it on Timeout > 0
	TCancelFn context.CancelFunc
	// Context for request
	Context context.Context
	// Logger for request
	Logger httpreq.ReqLogger

	// Retry configuration
	MaxRetries   int
	RetryDelay   int
	RetryChecker RetryChecker
	// contains filtered or unexported fields
}

Options for one request build

func NewOpt ¶ added in v0.3.0 

func NewOpt(fns ...OptionFn) *Options

NewOpt for request

func NewOpt2 ¶ added in v0.3.0 

func NewOpt2(fns []OptionFn, method string) *Options

NewOpt2 for request

type RequestCreator ¶ 

type RequestCreator interface {
	NewRequest(method, target string, body io.Reader) *http.Request
}

RequestCreator interface

type RequestCreatorFunc ¶ 

type RequestCreatorFunc func(method, target string, body io.Reader) *http.Request

RequestCreatorFunc func

type RespDecoder ¶ 

type RespDecoder interface {
	// Decode decodes the response into the value pointed to by ptr.
	Decode(resp *http.Response, ptr any) error
}

RespDecoder decodes http responses into struct values.

type Response ¶ 

type Response struct {
	// raw http.Response
	*http.Response
	// CostTime for a request-response. unit: ms
	CostTime int64
	// contains filtered or unexported fields
}

Response is a http.Response wrapper, add some useful methods.

func ConnectDo ¶ 

func ConnectDo(pathURL string, optFns ...OptionFn) (*Response, error)

ConnectDo sets the method to CONNECT and sets the given pathURL, then send request and return http response.

func DeleteDo ¶ 

func DeleteDo(pathURL string, optFns ...OptionFn) (*Response, error)

DeleteDo sets the method to DELETE and sets the given pathURL, then send request and return http response.

func GetDo ¶ 

func GetDo(pathURL string, optFns ...OptionFn) (*Response, error)

GetDo sets the method to GET and sets the given pathURL, then send request and return response.

func HeadDo ¶ added in v0.3.0 

func HeadDo(pathURL string, optFns ...OptionFn) (*Response, error)

HeadDo sets the method to HEAD and request the pathURL, then send request and return response.

func Must ¶ added in v0.3.0 

func Must(w *Response, err error) *Response

Must return response, if error will panic

func MustDo ¶ added in v0.3.0 

func MustDo(method, pathURL string, optFns ...OptionFn) *Response

MustDo sets the method to POST and sets the given pathURL, then send request and return http response.

func NewResponse ¶ added in v0.5.0 

func NewResponse(resp *http.Response, decoder RespDecoder) *Response

NewResponse create a new Response instance

func OptionsDo ¶ 

func OptionsDo(pathURL string, optFns ...OptionFn) (*Response, error)

OptionsDo sets the method to OPTIONS and request the pathURL, then send request and return response.

func PatchDo ¶ 

func PatchDo(pathURL string, data any, optFns ...OptionFn) (*Response, error)

PatchDo sets the method to PATCH and sets the given pathURL, then send request and return http response.

func PostDo ¶ 

func PostDo(pathURL string, data any, optFns ...OptionFn) (*Response, error)

PostDo sets the method to POST and sets the given pathURL, then send request and return http response.

func PutDo ¶ 

func PutDo(pathURL string, data any, optFns ...OptionFn) (*Response, error)

PutDo sets the method to PUT and sets the given pathURL, then send request and return http response.

func SendDo ¶ added in v0.3.0 

func SendDo(method, pathURL string, optFns ...OptionFn) (*Response, error)

SendDo sets the method to POST and sets the given pathURL, then send request and return http response.

func TraceDo ¶ 

func TraceDo(pathURL string, optFns ...OptionFn) (*Response, error)

TraceDo sets the method to TRACE and sets the given pathURL, then send request and return http response.

func (*Response) BodyBuffer ¶ 

func (r *Response) BodyBuffer() *bytes.Buffer

BodyBuffer read body to buffer.

NOTICE: must close resp body.

func (*Response) BodyString ¶ 

func (r *Response) BodyString() string

BodyString convert response body to string

func (*Response) CloseBody ¶ 

func (r *Response) CloseBody() error

CloseBody close resp body

func (*Response) ContentType ¶ 

func (r *Response) ContentType() string

ContentType get response content type

func (*Response) Decode ¶ 

func (r *Response) Decode(ptr any) error

Decode get the raw http.Response

func (*Response) HeaderString ¶ 

func (r *Response) HeaderString() string

HeaderString convert response headers to string

func (*Response) IsContentType ¶ 

func (r *Response) IsContentType(prefix string) bool

IsContentType check response content type is equals the given.

Usage: 

resp, err := greq.Post("some.host/path")
ok := resp.IsContentType("application/xml")

func (*Response) IsEmptyBody ¶ 

func (r *Response) IsEmptyBody() bool

IsEmptyBody check response body is empty

func (*Response) IsFail ¶ 

func (r *Response) IsFail() bool

IsFail check response status code != 200

func (*Response) IsJSONType ¶ 

func (r *Response) IsJSONType() bool

IsJSONType check response content type is JSON

func (*Response) IsOK ¶ 

func (r *Response) IsOK() bool

IsOK check response status code is 200

func (*Response) IsSuccessful ¶ 

func (r *Response) IsSuccessful() bool

IsSuccessful check response status code is in 200 - 300

func (*Response) QuietCloseBody ¶ 

func (r *Response) QuietCloseBody()

QuietCloseBody close resp body, ignore error

func (*Response) SaveFile ¶ added in v0.3.0 

func (r *Response) SaveFile(file string) (n int, err error)

SaveFile file on the response body is not-nil.

func (*Response) SetDecoder ¶ 

func (r *Response) SetDecoder(decoder RespDecoder)

SetDecoder for response

func (*Response) String ¶ 

func (r *Response) String() string

String convert Response to string

type RetryChecker ¶ added in v0.5.0 

type RetryChecker func(resp *Response, err error, attempt int) bool

RetryChecker function type for checking if a request should be retried

type XmlDecoder ¶ 

type XmlDecoder struct {
}

XmlDecoder decodes http response body into a XML-tagged struct value.

func (XmlDecoder) Decode ¶ 

func (d XmlDecoder) Decode(resp *http.Response, ptr any) error

Decode decodes the Response body into the value pointed to by ptr.

Image Source Files ¶

View all Source files

Image Directories ¶

Path Synopsis
cmd
gbench command
greq command
ext
batch
Package batch provides utilities for batch processing HTTP requests
 Package batch provides utilities for batch processing HTTP requests
bench
httpfile
Package httpfile provides HTTP request file(.http) parsing utilities.
 Package httpfile provides HTTP request file(.http) parsing utilities.

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.