分享每一天-Req 是一个简单易用还带黑魔法的 Go HTTP 客户端，写更少的代码，获得更高的效率.

Req 是一个简单易用还带黑魔法的 Go HTTP 客户端，写更少的代码，获得更高的效率.

GoLang 1519 0 创建时间：2022-08-27 15:53:03

HTTP 客户端

#### Req介绍
Req 是一个简单易用还带黑魔法的 Go HTTP 客户端，写更少的代码，获得更高的效率.

#### 特性
- 简单且在请求级别和客户端级别支持丰富的设置，均可使用链式调用的方法进行设置，请求级别可以覆盖客户端级别。
- 强大便捷的调试工具，包括调试日志、性能跟踪，甚至 dump 完整的请求和响应内容 (参考 Debugging - Dump/Log/Trace).
- 可以直接使用代码替代 curl 或 postman 等工具轻松进行 HTTP 测试，提供全局包装方法和 MustXXX 以用最少的代码测试 API (参考 HTTP 快速测试).
- 同时支持 HTTP/2 和 HTTP/1.1，如果服务器支持，默认情况下首选 HTTP/2，如有需要，也可以强制指定 HTTP 版本 (参考 强制指定 HTTP 版本).
- 嗅探并自动解码成 UTF-8 以避免乱码 (参考 自动解码).
- 根据 Content-Type 自动 Marshal 请求体和 Unmarshal 响应体。
- Transport 是可导出的, 它支持 dump 请求内容，可以很容易与已有的 http.Client 集成，能以最少的代码改动获得 API 调试能力。
- 用很简单的设置就可以轻松进行上传和下载，甚至还支持设置回调来显示进度 (参考 上传 和 下载)。
- 轻松在请求级别或客户端级别设置请求头, cookie, URL 路径参数, 查询参数, 表单数据, Basic Auth, Bearer Token 等设置。
- 轻松设置客户端的超时时间，代理，证书，重定向策略，Cookie 存储，压缩，keepalive 等。
- 支持设置请求和响应的中间件，分别会在请求发出前和响应返回前执行 (参考 请求和响应中间件).

#### 快速开始
安装 
首先你需要安装 Go (版本要求在 1.15 及其以上), 然后用以下命令安装 req:
```go
go get -u github.com/imroc/req/v3
```
将 req 导入到你的代码:
```go
import "github.com/imroc/req/v3"
```
#### 快速上手

```go
package main

import (
    "github.com/imroc/req/v3"
)

func main() {
    req.DevMode()
    req.MustGet("https://httpbin.org/uuid")

req.EnableForceHTTP1() // 强制 HTTP/1.1 看看效果
    req.MustGet("https://httpbin.org/uuid")
}
```
```go
$ go run main.go
2022/05/19 10:05:07.920113 DEBUG [req] HTTP/2 GET https://httpbin.org/uuid
:authority: httpbin.org
:method: GET
:path: /uuid
:scheme: https
user-agent: req/v3 (https://github.com/imroc/req/v3)
accept-encoding: gzip

:status: 200
date: Thu, 19 May 2022 02:05:08 GMT
content-type: application/json
content-length: 53
server: gunicorn/19.9.0
access-control-allow-origin: *
access-control-allow-credentials: true

{
  "uuid": "bd519208-35d1-4483-ad9f-e1555ae108ba"
}

2022/05/19 10:05:09.340974 DEBUG [req] HTTP/1.1 GET https://httpbin.org/uuid
GET /uuid HTTP/1.1
Host: httpbin.org
User-Agent: req/v3 (https://github.com/imroc/req/v3)
Accept-Encoding: gzip

HTTP/1.1 200 OK
Date: Thu, 19 May 2022 02:05:09 GMT
Content-Type: application/json
Content-Length: 53
Connection: keep-alive
Server: gunicorn/19.9.0
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true

{
  "uuid": "49b7f916-c6f3-49d4-a6d4-22ae93b71969"
}
```
以上示例代码非常适合快速测试，它使用全局包装方法直接调用 Client 和 Request 的方法(没有显式创建 Client 和 Request)，使用 Client 的 DevMode() 来查看请求详细信息，使用 Request 的 MustGet 发送 GET 请求而无需处理 error。

#### 简单的 GET 请求
```go
package main

import (
	"fmt"
	"github.com/imroc/req/v3"
	"log"
)

func main() {
	client := req.C() // Use C() to create a client.
	resp, err := client.R(). // Use R() to create a request.
		Get("https://httpbin.org/uuid")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp)
}
```
```go
{
  "uuid": "a4d4430d-0e5f-412f-88f5-722d84bc2a62"
}
```
#### 高级的 GET 请求
```go
package main

import (
  "fmt"
  "github.com/imroc/req/v3"
  "log"
  "time"
)

type ErrorMessage struct {
  Message string `json:"message"`
}

type UserInfo struct {
  Name string `json:"name"`
  Blog string `json:"blog"`
}

func main() {
  client := req.C().
    SetUserAgent("my-custom-client"). // Chainable client settings.
    SetTimeout(5 * time.Second)

var userInfo UserInfo
  var errMsg ErrorMessage
  resp, err := client.R().
    SetHeader("Accept", "application/vnd.github.v3+json"). // Chainable request settings
    SetPathParam("username", "imroc").
    SetResult(&userInfo). // Unmarshal response body into userInfo automatically if status code is between 200 and 299.
    SetError(&errMsg). // Unmarshal response body into errMsg automatically if status code >= 400.
    EnableDump(). // Enable dump at request level, only print dump content if there is an error or some unknown situation occurs to help troubleshoot.
    Get("https://api.github.com/users/{username}")

if err != nil { // Error handling.
    log.Println("error:", err)
    log.Println("raw content:")
    log.Println(resp.Dump()) // Record raw content when error occurs.
    return
  }

if resp.IsError() { // Status code >= 400.
    fmt.Println(errMsg.Message) // Record error message returned.
    return
  }

if resp.IsSuccess() { // Status code is between 200 and 299.
    fmt.Printf("%s (%s)\n", userInfo.Name, userInfo.Blog)
    return
  }

// Unknown status code.
  log.Println("unknown status", resp.Status)
  log.Println("raw content:")
  log.Println(resp.Dump()) // Record raw content when server returned unknown status code.
}
```

#### 基础 POST 请求
```go
package main

import (
  "fmt"
  "github.com/imroc/req/v3"
  "log"
)

type Repo struct {
  Name string `json:"name"`
  Url  string `json:"url"`
}

type Result struct {
  Data string `json:"data"`
}

func main() {
  client := req.C().DevMode()
  var result Result

resp, err := client.R().
    SetBody(&Repo{Name: "req", Url: "https://github.com/imroc/req"}).
    SetResult(&result).
    Post("https://httpbin.org/post")
  if err != nil {
    log.Fatal(err)
  }

if !resp.IsSuccess() {
    fmt.Println("bad response status:", resp.Status)
    return
  }
  fmt.Println("++++++++++++++++++++++++++++++++++++++++++++++++")
  fmt.Println("data:", result.Data)
  fmt.Println("++++++++++++++++++++++++++++++++++++++++++++++++")
}}
```
```go
2022/05/19 20:11:00.151171 DEBUG [req] HTTP/2 POST https://httpbin.org/post
:authority: httpbin.org
:method: POST
:path: /post
:scheme: https
user-agent: req/v3 (https://github.com/imroc/req/v3)
content-type: application/json; charset=utf-8
content-length: 55
accept-encoding: gzip

{"name":"req","website":"https://github.com/imroc/req"}

:status: 200
date: Thu, 19 May 2022 12:11:00 GMT
content-type: application/json
content-length: 651
server: gunicorn/19.9.0
access-control-allow-origin: *
access-control-allow-credentials: true

{
  "args": {},
  "data": "{\"name\":\"req\",\"website\":\"https://github.com/imroc/req\"}",
  "files": {},
  "form": {},
  "headers": {
    "Accept-Encoding": "gzip",
    "Content-Length": "55",
    "Content-Type": "application/json; charset=utf-8",
    "Host": "httpbin.org",
    "User-Agent": "req/v3 (https://github.com/imroc/req/v3)",
    "X-Amzn-Trace-Id": "Root=1-628633d4-7559d633152b4307288ead2e"
  },
  "json": {
    "name": "req",
    "website": "https://github.com/imroc/req"
  },
  "origin": "103.7.29.30",
  "url": "https://httpbin.org/post"
}

++++++++++++++++++++++++++++++++++++++++++++++++
data: {"name":"req","url":"https://github.com/imroc/req"}
++++++++++++++++++++++++++++++++++++++++++++++++
```
#### Do API 风格 
```go
package main

import (
	"fmt"
	"github.com/imroc/req/v3"
)

type APIResponse struct {
	Origin string `json:"origin"`
	Url    string `json:"url"`
}

func main() {
	var resp APIResponse
	c := req.C().SetBaseURL("https://httpbin.org/post")
	err := c.Post().
		SetBody("hello").
		Do().
		Into(&resp)
	if err != nil {
		panic(err)
	}
	fmt.Println("My IP is", resp.Origin)
}
```
- 链式调用的顺序更直观：先调用 Client 创建一个指定 Method 的请求，然后对请求使用链式调用进行设置，再使用 Do() 发起请求，返回 Response，最后再调用 Response.Into 进行 Unmarshal。
- 如果在请求期间发生 error 或 Unmarshal 时发生 error，最终 Response.Into 都会返回 error。
- 有些 API 的 url 是固定的，通过传不同 body 来实现不同类型的请求，这种场景可实现使用 Client.SetBaseURL 设置统一的 url，在发起请求时就无需为每个请求都设置 url，当然，如果你需要也可以调用 Request.SetURL 来设置。

[更多方法在](https://req.cool/zh/docs/prologue/quickstart/ "更多方法在")

Req 是一个简单易用还带黑魔法的 Go HTTP 客户端，写更少的代码，获得更高的效率.

商品推荐

广告推荐

推荐文章