Greq
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
.httpfile format requests - Supports download and upload file(s)
- Built-in command tool:
cmd/greqLightweight HTTP request tool similar to curl and supports the IDEA.httpfile formatcmd/gbenchLightweight HTTP request load testing tool similar toabtesting 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
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)
}
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")
SetHeader("req-id", "a string")
Set multi at once:
greq.New("some.host/api").
SetHeaders(map[string]string{
"req-id": "a string",
})
SetHeaders(map[string]string{
"req-id": "a string",
})
Set content type
greq.New("some.host/api").
ContentType("text/html")
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())
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() boolResponse.IsFail() boolResponse.IsEmptyBody() boolResponse.IsJSONType() boolResponse.IsContentType(prefix string) bool
Get response data
Response.ContentType() stringResponse.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)
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())
}
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
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
gbench -c 10 -n 100 -d '{"name": "inhere"}' https://httpbin.org/post