req

<img src="https://yellow-cdn.veclightyear.com/835a84d5/eee636b0-bb2b-4189-ac29-1c5d0f97a39e.png"> 具有黑魔法的简单Go HTTP客户端 <a href="https://github.com/imroc/req/actions/workflows/ci.yml?query=branch%3Amaster"><img src="https://yellow-cdn.veclightyear.com/835a84d5/ec5167aa-1786-43db-83c6-f3d3faaf2b64.svg" alt="构建状态"></a> <a href="https://goreportcard.com/report/github.com/imroc/req/v3"><img src="https://goreportcard.com/badge/github.com/imroc/req/v3" alt="Go报告卡"></a> <a href="https://pkg.go.dev/github.com/imroc/req/v3"><img src="https://yellow-cdn.veclightyear.com/835a84d5/45c11df4-1849-48d6-a439-bb6c14bbd19d.svg"></a> <a href="LICENSE"><img src="https://yellow-cdn.veclightyear.com/835a84d5/32b5706c-2497-4bff-af24-5f66c2322f9a.svg" alt="许可证"></a> <a href="https://github.com/imroc/req/releases"><img src="https://img.shields.io/github/v/release/imroc/req?display_name=tag&sort=semver" alt="GitHub发布"></a> <a href="https://github.com/avelino/awesome-go"><img src="https://yellow-cdn.veclightyear.com/835a84d5/348d59d6-2063-416f-8cac-18012725c234.svg" alt="在Awesome Go中被提及"></a>

文档

完整文档可在官方网站上获取：https://req.cool

<a name="Features">特性</a>

简单而强大：使用简单方便，提供丰富的客户端级别和请求级别设置，所有设置都是直观的链式方法。
易于调试：强大且方便的调试工具，包括调试日志、性能追踪，甚至可以转储完整的请求和响应内容（参见调试）。
轻松进行API测试：使用最少的代码即可进行API测试，无需显式创建任何Request或Client，甚至无需处理错误（参见快速HTTP测试）。
智能默认设置：如果可能，自动检测并解码为utf-8以避免乱码（参见自动解码），根据Content-Type自动编组请求体和解组响应体。
支持多个HTTP版本：支持HTTP/1.1、HTTP/2和HTTP/3，可以自动检测服务器端并为请求选择最佳的HTTP版本，您也可以根据需要强制指定协议（参见强制HTTP版本）。
支持重试：支持自动请求重试，并且完全可自定义（参见重试）。
HTTP指纹：支持HTTP指纹模拟，使我们能够通过识别HTTP指纹来访问禁止爬虫程序的网站（参见HTTP指纹）。
多种认证方法：您可以直接使用HTTP基本认证、Bearer认证令牌和摘要认证（参见认证）。
轻松下载和上传：您可以通过简单的请求设置下载和上传文件，甚至可以设置回调以显示实时进度（参见下载和上传）。
可导出：req.Transport是可导出的。与http.Transport相比，它还支持HTTP3、转储内容、中间件等。它可以直接替换现有项目中http.Client的Transport，通过最小的代码更改获得更强大的功能。
可扩展：支持请求、响应、客户端和传输的中间件（参见请求和响应中间件和客户端和传输中间件）。

<a name="Get-Started">入门</a>

安装

首先需要安装Go（需要1.20+版本），然后可以使用以下Go命令安装req：

go get github.com/imroc/req/v3

导入

将req导入到您的代码中：

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

基本用法

# 假设以下代码在main.go文件中
$ cat main.go

package main

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

func main() {
    req.DevMode() // 将包名视为Client，启用开发模式
    req.MustGet("https://httpbin.org/uuid") // 将包名视为Request，发送GET请求

    req.EnableForceHTTP1() // 强制使用HTTP/1.1
    req.MustGet("https://httpbin.org/uuid")
}

$ 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"
}

上面的示例代码适用于快速测试目的，使用DevMode()查看请求详情，并使用全局包装方法发送请求，这些方法在后台使用默认客户端发起请求。

在生产环境中，建议显式创建一个客户端，然后使用同一个客户端发送所有请求，请参阅下面的其他示例。

视频

以下是req的一系列视频教程：

Youtube 播放列表
BiliBili 播放列表（中文）

在官方网站上查看更多介绍、教程、示例、最佳实践和 API 参考。

<a name="Simple-Get">简单的 GET 请求</a>

package main

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

func main() {
	client := req.C() // 使用 C() 创建一个客户端
	resp, err := client.R(). // 使用 R() 创建一个请求
		Get("https://httpbin.org/uuid")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp)
}

{
  "uuid": "a4d4430d-0e5f-412f-88f5-722d84bc2a62"
}

<a name="Advanced-Get">高级 GET 请求</a>

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"). // 可链式调用的客户端设置
    SetTimeout(5 * time.Second)

  var userInfo UserInfo
  var errMsg ErrorMessage
  resp, err := client.R().
    SetHeader("Accept", "application/vnd.github.v3+json"). // 可链式调用的请求设置
    SetPathParam("username", "imroc"). // 替换 URL 中的路径变量
    SetSuccessResult(&userInfo). // 如果状态码在 200 到 299 之间，自动将响应体解析到 userInfo
    SetErrorResult(&errMsg). // 如果状态码 >= 400，自动将响应体解析到 errMsg
    EnableDump(). // 在请求级别启用转储，仅在发生错误或一些未知情况时打印转储内容以帮助故障排查
    Get("https://api.github.com/users/{username}")

  if err != nil { // 错误处理
    log.Println("错误：", err)
    log.Println("原始内容：")
    log.Println(resp.Dump()) // 当发生错误时记录原始内容
    return
  }

  if resp.IsErrorState() { // 状态码 >= 400
    fmt.Println(errMsg.Message) // 记录返回的错误消息
    return
  }

  if resp.IsSuccessState() { // 状态码在 200 到 299 之间
    fmt.Printf("%s (%s)\n", userInfo.Name, userInfo.Blog)
    return
  }

  // 未知状态码
  log.Println("未知状态", resp.Status)
  log.Println("原始内容：")
  log.Println(resp.Dump()) // 当服务器返回未知状态码时记录原始内容
}

通常会输出（成功状态）：

roc (https://imroc.cc)

<a name="More-Advanced-Get">更高级的 GET 请求</a>

你可以在客户端设置统一的错误处理逻辑，这样每次发送请求时只需关注成功情况，减少重复代码。

package main

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

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

func (msg *ErrorMessage) Error() string {
	return fmt.Sprintf("API 错误：%s", msg.Message)
}

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

var client = req.C().
	SetUserAgent("my-custom-client"). // 可链式调用的客户端设置
	SetTimeout(5 * time.Second).
	EnableDumpEachRequest().
	SetCommonErrorResult(&ErrorMessage{}).
	OnAfterResponse(func(client *req.Client, resp *req.Response) error {
		if resp.Err != nil { // 存在底层错误，如网络错误或解析错误
			return nil
		}
		if errMsg, ok := resp.ErrorResult().(*ErrorMessage); ok {
			resp.Err = errMsg // 将 API 错误转换为 Go 错误
			return nil
		}
		if !resp.IsSuccessState() {
			// 既不是成功响应也不是错误响应，记录详细信息以帮助故障排查
			resp.Err = fmt.Errorf("错误状态：%s\n原始内容：\n%s", resp.Status, resp.Dump())
		}
		return nil
	})

func main() {
	var userInfo UserInfo
	resp, err := client.R().
		SetHeader("Accept", "application/vnd.github.v3+json"). // 可链式调用的请求设置
		SetPathParam("username", "imroc").
		SetSuccessResult(&userInfo). // 如果状态码在 200 到 299 之间，自动将响应体解析到 userInfo
		Get("https://api.github.com/users/{username}")

	if err != nil { // 错误处理
		log.Println("错误：", err)
		return
	}

	if resp.IsSuccessState() { // 状态码在 200 到 299 之间
		fmt.Printf("%s (%s)\n", userInfo.Name, userInfo.Blog)
	}
}

<a name="Simple-Post">简单的 POST 请求</a>

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"}).
    SetSuccessResult(&result).
    Post("https://httpbin.org/post")
  if err != nil {
    log.Fatal(err)
  }

  if !resp.IsSuccessState() {
    fmt.Println("响应状态错误：", resp.Status)
    return
  }
  fmt.Println("++++++++++++++++++++++++++++++++++++++++++++++++")
  fmt.Println("数据：", result.Data)
  fmt.Println("++++++++++++++++++++++++++++++++++++++++++++++++")
}

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"
}

++++++++++++++++++++++++++++++++++++++++++++++++
数据：{"name":"req","url":"https://github.com/imroc/req"}
++++++++++++++++++++++++++++++++++++++++++++++++

Do API 风格

如果你喜欢，你也可以使用像下面这样的 Do API 风格来发送请求：

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("我的 IP 是", resp.Origin)
}

我的 IP 是 182.138.155.113

链式调用的顺序更直观：先调用 Client 创建一个指定 Method 的请求，然后用链式调用设置请求，再用 Do() 发送请求，返回 Response，最后调用 Response.Into 将响应体解析到指定对象中。
Response.Into 会在发送请求或解析过程中出错时返回错误。
某些 API 的 url 是固定的，通过传不同的 body 来实现不同的请求。在这种场景下，可以使用 Client.SetBaseURL 设置统一的 url，发起请求时就不需要每次都设置 url 了。当然，如果需要的话你也可以调用 Request.SetURL 来设置。

使用 Req 构建 SDK

这里是一个使用 req 构建 GitHub SDK 的示例，使用了两种风格（GetUserProfile_Style1、GetUserProfile_Style2）。

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

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

// Error 实现了 go 的 error 接口。
func (msg *ErrorMessage) Error() string {
	return fmt.Sprintf("API 错误：%s", msg.Message)
}

type GithubClient struct {
	*req.Client
}

func NewGithubClient() *GithubClient {
	return &GithubClient{
		Client: req.C().
			SetBaseURL("https://api.github.com").
			SetCommonErrorResult(&ErrorMessage{}).
			EnableDumpEachRequest().
			OnAfterResponse(func(client *req.Client, resp *req.Response) error {
				if resp.Err != nil { // 存在底层错误，如网络错误或解析错误。
					return nil
				}
				if errMsg, ok := resp.ErrorResult().(*ErrorMessage); ok {
					resp.Err = errMsg // 将 API 错误转换为 go 错误
					return nil
				}
				if !resp.IsSuccessState() {
					// 既不是成功响应也不是错误响应，记录详细信息以帮助排查
					resp.Err = fmt.Errorf("错误状态：%s\n原始内容：\n%s", resp.Status, resp.Dump())
				}
				return nil
			}),
	}
}

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

// GetUserProfile_Style1 返回指定用户的用户资料。
// Github API 文档：https://docs.github.com/en/rest/users/users#get-a-user
func (c *GithubClient) GetUserProfile_Style1(ctx context.Context, username string) (user *UserProfile, err error) {
	_, err = c.R().
		SetContext(ctx).
		SetPathParam("username", username).
		SetSuccessResult(&user).
		Get("/users/{username}")
	return
}

// GetUserProfile_Style2 返回指定用户的用户资料。
// Github API 文档：https://docs.github.com/en/rest/users/users#get-a-user
func (c *GithubClient) GetUserProfile_Style2(ctx context.Context, username string) (user *UserProfile, err error) {
	err = c.Get("/users/{username}").
		SetPathParam("username", username).
		Do(ctx).
		Into(&user)
	return
}

贡献

如果你有 bug 报告或功能请求，可以提交 issue，我们也欢迎pull requests。

联系

如果你有问题，可以通过以下方式联系我们：

Github 讨论
Slack | 加入

赞助商

如果你喜欢 req 并且它确实对你有帮助，欢迎用一杯咖啡犒劳我，不要忘记提及你的 github id。

非常感谢以下赞助商：

<table> <tr> <td align="center"> <a href="https://github.com/M-Cosmosss"> <img src="https://avatars.githubusercontent.com/u/46757262?v=4?s=100" width="160px" alt=""/> M-Cosmosss 🥇 </a> </td> <td align="center"> <a href="https://github.com/aadog"> <img src="https://avatars.githubusercontent.com/u/18098725?v=4?s=100" width="160px" alt=""/> aadog 🥈 </a> </td> </tr> </table>