req:Go 语言里让人上瘾的 HTTP 客户端
如果你写过一段时间 Go,大概率用过标准库 net/http。它很稳,但写起来啰嗦:构造请求、设置 Header、处理 Body、反序列化 JSON、错误处理……一个简单的 GET 请求往往要写七八行。
req 就是来解决这个痛点的。项目地址:
它是一个 Go 的 HTTP 客户端库,主打三个字:少写点。不过别被它的简洁误导——简洁的外表下藏着相当完整的能力,API 风格类似 Python 的 requests,用起来非常顺手。
一、它到底有多简单?
先看一个最普通的 GET 请求:
resp, err := req.Get("https://httpbin.org/get")
if err != nil {
panic(err)
}
fmt.Println(resp.StatusCode())
fmt.Println(resp.String())
没有 http.NewRequest,没有 client.Do,没有手动 io.ReadAll 再 defer resp.Body.Close()。req 全都帮你处理好了。
发 POST 并带上 JSON:
r, err := req.Post("https://httpbin.org/post", req.BodyJSON(map[string]any{
"name": "imroc",
"age": 18,
}))
想顺便把响应 JSON 解析到结构体里?一行搞定:
var result struct {
Json map[string]any `json:"json"`
}
r, err := req.Post("https://httpbin.org/post", req.BodyJSON(map[string]any{"a": 1})).
SetResult(&result).
Do()
这就是 req 的核心设计思路:把请求的各个要素做成链式方法,读起来几乎和自然语言一样。SetResult 负责把响应体反序列化进目标变量,SetError 负责错误响应,SetHeader、SetQueryParam、SetBasicAuth、SetBearerToken 各司其职。
二、链式 API 的优雅之处
req 的请求对象是可链式调用的,这带来的好处是:一个 HTTP 请求的完整语义可以在一行代码里表达清楚。
r, err := req.New().
SetMethod("PUT").
SetURL("https://httpbin.org/put").
SetHeader("X-Token", "abc").
SetQueryParam("page", "1").
SetBody(map[string]any{"hello": "world"}).
SetContentType("application/json").
Do()
等价于你在 net/http 里要写十几行、还要处理各种 error 的代码。而且它内置了常见的便捷方法:
req.Get/req.Post/req.Put/req.Delete/req.Patch/req.Headreq.BodyJSON(v)/req.BodyXML(v)req.QueryParam(k, v)/req.Header(k, v)req.BasicAuth(user, pass)/req.BearerToken(token)
对于大部分日常请求,用包级函数就够了;需要复用配置时,再自己创建 client。
三、Client:配置一次,处处复用
跟 http.Client 一样,你可以创建一个带默认配置的 client,比如统一设置 BaseURL、超时、重试策略、代理:
client := req.C().
SetBaseURL("https://api.example.com").
SetTimeout(5 * time.Second).
SetCommonHeader("User-Agent", "my-app/1.0")
resp, err := client.R().
SetQueryParam("q", "golang").
Get("/search")
注意 SetBaseURL + 相对路径这个组合,在写封装 SDK 时特别舒服。不用在每个方法里拼字符串。
四、容易被低估的杀手锏功能
如果只是 API 简洁,req 大概只能算”语法糖”。真正让我持续用它的,是它把很多工程化才需要的东西内置了。
1. 自动重试
client := req.C().
SetRetryCount(3).
SetRetryInterval(func(r *req.Response, attempt int) time.Duration {
return time.Duration(attempt) * time.Second
})
配合 SetRetryFixedInterval、SetRetryMaxWaitTime,以及自定义的 SetRetryCondition(判断哪些响应/错误需要重试),基本覆盖了生产场景的兜底需求。开箱即用的幂等重试,省去了自己写循环和退避逻辑。
2. 全自动 HTTP 调试
这是 req 非常讨喜的一个点。设置一个环境变量或一行开关,就能把请求和响应完整地打到控制台:
client := req.C().EnableDumpAll() // 或者 req.EnableDebugLog()、EnableDebugLogWithFunc(...)
它会把请求行、Header、响应状态、Body 按 curl 可复现的格式输出。调第三方接口的时候,直接把 Dump 内容复制成 curl 命令贴到终端验证,效率极高。
3. 内置可视化 Debug 工具
req 还附带了一个叫 req/debug(原 req.DebugLog、req.Trace)的能力,可以开一个本地 Web UI,可视化查看每次请求的详情,支持查看响应体、导入为 curl、重放等。类似浏览器的 Network 面板,但作用在 Go 进程里。排查偶发问题时特别有用。
4. 网络抓包与自定义 Transport
它支持挂载 httptrace、设置自定义 http.RoundTripper、接入代理,也能拿到 DNS、连接、TLS 等阶段耗时:
client := req.C().EnableTrace() // 开启调用链耗时统计 client := req.C().SetTransport(...) // 替换底层 Transport
5. 上传下载都很顺手
上传文件:
r, err := req.Post(url, req.FileUpload{
FileField: "file",
FileName: "a.png",
FilePath: "./a.png",
})
或者用 req.MultipartUpload 更精细地控制。下载的话,直接 resp.ToFile("out.zip")。断点续传、进度回调(SetOutput + 自定义 Writer)也都能组合实现。
6. 中间件式 Hook
req 提供了 AddClientHook、SetPreRequestHook、SetResponseHandler 等钩子,可以在请求前后、响应后插入逻辑,比如打日志、加签名、统一加 trace id——写基础设施封装的时候非常灵活。
7. 与标准库无缝互通
它支持通过 SetContext 传入 context.Context,支持 httputil、http.CookieJar、http.Transport,甚至能把 *http.Request 塞进去。也就是说,你已有的 net/http 体系不用推倒重来。
五、性能与稳定性
很多人会担心”封装这么好,是不是性能拉胯”。实际上 req 的 base 就是 net/http,它不做额外的 goroutine 或反射重活,绝大多数调用只是方法链上的字段赋值。官方也提供了 benchmark 跑分,和裸 net/http 相比在一个数量级。
稳定性方面,项目维护活跃、star 数万级、发布走语义化版本,被不少生产项目采用。作者 imroc 也是 Go 社区里比较活跃的开发者(写过不少高质量的 Go 相关内容)。
六、它适合谁?
- 调第三方 API 的服务:
SetBaseURL+ 重试 + Dump,一天能省一小时。 - 写内部 SDK / 客户端封装:链式 API + Hook + Client 复用,封装出来的东西又薄又好用。
- 脚本和 CLI 工具:一行一请求,比标准库舒服太多。
- 需要排查线上 HTTP 问题的场景:可视化 debug 和 trace 直接救命。
当然,如果你追求极致轻量、连依赖都不想引入,标准库无可替代。但对于绝大多数业务服务,req 的收益远大于它带来的依赖成本。
七、一句话总结
req 是那种”用过就回不去”的库:上手成本几乎为零,功能深度却经常给人惊喜。它把 HTTP 客户端该有的简洁、可观测性、工程化能力都照顾到了,却依然保持了非常小的 API 表面。
如果你还在为每个项目反复手写 http.NewRequest + io.ReadAll + JSON 解析,那真该试一下:
go get github.com/imroc/req/v3
项目地址再放一次:https://github.com/imroc/req
写得好不如用得好,找个接口试一手,你就明白我在说什么了。



还没有评论,来说两句吧...