admin管理员组

文章数量:819750

Go 每日一库之 resty

简介

resty是 Go 语言的一个 HTTP client 库。resty功能强大,特性丰富。它支持几乎所有的 HTTP 方法(GET/POST/PUT/DELETE/OPTION/HEAD/PATCH等),并提供了简单易用的 API。

快速使用

本文代码使用 Go Modules。

创建目录并初始化:

$ mkdir resty && cd resty
$ go mod init github/darjun/go-daily-lib/resty

安装resty库:

$ go get -u github/go-resty/resty/v2

下面我们来获取百度首页信息:

package mainimport ("fmt""log""github/go-resty/resty/v2"
)func main() {client := resty.New()resp, err := client.R().Get("")if err != nil {log.Fatal(err)}fmt.Println("Response Info:")fmt.Println("Status Code:", resp.StatusCode())fmt.Println("Status:", resp.Status())fmt.Println("Proto:", resp.Proto())fmt.Println("Time:", resp.Time())fmt.Println("Received At:", resp.ReceivedAt())fmt.Println("Size:", resp.Size())fmt.Println("Headers:")for key, value := range resp.Header() {fmt.Println(key, "=", value)}fmt.Println("Cookies:")for i, cookie := range resp.Cookies() {fmt.Printf("cookie%d: name:%s value:%s\n", i, cookie.Name, cookie.Value)}
}

resty使用比较简单。

  • 首先,调用一个resty.New()创建一个client对象;

  • 调用client对象的R()方法创建一个请求对象;

  • 调用请求对象的Get()/Post()等方法,传入参数 URL,就可以向对应的 URL 发送 HTTP 请求了。返回一个响应对象;

  • 响应对象提供很多方法可以检查响应的状态,首部,Cookie 等信息。

上面程序中我们获取了:

  • StatusCode():状态码,如 200;

  • Status():状态码和状态信息,如 200 OK;

  • Proto():协议,如 HTTP/1.1;

  • Time():从发送请求到收到响应的时间;

  • ReceivedAt():接收到响应的时刻;

  • Size():响应大小;

  • Header():响应首部信息,以http.Header类型返回,即map[string][]string

  • Cookies():服务器通过Set-Cookie首部设置的 cookie 信息。

运行程序输出的响应基本信息:

Response Info:
Status Code: 200
Status: 200 OK
Proto: HTTP/1.1
Time: 415.774352ms
Received At: 2021-06-26 11:42:45.307157 +0800 CST m=+0.416547795
Size: 302456

首部信息:

Headers:
Server = [BWS/1.1]
Date = [Sat, 26 Jun 2021 03:42:45 GMT]
Connection = [keep-alive]
Bdpagetype = [1]
Bdqid = [0xf5a61d240003b218]
Vary = [Accept-Encoding Accept-Encoding]
Content-Type = [text/html;charset=utf-8]
Set-Cookie = [BAIDUID=BF2EE47AAAF7A20C6971F1E897ABDD43:FG=1; expires=Thu, 31-Dec-37 23:55:55 GMT; max-age=2147483647; path=/; domain=.baidu BIDUPSID=BF2EE47AAAF7A20C6971F1E897ABDD43; expires=Thu, 31-Dec-37 23:55:55 GMT; max-age=2147483647; path=/; domain=.baidu PSTM=1624678965; expires=Thu, 31-Dec-37 23:55:55 GMT; max-age=2147483647; path=/; domain=.baidu BAIDUID=BF2EE47AAAF7A20C716E90B86906D6B0:FG=1; max-age=31536000; expires=Sun, 26-Jun-22 03:42:45 GMT; domain=.baidu; path=/; version=1; comment=bd BDSVRTM=0; path=/ BD_HOME=1; path=/ H_PS_PSSID=34099_31253_34133_34072_33607_34135_26350; path=/; domain=.baidu]
Traceid = [1624678965045126810617700867425882583576]
P3p = [CP=" OTI DSP COR IVA OUR IND COM " CP=" OTI DSP COR IVA OUR IND COM "]
X-Ua-Compatible = [IE=Edge,chrome=1]

注意其中有一个Set-Cookie首部,这部分内容会出现在 Cookie 部分:

Cookies:
cookie0: name:BAIDUID value:BF2EE47AAAF7A20C6971F1E897ABDD43:FG=1
cookie1: name:BIDUPSID value:BF2EE47AAAF7A20C6971F1E897ABDD43
cookie2: name:PSTM value:1624678965
cookie3: name:BAIDUID value:BF2EE47AAAF7A20C716E90B86906D6B0:FG=1
cookie4: name:BDSVRTM value:0
cookie5: name:BD_HOME value:1
cookie6: name:H_PS_PSSID value:34099_31253_34133_34072_33607_34135_26350

自动 Unmarshal

现在很多网站提供 API 接口,返回结构化的数据,如 JSON/XML 格式等。resty可以自动将响应数据 Unmarshal 到对应的结构体对象中。下面看一个例子,我们知道很多 js 文件都托管在 cdn 上,我们可以通过api.cdnjs/libraries获取这些库的基本信息,返回一个 JSON 数据,格式如下:

接下来,我们定义结构,然后使用resty拉取信息,自动 Unmarshal:

type Library struct {Name   stringLatest string
}type Libraries struct {Results []*Library
}func main() {client := resty.New()libraries := &Libraries{}client.R().SetResult(libraries).Get("")fmt.Printf("%d libraries\n", len(libraries.Results))for _, lib := range libraries.Results {fmt.Println("first library:")fmt.Printf("name:%s latest:%s\n", lib.Name, lib.Latest)break}
}

可以看到,我们只需要创建一个结果类型的对象,然后调用请求对象的SetResult()方法,resty会自动将响应的数据 Unmarshal 到传入的对象中。这里设置请求信息时使用链式调用的方式,即在一行中完成多个设置

运行:

$ go run main.go
4040 libraries
first library:
name:vue latest:.1.2/vue.min.js

一共 4040 个库,第一个就是 Vue✌️。我们请求就能获取 Vue 的详细信息:

感兴趣可自行用resty来拉取这些信息。

一般请求下,resty会根据响应中的Content-Type来推断数据格式。但是有时候响应中无Content-Type首部或与内容格式不一致,我们可以通过调用请求对象的ForceContentType()强制让resty按照特定的格式来解析响应:

client.R().SetResult(result).ForceContentType("application/json")

请求信息

resty提供了丰富的设置请求信息的方法。我们可以通过两种方式设置查询字符串。一种是调用请求对象的SetQueryString()设置我们拼接好的查询字符串:

client.R().SetQueryString("name=dj&age=18").Get(...)

另一种是调用请求对象的SetQueryParams(),传入map[string]string,由resty来帮我们拼接。显然这种更为方便:

client.R().SetQueryParams(map[string]string{"name": "dj","age": "18",}).Get(...)

resty还提供一种非常实用的设置路径参数接口,我们调用SetPathParams()传入map[string]string参数,然后后面的 URL 路径中就可以使用这个map中的键了:

client.R().SetPathParams(map[string]string{"user": "dj",}).Get("/v1/users/{user}/details")

注意,路径中的键需要用{}包起来。

设置首部:

client.R().SetHeader("Content-Type", "application/json").Get(...)

设置请求消息体:

client.R().SetHeader("Content-Type", "application/json").SetBody(`{"name": "dj", "age":18}`).Get(...)

消息体可以是多种类型:字符串,[]byte,对象,map[string]interface{}等。

设置携带Content-Length首部,resty自动计算:

client.R().SetBody(User{Name:"dj", Age:18}).SetContentLength(true).Get(...)

有些网站需要先获取 token,然后才能访问它的 API。设置 token:

client.R().SetAuthToken("youdontknow").Get(...)

案例

最后,我们通过一个案例来将上面介绍的这些串起来。现在我们想通过 GitHub 提供的 API 获取组织的仓库信息,API 文档见文后链接。GitHub API 请求地址为,获取仓库信息的请求格式如下:

GET /orgs/{org}/repos

我们还可以设置以下这些参数:

  • accept首部,这个必填,需要设置为application/vnd.github.v3+json

  • org:组织名,路径参数

  • type:仓库类型,查询参数,例如public/private/forks(fork的仓库)等;

  • sort:仓库的排序规则,查询参数,例如created/updated/pushed/full_name等。默认按创建时间排序;

  • direction:升序asc或降序dsc查询参数

  • per_page:每页多少条目,最大 100,默认 30,查询参数

  • page:当前请求第几页,与per_page一起做分页管理,默认 1,查询参数

GitHub API 必须设置 token 才能访问。登录 GitHub 账号,点开右上角头像,选择Settings

然后,选择Developer settings

选择Personal access tokens,然后点击右上角的Generate new token

填写 Note,表示 token 的用途,这个根据自己情况填写即可。下面复选框用于选择该 token 有哪些权限,这里不需要勾选:

点击下面的Generate token按钮即可生成 token:

注意,这个 token 只有现在能看见,关掉页面下次再进入就无法看到了。所以要保存好,另外不要用我的 token,测试完程序后我会删除 token????。

响应中的 JSON 格式数据如下所示:

字段非常多,为了方便起见,我这里之处理几个字段:

type Repository struct {ID              int        `json:"id"`NodeID          string     `json:"node_id"`Name            string     `json:"name"`FullName        string     `json:"full_name"`Owner           *Developer `json:"owner"`Private         bool       `json:"private"`Description     string     `json:"description"`Fork            bool       `json:"fork"`Language        string     `json:"language"`ForksCount      int        `json:"forks_count"`StargazersCount int        `json:"stargazers_count"`WatchersCount   int        `json:"watchers_count"`OpenIssuesCount int        `json:"open_issues_count"`
}type Developer struct {Login      string `json:"login"`ID         int    `json:"id"`NodeID     string `json:"node_id"`AvatarURL  string `json:"avatar_url"`GravatarID string `json:"gravatar_id"`Type       string `json:"type"`SiteAdmin  bool   `json:"site_admin"`
}

然后使用resty设置路径参数,查询参数,首部,Token 等信息,然后发起请求:

func main() {client := resty.New()var result []*Repositoryclient.R().SetAuthToken("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").SetHeader("Accept", "application/vnd.github.v3+json").SetQueryParams(map[string]string{"per_page":  "3","page":      "1","sort":      "created","direction": "asc",}).SetPathParams(map[string]string{"org": "golang",}).SetResult(&result).Get("/{org}/repos")for i, repo := range result {fmt.Printf("repo%d: name:%s stars:%d forks:%d\n", i+1, repo.Name, repo.StargazersCount, repo.ForksCount)}
}

上面程序拉取以创建时间升序排列的 3 个仓库:

$ go run main.go
repo1: name:gddo stars:1097 forks:289
repo2: name:lint stars:3892 forks:518
repo3: name:glog stars:2738 forks:775

Trace

介绍完resty的主要功能之后,我们再来看看resty提供的一个辅助功能:trace。我们在请求对象上调用EnableTrace()方法启用 trace。启用 trace 可以记录请求的每一步的耗时和其他信息。resty支持链式调用,也就是说我们可以在一行中完成创建请求,启用 trace,发起请求

client.R().EnableTrace().Get("")

在完成请求之后,我们通过调用请求对象的TraceInfo()方法获取信息:

ti := resp.Request.TraceInfo()
fmt.Println("Request Trace Info:")
fmt.Println("DNSLookup:", ti.DNSLookup)
fmt.Println("ConnTime:", ti.ConnTime)
fmt.Println("TCPConnTime:", ti.TCPConnTime)
fmt.Println("TLSHandshake:", ti.TLSHandshake)
fmt.Println("ServerTime:", ti.ServerTime)
fmt.Println("ResponseTime:", ti.ResponseTime)
fmt.Println("TotalTime:", ti.TotalTime)
fmt.Println("IsConnReused:", ti.IsConnReused)
fmt.Println("IsConnWasIdle:", ti.IsConnWasIdle)
fmt.Println("ConnIdleTime:", ti.ConnIdleTime)
fmt.Println("RequestAttempt:", ti.RequestAttempt)
fmt.Println("RemoteAddr:", ti.RemoteAddr.String())

我们可以获取以下信息:

  • DNSLookup:DNS 查询时间,如果提供的是一个域名而非 IP,就需要向 DNS 系统查询对应 IP 才能进行后续操作;

  • ConnTime:获取一个连接的耗时,可能从连接池获取,也可能新建;

  • TCPConnTime:TCP 连接耗时,从 DNS 查询结束到 TCP 连接建立;

  • TLSHandshake:TLS 握手耗时;

  • ServerTime:服务器处理耗时,计算从连接建立到客户端收到第一个字节的时间间隔;

  • ResponseTime:响应耗时,从接收到第一个响应字节,到接收到完整响应之间的时间间隔;

  • TotalTime:整个流程的耗时;

  • IsConnReused:TCP 连接是否复用了;

  • IsConnWasIdle:连接是否是从空闲的连接池获取的;

  • ConnIdleTime:连接空闲时间;

  • RequestAttempt:请求执行流程中的请求次数,包括重试次数;

  • RemoteAddr:远程的服务地址,IP:PORT格式。

resty对这些区分得很细。实际上resty也是使用标准库net/http/httptrace提供的功能,httptrace提供一个结构,我们可以设置各个阶段的回调函数:

// src/net/http/httptrace.go
type ClientTrace struct {GetConn func(hostPort string)GotConn func(GotConnInfo)PutIdleConn func(err error)GotFirstResponseByte func()Got100Continue func()Got1xxResponse func(code int, header textproto.MIMEHeader) error // Go 1.11DNSStart func(DNSStartInfo)DNSDone func(DNSDoneInfo)ConnectStart func(network, addr string)ConnectDone func(network, addr string, err error)TLSHandshakeStart func() // Go 1.8TLSHandshakeDone func(tls.ConnectionState, error) // Go 1.8WroteHeaderField func(key string, value []string) // Go 1.11WroteHeaders func()Wait100Continue func()WroteRequest func(WroteRequestInfo)
}

可以从字段名简单了解回调的含义。resty在启用 trace 后设置了如下回调:

// src/github/go-resty/resty/trace.go
func (t *clientTrace) createContext(ctx context.Context) context.Context {return httptrace.WithClientTrace(ctx,&httptrace.ClientTrace{DNSStart: func(_ httptrace.DNSStartInfo) {t.dnsStart = time.Now()},DNSDone: func(_ httptrace.DNSDoneInfo) {t.dnsDone = time.Now()},ConnectStart: func(_, _ string) {if t.dnsDone.IsZero() {t.dnsDone = time.Now()}if t.dnsStart.IsZero() {t.dnsStart = t.dnsDone}},ConnectDone: func(net, addr string, err error) {t.connectDone = time.Now()},GetConn: func(_ string) {t.getConn = time.Now()},GotConn: func(ci httptrace.GotConnInfo) {t.gotConn = time.Now()t.gotConnInfo = ci},GotFirstResponseByte: func() {t.gotFirstResponseByte = time.Now()},TLSHandshakeStart: func() {t.tlsHandshakeStart = time.Now()},TLSHandshakeDone: func(_ tls.ConnectionState, _ error) {t.tlsHandshakeDone = time.Now()},},)
}

然后在获取TraceInfo时,根据各个时间点计算耗时:

// src/github/go-resty/resty/request.go
func (r *Request) TraceInfo() TraceInfo {ct := r.clientTraceif ct == nil {return TraceInfo{}}ti := TraceInfo{DNSLookup:      ct.dnsDone.Sub(ct.dnsStart),TLSHandshake:   ct.tlsHandshakeDone.Sub(ct.tlsHandshakeStart),ServerTime:     ct.gotFirstResponseByte.Sub(ct.gotConn),IsConnReused:   ct.gotConnInfo.Reused,IsConnWasIdle:  ct.gotConnInfo.WasIdle,ConnIdleTime:   ct.gotConnInfo.IdleTime,RequestAttempt: r.Attempt,}if ct.gotConnInfo.Reused {ti.TotalTime = ct.endTime.Sub(ct.getConn)} else {ti.TotalTime = ct.endTime.Sub(ct.dnsStart)}if !ct.connectDone.IsZero() {ti.TCPConnTime = ct.connectDone.Sub(ct.dnsDone)}if !ct.gotConn.IsZero() {ti.ConnTime = ct.gotConn.Sub(ct.getConn)}if !ct.gotFirstResponseByte.IsZero() {ti.ResponseTime = ct.endTime.Sub(ct.gotFirstResponseByte)}if ct.gotConnInfo.Conn != nil {ti.RemoteAddr = ct.gotConnInfo.Conn.RemoteAddr()}return ti
}

运行输出:

$ go run main.go
Request Trace Info:
DNSLookup: 2.815171ms
ConnTime: 941.635171ms
TCPConnTime: 269.069692ms
TLSHandshake: 669.276011ms
ServerTime: 274.623991ms
ResponseTime: 112.216µs
TotalTime: 1.216276906s
IsConnReused: false
IsConnWasIdle: false
ConnIdleTime: 0s
RequestAttempt: 1
RemoteAddr: 18.235.124.214:443

我们看到 TLS 消耗了近一半的时间。

总结

本文我介绍了 Go 语言一款非常方便易用的 HTTP Client 库。resty提供非常实用的,丰富的 API。链式调用,自动 Unmarshal,请求参数/路径设置这些功能非常方便好用,让我们的工作事半功倍。限于篇幅原因,很多高级特性未能一一介绍,如提交表单,上传文件等等等等。只能留待感兴趣的大家去探索了。

大家如果发现好玩、好用的 Go 语言库,欢迎到 Go 每日一库 GitHub 上提交 issue????

参考

  1. Go 每日一库 GitHub:

  2. resty GitHub:github/go-resty/resty

  3. GitHub API:

我的博客:

欢迎关注我的微信公众号【GoUpUp】,共同学习,一起进步~

本文标签: Go 每日一库之 resty