Simple Go HTTP client with Black Magic
Full documentation is available on the official website: https://req.cool.
- Simple and Powerful: Providing rich client-level and request-level settings, all of which are intuitive and chainable methods, and the request-level setting takes precedence if both are set.
- Easy Debugging: Powerful and convenient debug utilities, including debug logs, performance traces, and even dump the complete request and response content (see Debugging).
- Easy API Testing: API testing can be done with minimal code, no need to explicitly create any Requests and Clients, or even to handle errors (See Quick HTTP Test)
- Smart by Default: Detect and decode to utf-8 automatically if possible to avoid garbled characters (See Auto Decode), marshal request body and unmarshal response body automatically according to the Content-Type.
- Works fine with HTTP2: Support both with HTTP/2 and HTTP/1.1, and HTTP/2 is preferred by default if server support, you can also force the protocol if you want (See Force HTTP version).
- Support Retry: Support automatic request retry and is fully customizable (See Retry).
- Easy Download and Upload: You can download and upload files with simple request settings, and even set a callback to show real-time progress (See Download and Upload).
- Exportable:
Transportis exportable, which support dump requests, it's easy to integrate with existing http.Client, so you can debug APIs with minimal code change. - Extensible: Support Middleware for Request and Response (See Request and Response Middleware).
Install
go get github.com/imroc/req/v3Import
import "github.com/imroc/req/v3"Basic Usage
// For testing, you can create and send a request with the global wrapper methods
// that use the default client behind the scenes to initiate the request (you can
// just treat package name `req` as a Client or Request, no need to create any client
// or Request explicitly).
req.DevMode() // Use Client.DevMode to see all details, try and surprise :)
req.Get("https://httpbin.org/get") // Use Request.Get to send a GET request.
// In production, create a client explicitly and reuse it to send all requests
client := req.C(). // Use C() to create a client and set with chainable client settings.
SetUserAgent("my-custom-client").
SetTimeout(5 * time.Second).
DevMode()
resp, err := client.R(). // Use R() to create a request and set with chainable request settings.
SetHeader("Accept", "application/vnd.github.v3+json").
SetPathParam("username", "imroc").
SetQueryParam("page", "1").
SetResult(&result). // Unmarshal response into struct automatically if status code >= 200 and <= 299.
SetError(&errMsg). // Unmarshal response into struct automatically if status code >= 400.
EnableDump(). // Enable dump at request level to help troubleshoot, log content only when an unexpected exception occurs.
Get("https://api.github.com/users/{username}/repos")
if err != nil {
// Handle error.
// ...
return
}
if resp.IsSuccess() {
// Handle result.
// ...
return
}
if resp.IsError() {
// Handle errMsg.
// ...
return
}
// Handle unexpected response (corner case).
err = fmt.Errorf("got unexpected response, raw dump:\n%s", resp.Dump())
// ...Videos
- Get Started With Req (English, Youtube)
- 快速上手 req (Chinese, BiliBili)
More
Check more introduction, tutorials, examples, best practices and API references on the official website.
Req released under MIT license, refer LICENSE file.