Go 每日一库之 gentleman

时间  2020-04-10
标签 每日 gentleman 繁體版
原文   原文链接

简介

gentleman是一个功能齐全、插件驱动的 HTTP 客户端。gentleman以扩展性为原则，能够基于内置的或第三方插件建立具备丰富特性的、可复用的 HTTP 客户端。相比标准库net/http，gentleman更灵活、易用。git

快速使用

先安装：程序员

$ go get gopkg.in/h2non/gentleman.v2
复制代码

后使用：github

package main

import (
  "fmt"

  "gopkg.in/h2non/gentleman.v2"
)

func main() {
  cli := gentleman.New()

  cli.URL("https://dog.ceo")

  req := cli.Request()

  req.Path("/api/breeds/image/random")

  req.SetHeader("Client", "gentleman")

  res, err := req.Send()

  if err != nil {
    fmt.Printf("Request error: %vn", err)
    return
  }

  if !res.Ok {
    fmt.Printf("Invalid server response: %dn", res.StatusCode)
    return
  }

  fmt.Printf("Body: %s", res.String())
}
复制代码

gentleman目前有两个版本v1和v2，v2已经稳定，推荐使用，示例中使用的就是v2。gentleman的使用遵循下面的流程：golang

  • 调用gentleman.New()建立一个 HTTP 客户端cli，此cli对象可复用；
  • 调用cli.URL()设置要请求的 URL 基础地址；
  • 调用cli.Request()建立一个请求对象req；
  • 调用req.Path()设置请求的路径，基于前面设置的 URL；
  • 调用req.Header()设置请求首部（Header），上面代码设置首部Client为gentleman；
  • 调用req.Send()发送请求，获取响应对象res；
  • 对响应对象res进行处理。

上面的测试 API 是我从public-apis找的。public-apis是 GitHub 上一个收集各类开放 API 的仓库。本文后面部分的 API 也来自于这个仓库。从https://dog.ceo咱们能够获取各类和狗相关的信息，上面请求的路径/api/breeds/image/random将返回一个随机品种的狗的图片。运行结果：json

Body: {"message":"https://images.dog.ceo/breeds/malamute/n02110063_10567.jpg","status":"success"}
复制代码

因为是随机的，每次运行结果可能都不相同，status为success表示运行成功，message对应的值为图片的 URL。感兴趣本身在浏览器中打开返回的 URL，我获取的图片以下：api

插件

gentleman中的特性不少都是经过插件来实现的。gentleman内置了不少经常使用的插件。若是要实现的特性没法经过内置插件来完成，还有第三方插件可供选择，固然还能够自定义插件！gentleman的插件都是存放在plugins子目录中的，下面介绍几个经常使用的插件。浏览器

body

客户端有时须要发送 JSON、XML 等格式的数据，body插件能够很好地完成这个任务：微信

package main

import (
  "fmt"
  "gopkg.in/h2non/gentleman.v2"
  "gopkg.in/h2non/gentleman.v2/plugins/body"
)

func main() {
  cli := gentleman.New()
  cli.URL("http://httpbin.org/post")

  data := map[string]string{"foo": "bar"}
  cli.Use(body.JSON(data))

  req := cli.Request()
  req.Method("POST")

  res, err := req.Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }

  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  fmt.Printf("Status: %d\n", res.StatusCode)
  fmt.Printf("Body: %s", res.String())
}
复制代码

注意插件的导入方式：import "gopkg.in/h2non/gentleman.v2/plugins/body"。cookie

调用客户端对象cli或请求对象req的Use()方法使用插件。区别在于cli.Use()调用以后，全部经过该cli建立的请求对象都使用该插件，req.Use()只对该请求生效，在本例中使用req.Use(body.JSON(data))也是能够的。上面使用body.JSON()插件，每次发送请求时，都将data转为 JSON 设置到请求体中，并设置相应的首部（Content-Type/Content-Length）。req.Method("POST")设置使用 POST 方法。本次请求使用的 URL http://httpbin.org/post会回显请求的信息，看运行结果：app

Status: 200
Body: {
  "args": {}, 
  "data": "{\"foo\":\"bar\"}\n", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept-Encoding": "gzip", 
    "Content-Length": "14", 
    "Content-Type": "application/json", 
    "Host": "httpbin.org", 
    "User-Agent": "gentleman/2.0.4", 
    "X-Amzn-Trace-Id": "Root=1-5e8dd0c7-ab423c10fb530deade846500"
  }, 
  "json": {
    "foo": "bar"
  }, 
  "origin": "124.77.254.163", 
  "url": "http://httpbin.org/post"
}
复制代码

发送 XML 格式与上面的很是相似：

type User struct {
  Name string `xml:"name"`
  Age  int    `xml:"age"`
}

func main() {
  cli := gentleman.New()
  cli.URL("http://httpbin.org/post")

  req := cli.Request()
  req.Method("POST")

  u := User{Name: "dj", Age: 18}
  req.Use(body.XML(u))
  // ...
}
复制代码

后半部分同样的代码我就省略了，运行结果：

Status: 200
Body: {
  "args": {}, 
  "data": "<User><name>dj</name><age>18</age></User>", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept-Encoding": "gzip", 
    "Content-Length": "41", 
    "Content-Type": "application/xml", 
    "Host": "httpbin.org", 
    "User-Agent": "gentleman/2.0.4", 
    "X-Amzn-Trace-Id": "Root=1-5e8dd339-830dba04536ceef247156746"
  }, 
  "json": null, 
  "origin": "222.64.16.70", 
  "url": "http://httpbin.org/post"
}
复制代码

header

header插件用于在发送请求前添加一些通用的首部，如 APIKey；或者删除一些自动加上的首部，如User-Agent。通常header插件应用在cli对象上：

package main

import (
  "fmt"
  "gopkg.in/h2non/gentleman.v2"
  "gopkg.in/h2non/gentleman.v2/plugins/headers"
)

func main() {
  cli := gentleman.New()
  cli.URL("https://api.thecatapi.com")

  cli.Use(headers.Set("x-api-key", "479ce48d-db30-46a4-b1a0-91ac4c1477b8"))
  cli.Use(headers.Del("User-Agent"))

  req := cli.Request()
  req.Path("/v1/breeds")
  res, err := req.Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  fmt.Printf("Status: %d\n", res.StatusCode)
  fmt.Printf("Body: %s", res.String())
}
复制代码

上面咱们使用了https://api.thecatapi.com，这个 API 能够获取猫的品种信息，支持返回所有品种，搜索，分页等操做。API 使用须要申请 APIKey，我本身申请了一个479ce48d-db30-46a4-b1a0-91ac4c1477b8。thecatapi要求在请求首部中设置x-api-key为咱们申请到的 APIKey。

headers能够很方便的实现这个功能，只须要在cli对象上设置一次便可。另外，gentleman会自动在请求中添加一个User-Agent首部，内容是gentleman的版本信息。细心的童鞋可能已经发现了，在上一节的输出中有User-Agent: gentleman/2.0.4这个首部。在本例中，咱们使用header.Del()删除这个首部。

输出内容太多，我这里就不贴了。

query

HTTP 请求一般会在 URL 的?后带上查询字符串（query string），gentleman的内置插件query能够很好的管理这个信息。咱们能够基于上面代码，给请求带上参数page和limit使之分页返回：

package main

import (
  "fmt"

  "gopkg.in/h2non/gentleman.v2"
  "gopkg.in/h2non/gentleman.v2/plugins/headers"
  "gopkg.in/h2non/gentleman.v2/plugins/query"
)

func main() {
  cli := gentleman.New()
  cli.URL("https://api.thecatapi.com")

  cli.Use(headers.Set("x-api-key", "479ce48d-db30-46a4-b1a0-91ac4c1477b8"))
  cli.Use(query.Set("attach_breed", "beng"))
  cli.Use(query.Set("limit", "2"))
  cli.Use(headers.Del("User-Agent"))

  req := cli.Request()
  req.Path("/v1/breeds")
  req.Use(query.Set("page", "1"))
  res, err := req.Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  fmt.Printf("Status: %d\n", res.StatusCode)
  fmt.Printf("Body: %s", res.String())
}
复制代码

品种和每页显示数量最好仍是在cli对象中设置，每一个请求对象共用：

cli.Use(query.Set("attach_breed", "beng"))
cli.Use(query.Set("limit", "2"))
复制代码

当前请求的页数在req对象上设置：

req.Use(query.Set("page", "1"))
复制代码

其余的代码与上一个示例彻底同样。除了设置query string，还能够经过query.Del()删除某个键值对。

url

路径参数有些时候颇有用，由于咱们在开发中时常会碰到类似的路径，只是中间某个部分不同，例如/info/user/1，/info/book/1等。重复写这些路径不只很枯燥，并且容易出错。因而，偷懒的程序员发明了路径参数，形如/info/:class/1，咱们能够传入参数user或book组成完整的路径。gentleman内置了插件url用来处理路径参数问题：

package main

import (
  "fmt"
  "os"

  "gopkg.in/h2non/gentleman.v2"
  "gopkg.in/h2non/gentleman.v2/plugins/headers"
  "gopkg.in/h2non/gentleman.v2/plugins/url"
)

func main() {
  cli := gentleman.New()
  cli.URL("https://api.thecatapi.com/")

  cli.Use(headers.Set("x-api-key", "479ce48d-db30-46a4-b1a0-91ac4c1477b8"))
  cli.Use(url.Path("/v1/:type"))

  for _, arg := range os.Args[1:] {
    req := cli.Request()
    req.Use(url.Param("type", arg))
    res, err := req.Send()
    if err != nil {
      fmt.Printf("Request error: %s\n", err)
      return
    }
    if !res.Ok {
      fmt.Printf("Invalid server response: %d\n", res.StatusCode)
      return
    }

    fmt.Printf("Status: %d\n", res.StatusCode)
    fmt.Printf("Body: %s\n", res.String())
  }
}
复制代码

thecatapi除了能够获取猫的品种，还有用户投票、各类分类信息。它们的请求路径都差很少，/v1/breeds、/v1/votes、/v1/categories。咱们使用url简化程序编写。上面程序在客户端对象cli上使用插件url.Path("/v1/:type")，调用url.Param("type", arg)用命令行中的参数分别替换type进行 HTTP 请求。运行程序：

$ go run main.go breeds votes categories
复制代码

其余

gentleman内置了将近 20 个插件，有身份认证相关的auth、有cookies、有压缩相关的compression、有代理相关的proxy、有重定向相关的redirect、有超时相关的timeout、有重试的retry、有服务发现的consul等等等等。感兴趣可自行去探索。

自定义

若是内置的和第三方的插件都不能知足咱们的需求，咱们还能够自定义插件。自定义的插件须要实现下面的接口：

// src/gopkg.in/h2non/gentleman.v2/plugin/plugin.go
type Plugin interface {
  Enable()
  Disable()
  Disabled() bool
  Remove()
  Removed() bool
  Exec(string, *context.Context, context.Handler)
}
复制代码

Exec()方法在 HTTP 请求的各个生命周期都会调用，能够在请求前添加一些首部、删除查询字符串，响应返回后进行一些处理等。

经过实现Plugin接口的方式实现插件比较繁琐，且不少插件每每只关注生命周期的某个点，不用处理全部的生命周期事件。gentleman提供了一个Layer结构，能够注册某个生命周期的方法，同时提供NewRequestPlugin/NewResponsePlugin/NewErrorPlugin等便捷函数。

咱们如今来实现一个插件，在请求以前输出一行信息，收到响应以后输出一行信息：

package main

import (
  "fmt"

  "gopkg.in/h2non/gentleman.v2"
  c "gopkg.in/h2non/gentleman.v2/context"
  "gopkg.in/h2non/gentleman.v2/plugin"
)

func main() {
  cli := gentleman.New()
  cli.URL("https://httpbin.org")

  cli.Use(plugin.NewRequestPlugin(func(ctx *c.Context, h c.Handler) {
    fmt.Println("request")

    h.Next(ctx)
  }))

  cli.Use(plugin.NewResponsePlugin(func(ctx *c.Context, h c.Handler) {
    fmt.Println("response")

    h.Next(ctx)
  }))

  req := cli.Request()
  req.Path("/headers")
  res, err := req.Send()
  if err != nil {
    fmt.Printf("Request error: %s\n", err)
    return
  }
  if !res.Ok {
    fmt.Printf("Invalid server response: %d\n", res.StatusCode)
    return
  }

  fmt.Printf("Status: %d\n", res.StatusCode)
  fmt.Printf("Body: %s", res.String())
}
复制代码

因为NewRequestPlugin/NewResponsePlugin这些便利函数，咱们只须要实现一个类型为func(ctx *c.Context, h c.Handler)的函数便可，在ctx中有Request和Response等信息，能够在发起请求前对请求进行一些操做以及得到响应时对响应进行一些操做。上面只是简单地输出信息。

总结

使用gentleman能够实现灵活、便捷的 HTTP 客户端，它提供了丰富的插件，用起来吧~

你们若是发现好玩、好用的 Go 语言库，欢迎到 Go 每日一库 GitHub 上提交 issue😄

参考

  1. gentleman GitHub：github.com/h2non/gentl…
  2. Go 每日一库 GitHub：github.com/darjun/go-d…

我

个人博客：darjun.github.io

欢迎关注个人微信公众号【GoUpUp】，共同窗习，一块儿进步~

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程