大俊的博客

关于我

Thu, 08 Mar 2018 21:38:52 +0800

游戏服务端开发，Gopher。
兴趣爱好广泛，喜欢Go，算法等。平时喜欢做 LeetCode 算法题。欢迎关注个人公众号：李子编程（ advance-programming）。

一起用Go来做一个游戏(下)

Wed, 23 Nov 2022 22:39:30 +0000

打包资源

使用file2byteslice包我们可以将图片和config.json文件打包进二进制程序中，之后编译生成一个二进制程序。然后拷贝这一个文件即可，不用再拷贝图片和其他配置文件了。

golang有很多第三方包可以将打包资源，原理其实很简单——读取资源文件的内容，然后生成一个go文件，在这个文件中创建一个变量保存这个文件的二进制内容。

我们将使用ebiten作者编写的file2byteslice包。首先使用go install命令安装它：

`1`	`$ go install github.com/hajimehoshi/file2byteslice`

file2byteslice的命令格式如下：

`1`	`$ file2byteslice -input INPUT_FILE -output OUTPUT_FILE -package PACKAGE_NAME -var VARIABLE_NAME`

故我们可以这样来打包文件：

1
2
3

$ file2byteslice -input ../images/ship.png -output resources/ship.go -package resources -var ShipPng
$ file2byteslice -input ../images/alien.png -output resources/alien.go -package resources -var AlienPng
$ file2byteslice -input config.json -output resources/config.go -package resources -var ConfigJson

生成文件如下：

相应的加载这些文件的代码需要相应的修改：

// alien.go
func NewAlien(cfg *Config) *Alien {
  img, _, err := ebitenutil.NewImageFromReader(bytes.NewReader(resources.AlienPng))
  if err != nil {
    log.Fatal(err)
  }
  // ...
}

// ship.go
func NewShip(screenWidth, screenHeight int) *Ship {
  img, _, err := ebitenutil.NewImageFromReader(bytes.NewReader(resources.ShipPng))
  if err != nil {
    log.Fatal(err)
  }
  // ...
}

// config.go
func loadConfig() *Config {
  var cfg Config
  if err := json.NewDecoder(bytes.NewReader(resources.ConfigJson)).Decode(&cfg); err != nil {
    log.Fatalf("json.Decode failed: %v\n", err)
  }

  return &cfg
}

然后，我们就可以编译成一个游戏二进制程序随意拷贝到其他电脑上运行了：

`1`	`$ go build -o alien_invasion`

go generate

前面先安装file2byteslice程序，然后一个命令一个命令地执行打包，操作起来很是繁琐。如果有文件修改，这个过程又需要来一次。

实际上，我们可以使用go generate让上面的过程更智能一点。在main.go文件中添加如下几行注释：

//go:generate go install github.com/hajimehoshi/file2byteslice
//go:generate mkdir resources
//go:generate file2byteslice -input ../images/ship.png -output resources/ship.go -package resources -var ShipPng
//go:generate file2byteslice -input ../images/alien.png -output resources/alien.go -package resources -var AlienPng
//go:generate file2byteslice -input config.json -output resources/config.go -package resources -var ConfigJson

注意，//和go:generate之间一定不能有空格，一定不能有空格，一定不能有空格，重要的事情说3遍！然后执行下面的命令即可完成安装file2byteslice和打包资源的工作：

`1`	`$ go generate`

让游戏在网页上运行

借助于wasm的强大功能，我们的游戏可以很好地在web上运行！为了让程序能够在网页上运行，我们需要将其编译成wasm。Go内置对wasm的支持。编译方式如下：

`1`	`$ GOOS=js GOARCH=wasm go build -o alien_invasion.wasm`

Go提供的胶水代码，将位于$GOROOT/misc/wasm目录下的wasm_exec.html和wasm_exec.js文件拷贝到我们的项目目录下。注意wasm_exec.html文件中默认是加载名为test.wasm的文件，我们需要将加载文件改为alien_invasion.wasm，或者将生成的文件改名为test.wasm。

然后编写一个简单的web服务器：

package main

import (
  "log"
  "net/http"
)

func main() {
  if err := http.ListenAndServe(":8080", http.FileServer(http.Dir("."))); err != nil {
    log.Fatal(err)
  }
}

运行：

`1`	`$ go run main.go`

打开浏览器输入地址：localhost:8080/wasm_exec.html。

点击run按钮即可愉快地玩耍啦！

项目的不足

到目前为止，我们的游戏基本上可玩，但是还有很多的不足：

没有声音！
外星人没有横向的运动！
分数都没有！

这些有兴趣的童鞋可以自己去实现了😀。

总结

接着上文，本文介绍了如何将资源文件打包进一个二进制程序中，方便相互之间的传播。然后我们不费吹灰之力就将这个游戏移至到了网页之中。

总的来说ebiten是一款简单、易上手的2D游戏开发引擎。对游戏开发感兴趣的童鞋可以使用它来快速开发，引起自己的兴趣。用它来开发一些小游戏也是得心应手，而且自带跨平台功能，十分方便。但是，大型、复杂游戏的开发还是要借助专业的引擎。

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

参考

Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib
ebitengine 官网：https://ebitengine.org/
Python 编程（从入门到实践）：https://book.douban.com/subject/35196328/

我

我的博客：https://darjun.github.io

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

一起用Go来做一个游戏(中)

Fri, 18 Nov 2022 22:39:30 +0000

限制飞船的活动范围

上一篇文章还留了个尾巴，细心的同学应该发现了：飞船可以移动出屏幕！！！现在我们就来限制一下飞船的移动范围。我们规定飞船可以左右超过半个身位，如下图所示：

很容易计算得出，左边位置的x坐标为：

`1`	`x = -W2/2`

右边位置的坐标为：

`1`	`x = W1 - W2/2`

修改input.go的代码如下：

func (i *Input) Update(ship *Ship, cfg *Config) {
  if ebiten.IsKeyPressed(ebiten.KeyLeft) {
    ship.x -= cfg.ShipSpeedFactor
    if ship.x < -float64(ship.width)/2 {
      ship.x = -float64(ship.width) / 2
    }
  } else if ebiten.IsKeyPressed(ebiten.KeyRight) {
    ship.x += cfg.ShipSpeedFactor
    if ship.x > float64(cfg.ScreenWidth)-float64(ship.width)/2 {
      ship.x = float64(cfg.ScreenWidth) - float64(ship.width)/2
    }
  }
}

运行结果如下：

发射子弹

我们不用另外准备子弹的图片，直接画一个矩形就ok。为了可以灵活控制，我们将子弹的宽、高、颜色以及速率都用配置文件来控制：

{
  "bulletWidth": 3,
  "bulletHeight": 15,
  "bulletSpeedFactor": 2,
  "bulletColor": {
    "r": 80,
    "g": 80,
    "b": 80,
    "a": 255
  }
}

新增一个文件bullet.go，定义子弹的结构类型和New方法：

type Bullet struct {
  image       *ebiten.Image
  width       int
  height      int
  x           float64
  y           float64
  speedFactor float64
}

func NewBullet(cfg *Config, ship *Ship) *Bullet {
  rect := image.Rect(0, 0, cfg.BulletWidth, cfg.BulletHeight)
  img := ebiten.NewImageWithOptions(rect, nil)
  img.Fill(cfg.BulletColor)

  return &Bullet{
    image:       img,
    width:       cfg.BulletWidth,
    height:      cfg.BulletHeight,
    x:           ship.x + float64(ship.width-cfg.BulletWidth)/2,
    y:           float64(cfg.ScreenHeight - ship.height - cfg.BulletHeight),
    speedFactor: cfg.BulletSpeedFactor,
  }
}

首先根据配置的宽高创建一个rect对象，然后调用ebiten.NewImageWithOptions创建一个*ebiten.Image对象。

子弹都是从飞船头部发出的，所以它的横坐标等于飞船中心的横坐标，左上角的纵坐标=屏幕高度-飞船高-子弹高。

随便增加子弹的绘制方法：

func (bullet *Bullet) Draw(screen *ebiten.Image) {
  op := &ebiten.DrawImageOptions{}
  op.GeoM.Translate(bullet.x, bullet.y)
  screen.DrawImage(bullet.image, op)
}

我们在Game对象中增加一个map来管理子弹：

type Game struct {
  // -------省略-------
  bullets map[*Bullet]struct{}
}

func NewGame() *Game {
  return &Game{
    // -------省略-------
    bullets: make(map[*Bullet]struct{}),
  }
}

然后在Draw方法中，我们需要将子弹也绘制出来：

func (g *Game) Draw(screen *ebiten.Image) {
  screen.Fill(g.cfg.BgColor)
  g.ship.Draw(screen)
  for bullet := range g.bullets {
    bullet.Draw(screen)
  }
}

子弹位置如何更新呢？在Game.Update中更新，与飞船类似，只是飞船只能水平移动，而子弹只能垂直移动。

func (g *Game) Update() error {
  for bullet := range g.bullets {
    bullet.y -= bullet.speedFactor
  }
  // -------省略-------
}

子弹的更新、绘制逻辑都完成了，可是我们还没有子弹！现在我们就来实现按空格发射子弹的功能。我们需要在Input.Update方法中判断空格键是否按下，由于该方法需要访问Game对象的多个字段，干脆传入Game对象：

func (i *Input) Update(g *Game) {
  if ebiten.IsKeyPressed(ebiten.KeyLeft) {
    // -------省略-------
  } else if ebiten.IsKeyPressed(ebiten.KeyRight) {
    // -------省略-------
  } else if ebiten.IsKeyPressed(ebiten.KeySpace) {
    bullet := NewBullet(g.cfg, g.ship)
    g.addBullet(bullet)
  }
}

给Game对象增加一个addBullet方法：

1
2
3

func (g *Game) addBullet(bullet *Bullet) {
  g.bullets[bullet] = struct{}{}
}

目前有两个问题：

无法一边移动一边发射，仔细看看Input.Update方法中的代码，你能发现什么问题吗？
子弹太多了，我们想要限制子弹的数量。

下面来逐一解决这些问题。

第一个问题很好解决，因为在KeyLeft/KeyRight/KeySpace这三个判断中我们用了if-else。这样会优先处理移动的操作。将KeySpace移到一个单独的if中即可：

func (i *Input) Update(g *Game) {
  // -------省略-------
  if ebiten.IsKeyPressed(ebiten.KeySpace) {
    bullet := NewBullet(g.cfg, g.ship)
    g.addBullet(bullet)
  }
}

第二个问题，在配置中，增加同时最多存在的子弹数：

1
2
3

{
  "maxBulletNum": 10
}

1
2
3

type Config struct {
  MaxBulletNum      int        `json:"maxBulletNum"`
}

然后我们在Input.Update方法中判断，如果目前存在的子弹数小于MaxBulletNum才能创建新的子弹：

if ebiten.IsKeyPressed(ebiten.KeySpace) {
  if len(g.bullets) < cfg.MaxBulletNum {
    bullet := NewBullet(g.cfg, g.ship)
    g.addBullet(bullet)
  }
}

再次运行：

数量好像被限制了，但是不是我们配置的10。原来Input.Update()的调用间隔太短了，导致我们一次space按键会发射多个子弹。我们可以控制两个子弹之间的时间间隔。同样用配置文件来控制（单位毫秒）：

1
2
3

{
  "bulletInterval": 50
}

1
2
3

type Config struct {
  BulletInterval    int64      `json:"bulletInterval"`
}

在Input结构中增加一个lastBulletTime字段记录上次发射子弹的时间：

1
2
3

type Input struct {
  lastBulletTime time.Time
}

距离上次发射子弹的时间大于BulletInterval毫秒，才能再次发射，发射成功之后更新时间：

func (i *Input) Update(g *Game) {
  // -------省略-------
  if ebiten.IsKeyPressed(ebiten.KeySpace) {
    if len(g.bullets) < g.cfg.MaxBulletNum &&
      time.Now().Sub(i.lastBulletTime).Milliseconds() > g.cfg.BulletInterval {
      bullet := NewBullet(g.cfg, g.ship)
      g.addBullet(bullet)
      i.lastBulletTime = time.Now()
    }
  }
}

运行：

又出现了一个问题，10个子弹飞出屏幕外之后还是不能发射子弹。我们需要把离开屏幕的子弹删除。这适合在Game.Update函数中做：

func (g *Game) Update() error {
  g.input.Update(g)
  for bullet := range g.bullets {
    if bullet.outOfScreen() {
      delete(g.bullets, bullet)
    }
  }
  return nil
}

为了Bullet添加判断是否处于屏幕外的方法：

1
2
3

func (bullet *Bullet) outOfScreen() bool {
  return bullet.y < -float64(bullet.height)
}

再次运行：

外星人来了

外星人图片如下：

同飞船一样，编写Alien类，添加绘制自己的方法：

type Alien struct {
  image       *ebiten.Image
  width       int
  height      int
  x           float64
  y           float64
  speedFactor float64
}

func NewAlien(cfg *Config) *Alien {
  img, _, err := ebitenutil.NewImageFromFile("../images/alien.png")
  if err != nil {
    log.Fatal(err)
  }

  width, height := img.Size()
  return &Alien{
    image:       img,
    width:       width,
    height:      height,
    x:           0,
    y:           0,
    speedFactor: cfg.AlienSpeedFactor,
  }
}

func (alien *Alien) Draw(screen *ebiten.Image) {
  op := &ebiten.DrawImageOptions{}
  op.GeoM.Translate(alien.x, alien.y)
  screen.DrawImage(alien.image, op)
}

游戏开始时需要创建一组外星人，计算一行可以容纳多少个外星人，考虑到左右各留一定的空间，两个外星人之间留一点空间。在游戏一开始就创建一组外星人：

type Game struct {
  // Game结构中的map用来存储外星人对象
  aliens  map[*Alien]struct{}
}

func NewGame() *Game {
  g := &Game{
    // 创建map
    aliens:  make(map[*Alien]struct{}),
  }
  // 调用 CreateAliens 创建一组外星人
  g.CreateAliens()
  return g
}

func (g *Game) CreateAliens() {
  alien := NewAlien(g.cfg)

  availableSpaceX := g.cfg.ScreenWidth - 2*alien.width
  numAliens := availableSpaceX / (2 * alien.width)

  for i := 0; i < numAliens; i++ {
    alien = NewAlien(g.cfg)
    alien.x = float64(alien.width + 2*alien.width*i)
    g.addAlien(alien)
  }
}

左右各留一个外星人宽度的空间：

`1`	`availableSpaceX := g.cfg.ScreenWidth - 2*alien.width`

然后，两个外星人之间留一个外星人宽度的空间。所以一行可以创建的外星人的数量为：

`1`	`numAliens := availableSpaceX / (2 * alien.width)`

创建一组外星人，依次排列。

同样地，我们需要在Game.Draw方法中添加绘制外星人的代码：

func (g *Game) Draw(screen *ebiten.Image) {
  // -------省略-------
  for alien := range g.aliens {
    alien.Draw(screen)
  }
}

运行：

再创建两行：

func (g *Game) CreateAliens() {
  // -------省略-------
  for row := 0; row < 2; row++ {
    for i := 0; i < numAliens; i++ {
      alien = NewAlien(g.cfg)
      alien.x = float64(alien.width + 2*alien.width*i)
      alien.y = float64(alien.height*row) * 1.5
      g.addAlien(alien)
    }
  }
}

让外星人都起来，同样地还是在Game.Update方法中更新位置：

func (g *Game) Update() error {
  // -------省略-------
  for alien := range g.aliens {
    alien.y += alien.speedFactor
  }
  // -------省略-------
}

射击！！

当前子弹碰到外星人直接穿过去了，我们希望能击杀外星人。这需要检查子弹和外星人之间的碰撞。我们新增一个文件collision.go，并编写检查子弹与外星人是否碰撞的函数。这里我采用最直观的碰撞检测方法，即子弹的4个顶点只要有一个位于外星人矩形中，就认为它们碰撞。

// CheckCollision 检查子弹和外星人之间是否有碰撞
func CheckCollision(bullet *Bullet, alien *Alien) bool {
  alienTop, alienLeft := alien.y, alien.x
  alienBottom, alienRight := alien.y+float64(alien.height), alien.x+float64(alien.width)
  // 左上角
  x, y := bullet.x, bullet.y
  if y > alienTop && y < alienBottom && x > alienLeft && x < alienRight {
    return true
  }

  // 右上角
  x, y = bullet.x+float64(bullet.width), bullet.y
  if y > alienTop && y < alienBottom && x > alienLeft && x < alienRight {
    return true
  }

  // 左下角
  x, y = bullet.x, bullet.y+float64(bullet.height)
  if y > alienTop && y < alienBottom && x > alienLeft && x < alienRight {
    return true
  }

  // 右下角
  x, y = bullet.x+float64(bullet.width), bullet.y+float64(bullet.height)
  if y > alienTop && y < alienBottom && x > alienLeft && x < alienRight {
    return true
  }

  return false
}

接着我们在Game.Update方法中调用这个方法，并且将碰撞的子弹和外星人删除。

func (g *Game) CheckCollision() {
  for alien := range g.aliens {
    for bullet := range g.bullets {
      if CheckCollision(bullet, alien) {
        delete(g.aliens, alien)
        delete(g.bullets, bullet)
      }
    }
  }
}

func (g *Game) Update() error {
  // -------省略-------

  g.CheckCollision()

  // -------省略-------
  return nil
}

注意将碰撞检测放在位置更新之后。运行：

增加主界面和结束界面

现在一旦运行程序，外星人们就开始运动了。我们想要增加一个按下空格键才开始的功能，并且游戏结束之后，我们也希望能显示一个Game Over的界面。首先，我们定义几个常量，表示游戏当前所处的状态：

const (
  ModeTitle Mode = iota
  ModeGame
  ModeOver
)

Game结构中需要增加mode字段表示当前游戏所处的状态：

type Game struct {
  mode    Mode
  // ...
}

为了显示开始界面，涉及到文字的显示，文字显示和字体处理起来都比较麻烦。ebitengine内置了一些字体，我们可以据此创建几个字体对象：

var (
  titleArcadeFont font.Face
  arcadeFont      font.Face
  smallArcadeFont font.Face
)

func (g *Game) CreateFonts() {
  tt, err := opentype.Parse(fonts.PressStart2P_ttf)
  if err != nil {
    log.Fatal(err)
  }
  const dpi = 72
  titleArcadeFont, err = opentype.NewFace(tt, &opentype.FaceOptions{
    Size:    float64(g.cfg.TitleFontSize),
    DPI:     dpi,
    Hinting: font.HintingFull,
  })
  if err != nil {
    log.Fatal(err)
  }
  arcadeFont, err = opentype.NewFace(tt, &opentype.FaceOptions{
    Size:    float64(g.cfg.FontSize),
    DPI:     dpi,
    Hinting: font.HintingFull,
  })
  if err != nil {
    log.Fatal(err)
  }
  smallArcadeFont, err = opentype.NewFace(tt, &opentype.FaceOptions{
    Size:    float64(g.cfg.SmallFontSize),
    DPI:     dpi,
    Hinting: font.HintingFull,
  })
  if err != nil {
    log.Fatal(err)
  }
}

fonts.PressStart2P_ttf就是ebitengine提供的字体。创建字体的方法一般在需要的时候微调即可。将创建外星人和字体封装在Game的init方法中：

func (g *Game) init() {
  g.CreateAliens()
  g.CreateFonts()
}

func NewGame() *Game {
  // ...
  g.init()
  return g
}

启动时游戏处于ModeTitle状态，处于ModeTitle和ModeOver时只需要在屏幕上显示一些文字即可。只有在ModeGame状态才需要显示飞船和外星人：

func (g *Game) Draw(screen *ebiten.Image) {
  screen.Fill(g.cfg.BgColor)

  var titleTexts []string
  var texts []string
  switch g.mode {
  case ModeTitle:
    titleTexts = []string{"ALIEN INVASION"}
    texts = []string{"", "", "", "", "", "", "", "PRESS SPACE KEY", "", "OR LEFT MOUSE"}
  case ModeGame:
    g.ship.Draw(screen)
    for bullet := range g.bullets {
      bullet.Draw(screen)
    }
    for alien := range g.aliens {
      alien.Draw(screen)
    }
  case ModeOver:
    texts = []string{"", "GAME OVER!"}
  }

  for i, l := range titleTexts {
    x := (g.cfg.ScreenWidth - len(l)*g.cfg.TitleFontSize) / 2
    text.Draw(screen, l, titleArcadeFont, x, (i+4)*g.cfg.TitleFontSize, color.White)
  }
  for i, l := range texts {
    x := (g.cfg.ScreenWidth - len(l)*g.cfg.FontSize) / 2
    text.Draw(screen, l, arcadeFont, x, (i+4)*g.cfg.FontSize, color.White)
  }
}

在Game.Update方法中，我们判断在ModeTitle状态下按下空格，鼠标左键游戏开始，切换为ModeGame状态。游戏结束时切换为GameOver状态，在GameOver状态后按下空格或鼠标左键即重新开始游戏。

func (g *Game) Update() error {
  switch g.mode {
  case ModeTitle:
    if g.input.IsKeyPressed() {
      g.mode = ModeGame
    }
  case ModeGame:
    for bullet := range g.bullets {
      bullet.y -= bullet.speedFactor
    }

    for alien := range g.aliens {
      alien.y += alien.speedFactor
    }

    g.input.Update(g)

    g.CheckCollision()

    for bullet := range g.bullets {
      if bullet.outOfScreen() {
        delete(g.bullets, bullet)
      }
    }
  case ModeOver:
    if g.input.IsKeyPressed() {
      g.init()
      g.mode = ModeTitle
    }
  }

  return nil
}

input.go中增加IsKeyPressed方法判断是否有空格或鼠标左键按下。

判断游戏胜负

我们规定如果击杀所有外星人则游戏胜利，有3个外星人移出屏幕外或者碰撞到飞船则游戏失败。

首先增加一个字段failCount用于记录移出屏幕外的外星人数量和与飞船碰撞的外星人数量之和：

type Game struct {
  // -------省略-------
  failCount int // 被外星人碰撞和移出屏幕的外星人数量之和
}

然后我们在Game.Update方法中检测外星人是否移出屏幕，以及是否与飞船碰撞：

for alien := range g.aliens {
  if alien.outOfScreen(g.cfg) {
    g.failCount++
    delete(g.aliens, alien)
    continue
  }

  if CheckCollision(alien, g.ship) {
    g.failCount++
    delete(g.aliens, alien)
    continue
  }
}

这里有一个问题，还记得吗？我们前面编写的CheckCollision函数接受的参数类型是*Alien和*Bullet，这里我们需要重复编写接受参数为*Ship和*Alien的函数吗？不用！

我们将表示游戏中的实体对象抽象成一个GameObject结构：

type GameObject struct {
  width  int
  height int
  x      float64
  y      float64
}

func (gameObj *GameObject) Width() int {
  return gameObj.width
}

func (gameObj *GameObject) Height() int {
  return gameObj.height
}

func (gameObj *GameObject) X() float64 {
  return gameObj.x
}

func (gameObj *GameObject) Y() float64 {
  return gameObj.y
}

然后定义一个接口Entity：

type Entity interface {
  Width() int
  Height() int
  X() float64
  Y() float64
}

最后让我们游戏中的实体内嵌这个GameObject对象，即可自动实现Entity接口：

type Alien struct {
  GameObject
  image       *ebiten.Image
  speedFactor float64
}

这样CheckCollision即可改为接受两个Entity接口类型的参数：

// CheckCollision 两个物体之间是否碰撞
func CheckCollision(entityA, entityB Entity) bool {
  top, left := entityA.Y(), entityA.X()
  bottom, right := entityA.Y()+float64(entityA.Height()), entityA.X()+float64(entityA.Width())
  // 左上角
  x, y := entityB.X(), entityB.Y()
  if y > top && y < bottom && x > left && x < right {
    return true
  }

  // 右上角
  x, y = entityB.X()+float64(entityB.Width()), entityB.Y()
  if y > top && y < bottom && x > left && x < right {
    return true
  }

  // 左下角
  x, y = entityB.X(), entityB.Y()+float64(entityB.Height())
  if y > top && y < bottom && x > left && x < right {
    return true
  }

  // 右下角
  x, y = entityB.X()+float64(entityB.Width()), entityB.Y()+float64(entityB.Height())
  if y > top && y < bottom && x > left && x < right {
    return true
  }

  return false
}

如果游戏失败则切换为ModeOver模式，屏幕上显示"Game Over!"。如果游戏胜利，则显示"You Win!"：

if g.failCount >= 3 {
  g.overMsg = "Game Over!"
} else if len(g.aliens) == 0 {
  g.overMsg = "You Win!"
}

if len(g.overMsg) > 0 {
  g.mode = ModeOver
  g.aliens = make(map[*Alien]struct{})
  g.bullets = make(map[*Bullet]struct{})
}

注意，为了下次游戏能顺序进行，这里需要清楚所有的子弹和外星人。运行：

总结

本文接着上篇文章，介绍了发射子弹，检测碰撞，增加主界面和游戏结束界面等内容。至此一个简答的游戏就做出来了。可以看出使用ebitengine做一个游戏还是很简单的，非常推荐尝试呢！上手之后，建议看看官方仓库examples目录中的示例，会非常有帮助。

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

参考

Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib
ebitengine 官网：https://ebitengine.org/
Python 编程（从入门到实践）：https://book.douban.com/subject/35196328/

我

我的博客：https://darjun.github.io

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

一起用Go来做一个游戏(上)

Tue, 15 Nov 2022 22:39:30 +0000

引子

最近偶然看到一个Go语言库，口号喊出“一个超级简单（dead simple）的2D游戏引擎”，好奇点开了它的官网。

官网上已经有很多可以在线体验的小游戏了（利用WASM技术）。例如曾经风靡一时的2048：

当然只要安装了Go，我们也键入下面的命令本地运行这个游戏：

`1`	`$ go run -tags=example github.com/hajimehoshi/ebiten/v2/examples/2048@latest`

还有童年《俄罗斯方块》：

有14年左右让无数人疯狂的《Flappy Bird》（或许称为Flappy Gopher更贴切一点😀）：

这些瞬间让我产生了极大的兴趣。简单浏览一下文档，整体感觉下来，虽然与成熟的游戏引擎（如Cocos2dx，DirectX，Unity3d等）相比，ebiten功能还不算丰富。但是麻雀虽小，五脏俱全。ebiten的API设计比较简单，使用也很方便，即使对于新手也可以在1-2个小时内掌握，并开发出一款简单的游戏。更妙的是，Go语言让ebitengine实现了跨平台！

接下来的3篇文章，我会介绍ebitengine这个库。对于游戏引擎来说，只介绍它的API用法似乎有点纸上谈兵。恰好我想起之前看到一个《外星人入侵》的小游戏，刚好可以拿来练手。那请大家坐稳扶好，我们出发咯。

安装

ebitengine 要求Go版本 >= 1.15。使用go module下载这个包：

`1`	`$ go get -u github.com/hajimehoshi/ebiten/v2`

显示窗口

游戏开发第一步是将游戏窗口显示出来，并且能在窗口上显示一些文字。先看代码：

package main

import (
  "log"

  "github.com/hajimehoshi/ebiten/v2"
  "github.com/hajimehoshi/ebiten/v2/ebitenutil"
)

type Game struct{}

func (g *Game) Update() error {
  return nil
}

func (g *Game) Draw(screen *ebiten.Image) {
  ebitenutil.DebugPrint(screen, "Hello, World")
}

func (g *Game) Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int) {
  return 320, 240
}

func main() {
  ebiten.SetWindowSize(640, 480)
  ebiten.SetWindowTitle("外星人入侵")
  if err := ebiten.RunGame(&Game{}); err != nil {
    log.Fatal(err)
  }
}

使用命令go run运行该程序：

`1`	`$ go run main.go`

我们会看到一个窗口，标题为外星人入侵，并且左上角显示了文字Hello，World：

现在我们来分析使用ebiten开发的游戏程序的结构。

首先，ebiten引擎运行时要求传入一个游戏对象，该对象的必须实现ebiten.Game这个接口：

// Game defines necessary functions for a game.
type Game interface {
  Update() error
  Draw(screen *Image)
  Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int)
}

ebiten.Game接口定义了ebiten游戏需要的3个方法：Update,Draw和Layout。

Update：每个tick都会被调用。tick是引擎更新的一个时间单位，默认为1/60s。tick的倒数我们一般称为帧，即游戏的更新频率。默认ebiten游戏是60帧，即每秒更新60次。该方法主要用来更新游戏的逻辑状态，例如子弹位置更新。上面的例子中，游戏对象没有任何状态，故Update方法为空。注意到Update方法的返回值为error类型，当Update方法返回一个非空的error值时，游戏停止。在上面的例子中，我们一直返回nil，故只有关闭窗口时游戏才停止。
Draw：每帧（frame）调用。帧是渲染使用的一个时间单位，依赖显示器的刷新率。如果显示器的刷新率为60Hz，Draw将会每秒被调用60次。Draw接受一个类型为*ebiten.Image的screen对象。ebiten引擎每帧会渲染这个screen。在上面的例子中，我们调用ebitenutil.DebugPrint函数在screen上渲染一条调试信息。由于调用Draw方法前，screen会被重置，故DebugPrint每次都需要调用。
Layout：该方法接收游戏窗口的尺寸作为参数，返回游戏的逻辑屏幕大小。我们实际上计算坐标是对应这个逻辑屏幕的，Draw将逻辑屏幕渲染到实际窗口上。这个时候可能会出现伸缩。在上面的例子中游戏窗口大小为(640, 480)，Layout返回的逻辑大小为(320, 240)，所以显示会放大1倍。

在main函数中，

`1`	`ebiten.SetWindowSize(640, 480)`

设置游戏窗口的大小。

而

`1`	`ebiten.SetWindowTitle("外星人入侵")`

设置窗口标题，标题显示在窗口的左上角。

一切准备就绪，创建一个Game对象，调用ebiten.RunGame()运行。是不是很简单？

处理输入

没有交互的游戏不是真的游戏！下面我们来监听键盘的输入，当前只处理3个键：左方向←，右方向→和空格。

ebiten提供函数IsKeyPressed来判断某个键是否按下，同时内置了100多个键的常量定义，见源码keys.go文件。ebiten.KeyLeft表示左方向键，ebiten.KeyRight表示右方向键，ebiten.KeySpace表示空格。

为了代码清晰，我们定义一个Input结构来处理输入：

type Input struct {
  msg string
}

func (i *Input) Update() {
  if ebiten.IsKeyPressed(ebiten.KeyLeft) {
    fmt.Println("←←←←←←←←←←←←←←←←←←←←←←←")
    i.msg = "left pressed"
  } else if ebiten.IsKeyPressed(ebiten.KeyRight) {
    fmt.Println("→→→→→→→→→→→→→→→→→→→→→→→")
    i.msg = "right pressed"
  } else if ebiten.IsKeyPressed(ebiten.KeySpace) {
    fmt.Println("-----------------------")
    i.msg = "space pressed"
  }
}

Game结构中添加一个Input类型的字段，并且为了方便新增NewGame方法用于创建Game对象：

type Game struct {
  input *Input
}

func NewGame() *Game {
  return &Game{
    input: &Input{msg: "Hello, World!"},
  }
}

Game结构的Update方法中，我们需要调用Input的Update方法触发按键的判断：

func (g *Game) Update() error {
  g.input.Update()
  return nil
}

Game的Draw方法中将显示Input的msg字段：

1
2
3

func (g *Game) Draw(screen *ebiten.Image) {
  ebitenutil.DebugPrint(screen, g.input.msg)
}

将main函数中创建Game对象的方式修改如下：

game := NewGame()

if err := ebiten.RunGame(game); err != nil {
  log.Fatal(err)
}

使用go run命令运行：

`1`	`$ go run main.go`

窗口与前一个例子相同，然而我们可以在窗口上按←→和空格，观察控制台输出：

设置背景

黑色背景看起来有些无趣，我们现在就来换一个背景。

func (g *Game) Draw(screen *ebiten.Image) {
  screen.Fill(color.RGBA{R: 200, G: 200, B: 200, A: 255})
  ebitenutil.DebugPrint(screen, g.input.msg)
}

ebiten.Image定义了一个名为Fill的方法，可以传入一个颜色对象color.RGBA，将背景填充为特定颜色。Draw函数的参数为*ebiten.Image类型，它表示的是屏幕对象，ebitengine引擎最终会将screen显示出来，故填充它的背景即可修改窗口的背景。代码中我们将背景颜色修改为灰色(R:200,G:200,B:200)。

注意：由于每帧都会调用Draw方法刷新屏幕内容，所以每次调用都需要填充背景。

运行结果如下：

第一次重构

目前为止，我们的实现了显示窗口和处理输入的功能。我们先分析一下目前的程序有哪些问题：

所有逻辑都堆在一个文件中，修改不便
逻辑中直接出现字面值，例如640/480，字符串"外星人入侵"等，每次修改都需要重新编译程序

在继续之前，我们先对代码组织结构做一次重构，这能让我们走得更远。

为了清晰，方便管理，我们逻辑拆分到4个文件中：

game.go：编写Game对象，并实现相关方法，同时负责协调其他各个模块
input.go：输入相关的逻辑
config.go：专门负责配置相关的逻辑
main.go：main函数，负责创建Game对象，运行游戏

为了程序的灵活修改，我们将程序中的可变项都作为配置存放在文件中，程序启动时自动读取这个配置文件。我选择json作为配置文件的格式：

{
  "screenWidth": 640,
  "screenHeight": 480,
  "title": "外星人入侵",
  "bgColor": {
    "r": 230,
    "g": 230,
    "b": 230,
    "a": 255
  }
}

然后定义配置的结构和加载配置的函数：

type Config struct {
    ScreenWidth  int        `json:"screenWidth"`
    ScreenHeight int        `json:"screenHeight"`
    Title        string     `json:"title"`
    BgColor      color.RGBA `json:"bgColor"`
}

func loadConfig() *Config {
    f, err := os.Open("./config.json")
    if err != nil {
        log.Fatalf("os.Open failed: %v\n", err)
    }

    var cfg Config
    err = json.NewDecoder(f).Decode(&cfg)
    if err != nil {
    log.Fatalf("json.Decode failed: %v\n", err)
}

    return &cfg
}

将游戏核心逻辑移到game.go文件中，定义游戏对象结构和创建游戏对象的方法：

type Game struct {
  input *Input
  cfg   *Config
}

func NewGame() *Game {
  cfg := loadConfig()
  ebiten.SetWindowSize(cfg.ScreenWidth, cfg.ScreenHeight)
  ebiten.SetWindowTitle(cfg.Title)

  return &Game{
    input: &Input{},
    cfg:   cfg,
  }
}

先从配置文件中加载配置，然后根据配置设置游戏窗口大小和标题。拆分之后，Draw和Layout方法实现如下：

func (g *Game) Draw(screen *ebiten.Image) {
  ebitenutil.DebugPrint(screen, "Hello, World!")
  screen.Fill(g.cfg.BgColor)
}

func (g *Game) Layout(outsideWidth, outsideHeight int) (screenWidth, screenHeight int) {
  return g.cfg.ScreenWidth / 2, g.cfg.ScreenHeight / 2
}

第一次重构到此完成，现在来看一下文件结构，是否更清晰了呢？

├── config.go
├── config.json
├── game.go
├── input.go
└── main.go

注意，因为拆分成了多个文件，所以运行程序不能再使用go run main.go命令了，需要改为go run .。

显示图片

接下来我们尝试在屏幕底部中心位置显示一张飞船的图片：

ebitengine引擎提供了ebitenutil.NewImageFromFile函数，传入图片路径即可加载该图片，so easy。为了很好的管理游戏中的各个实体，我们给每个实体都定义一个结构。先定义飞船结构：

import (
    _ "golang.org/x/image/bmp"
)

type Ship struct {
  image  *ebiten.Image
  width  int
  height int
}

func NewShip() *Ship {
  img, _, err := ebitenutil.NewImageFromFile("../images/ship.bmp")
  if err != nil {
    log.Fatal(err)
  }

  width, height := img.Size()
  ship := &Ship{
    image:  img,
    width:  width,
    height: height,
  }

  return ship
}

我提供了两种图片格式，一种是png，一种是bmp，用哪种都可以。注意，需要将对应的图片解码包导入。Go标准库提供了三种格式的解码包，image/png，image/jpeg，image/gif。也就是说标准库中没有bmp格式的解码包，所幸golang.org/x仓库没有让我们失望，golang.org/x/image/bmp提供了解析bmp格式图片的功能。我们这里不需要显式的使用对应的图片库，故使用import _这种方式，让init函数产生副作用。

然后在游戏对象中添加飞船类型的字段：

func NewGame() *Game {
  // 相同的代码省略...
  return &Game {
    input:   &Input{},
    ship:  NewShip(),
    cfg:  cfg,
  }
}

为了将飞船显示在屏幕底部中央位置，我们需要计算坐标。ebitengine采用如下所示的二维坐标系：

x轴向右，y轴向下，左上角为原点。我们需要计算飞船左上角的位置。由上图很容易计算出：

1
2

x=(W1-W2)/2
y=H1-H2

为了在屏幕上显示飞船图片，我们需要调用*ebiten.Image的DrawImage方法，该方法的第二个参数可以用于指定坐标相对于原点的偏移：

func (g *Game) Draw(screen *ebiten.Image) {
  screen.Fill(g.cfg.BgColor)
  op := &ebiten.DrawImageOptions{}
  op.GeoM.Translate(float64(g.cfg.ScreenWidth-g.ship.width)/2, float64(g.cfg.ScreenHeight-g.ship.height))
  screen.DrawImage(g.ship.image, op)
}

我们给Ship类型增加一个绘制自身的方法，传入屏幕对象screen和配置，让代码更好维护：

func (ship *Ship) Draw(screen *ebiten.Image, cfg *Config) {
    op := &ebiten.DrawImageOptions{}
    op.GeoM.Translate(float64(cfg.ScreenWidth-ship.width)/2, float64(cfg.ScreenHeight-ship.height))
    screen.DrawImage(ship.image, op)
}

这样游戏对象中的Draw方法就可以简化为：

func (g *Game) Draw(screen *ebiten.Image) {
    screen.Fill(g.cfg.BgColor)
    g.ship.Draw(screen, g.cfg)
}

运行：

移动飞船

现在我们来实现使用左右方向键来控制飞船的移动。首先给飞船的类型增加x/y坐标字段：

type Ship struct {
    // 与前面的代码一样
    x float64 // x坐标
    y float64 // y坐标
}

我们前面已经计算出飞船位于屏幕底部中心时的坐标，在创建飞船时将该坐标赋给xy：

func NewShip(screenWidth, screenHeight int) *Ship {
  ship := &Ship{
    // ...
    x: float64(screenWidth-width) / 2,
    y: float64(screenHeight - height),
  }

  return ship
}

由于NewShip计算初始坐标需要屏幕尺寸，故增加屏幕宽、高两个参数，由NewGame方法传入：

func NewGame() *Game {
  // 与上面的代码一样

  return &Game{
    input: &Input{},
    ship:  NewShip(cfg.ScreenWidth, cfg.ScreenHeight),
    cfg:   cfg,
  }
}

然后我们在Input的Update方法中根据按下的是左方向键还是右方向键来更新飞船的坐标：

type Input struct{}

func (i *Input) Update(ship *Ship) {
  if ebiten.IsKeyPressed(ebiten.KeyLeft) {
    ship.x -= 1
  } else if ebiten.IsKeyPressed(ebiten.KeyRight) {
    ship.x += 1
  }
}

由于需要修改飞船坐标，Game.Update方法调用Input.Update时需要传入飞船对象：

func (g *Game) Update() error {
  g.input.Update(g.ship)
  return nil
}

好了，现在可以运行程序了go run .，效果如下：

注意到，目前有两个问题：

移动太慢
可以移出屏幕

因为现在每次只对x坐标修改1个像素位置，故而显得太慢。我们可以在增加一个飞船速度的配置项来控制每次变化的像素数：

{
  "screenWidth": 640,
  "screenHeight": 480,
  "title": "外星人入侵",
  "bgColor": {
    "r": 230,
    "g": 230,
    "b": 230,
    "a": 255
  },
  "shipSpeedFactor": 3
}

config.go需要相应的修改：

type Config struct {
    // 一样的代码
    ShipSpeedFactor float64    `json:"shipSpeedFactor"`
}

修改Input.Update方法，每次更新ShipSpeedFactor个像素：

func (i *Input) Update(ship *Ship, cfg *Config) {
  if ebiten.IsKeyPressed(ebiten.KeyLeft) {
    ship.x -= cfg.ShipSpeedFactor
  } else if ebiten.IsKeyPressed(ebiten.KeyRight) {
    ship.x += cfg.ShipSpeedFactor
  }
}

因为在Input.Update方法中需要访问配置，因此增加Config类型的参数，由Game.Update方法传入：

func (g *Game) Update() error {
  g.input.Update(g.ship, g.cfg)
  return nil
}

运行，是不是快了很多呢？

总结

本文介绍了2D游戏开发库ebiten的基本使用，并开始开发一个外星人入侵的游戏（1/3），目前只能在屏幕上移动飞船，下篇文章继续完成剩下的内容。

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

参考

Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib
ebitengine 官网：https://ebitengine.org/
Python 编程（从入门到实践）：https://book.douban.com/subject/35196328/

我

我的博客：https://darjun.github.io

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

Go中调用外部命令的几种姿势

Tue, 01 Nov 2022 13:45:30 +0000

引子

在工作中，我时不时地会需要在Go中调用外部命令。前段时间我做了一个工具，在钉钉群中添加了一个机器人，@这个机器人可以让它执行一些写好的脚本程序完成指定的任务。机器人倒是不难，照着钉钉开发者文档添加好机器人，然后@这个机器人就会向一个你指定的服务器发送一个POST请求，请求中会附带文本消息。所以我要做的就是搭一个Web服务器，可以用go原生的net/http包，也可以用gin/fasthttp/fiber这些Web框架。收到请求之后，检查附带文本中的关键字去调用对应的程序，然后返回结果。

go标准库中的os/exec包对调用外部程序提供了支持，本文详细介绍os/exec的使用姿势。

运行命令

Linux中有个cal命令，它可以显示指定年、月的日历，如果不指定年、月，默认为当前时间对应的年月。如果使用的是Windows，推荐安装msys2，这个软件包含了绝大多数的Linux常用命令。

那么，在Go代码中怎么调用这个命令呢？其实也很简单：

func main() {
  cmd := exec.Command("cal")
  err := cmd.Run()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }
}

首先，我们调用exec.Command传入命令名，创建一个命令对象exec.Cmd。接着调用该命令对象的Run()方法运行它。

如果你实际运行了，你会发现什么也没有发生，哈哈。事实上，使用os/exec执行命令，标准输出和标准错误默认会被丢弃。

显示输出

exec.Cmd对象有两个字段Stdout和Stderr，类型皆为io.Writer。我们可以将任意实现了io.Writer接口的类型实例赋给这两个字段，继而实现标准输出和标准错误的重定向。io.Writer接口在 Go 标准库和第三方库中随处可见，例如*os.File、*bytes.Buffer、net.Conn。所以我们可以将命令的输出重定向到文件、内存缓存甚至发送到网络中。

显示到标准输出

将exec.Cmd对象的Stdout和Stderr这两个字段都设置为os.Stdout，那么输出内容都将显示到标准输出：

func main() {
  cmd := exec.Command("cal")
  cmd.Stdout = os.Stdout
  cmd.Stderr = os.Stderr
  err := cmd.Run()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }
}

运行程序。我在git bash运行，得到如下结果：

输出了中文，检查一下环境变量LANG的值，果然是zh_CN.UTF-8。如果想输出英文，可以将环境变量LANG设置为en_US.UTF-8：

1
2
3

$ echo $LANG
zh_CN.UTF-8
$ LANG=en_US.UTF-8 go run main.go

得到输出：

输出到文件

打开或创建文件，然后将文件句柄赋给exec.Cmd对象的Stdout和Stderr这两个字段即可实现输出到文件的功能。

func main() {
  f, err := os.OpenFile("out.txt", os.O_WRONLY|os.O_CREATE, os.ModePerm)
  if err != nil {
    log.Fatalf("os.OpenFile() failed: %v\n", err)
  }

  cmd := exec.Command("cal")
  cmd.Stdout = f
  cmd.Stderr = f
  err = cmd.Run()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }
}

os.OpenFile打开一个文件，指定os.O_CREATE标志让操作系统在文件不存在时自动创建一个，返回该文件对象*os.File。*os.File实现了io.Writer接口。

运行程序：

$ go run main.go
$ cat out.txt
    November 2022   
Su Mo Tu We Th Fr Sa
       1  2  3  4  5
 6  7  8  9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30

发送到网络

现在我们来编写一个日历服务，接收年、月信息，返回该月的日历。

func cal(w http.ResponseWriter, r *http.Request) {
  year := r.URL.Query().Get("year")
  month := r.URL.Query().Get("month")

  cmd := exec.Command("cal", month, year)
  cmd.Stdout = w
  cmd.Stderr = w

  err := cmd.Run()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }
}

func main() {
  http.HandleFunc("/cal", cal)
  http.ListenAndServe(":8080", nil)
}

这里为了简单，错误处理都省略了。正常情况下，year和month参数都需要做合法性校验。exec.Command函数接收一个字符串类型的可变参数作为命令的参数：

`1`	`func Command(name string, arg ...string) *Cmd`

运行程序，使用浏览器请求localhost:8080/cal?year=2021&month=2得到：

保存到内存对象中

*bytes.Buffer同样也实现了io.Writer接口，故如果我们创建一个*bytes.Buffer对象，并将其赋给exec.Cmd的Stdout和Stderr这两个字段，那么命令执行之后，该*bytes.Buffer对象中保存的就是命令的输出。

func main() {
  buf := bytes.NewBuffer(nil)
  cmd := exec.Command("cal")
  cmd.Stdout = buf
  cmd.Stderr = buf
  err := cmd.Run()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }

  fmt.Println(buf.String())
}

运行：

$ go run main.go
    November 2022   
Su Mo Tu We Th Fr Sa
       1  2  3  4  5
 6  7  8  9 10 11 12
13 14 15 16 17 18 19
20 21 22 23 24 25 26
27 28 29 30

运行命令，然后得到输出的字符串或字节切片这种模式是如此的普遍，并且使用便利，os/exec包提供了一个便捷方法：CombinedOutput。

输出到多个目的地

有时，我们希望能输出到文件和网络，同时保存到内存对象。使用go提供的io.MultiWriter可以很容易实现这个需求。io.MultiWriter很方便地将多个io.Writer转为一个io.Writer。

我们稍微修改上面的web程序：

func cal(w http.ResponseWriter, r *http.Request) {
  year := r.URL.Query().Get("year")
  month := r.URL.Query().Get("month")

  f, _ := os.OpenFile("out.txt", os.O_CREATE|os.O_WRONLY, os.ModePerm)
  buf := bytes.NewBuffer(nil)
  mw := io.MultiWriter(w, f, buf)

  cmd := exec.Command("cal", month, year)
  cmd.Stdout = mw
  cmd.Stderr = mw

  err := cmd.Run()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }

  fmt.Println(buf.String())
}

调用io.MultiWriter将多个io.Writer整合成一个io.Writer，然后将cmd对象的Stdout和Stderr都赋值为这个io.Writer。这样，命令运行时产出的输出会分别送往http.ResponseWriter、*os.File以及*bytes.Buffer。

运行命令，获取输出

前面提到，我们常常需要运行命令，返回输出。exec.Cmd对象提供了一个便捷方法：CombinedOutput()。该方法运行命令，将输出内容以一个字节切片返回便于后续处理。所以，上面获取输出的程序可以简化为：

func main() {
  cmd := exec.Command("cal")
  output, err := cmd.CombinedOutput()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }

  fmt.Println(string(output))
}

So easy!

CombinedOutput()方法的实现很简单，先将标准输出和标准错误重定向到*bytes.Buffer对象，然后运行程序，最后返回该对象中的字节切片：

func (c *Cmd) CombinedOutput() ([]byte, error) {
  if c.Stdout != nil {
    return nil, errors.New("exec: Stdout already set")
  }
  if c.Stderr != nil {
    return nil, errors.New("exec: Stderr already set")
  }
  var b bytes.Buffer
  c.Stdout = &b
  c.Stderr = &b
  err := c.Run()
  return b.Bytes(), err
}

CombinedOutput方法前几行判断表明，Stdout和Stderr必须是未设置状态。这其实很好理解，一般情况下，如果已经打算使用CombinedOutput方法获取输出内容，不会再自找麻烦地再去设置Stdout和Stderr字段了。

与CombinedOutput类似的还有Output方法，区别是Output只会返回运行命令产出的标准输出内容。

分别获取标准输出和标准错误

创建两个*bytes.Buffer对象，分别赋给exec.Cmd对象的Stdout和Stderr这两个字段，然后运行命令即可分别获取标准输出和标准错误。

func main() {
  cmd := exec.Command("cal", "15", "2012")
  var stdout, stderr bytes.Buffer
  cmd.Stdout = &stdout
  cmd.Stderr = &stderr
  err := cmd.Run()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }

  fmt.Printf("output:\n%s\nerror:\n%s\n", stdout.String(), stderr.String())
}

标准输入

exec.Cmd对象有一个类型为io.Reader的字段Stdin。命令运行时会从这个io.Reader读取输入。先来看一个最简单的例子：

func main() {
  cmd := exec.Command("cat")
  cmd.Stdin = bytes.NewBufferString("hello\nworld")
  cmd.Stdout = os.Stdout
  err := cmd.Run()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }
}

如果不带参数运行cat命令，则进入交互模式，cat按行读取输入，并且原样发送到输出。

再来看一个复杂点的例子。Go标准库中compress/bzip2包只提供解压方法，并没有压缩方法。我们可以利用Linux命令bzip2实现压缩。bzip2从标准输入中读取数据，将其压缩，并发送到标准输出。

func bzipCompress(d []byte) ([]byte, error) {
  var out bytes.Buffer
  cmd := exec.Command("bzip2", "-c", "-9")
  cmd.Stdin = bytes.NewBuffer(d)
  cmd.Stdout = &out
  err := cmd.Run()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }

  return out.Bytes(), nil
}

参数-c表示压缩，-9表示压缩等级，9为最高。为了验证函数的正确性，写个简单的程序，先压缩"hello world"字符串，然后解压，看看是否能得到原来的字符串：

func main() {
  data := []byte("hello world")
  compressed, _ := bzipCompress(data)
  r := bzip2.NewReader(bytes.NewBuffer(compressed))
  decompressed, _ := ioutil.ReadAll(r)
  fmt.Println(string(decompressed))
}

运行程序，输出"hello world"。

环境变量

环境变量可以在一定程度上微调程序的行为，当然这需要程序的支持。例如，设置ENV=production会抑制调试日志的输出。每个环境变量都是一个键值对。exec.Cmd对象中有一个类型为[]string的字段Env。我们可以通过修改它来达到控制命令运行时的环境变量的目的。

package main

import (
  "fmt"
  "log"
  "os"
  "os/exec"
)

func main() {
  cmd := exec.Command("bash", "-c", "./test.sh")

  nameEnv := "NAME=darjun"
  ageEnv := "AGE=18"

  newEnv := append(os.Environ(), nameEnv, ageEnv)
  cmd.Env = newEnv

  out, err := cmd.CombinedOutput()
  if err != nil {
    log.Fatalf("cmd.Run() failed: %v\n", err)
  }

  fmt.Println(string(out))
}

上面代码获取系统的环境变量，然后又添加了两个环境变量NAME和AGE。最后使用bash运行脚本test.sh：

#!/bin/bash

echo $NAME
echo $AGE
echo $GOPATH

程序运行结果：

$ go run main.go 
darjun
18
D:\workspace\code\go

检查命令是否存在

一般在运行命令之前，我们通过希望能检查要运行的命令是否存在，如果存在则直接运行，否则提示用户安装此命令。os/exec包提供了函数LookPath可以获取命令所在目录，如果命令不存在，则返回一个error。

func main() {
  path, err := exec.LookPath("ls")
  if err != nil {
    fmt.Printf("no cmd ls: %v\n", err)
  } else {
    fmt.Printf("find ls in path:%s\n", path)
  }

  path, err = exec.LookPath("not-exist")
  if err != nil {
    fmt.Printf("no cmd not-exist: %v\n", err)
  } else {
    fmt.Printf("find not-exist in path:%s\n", path)
  }
}

运行：

1
2
3

$ go run main.go 
find ls in path:C:\Program Files\Git\usr\bin\ls.exe
no cmd not-exist: exec: "not-exist": executable file not found in %PATH%

封装

执行外部命令的流程比较固定：

调用exec.Command()创建命令对象；
调用Cmd.Run()执行命令

如果要获取输出，需要调用CombinedOutput/Output之类的方法，或者手动创建bytes.Buffer对象并赋值给exec.Cmd的Stdout和Stderr字段。为了使用方便，我编写了一个包goexec。

接口如下：

// 执行命令，丢弃标准输出和标准错误
func RunCommand(cmd string, arg []string, opts ...Option) error
// 执行命令，以[]byte类型返回输出
func CombinedOutput(cmd string, arg []string, opts ...Option) ([]byte, error)
// 执行命令，以string类型返回输出
func CombinedOutputString(cmd string, arg []string, opts ...Option) (string, error)
// 执行命令，以[]byte类型返回标准输出
func Output(cmd string, arg []string, opts ...Option) ([]byte, error)
// 执行命令，以string类型返回标准输出
func OutputString(cmd string, arg []string, opts ...Option) (string, error)
// 执行命令，以[]byte类型分别返回标准输出和标准错误
func SeparateOutput(cmd string, arg []string, opts ...Option) ([]byte, []byte, error)
// 执行命令，以string类型分别返回标准输出和标准错误
func SeparateOutputString(cmd string, arg []string, opts ...Option) (string, string, error)

相较于直接使用os/exec包，我倾向于一次函数调用就能获得结果。对输入、设置环境变量这些功能，我通过Option模式来提供支持。

type Option func(*exec.Cmd)

func WithStdin(stdin io.Reader) Option {
  return func(c *exec.Cmd) {
    c.Stdin = stdin
  }
}

func Without(stdout io.Writer) Option {
  return func(c *exec.Cmd) {
    c.Stdout = stdout
  }
}

func WithStderr(stderr io.Writer) Option {
  return func(c *exec.Cmd) {
    c.Stderr = stderr
  }
}

func WithOutWriter(out io.Writer) Option {
  return func(c *exec.Cmd) {
    c.Stdout = out
    c.Stderr = out
  }
}

func WithEnv(key, value string) Option {
  return func(c *exec.Cmd) {
    c.Env = append(os.Environ(), fmt.Sprintf("%s=%s", key, value))
  }
}

func applyOptions(cmd *exec.Cmd, opts []Option) {
  for _, opt := range opts {
    opt(cmd)
  }
}

使用非常简单：

1
2
3

func main() {
  fmt.Println(goexec.CombinedOutputString("cal", nil, goexec.WithEnv("LANG", "en_US.UTF-8")))
}

有一点我不太满意，为了使用Option模式，本来可以用可变参数来传递命令参数，现在只能用切片了，即使不需要指定参数，也必须要传入一个nil。暂时还没有想到比较优雅的解决方法。

总结

本文介绍了使用os/exec这个标准库调用外部命令的各种姿势。同时为了便于使用，我编写了一个goexec包封装对os/exec的调用。这个包目前for我自己使用是没有问题的，大家有其他需求可以提issue或者自己魔改😄。

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

参考

Advanced command execution in go with os/exec: https://blog.kowalczyk.info/article/wOYk/advanced-command-execution-in-go-with-osexec.html
goexec: https://github.com/darjun/goexec
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 gore

Mon, 18 Jul 2022 22:30:23 +0000

简介

周末闲逛 GitHub 的时候发现一个很好玩的 Go 语言的 REPL（read-eval-print-loop）工具。本文和大家分享一下这个工具：gore。

首先放一张 GitHub 的动图感受一下：

快速使用

gore 是一个命令行工具，需要配合 Go Module 安装。Go 环境安装完成之后，执行下面的命令安装 gore：

`1`	`$ go install github.com/x-motemen/gore/cmd/gore@latest`

go install 命令会将会在$GOPATH/bin目录生成的 gore 可执行文件。强烈推荐大家把$GOPATH/bin加入到系统的可执行文件搜索目录（即$PATH）中。

执行下面的命令即可进入 Go 的 REPL：

$ gore

命令

目前支持的命令还不多。我将命令分为两类，一种是基础命令，一种是代码相关命令。

注意，在 gore 中所有的命令必须以:开始。非:开始的行会被识别为代码。

基础命令

help：显示命令列表

doc：我觉得这个命令挺有意思，它可以显示一个包、结构体或接口的文档。如果要查看标准库的文档，例如math/bits，可以直接键入命令:doc bits。

注意，要查看文档的包必须先使用:import命令导入。并且传给:doc命令的参数必须是包去掉路径的部分，例如我们不能使用:doc math/bits，必须使用:doc bits。

doc 也可以用来查看第三方库的文档。也是先导入后查看：

quit：退出 REPL。

代码命令

import：导入包的命令。既可以导入标准库的包，也可以导入第三方库的包，gore 会自动调用 go get 去下载第三方库

type：输出表达式会变量的类型

print：我们在 gore 中输入的代码都会存放在一个临时文件中。print 命令会打印这个临时文件的内容。

clear：清空临时文件。执行 clear 命令之后 print 将会打印一个空的 main 函数。

write [<filename>]：将临时文件保存到指定的路径中。

特性

行编辑：通过左右键在行内移动光标，退格键删除光标前的内容，重新输入内容
命令历史：gore 会保存之前输入的命令历史，可以通过上下键找出之前执行的命令。
多行输入：如果 gore 检测到输入还没有结束就换行了，它会等待输入结束再执行这条语句。例如 if 语句
自动补全：使用 TAB 键可以自动补全命令，不能补全代码
代码补全：这个我没试过，文档介绍说需要 gocode 配合
自动导入：使用选项-autoimport启动可以自动导入要使用的包

缺点

体验下来，我觉得有几个缺点：

启动速度较慢。键入 gore 命令按下回车要等好几秒。其他命令的执行速度也不快
doc 命令的限制有点奇怪。为什么包不能加路径？go doc 是可以加路径的。也有可能我使用的姿势不对，有知道的可以指点一二😀

多行输入有点反直觉。如果我没有输入完整的代码，它会一直等着我输入。可是我已经不想输入了。有一次我键入 type 命令时忘记加:了，就变成这样了：

当然，可以通过Ctrl + C终止输入，这个让我摸索了好一会儿。我个人使用其他软件的经验是连续几个空行就可以终止了。这一点严格不算缺点，只是不符合我的习惯。

总结

总体来说 gore 是一个比较好玩的工具，期待项目发展壮大！

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

参考

gore GitHub：github.com/x-motemen/gore
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 roaring

Sun, 17 Jul 2022 10:40:23 +0000

简介

集合是软件中的基本抽象。实现集合的方法有很多，例如 hash set、tree等。要实现一个整数集合，位图（bitmap，也称为 bitset 位集合，bitvector 位向量）是个不错的方法。使用 n 个位（bit），我们可以表示整数范围[0, n)。如果整数 i 在集合中，第 i 位设置为 1。这样集合的交集（intersection）、并集（unions）和差集（difference）可以利用整数的按位与、按位或和按位与非来实现。而计算机执行位运算是非常迅速的。

上一篇文章我介绍了bitset这个库。

bitset 在某些场景中会消耗大量的内存。例如，设置第 1,000,000 位，需要占用超过 100kb 的内存。为此 bitset 库的作者又开发了压缩位图库：roaring。

本文首先介绍了 roaring 的使用。最后分析 roaring 的文件存储格式。

安装

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir -p roaring && cd roaring
$ go mod init github.com/darjun/go-daily-lib/roaring

安装roaring库：

`1`	`$ go get -u github.com/RoaringBitmap/roaring`

使用

基本操作

func main() {
  bm1 := roaring.BitmapOf(1, 2, 3, 4, 5, 100, 1000)
  fmt.Println(bm1.String())         // {1,2,3,4,5,100,1000}
  fmt.Println(bm1.GetCardinality()) // 7
  fmt.Println(bm1.Contains(3))      // true

  bm2 := roaring.BitmapOf(1, 100, 500)
  fmt.Println(bm2.String())         // {1,100,500}
  fmt.Println(bm2.GetCardinality()) // 3
  fmt.Println(bm2.Contains(300))    // false

  bm3 := roaring.New()
  bm3.Add(1)
  bm3.Add(11)
  bm3.Add(111)
  fmt.Println(bm3.String())         // {1,11,111}
  fmt.Println(bm3.GetCardinality()) // 3
  fmt.Println(bm3.Contains(11))     // true

  bm1.Or(bm2)                       // 执行并集
  fmt.Println(bm1.String())         // {1,2,3,4,5,100,500,1000}
  fmt.Println(bm1.GetCardinality()) // 8
  fmt.Println(bm1.Contains(500))    // true

  bm2.And(bm3)                      // 执行交集
  fmt.Println(bm2.String())         // {1}
  fmt.Println(bm2.GetCardinality()) // 1
  fmt.Println(bm2.Contains(1))      // true
}

上面演示了两种创建 roaring bitmap 的方式：

roaring.BitmapOf()：传入集合元素，创建位图并添加这些元素
roaring.New()：创建一个空位图

首先，我们创建了一个位图 bm1:{1,2,3,4,5,100,1000}。输出它的字符串表示，集合大小，检查 3 是否在集合中。

然后又创建了一个位图 bm2:{1,100,500}。输出检查三连。

接着创建了一个空位图 bm3，依次添加元素 1，11，111。输出检查三连。

然后我们对 bm1 和 bm2 执行并集，结果直接存放在 bm1 中。由于集合中的元素各不相同，此时 bm1 中的元素为{1,2,3,4,5,100,500,1000}，大小为 8。

再然后我们对 bm2 和 bm3 执行交集，结果直接存放在 bm2 中。此时 bm2 中的元素为{1}，大小为 1。

可以看出 roaring 提供的基本操作与 bitset 大体相同。只是命名完全不一样，在使用时需要特别注意。

bm.String()：返回 bitmap 的字符串表示
bm.Add(n)：添加元素 n
bm.GetCardinality()：返回集合的基数（Cardinality），即元素个数
bm1.And(bm2)：执行集合交集，会修改 bm1
bm1.Or(bm2)：执行集合并集，会修改 bm1

迭代

roaring 位图支持迭代。

func main() {
  bm := roaring.BitmapOf(1, 2, 3, 4, 5, 100, 1000)

  i := bm.Iterator()
  for i.HasNext() {
    fmt.Println(i.Next())
  }
}

与很多编程语言支持的迭代器一样，先调用对象的Iterator()返回一个迭代器，然后循环调用HasNext()检查是否有下一个元素，调用i.Next()返回下一个元素。

上面代码依次输出 1，2，3，4，5，100，1000。

并行操作

roaring 支持位图集合运算的并行执行。可以指定使用多少个 goroutine 对集合执行交集、并集等。同时可以传入可变数量的位图集合：

func main() {
  bm1 := roaring.BitmapOf(1, 2, 3, 4, 5, 100, 1000)
  bm2 := roaring.BitmapOf(1, 100, 500)
  bm3 := roaring.BitmapOf(1, 10, 1000)

  bmAnd := roaring.ParAnd(4, bm1, bm2, bm3)
  fmt.Println(bmAnd.String())         // {1}
  fmt.Println(bmAnd.GetCardinality()) // 1
  fmt.Println(bmAnd.Contains(1))      // true
  fmt.Println(bmAnd.Contains(100))    // false

  bmOr := roaring.ParOr(4, bm1, bm2, bm3)
  fmt.Println(bmOr.String())         // {1,2,3,4,5,10,100,500,1000}
  fmt.Println(bmOr.GetCardinality()) // 9
  fmt.Println(bmOr.Contains(10))     // true
}

并行操作使用相应接口的Par*版本，第一个参数指定 worker 数量，接着传入任意多个 bitmap。

写入与读取

roaring 可以将压缩的位图写入到文件中，并且格式与其他语言的实现保持兼容。也就是说，我们可以用 Go 将 roaring 位图写入文件，然后通过网络发送给另一台机器，在这台机器上使用 C++ 或 Java 的实现读取这个文件。

func main() {
  bm := roaring.BitmapOf(1, 3, 5, 7, 100, 300, 500, 700)

  buf := &bytes.Buffer{}
  bm.WriteTo(buf)

  newBm := roaring.New()
  newBm.ReadFrom(buf)
  if bm.Equals(newBm) {
    fmt.Println("write and read back ok.")
  }
}

WriteTo(w io.Writer)：写入一个 io.Writer，可以是内存（byte.Buffer），可以是文件（os.File），甚至可以是网络（net.Conn)
ReadFrom(r io.Reader)：从一个 io.Reader 中读取，来源同样可以是内存、文件或网络等

注意WriteTo的返回值为size和err，使用时需要处理错误情况。ReadFrom也是返回size和err，同样需要处理处理。

64 位版本

默认情况下，roaring 位图只能用来存储 32 位整数。所以 roaring 位图最多能包含 4294967296（2^32）个整数。

roaring 也提供了存储 64 位整数的扩展，即github.com/RoaringBitmap/roaring/roaring64。提供的接口基本相同。然而，64 位版本不保证与 Java/C++ 等格式兼容。

存储格式

roaring 可以写入文件中，也可以从文件中读取。并且提供多种语言兼容的格式。下面我们一起来看看存储的格式。

roaring 位图默认只能存储 32 位的整数。在序列化时，将这些整数分容器（container）存储。每个容器有一个 16 位表示的基数（Cardinality，即元素个数，范围[1,2^16]）和一个键（key）。键取元素的最高有效 16 位（most significant），所以键的范围为[0, 65536)。这样如果两个整数的最高 16 位有效位相同，那么它们将被保存在同一个容器中。这样做还有一个好处：可以减少占用的空间。

所有整数均采用小端存储。

概览

roaring 采用的存储格式布局如下：

从上到下依次介绍。

开始部分是一个 Cookie Header。它用来识别一个二进制流是不是一个 roaring 位图，并且存储一些少量信息。

cookie 这个词有点意思，本意是饼干。我的理解是指小物件，所以 http 中的 cookie 只是用来存储少量信息。这里的 Cookie Header 也是如此。

接下来是 Descriptive Header。见名知义，它用来描述容器的信息。后面会详细介绍容器。

接下来有一个可选的 Offset Header。它记录了每个容器相对于首位的偏移，这让我们可以随机访问任意容器。

最后一部分是存储实际数据的容器。roaring 中一共有 3 种类型的容器：

array（数组型）：16bit 整数数组
bitset（位集型）：使用上一篇文章介绍的 bitset 存储数据
run：这个有点不好翻译。有些人可能听说过 run-length 编码，有翻译成游程编码的。即使用长度+数据来编码，比如"0000000000"可以编码成"10,0"，表示有 10 个 0。run 容器也是类似的，后文详述

设计这种的布局，是为了不用将存储的位图全部载入内存就可以随机读取它的数据。并且每个容器的范围相互独立，这使得并行计算变得容易。

Cookier Header 有两种类型，分别占用 32bit 和 64bit 的空间。

第一种类型，前 32bit 的值为 12346，此时紧接着的 32bit 表示容器数量（记为 n）。同时这意味着，后面没有 run 类型的容器。12346 这魔术数字被定义为常量SERIAL_COOKIE_NO_RUNCONTAINER，含义不言自明。

第二种类型，前 32bit 的最低有效 16 位的值为 12347。此时，最高有效 16 位存储的值等于容器数量-1。将 cookie 右移 16 位再加 1 即可得到容器数量。由于这种类型的容器数量不会为 0，采用这种编码我们能的容器数量会多上 1 个。这种方法在很多地方都有应用，例如 redis。后面紧接着会使用 (n+7)/8 字节（作为一个 bitset）表示后面的容器是否 run 容器。每位对应一个容器，1 表示对应的容器是 run 容器，0 表示不是 run 容器。

由于是小端存储，所以流的前 16bit 一定是 12346 或 12347。如果读取到了其它的值，说明文件损坏，直接退出程序即可。

Descriptive Header

Cookie Header 之后就是 Descriptive Header。它使用一对 16bit 数据描述每个容器。一个 16bit 存储键（即整数的最高有效 16bit），另一个 16bit 存储对应容器的基数（Cardinality）-1（又见到了），即容器存储的整数数量）。如果有 n 个容器，则 Descriptive Header 需要 32n 位或 4n 字节。

扫描 Descriptive Header 之后，我们就能知道每个容器的类型。如果 cookie 值为 12347，cookie 后有一个 bitset 表示每个容器是否是 run 类型。对于非 run 类型的容器，如果容器的基数（Cardinality）小于等于 4096，它是一个 array 容器。反之，这是一个 bitset 容器

Offset Header

满足以下任一条件，Offset Header 就会存在：

cookie 的值为 SERIAL_COOKIE_NO_RUNCONTAINER（即 12346）
cookie 的值为 SERIAL_COOKIE（即 12347），并且至少有 4 个容器。也有一个常量NO_OFFSET_THRESHOLD = 4

Offset Header 为每个容器使用 32bit 值存储对应容器距离流开始处的偏移，单位字节。

Container

接下来就是实际存储数据的容器了。前面简单提到过，容器有三种类型。

array

存储有序的 16bit 无符号整数值，有序便于使用二分查找提高效率。16bit 值只是数据的最低有效 16bit，还记得 Descriptive Header 中每个容器都有一个 16bit 的 key 吧。将它们拼接起来才是实际的数据。

如果容器有 x 个值，占用空间 2x 字节。

bitmap/bitset

bitset 容器固定使用 8KB 的空间，以 64bit 为单位（称为字，word）序列化。因此，如果值 j 存在，则第 j/64 个字（从 0 开始）的 j%64 位会被设置为 1（从 0 开始）。

run

以一个表示 run 数量的 16bit 整数开始。后续每个 run 用一对 16bit 整数表示，前一个 16bit 表示开始的值，后一个 16bit 表示长度-1（又双见到了）。例如，11,4 表示数据 11,12,13,14,15。

手撸解析代码

验证我们是否真的理解了 roaring 布局最有效的方法就是手撸一个解析。使用标准库encoding/binary可以很容易地处理大小端问题。

定义常量:

const (
  SERIAL_COOKIE_NO_RUNCONTAINER = 12346
  SERIAL_COOKIE                 = 12347
  NO_OFFSET_THRESHOLD           = 4
)

读取 Cookie Header:

func readCookieHeader(r io.Reader) (cookie uint16, containerNum uint32, runFlagBitset []byte) {
  binary.Read(r, binary.LittleEndian, &cookie)
  switch cookie {
  case SERIAL_COOKIE_NO_RUNCONTAINER:
    var dummy uint16
    binary.Read(r, binary.LittleEndian, &dummy)
    binary.Read(r, binary.LittleEndian, &containerNum)

  case SERIAL_COOKIE:
    var u16 uint16
    binary.Read(r, binary.LittleEndian, &u16)
    containerNum = uint32(u16)
    buf := make([]uint8, (containerNum+7)/8)
    r.Read(buf)
    runFlagBitset = buf[:]

  default:
    log.Fatal("unknown cookie")
  }

  fmt.Println(cookie, containerNum, runFlagBitset)
  return
}

读取 Descriptive Header:

func readDescriptiveHeader(r io.Reader, containerNum uint32) []KeyCard {
  var keycards []KeyCard
  var key uint16
  var card uint16
  for i := 0; i < int(containerNum); i++ {
    binary.Read(r, binary.LittleEndian, &key)
    binary.Read(r, binary.LittleEndian, &card)
    card += 1
    fmt.Println("container", i, "key", key, "card", card)

    keycards = append(keycards, KeyCard{key, card})
  }

  return keycards
}

读取 Offset Header:

func readOffsetHeader(r io.Reader, cookie uint16, containerNum uint32) {
  if cookie == SERIAL_COOKIE_NO_RUNCONTAINER ||
    (cookie == SERIAL_COOKIE && containerNum >= NO_OFFSET_THRESHOLD) {
    // have offset header
    var offset uint32
    for i := 0; i < int(containerNum); i++ {
      binary.Read(r, binary.LittleEndian, &offset)
      fmt.Println("offset", i, offset)
    }
  }
}

读取容器，根据类型调用不同的函数:

// array
func readArrayContainer(r io.Reader, key, card uint16, bm *roaring.Bitmap) {
  var value uint16
  for i := 0; i < int(card); i++ {
    binary.Read(r, binary.LittleEndian, &value)
    bm.Add(uint32(key)<<16 | uint32(value))
  }
}

// bitmap
func readBitmapContainer(r io.Reader, key, card uint16, bm *roaring.Bitmap) {
  var u64s [1024]uint64
  for i := 0; i < 1024; i++ {
    binary.Read(r, binary.LittleEndian, &u64s[i])
  }

  bs := bitset.From(u64s[:])
  for i := uint32(0); i < 8192; i++ {
    if bs.Test(uint(i)) {
      bm.Add(uint32(key)<<16 | i)
    }
  }
}

// run
func readRunContainer(r io.Reader, key uint16, bm *roaring.Bitmap) {
  var runNum uint16
  binary.Read(r, binary.LittleEndian, &runNum)

  var startNum uint16
  var length uint16
  for i := 0; i < int(runNum); i++ {
    binary.Read(r, binary.LittleEndian, &startNum)
    binary.Read(r, binary.LittleEndian, &length)
    length += 1
    for j := uint16(0); j < length; j++ {
      bm.Add(uint32(key)<<16 | uint32(startNum+j))
    }
  }
}

整合:

func main() {
  data, err := ioutil.ReadFile("../roaring.bin")
  if err != nil {
    log.Fatal(err)
  }

  r := bytes.NewReader(data)
  cookie, containerNum, runFlagBitset := readCookieHeader(r)

  keycards := readDescriptiveHeader(r, containerNum)
  readOffsetHeader(r, cookie, containerNum)

  bm := roaring.New()
  for i := uint32(0); i < uint32(containerNum); i++ {
    if runFlagBitset != nil && runFlagBitset[i/8]&(1<<(i%8)) != 0 {
      // run
      readRunContainer(r, keycards[i].key, bm)
    } else if keycards[i].card <= 4096 {
      // array
      readArrayContainer(r, keycards[i].key, keycards[i].card, bm)
    } else {
      // bitmap
      readBitmapContainer(r, keycards[i].key, keycards[i].card, bm)
    }
  }

  fmt.Println(bm.String())
}

我将写入读取那个示例中的 byte.Buffer 保存到文件roaring.bin中。上面的程序就可以解析这个文件:

12346 1 []
container 0 key 0 card 8
offset 0 16
{1,3,5,7,100,300,500,700}

成功还原了位图😀

总结

本文我们首先介绍了 roaring 压缩位图的使用。如果不考虑内部实现，压缩位图和普通的位图在使用上并没有多少区别。

然后我通过 8 张原理图详细分析了存储的格式。

最后通过手撸一个解析来加深对原理的理解。

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

参考

roaring GitHub：github.com/RoaringBitmap/roaring
roaring 文件格式：https://github.com/RoaringBitmap/RoaringFormatSpec
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 bitset

Sat, 16 Jul 2022 12:30:23 +0000

简介

我们都知道计算机是基于二进制的，位运算是计算机的基础运算。位运算的优势很明显，CPU 指令原生支持、速度快。基于位运算的位集合在有限的场景中替换集合数据结构可以收到意想不到的效果。bitset库实现了位集合及相关操作，不妨拿来即用。

安装

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir -p bitset && cd bitset
$ go mod init github.com/darjun/go-daily-lib/bitset

安装bitset库：

`1`	`$ go get -u github.com/bits-and-blooms/bitset`

使用

位集合的基本操作有：

检查位（Test）：检查某个索引是否为 1。类比检查元素是否在集合中
设置位（Set）：将某个索引设置为 1。类比向集合添加元素
清除位（Clear）：将某个索引清除，设置为 0。类比从集合中删除元素
翻转位（Flip）：如果某个索引为 1，则设置为 0，反之设置为 1
并（Union）：两个位集合执行并操作。类比集合的并
交（Intersection）：两个位集合执行交操作。类比集合的交

位集合一般用于小数值的非负整数的场景中。就拿游戏中简单的签到举例吧，很多游戏都有签到活动，短的有 7 天的，长的有 30 天。这种就很适合使用位集合。每个位的值表示其索引位置对应的那天有没有签到。

type Player struct {
  sign *bitset.BitSet
}

func NewPlayer(sign uint) *Player {
  return &Player{
    sign: bitset.From([]uint64{uint64(sign)}),
  }
}

func (this *Player) Sign(day uint) {
  this.sign.Set(day)
}

func (this *Player) IsSigned(day uint) bool {
  return this.sign.Test(day)
}

func main() {
  player := NewPlayer(1) // 第一天签到
  for day := uint(2); day <= 7; day++ {
    if rand.Intn(100)&1 == 0 {
      player.Sign(day - 1)
    }
  }

  for day := uint(1); day <= 7; day++ {
    if player.IsSigned(day - 1) {
      fmt.Printf("day:%d signed\n", day)
    }
  }
}

bitset 提供了多种创建 BitSet 对象的方法。

首先 bitset.BitSet 零值可用，如果一开始不知道有多少元素，可以使用这种方式创建：

`1`	`var b bitset.BitSet`

BitSet 在设置时自动调整大小。如果事先知道长度，创建 BitSet 时可传入此值，能有效避免自动调整的开销：

`1`	`b := bitset.New(100)`

bitset 结构支持链式调用，大部分方法返回自身的指针，所以可以这样写：

`1`	`b.Set(10).Set(11).Clear(12).Flip(13);`

注意，bitset 的索引是从 0 开始的。

记得之前在网上看过一道题：

一个农夫带着一只狼、一头羊和一颗白菜来到河边。他需要用船把他们带到对岸。然而，这艘船只能容下农夫本人和另外一种东西（要么是狼，要么是羊，要么是白菜）。如果农夫不在场的话，狼就会吃掉羊，羊会吃掉白菜。请为农夫解决这个问题。

这其实是一个状态搜索的问题，用回溯法就能解决。农夫、狼、羊、白菜都有两个状态，即在河左岸（假设刚开始农夫所处的是左岸）还是河右岸。这里实际上还有个船的状态，由于船一定和农夫的状态是一致的，就不用额外考虑了。这些状态我们很容易用位集合来表示：

const (
  FARMER = iota
  WOLF
  SHEEP
  CABBAGE
)

编写一个函数来判断状态是否合法。有两种状态不合法：

狼和羊在同一边，并且不和农夫在同一边。此时狼会吃掉羊
羊和白菜在同一边，并且不和农夫在同一边。此时羊会吃掉白菜

func IsStateValid(state *bitset.BitSet) bool {
  if state.Test(WOLF) == state.Test(SHEEP) &&
    state.Test(WOLF) != state.Test(FARMER) {
    // 狼和羊在同一边，并且不和农夫在同一边
    // 狼会吃掉羊，非法
    return false
  }

  if state.Test(SHEEP) == state.Test(CABBAGE) &&
    state.Test(SHEEP) != state.Test(FARMER) {
    // 羊和白菜在同一边，并且不和农夫在同一边
    // 羊会吃掉白菜，非法
    return false
  }

  return true
}

接下来编写搜索函数：

func search(b *bitset.BitSet, visited map[string]struct{}) bool {
  if !IsStateValid(b) {
    return false
  }

  if _, exist := visited[b.String()]; exist {
    // 状态已遍历
    return false
  }

  if b.Count() == 4 {
    return true
  }

  visited[b.String()] = struct{}{}
  for index := uint(FARMER); index <= CABBAGE; index++ {
    if b.Test(index) != b.Test(FARMER) {
      // 与农夫不在一边，不能带上船
      continue
    }

    // 带到对岸去
    b.Flip(index)
    if index != FARMER {
      // 如果 index 为 FARMER，表示不带任何东西
      b.Flip(FARMER)
    }

    if search(b, visited) {
      return true
    }

    // 状态恢复
    b.Flip(index)
    if index != FARMER {
      b.Flip(FARMER)
    }
  }

  return false
}

主函数：

func main() {
  b := bitset.New(4)

  visited := make(map[string]struct{})
  fmt.Println(search(b, visited))
}

初始时，所有状态为 0，都到对岸之后所有状态为 1，故b.Count() == 4表示都已到达对岸了。由于搜索是盲目的，可能会无限循环：这次农夫将羊带到对岸，下次又将其从对岸带回来了。所以我们需要做状态去重。bitset.String()返回当前位集合的字符串表示，我们以此来判断状态是否重复。

for 循环依次尝试带各种物品，或什么也不带。驱动查找过程。

如果想得到农夫正确的动作序列，可以给 search 加一个参数，记录每一步的操作：

func search(b *bitset.BitSet, visited map[string]struct{}, path *[]*bitset.BitSet) bool {
  // 记录路径
  *path = append(*path, b.Clone())
  if b.Count() == 4 {
    return true
  }

  // ...
  *path = (*path)[:len(*path)-1]

  return false
}

func main() {
  b := bitset.New(4)

  visited := make(map[string]struct{})
  var path []*bitset.BitSet
  if search(b, visited, &path) {
    PrintPath(path)
  }
}

如果找到解，打印之：

var names = []string{"农夫", "狼", "羊", "白菜"}

func PrintState(b *bitset.BitSet) {
  fmt.Println("=======================")
  fmt.Println("河左岸：")
  for index := uint(FARMER); index <= CABBAGE; index++ {
    if !b.Test(index) {
      fmt.Println(names[index])
    }
  }

  fmt.Println("河右岸：")
  for index := uint(FARMER); index <= CABBAGE; index++ {
    if b.Test(index) {
      fmt.Println(names[index])
    }
  }
  fmt.Println("=======================")
}

func PrintMove(cur, next *bitset.BitSet) {
  for index := uint(WOLF); index <= CABBAGE; index++ {
    if cur.Test(index) != next.Test(index) {
      if !cur.Test(FARMER) {
        fmt.Printf("农夫将【%s】从河左岸带到河右岸\n", names[index])
      } else {
        fmt.Printf("农夫将【%s】从河右岸带到河左岸\n", names[index])

      }
      return
    }
  }

  if !cur.Test(FARMER) {
    fmt.Println("农夫独自从河左岸到河右岸")
  } else {
    fmt.Println("农夫独自从河右岸到河左岸")
  }
}

func PrintPath(path []*bitset.BitSet) {
  cur := path[0]
  PrintState(cur)

  for i := 1; i < len(path); i++ {
    next := path[i]
    PrintMove(cur, next)
    PrintState(next)
    cur = next
  }
}

运行：

=======================
河左岸：
农夫
狼
羊
白菜

河右岸：
=======================
农夫将【羊】从河左岸带到河右岸
=======================
河左岸：
狼
白菜

河右岸：
农夫
羊
=======================
农夫独自从河右岸到河左岸
=======================
河左岸：
农夫
狼
白菜

河右岸：
羊
=======================
农夫将【狼】从河左岸带到河右岸
=======================
河左岸：
白菜

河右岸：
农夫
狼
羊
=======================
农夫将【羊】从河右岸带到河左岸
=======================
河左岸：
农夫
羊
白菜

河右岸：
狼
=======================
农夫将【白菜】从河左岸带到河右岸
=======================
河左岸：
羊

河右岸：
农夫
狼
白菜
=======================
农夫独自从河右岸到河左岸
=======================
河左岸：
农夫
羊

河右岸：
狼
白菜
=======================
农夫将【羊】从河左岸带到河右岸
=======================
河左岸：

河右岸：
农夫
狼
羊
白菜
=======================

即农夫操作过程为：将羊带到右岸->独自返回->将白菜带到右岸->再将羊带回左岸->带上狼到右岸->独自返回->最后将羊带到右岸->完成。

为什么要使用它？

似乎直接使用位运算就可以了，为什么要使用 bitset 库呢？

因为通用，上面列举的两个例子都是很小的整数值，如果整数值超过 64 位，我们必然要通过切片来存储。此时手写操作就非常不便了，而且容易出错。

库的优势体现在：

足够通用
持续优化
大规模使用

只要对外提供的接口保持不变，它可以一直优化内部实现。虽然我们也可以做，但是费时费力。而且有些优化涉及到比较复杂的算法，自己实现的难度较高且易错。

有一个很典型的例子，求一个 uint64 的二进制表示中 1 的数量（popcnt，或 population count）。实现的方法有很多。

最直接的，我们一位一位地统计：

func popcnt1(n uint64) uint64 {
  var count uint64

  for n > 0 {
    if n&1 == 1 {
      count++
    }

    n >>= 1
  }

  return count
}

考虑空间换时间，我们可以预先计算 0-255 这 256 个数字的二进制表示中 1 的个数，然后每 8 位计算一次，可能将计算次数减少到之前的 1/8。这也是标准库中的做法：

const pop8tab = "" +
  "\x00\x01\x01\x02\x01\x02\x02\x03\x01\x02\x02\x03\x02\x03\x03\x04" +
  "\x01\x02\x02\x03\x02\x03\x03\x04\x02\x03\x03\x04\x03\x04\x04\x05" +
  "\x01\x02\x02\x03\x02\x03\x03\x04\x02\x03\x03\x04\x03\x04\x04\x05" +
  "\x02\x03\x03\x04\x03\x04\x04\x05\x03\x04\x04\x05\x04\x05\x05\x06" +
  "\x01\x02\x02\x03\x02\x03\x03\x04\x02\x03\x03\x04\x03\x04\x04\x05" +
  "\x02\x03\x03\x04\x03\x04\x04\x05\x03\x04\x04\x05\x04\x05\x05\x06" +
  "\x02\x03\x03\x04\x03\x04\x04\x05\x03\x04\x04\x05\x04\x05\x05\x06" +
  "\x03\x04\x04\x05\x04\x05\x05\x06\x04\x05\x05\x06\x05\x06\x06\x07" +
  "\x01\x02\x02\x03\x02\x03\x03\x04\x02\x03\x03\x04\x03\x04\x04\x05" +
  "\x02\x03\x03\x04\x03\x04\x04\x05\x03\x04\x04\x05\x04\x05\x05\x06" +
  "\x02\x03\x03\x04\x03\x04\x04\x05\x03\x04\x04\x05\x04\x05\x05\x06" +
  "\x03\x04\x04\x05\x04\x05\x05\x06\x04\x05\x05\x06\x05\x06\x06\x07" +
  "\x02\x03\x03\x04\x03\x04\x04\x05\x03\x04\x04\x05\x04\x05\x05\x06" +
  "\x03\x04\x04\x05\x04\x05\x05\x06\x04\x05\x05\x06\x05\x06\x06\x07" +
  "\x03\x04\x04\x05\x04\x05\x05\x06\x04\x05\x05\x06\x05\x06\x06\x07" +
  "\x04\x05\x05\x06\x05\x06\x06\x07\x05\x06\x06\x07\x06\x07\x07\x08"

func popcnt2(n uint64) uint64 {
  var count uint64

  for n > 0 {
    count += uint64(pop8tab[n&0xff])
    n >>= 8
  }

  return count
}

最后是 bitset 库中的算法：

func popcnt3(x uint64) (n uint64) {
  x -= (x >> 1) & 0x5555555555555555
  x = (x>>2)&0x3333333333333333 + x&0x3333333333333333
  x += x >> 4
  x &= 0x0f0f0f0f0f0f0f0f
  x *= 0x0101010101010101
  return x >> 56
}

对以上三种实现进行性能测试：

goos: windows
goarch: amd64
pkg: github.com/darjun/go-daily-lib/bitset/popcnt
cpu: Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz
BenchmarkPopcnt1-8         52405             24409 ns/op
BenchmarkPopcnt2-8        207452              5443 ns/op
BenchmarkPopcnt3-8       1777320               602 ns/op
PASS
ok      github.com/darjun/go-daily-lib/bitset/popcnt    4.697s

popcnt3 相对 popcnt1 有 40 倍的性能提升。在学习上我们可以自己尝试造轮子，以此来加深自己对技术的理解。但是在工程上，通常更倾向于使用稳定的、高效的库。

总结

本文借着 bitset 库介绍了位集合的使用。并且应用 bitset 解决了农夫过河问题。最后我们讨论了为什么要使用库？

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

一点闲话

我发现人的惰性实在是太可怕了。虽然这半年来没写文章一开始是因为工作上的原因，后来单纯是因为惯性，因为懒。而且总是“装着很忙”来逃避需要花时间、花精力的事情。在这种想动又不想动的角逐之间，时间就这么一晃而过。

我们总是在抱怨没有时间，没有时间。但仔细想想，仔细算算，我们花在刷短视频，玩游戏上的时间其实并不少。

上周我在阮一峰老师的周刊上看到一篇文章《人生不短》，看了之后深有触动。人总该有所坚持，生活才有意义。

参考

bitset GitHub：github.com/bits-and-blooms/bitset
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 testify

Wed, 11 Aug 2021 07:16:23 +0000

简介

testify可以说是最流行的（从 GitHub star 数来看）Go 语言测试库了。testify提供了很多方便的函数帮助我们做assert和错误信息输出。使用标准库testing，我们需要自己编写各种条件判断，根据判断结果决定输出对应的信息。

testify核心有三部分内容：

assert：断言；
mock：测试替身；
suite：测试套件。

准备工作

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir -p testify && cd testify
$ go mod init github.com/darjun/go-daily-lib/testify

安装testify库：

`1`	`$ go get -u github.com/stretchr/testify`

`assert`

assert子库提供了便捷的断言函数，可以大大简化测试代码的编写。总的来说，它将之前需要判断 + 信息输出的模式：

1
2
3

if got != expected {
  t.Errorf("Xxx failed expect:%d got:%d", got, expected)
}

简化为一行断言代码：

`1`	`assert.Equal(t, got, expected, "they should be equal")`

结构更清晰，更可读。熟悉其他语言测试框架的开发者对assert的相关用法应该不会陌生。此外，assert中的函数会自动生成比较清晰的错误描述信息：

func TestEqual(t *testing.T) {
  var a = 100
  var b = 200
  assert.Equal(t, a, b, "")
}

使用testify编写测试代码与testing一样，测试文件为_test.go，测试函数为TestXxx。使用go test命令运行测试：

$ go test
--- FAIL: TestEqual (0.00s)
    assert_test.go:12:
                Error Trace:
                Error:          Not equal:
                                expected: 100
                                actual  : 200
                Test:           TestEqual
FAIL
exit status 1
FAIL    github.com/darjun/go-daily-lib/testify/assert   0.107s

我们看到信息更易读。

testify提供的assert类函数众多，每种函数都有两个版本，一个版本是函数名不带f的，一个版本是带f的，区别就在于带f的函数，我们需要指定至少两个参数，一个格式化字符串format，若干个参数args：

1
2

func Equal(t TestingT, expected, actual interface{}, msgAndArgs ...interface{})
func Equalf(t TestingT, expected, actual interface{}, msg string, args ...interface{})

实际上，在Equalf()函数内部调用了Equal()：

func Equalf(t TestingT, expected interface{}, actual interface{}, msg string, args ...interface{}) bool {
  if h, ok := t.(tHelper); ok {
    h.Helper()
  }
  return Equal(t, expected, actual, append([]interface{}{msg}, args...)...)
}

所以，我们只需要关注不带f的版本即可。

`Contains`

函数类型：

`1`	`func Contains(t TestingT, s, contains interface{}, msgAndArgs ...interface{}) bool`

Contains断言s包含contains。其中s可以是字符串，数组/切片，map。相应地，contains为子串，数组/切片元素，map 的键。

`DirExists`

函数类型：

`1`	`func DirExists(t TestingT, path string, msgAndArgs ...interface{}) bool`

DirExists断言路径path是一个目录，如果path不存在或者是一个文件，断言失败。

`ElementsMatch`

函数类型：

`1`	`func ElementsMatch(t TestingT, listA, listB interface{}, msgAndArgs ...interface{}) bool`

ElementsMatch断言listA和listB包含相同的元素，忽略元素出现的顺序。listA/listB必须是数组或切片。如果有重复元素，重复元素出现的次数也必须相等。

`Empty`

函数类型：

`1`	`func Empty(t TestingT, object interface{}, msgAndArgs ...interface{}) bool`

Empty断言object是空，根据object中存储的实际类型，空的含义不同：

指针：nil；
整数：0；
浮点数：0.0；
字符串：空串""；
布尔：false；
切片或 channel：长度为 0。

`EqualError`

函数类型：

`1`	`func EqualError(t TestingT, theError error, errString string, msgAndArgs ...interface{}) bool`

EqualError断言theError.Error()的返回值与errString相等。

`EqualValues`

函数类型：

`1`	`func EqualValues(t TestingT, expected, actual interface{}, msgAndArgs ...interface{}) bool`

EqualValues断言expected与actual相等，或者可以转换为相同的类型，并且相等。这个条件比Equal更宽，Equal()返回true则EqualValues()肯定也返回true，反之则不然。实现的核心是下面两个函数，使用了reflect.DeapEqual()：

func ObjectsAreEqual(expected, actual interface{}) bool {
  if expected == nil || actual == nil {
    return expected == actual
  }

  exp, ok := expected.([]byte)
  if !ok {
    return reflect.DeepEqual(expected, actual)
  }

  act, ok := actual.([]byte)
  if !ok {
    return false
  }
  if exp == nil || act == nil {
    return exp == nil && act == nil
  }
  return bytes.Equal(exp, act)
}

func ObjectsAreEqualValues(expected, actual interface{}) bool {
    // 如果`ObjectsAreEqual`返回 true，直接返回
  if ObjectsAreEqual(expected, actual) {
    return true
  }

  actualType := reflect.TypeOf(actual)
  if actualType == nil {
    return false
  }
  expectedValue := reflect.ValueOf(expected)
  if expectedValue.IsValid() && expectedValue.Type().ConvertibleTo(actualType) {
    // 尝试类型转换
    return reflect.DeepEqual(expectedValue.Convert(actualType).Interface(), actual)
  }

  return false
}

例如我基于int定义了一个新类型MyInt，它们的值都是 100，Equal()调用将返回 false，EqualValues()会返回 true：

type MyInt int

func TestEqual(t *testing.T) {
  var a = 100
  var b MyInt = 100
  assert.Equal(t, a, b, "")
  assert.EqualValues(t, a, b, "")
}

`Error`

函数类型：

`1`	`func Error(t TestingT, err error, msgAndArgs ...interface{}) bool`

Error断言err不为nil。

`ErrorAs`

函数类型：

`1`	`func ErrorAs(t TestingT, err error, target interface{}, msgAndArgs ...interface{}) bool`

ErrorAs断言err表示的 error 链中至少有一个和target匹配。这个函数是对标准库中errors.As的包装。

`ErrorIs`

函数类型：

`1`	`func ErrorIs(t TestingT, err, target error, msgAndArgs ...interface{}) bool`

ErrorIs断言err的 error 链中有target。

逆断言

上面的断言都是它们的逆断言，例如NotEqual/NotEqualValues等。

Assertions 对象

观察到上面的断言都是以TestingT为第一个参数，需要大量使用时比较麻烦。testify提供了一种方便的方式。先以*testing.T创建一个*Assertions对象，Assertions定义了前面所有的断言方法，只是不需要再传入TestingT参数了。

func TestEqual(t *testing.T) {
  assertions := assert.New(t)
  assertion.Equal(a, b, "")
  // ...
}

顺带提一句TestingT是一个接口，对*testing.T做了一个简单的包装：

1
2
3

type TestingT interface{
  Errorf(format string, args ...interface{})
}

require

require提供了和assert同样的接口，但是遇到错误时，require直接终止测试，而assert返回false。

mock

testify提供了对 Mock 的简单支持。Mock 简单来说就是构造一个仿对象，仿对象提供和原对象一样的接口，在测试中用仿对象来替换原对象。这样我们可以在原对象很难构造，特别是涉及外部资源（数据库，访问网络等）。例如，我们现在要编写一个从一个站点拉取用户列表信息的程序，拉取完成之后程序显示和分析。如果每次都去访问网络会带来极大的不确定性，甚至每次返回不同的列表，这就给测试带来了极大的困难。我们可以使用 Mock 技术。

package main

import (
  "encoding/json"
  "fmt"
  "io/ioutil"
  "net/http"
)

type User struct {
  Name string
  Age  int
}

type ICrawler interface {
  GetUserList() ([]*User, error)
}

type MyCrawler struct {
  url string
}

func (c *MyCrawler) GetUserList() ([]*User, error) {
  resp, err := http.Get(c.url)
  if err != nil {
    return nil, err
  }

  defer resp.Body.Close()
  data, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    return nil, err
  }

  var userList []*User
  err = json.Unmarshal(data, &userList)
  if err != nil {
    return nil, err
  }

  return userList, nil
}

func GetAndPrintUsers(crawler ICrawler) {
  users, err := crawler.GetUserList()
  if err != nil {
    return
  }

  for _, u := range users {
    fmt.Println(u)
  }
}

Crawler.GetUserList()方法完成爬取和解析操作，返回用户列表。为了方便 Mock，GetAndPrintUsers()函数接受一个ICrawler接口。现在来定义我们的 Mock 对象，实现ICrawler接口：

package main

import (
  "github.com/stretchr/testify/mock"
  "testing"
)

type MockCrawler struct {
  mock.Mock
}

func (m *MockCrawler) GetUserList() ([]*User, error) {
  args := m.Called()
  return args.Get(0).([]*User), args.Error(1)
}

var (
  MockUsers []*User
)

func init() {
  MockUsers = append(MockUsers, &User{"dj", 18})
  MockUsers = append(MockUsers, &User{"zhangsan", 20})
}

func TestGetUserList(t *testing.T) {
  crawler := new(MockCrawler)
  crawler.On("GetUserList").Return(MockUsers, nil)

  GetAndPrintUsers(crawler)

  crawler.AssertExpectations(t)
}

实现GetUserList()方法时，需要调用Mock.Called()方法，传入参数（示例中无参数）。Called()会返回一个mock.Arguments对象，该对象中保存着返回的值。它提供了对基本类型和error的获取方法Int()/String()/Bool()/Error()，和通用的获取方法Get()，通用方法返回interface{}，需要类型断言为具体类型，它们都接受一个表示索引的参数。

crawler.On("GetUserList").Return(MockUsers, nil)是 Mock 发挥魔法的地方，这里指示调用GetUserList()方法的返回值分别为MockUsers和nil，返回值在上面的GetUserList()方法中被Arguments.Get(0)和Arguments.Error(1)获取。

最后crawler.AssertExpectations(t)对 Mock 对象做断言。

运行：

$ go test
&{dj 18}
&{zhangsan 20}
PASS
ok      github.com/darjun/testify       0.258s

GetAndPrintUsers()函数功能正常执行，并且我们通过 Mock 提供的用户列表也能正确获取。

使用 Mock，我们可以精确断言某方法以特定参数的调用次数，Times(n int)，它有两个便捷函数Once()/Twice()。下面我们要求函数Hello(n int)要以参数 1 调用 1次，参数 2 调用两次，参数 3 调用 3 次：

type IExample interface {
  Hello(n int) int
}

type Example struct {
}

func (e *Example) Hello(n int) int {
  fmt.Printf("Hello with %d\n", n)
  return n
}

func ExampleFunc(e IExample) {
  for n := 1; n <= 3; n++ {
    for i := 0; i <= n; i++ {
      e.Hello(n)
    }
  }
}

编写 Mock 对象：

type MockExample struct {
  mock.Mock
}

func (e *MockExample) Hello(n int) int {
  args := e.Mock.Called(n)
  return args.Int(0)
}

func TestExample(t *testing.T) {
  e := new(MockExample)

  e.On("Hello", 1).Return(1).Times(1)
  e.On("Hello", 2).Return(2).Times(2)
  e.On("Hello", 3).Return(3).Times(3)

  ExampleFunc(e)

  e.AssertExpectations(t)
}

运行：

$ go test
--- FAIL: TestExample (0.00s)
panic:
assert: mock: The method has been called over 1 times.
        Either do one more Mock.On("Hello").Return(...), or remove extra call.
        This call was unexpected:
                Hello(int)
                0: 1
        at: [equal_test.go:13 main.go:22] [recovered]

原来ExampleFunc()函数中<=应该是<导致多调用了一次，修改过来继续运行：

1
2
3

$ go test
PASS
ok      github.com/darjun/testify       0.236s

我们还可以设置以指定参数调用会导致 panic，测试程序的健壮性：

`1`	`e.On("Hello", 100).Panic("out of range")`

suite

testify提供了测试套件的功能（TestSuite），testify测试套件只是一个结构体，内嵌一个匿名的suite.Suite结构。测试套件中可以包含多个测试，它们可以共享状态，还可以定义钩子方法执行初始化和清理操作。钩子都是通过接口来定义的，实现了这些接口的测试套件结构在运行到指定节点时会调用对应的方法。

1
2
3

type SetupAllSuite interface {
  SetupSuite()
}

如果定义了SetupSuite()方法（即实现了SetupAllSuite接口），在套件中所有测试开始运行前调用这个方法。对应的是TearDownAllSuite：

1
2
3

type TearDownAllSuite interface {
  TearDownSuite()
}

如果定义了TearDonwSuite()方法（即实现了TearDownSuite接口），在套件中所有测试运行完成后调用这个方法。

1
2
3

type SetupTestSuite interface {
  SetupTest()
}

如果定义了SetupTest()方法（即实现了SetupTestSuite接口），在套件中每个测试执行前都会调用这个方法。对应的是TearDownTestSuite：

1
2
3

type TearDownTestSuite interface {
  TearDownTest()
}

如果定义了TearDownTest()方法（即实现了TearDownTest接口），在套件中每个测试执行后都会调用这个方法。

还有一对接口BeforeTest/AfterTest，它们分别在每个测试运行前/后调用，接受套件名和测试名作为参数。

我们来编写一个测试套件结构作为演示：

type MyTestSuit struct {
  suite.Suite
  testCount uint32
}

func (s *MyTestSuit) SetupSuite() {
  fmt.Println("SetupSuite")
}

func (s *MyTestSuit) TearDownSuite() {
  fmt.Println("TearDownSuite")
}

func (s *MyTestSuit) SetupTest() {
  fmt.Printf("SetupTest test count:%d\n", s.testCount)
}

func (s *MyTestSuit) TearDownTest() {
  s.testCount++
  fmt.Printf("TearDownTest test count:%d\n", s.testCount)
}

func (s *MyTestSuit) BeforeTest(suiteName, testName string) {
  fmt.Printf("BeforeTest suite:%s test:%s\n", suiteName, testName)
}

func (s *MyTestSuit) AfterTest(suiteName, testName string) {
  fmt.Printf("AfterTest suite:%s test:%s\n", suiteName, testName)
}

func (s *MyTestSuit) TestExample() {
  fmt.Println("TestExample")
}

这里只是简单在各个钩子函数中打印信息，统计执行完成的测试数量。由于要借助go test运行，所以需要编写一个TestXxx函数，在该函数中调用suite.Run()运行测试套件：

1
2
3

func TestExample(t *testing.T) {
  suite.Run(t, new(MyTestSuit))
}

suite.Run(t, new(MyTestSuit))会将运行MyTestSuit中所有名为TestXxx的方法。运行：

$ go test
SetupSuite
SetupTest test count:0
BeforeTest suite:MyTestSuit test:TestExample
TestExample
AfterTest suite:MyTestSuit test:TestExample
TearDownTest test count:1
TearDownSuite
PASS
ok      github.com/darjun/testify       0.375s

测试 HTTP 服务器

Go 标准库提供了一个httptest用于测试 HTTP 服务器。现在编写一个简单的 HTTP 服务器：

func index(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintln(w, "Hello World")
}

func greeting(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintf(w, "welcome, %s", r.URL.Query().Get("name"))
}

func main() {
  mux := http.NewServeMux()
  mux.HandleFunc("/", index)
  mux.HandleFunc("/greeting", greeting)

  server := &http.Server{
    Addr:    ":8080",
    Handler: mux,
  }

  if err := server.ListenAndServe(); err != nil {
    log.Fatal(err)
  }
}

很简单。httptest提供了一个ResponseRecorder类型，它实现了http.ResponseWriter接口，但是它只是记录写入的状态码和响应内容，不会发送响应给客户端。这样我们可以将该类型的对象传给处理器函数。然后构造服务器，传入该对象来驱动请求处理流程，最后测试该对象中记录的信息是否正确：

func TestIndex(t *testing.T) {
  recorder := httptest.NewRecorder()
  request, _ := http.NewRequest("GET", "/", nil)
  mux := http.NewServeMux()
  mux.HandleFunc("/", index)
  mux.HandleFunc("/greeting", greeting)

  mux.ServeHTTP(recorder, request)

  assert.Equal(t, recorder.Code, 200, "get index error")
  assert.Contains(t, recorder.Body.String(), "Hello World", "body error")
}

func TestGreeting(t *testing.T) {
  recorder := httptest.NewRecorder()
  request, _ := http.NewRequest("GET", "/greeting", nil)
  request.URL.RawQuery = "name=dj"
  mux := http.NewServeMux()
  mux.HandleFunc("/", index)
  mux.HandleFunc("/greeting", greeting)

  mux.ServeHTTP(recorder, request)

  assert.Equal(t, recorder.Code, 200, "greeting error")
  assert.Contains(t, recorder.Body.String(), "welcome, dj", "body error")
}

运行：

1
2
3

$ go test
PASS
ok      github.com/darjun/go-daily-lib/testify/httptest 0.093s

很简单，没有问题。

但是我们发现一个问题，上面的很多代码有重复，recorder/mux等对象的创建，处理器函数的注册。使用suite我们可以集中创建，省略这些重复的代码：

type MySuite struct {
  suite.Suite
  recorder *httptest.ResponseRecorder
  mux      *http.ServeMux
}

func (s *MySuite) SetupSuite() {
  s.recorder = httptest.NewRecorder()
  s.mux = http.NewServeMux()
  s.mux.HandleFunc("/", index)
  s.mux.HandleFunc("/greeting", greeting)
}

func (s *MySuite) TestIndex() {
  request, _ := http.NewRequest("GET", "/", nil)
  s.mux.ServeHTTP(s.recorder, request)

  s.Assert().Equal(s.recorder.Code, 200, "get index error")
  s.Assert().Contains(s.recorder.Body.String(), "Hello World", "body error")
}

func (s *MySuite) TestGreeting() {
  request, _ := http.NewRequest("GET", "/greeting", nil)
  request.URL.RawQuery = "name=dj"

  s.mux.ServeHTTP(s.recorder, request)

  s.Assert().Equal(s.recorder.Code, 200, "greeting error")
  s.Assert().Contains(s.recorder.Body.String(), "welcome, dj", "body error")
}

最后编写一个TestXxx驱动测试：

1
2
3

func TestHTTP(t *testing.T) {
  suite.Run(t, new(MySuite))
}

总结

testify扩展了testing标准库，断言库assert，测试替身mock和测试套件suite，让我们编写测试代码更容易！

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

参考

testify GitHub：github.com/stretchr/testify
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 testing

Tue, 03 Aug 2021 23:30:23 +0000

简介

testing是 Go 语言标准库自带的测试库。在 Go 语言中编写测试很简单，只需要遵循 Go 测试的几个约定，与编写正常的 Go 代码没有什么区别。Go 语言中有 3 种类型的测试：单元测试，性能测试，示例测试。下面依次来介绍。

单元测试

单元测试又称为功能性测试，是为了测试函数、模块等代码的逻辑是否正确。接下来我们编写一个库，用于将表示罗马数字的字符串和整数互转。罗马数字是由M/D/C/L/X/V/I这几个字符根据一定的规则组合起来表示一个正整数：

M=1000，D=500，C=100，L=50，X=10，V=5，I=1；
只能表示 1-3999 范围内的整数，不能表示 0 和负数，不能表示 4000 及以上的整数，不能表示分数和小数（当然有其他复杂的规则来表示这些数字，这里暂不考虑）；
每个整数只有一种表示方式，一般情况下，连写的字符表示对应整数相加，例如I=1，II=2，III=3。但是，十位字符（I/X/C/M）最多出现 3 次，所以不能用IIII表示 4，需要在V左边添加一个I（即IV）来表示，不能用VIIII表示 9，需要使用IX代替。另外五位字符（V/L/D）不能连续出现 2 次，所以不能出现VV，需要用X代替。

// roman.go
package roman

import (
  "bytes"
  "errors"
  "regexp"
)

type romanNumPair struct {
  Roman string
  Num   int
}

var (
  romanNumParis []romanNumPair
  romanRegex    *regexp.Regexp
)

var (
  ErrOutOfRange   = errors.New("out of range")
  ErrInvalidRoman = errors.New("invalid roman")
)

func init() {
  romanNumParis = []romanNumPair{
    {"M", 1000},
    {"CM", 900},
    {"D", 500},
    {"CD", 400},
    {"C", 100},
    {"XC", 90},
    {"L", 50},
    {"XL", 40},
    {"X", 10},
    {"IX", 9},
    {"V", 5},
    {"IV", 4},
    {"I", 1},
  }

  romanRegex = regexp.MustCompile(`^M{0,3}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})$`)
}

func ToRoman(n int) (string, error) {
  if n <= 0 || n >= 4000 {
    return "", ErrOutOfRange
  }
  var buf bytes.Buffer
  for _, pair := range romanNumParis {
    for n > pair.Num {
      buf.WriteString(pair.Roman)
      n -= pair.Num
    }
  }

  return buf.String(), nil
}

func FromRoman(roman string) (int, error) {
  if !romanRegex.MatchString(roman) {
    return 0, ErrInvalidRoman
  }

  var result int
  var index int
  for _, pair := range romanNumParis {
    for roman[index:index+len(pair.Roman)] == pair.Roman {
      result += pair.Num
      index += len(pair.Roman)
    }
  }

  return result, nil
}

在 Go 中编写测试很简单，只需要在待测试功能所在文件的同级目录中创建一个以_test.go结尾的文件。在该文件中，我们可以编写一个个测试函数。测试函数名必须是TestXxxx这个形式，而且Xxxx必须以大写字母开头，另外函数带有一个*testing.T类型的参数：

// roman_test.go
package roman

import (
  "testing"
)

func TestToRoman(t *testing.T) {
  _, err1 := ToRoman(0)
  if err1 != ErrOutOfRange {
    t.Errorf("ToRoman(0) expect error:%v got:%v", ErrOutOfRange, err1)
  }

  roman2, err2 := ToRoman(1)
  if err2 != nil {
    t.Errorf("ToRoman(1) expect nil error, got:%v", err2)
  }
  if roman2 != "I" {
    t.Errorf("ToRoman(1) expect:%s got:%s", "I", roman2)
  }
}

在测试函数中编写的代码与正常的代码没有什么不同，调用相应的函数，返回结果，判断结果与预期是否一致，如果不一致则调用testing.T的Errorf()输出错误信息。运行测试时，这些错误信息会被收集起来，运行结束后统一输出。

测试编写完成之后，使用go test命令运行测试，输出结果：

$ go test
--- FAIL: TestToRoman (0.00s)
    roman_test.go:18: ToRoman(1) expect:I got:
FAIL
exit status 1
FAIL    github.com/darjun/go-daily-lib/testing  0.172s

我故意将ToRoman()函数中写错了一行代码，n > pair.Num中>应该为>=，单元测试成功找出了错误。修改之后重新运行测试：

1
2
3

$ go test
PASS
ok      github.com/darjun/go-daily-lib/testing  0.178s

这次测试都通过了！

我们还可以给go test命令传入-v选项，输出详细的测试信息：

$ go test -v
=== RUN   TestToRoman
--- PASS: TestToRoman (0.00s)
PASS
ok      github.com/darjun/go-daily-lib/testing  0.174s

在运行每个测试函数前，都输出一行=== RUN，运行结束之后输出--- PASS或--- FAIL信息。

表格驱动测试

在上面的例子中，我们实际上只测试了两种情况，0 和 1。按照这种方式将每种情况都写出来就太繁琐了，Go 中流行使用表格的方式将各个测试数据和结果列举出来：

func TestToRoman(t *testing.T) {
  testCases := []struct {
    num    int
    expect string
    err    error
  }{
    {0, "", ErrOutOfRange},
    {1, "I", nil},
    {2, "II", nil},
    {3, "III", nil},
    {4, "IV", nil},
    {5, "V", nil},
    {6, "VI", nil},
    {7, "VII", nil},
    {8, "VIII", nil},
    {9, "IX", nil},
    {10, "X", nil},
    {50, "L", nil},
    {100, "C", nil},
    {500, "D", nil},
    {1000, "M", nil},
    {31, "XXXI", nil},
    {148, "CXLVIII", nil},
    {294, "CCXCIV", nil},
    {312, "CCCXII", nil},
    {421, "CDXXI", nil},
    {528, "DXXVIII", nil},
    {621, "DCXXI", nil},
    {782, "DCCLXXXII", nil},
    {870, "DCCCLXX", nil},
    {941, "CMXLI", nil},
    {1043, "MXLIII", nil},
    {1110, "MCX", nil},
    {1226, "MCCXXVI", nil},
    {1301, "MCCCI", nil},
    {1485, "MCDLXXXV", nil},
    {1509, "MDIX", nil},
    {1607, "MDCVII", nil},
    {1754, "MDCCLIV", nil},
    {1832, "MDCCCXXXII", nil},
    {1993, "MCMXCIII", nil},
    {2074, "MMLXXIV", nil},
    {2152, "MMCLII", nil},
    {2212, "MMCCXII", nil},
    {2343, "MMCCCXLIII", nil},
    {2499, "MMCDXCIX", nil},
    {2574, "MMDLXXIV", nil},
    {2646, "MMDCXLVI", nil},
    {2723, "MMDCCXXIII", nil},
    {2892, "MMDCCCXCII", nil},
    {2975, "MMCMLXXV", nil},
    {3051, "MMMLI", nil},
    {3185, "MMMCLXXXV", nil},
    {3250, "MMMCCL", nil},
    {3313, "MMMCCCXIII", nil},
    {3408, "MMMCDVIII", nil},
    {3501, "MMMDI", nil},
    {3610, "MMMDCX", nil},
    {3743, "MMMDCCXLIII", nil},
    {3844, "MMMDCCCXLIV", nil},
    {3888, "MMMDCCCLXXXVIII", nil},
    {3940, "MMMCMXL", nil},
    {3999, "MMMCMXCIX", nil},
    {4000, "", ErrOutOfRange},
  }

  for _, testCase := range testCases {
    got, err := ToRoman(testCase.num)
    if got != testCase.expect {
      t.Errorf("ToRoman(%d) expect:%s got:%s", testCase.num, testCase.expect, got)
    }

    if err != testCase.err {
      t.Errorf("ToRoman(%d) expect error:%v got:%v", testCase.num, testCase.err, err)
    }
  }
}

上面将要测试的每种情况列举出来，然后针对每个整数调用ToRoman()函数，比较返回的罗马数字字符串和错误值是否与预期的相符。后续要添加新的测试用例也很方便。

分组和并行

有时候对同一个函数有不同维度的测试，将这些组合在一起有利于维护。例如上面对ToRoman()函数的测试可以分为非法值，单个罗马字符和普通 3 种情况。

为了分组，我对代码做了一定程度的重构，首先抽象一个toRomanCase结构：

type toRomanCase struct {
  num    int
  expect string
  err    error
}

将所有的测试数据划分到 3 个组中：

var (
  toRomanInvalidCases []toRomanCase
  toRomanSingleCases  []toRomanCase
  toRomanNormalCases  []toRomanCase
)

func init() {
  toRomanInvalidCases = []toRomanCase{
    {0, "", roman.ErrOutOfRange},
    {4000, "", roman.ErrOutOfRange},
  }

  toRomanSingleCases = []toRomanCase{
    {1, "I", nil},
    {5, "V", nil},
    // ...
  }

  toRomanNormalCases = []toRomanCase{
    {2, "II", nil},
    {3, "III", nil},
    // ...
  }
}

然后为了避免代码重复，抽象一个运行多个toRomanCase的函数：

func testToRomanCases(cases []toRomanCase, t *testing.T) {
  for _, testCase := range cases {
    got, err := roman.ToRoman(testCase.num)
    if got != testCase.expect {
      t.Errorf("ToRoman(%d) expect:%s got:%s", testCase.num, testCase.expect, got)
    }

    if err != testCase.err {
      t.Errorf("ToRoman(%d) expect error:%v got:%v", testCase.num, testCase.err, err)
    }
  }
}

为每个分组定义一个测试函数：

func testToRomanInvalid(t *testing.T) {
  testToRomanCases(toRomanInvalidCases, t)
}

func testToRomanSingle(t *testing.T) {
  testToRomanCases(toRomanSingleCases, t)
}

func testToRomanNormal(t *testing.T) {
  testToRomanCases(toRomanNormalCases, t)
}

在原来的测试函数中，调用t.Run()运行不同分组的测试函数，t.Run()第一个参数为子测试名，第二个参数为子测试函数：

func TestToRoman(t *testing.T) {
  t.Run("Invalid", testToRomanInvalid)
  t.Run("Single", testToRomanSingle)
  t.Run("Normal", testToRomanNormal)
}

运行：

$ go test -v
=== RUN   TestToRoman
=== RUN   TestToRoman/Invalid
=== RUN   TestToRoman/Single
=== RUN   TestToRoman/Normal
--- PASS: TestToRoman (0.00s)
    --- PASS: TestToRoman/Invalid (0.00s)
    --- PASS: TestToRoman/Single (0.00s)
    --- PASS: TestToRoman/Normal (0.00s)
PASS
ok      github.com/darjun/go-daily-lib/testing  0.188s

可以看到，依次运行 3 个子测试，子测试名是父测试名和t.Run()指定的名字组合而成的，如TestToRoman/Invalid。

默认情况下，这些测试都是依次顺序执行的。如果各个测试之间没有联系，我们可以让他们并行以加快测试速度。方法也很简单，在testToRomanInvalid/testToRomanSingle/testToRomanNormal这 3 个函数开始处调用t.Parallel()，由于这 3 个函数直接调用了testToRomanCases，也可以只在testToRomanCases函数开头出添加：

func testToRomanCases(cases []toRomanCase, t *testing.T) {
  t.Parallel()
  // ...
}

运行：

$ go test -v
...
--- PASS: TestToRoman (0.00s)
    --- PASS: TestToRoman/Invalid (0.00s)
    --- PASS: TestToRoman/Normal (0.00s)
    --- PASS: TestToRoman/Single (0.00s)
PASS
ok      github.com/darjun/go-daily-lib/testing  0.182s

我们发现测试完成的顺序并不是我们指定的顺序。

另外，这个示例中我将roman_test.go文件移到了roman_test包中，所以需要import "github.com/darjun/go-daily-lib/testing/roman"。这种方式在测试包有循环依赖的情况下非常有用，例如标准库中net/http依赖net/url，url的测试函数依赖net/http，如果把测试放在net/url包中，那么就会导致循环依赖url_test(net/url)->net/http->net/url。这时可以将url_test放在一个独立的包中。

主测试函数

有一种特殊的测试函数，函数名为TestMain()，接受一个*testing.M类型的参数。这个函数一般用于在运行所有测试前执行一些初始化逻辑（如创建数据库链接），或所有测试都运行结束之后执行一些清理逻辑（释放数据库链接）。如果测试文件中定义了这个函数，则go test命令会直接运行这个函数，否者go test会创建一个默认的TestMain()函数。这个函数的默认行为就是运行文件中定义的测试。我们自定义TestMain()函数时，也需要手动调用m.Run()方法运行测试函数，否则测试函数不会运行。默认的TestMain()类似下面代码：

1
2
3

func TestMain(m *testing.M) {
  os.Exit(m.Run())
}

下面自定义一个TestMain()函数，打印go test支持的选项：

func TestMain(m *testing.M) {
  flag.Parse()
  flag.VisitAll(func(f *flag.Flag) {
    fmt.Printf("name:%s usage:%s value:%v\n", f.Name, f.Usage, f.Value)
  })
  os.Exit(m.Run())
}

运行：

$ go test -v
name:test.bench usage:run only benchmarks matching `regexp` value:
name:test.benchmem usage:print memory allocations for benchmarks value:false
name:test.benchtime usage:run each benchmark for duration `d` value:1s
name:test.blockprofile usage:write a goroutine blocking profile to `file` value:
name:test.blockprofilerate usage:set blocking profile `rate` (see runtime.SetBlockProfileRate) value:1
name:test.count usage:run tests and benchmarks `n` times value:1
name:test.coverprofile usage:write a coverage profile to `file` value:
name:test.cpu usage:comma-separated `list` of cpu counts to run each test with value:
name:test.cpuprofile usage:write a cpu profile to `file` value:
name:test.failfast usage:do not start new tests after the first test failure value:false
name:test.list usage:list tests, examples, and benchmarks matching `regexp` then exit value:
name:test.memprofile usage:write an allocation profile to `file` value:
name:test.memprofilerate usage:set memory allocation profiling `rate` (see runtime.MemProfileRate) value:0
name:test.mutexprofile usage:write a mutex contention profile to the named file after execution value:
name:test.mutexprofilefraction usage:if >= 0, calls runtime.SetMutexProfileFraction() value:1
name:test.outputdir usage:write profiles to `dir` value:
name:test.paniconexit0 usage:panic on call to os.Exit(0) value:true
name:test.parallel usage:run at most `n` tests in parallel value:8
name:test.run usage:run only tests and examples matching `regexp` value:
name:test.short usage:run smaller test suite to save time value:false
name:test.testlogfile usage:write test action log to `file` (for use only by cmd/go) value:
name:test.timeout usage:panic test binary after duration `d` (default 0, timeout disabled) value:10m0s
name:test.trace usage:write an execution trace to `file` value:
name:test.v usage:verbose: print additional output value:tru

这些选项也可以通过go help testflag查看。

其他

另一个函数FromRoman()我没有写任何测试，就交给大家了😀

性能测试

性能测试是为了对函数的运行性能进行评测。性能测试也必须在_test.go文件中编写，且函数名必须是BenchmarkXxxx开头。性能测试函数接受一个*testing.B的参数。下面我们编写 3 个计算第 n 个斐波那契数的函数。

第一种方式：递归

func Fib1(n int) int {
  if n <= 1 {
    return n
  }
  
  return Fib1(n-1) + Fib1(n-2)
}

第二种方式：备忘录

func fibHelper(n int, m map[int]int) int {
  if n <= 1 {
    return n
  }

  if v, ok := m[n]; ok {
    return v
  }
  
  v := fibHelper(n-2, m) + fibHelper(n-1, m)
  m[n] = v
  return v
}

func Fib2(n int) int {
  m := make(map[int]int)
  return fibHelper(n, m)
}

第三种方式：迭代

func Fib3(n int) int {
  if n <= 1 {
    return n
  }
  
  f1, f2 := 0, 1
  for i := 2; i <= n; i++ {
    f1, f2 = f2, f1+f2
  }
  
  return f2
}

下面我们来测试这 3 个函数的执行效率：

// fib_test.go
func BenchmarkFib1(b *testing.B) {
  for i := 0; i < b.N; i++ {
    Fib1(20)
  }
}

func BenchmarkFib2(b *testing.B) {
  for i := 0; i < b.N; i++ {
    Fib2(20)
  }
}

func BenchmarkFib3(b *testing.B) {
  for i := 0; i < b.N; i++ {
    Fib3(20)
  }
}

需要特别注意的是N，go test会一直调整这个数值，直到测试时间能得出可靠的性能数据为止。运行：

$ go test -bench=.
goos: windows
goarch: amd64
pkg: github.com/darjun/go-daily-lib/testing/fib
cpu: Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz
BenchmarkFib1-8            31110             39144 ns/op
BenchmarkFib2-8           582637              3127 ns/op
BenchmarkFib3-8         191600582            5.588 ns/op
PASS
ok      github.com/darjun/go-daily-lib/testing/fib      5.225s

性能测试默认不会执行，需要通过-bench=.指定运行。-bench选项的值是一个简单的模式，.表示匹配所有的，Fib表示运行名字中有Fib的。

上面的测试结果表示Fib1在指定时间内执行了 31110 次，平均每次 39144 ns，Fib2在指定时间内运行了 582637 次，平均每次耗时 3127 ns，Fib3在指定时间内运行了 191600582 次，平均每次耗时 5.588 ns。

其他选项

有一些选项可以控制性能测试的执行。

-benchtime：设置每个测试的运行时间。

`1`	`$ go test -bench=. -benchtime=30s`

运行了更长的时间：

$ go test -bench=. -benchtime=30s
goos: windows
goarch: amd64
pkg: github.com/darjun/go-daily-lib/testing/fib
cpu: Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz
BenchmarkFib1-8           956464             38756 ns/op
BenchmarkFib2-8         17862495              2306 ns/op
BenchmarkFib3-8       1000000000             5.591 ns/op
PASS
ok      github.com/darjun/go-daily-lib/testing/fib      113.498s

-benchmem：输出性能测试函数的内存分配情况。

-memprofile file：将内存分配数据写入文件。

-cpuprofile file：将 CPU 采样数据写入文件，方便使用go tool pprof工具分析，详见我的另一篇文章《你不知道的 Go 之 pprof》

运行：

$ go test -bench=. -benchtime=10s -cpuprofile=./cpu.prof -memprofile=./mem.prof
goos: windows
goarch: amd64
pkg: github.com/darjun/fib
BenchmarkFib1-16          356006             33423 ns/op
BenchmarkFib2-16         8958194              1340 ns/op
BenchmarkFib3-16        1000000000               6.60 ns/op
PASS
ok      github.com/darjun/fib   33.321s

同时生成了 CPU 采样数据和内存分配数据，通过go tool pprof分析：

$ go tool pprof ./cpu.prof
Type: cpu
Time: Aug 4, 2021 at 10:21am (CST)
Duration: 32.48s, Total samples = 36.64s (112.81%)
Entering interactive mode (type "help" for commands, "o" for options)
(pprof) top10
Showing nodes accounting for 29640ms, 80.90% of 36640ms total
Dropped 153 nodes (cum <= 183.20ms)
Showing top 10 nodes out of 74
      flat  flat%   sum%        cum   cum%
   11610ms 31.69% 31.69%    11620ms 31.71%  github.com/darjun/fib.Fib1
    6490ms 17.71% 49.40%     6680ms 18.23%  github.com/darjun/fib.Fib3
    2550ms  6.96% 56.36%     8740ms 23.85%  runtime.mapassign_fast64
    2050ms  5.59% 61.95%     2060ms  5.62%  runtime.stdcall2
    1620ms  4.42% 66.38%     2140ms  5.84%  runtime.mapaccess2_fast64
    1480ms  4.04% 70.41%    12350ms 33.71%  github.com/darjun/fib.fibHelper
    1480ms  4.04% 74.45%     2960ms  8.08%  runtime.evacuate_fast64
    1050ms  2.87% 77.32%     1050ms  2.87%  runtime.memhash64
     760ms  2.07% 79.39%      760ms  2.07%  runtime.stdcall7
     550ms  1.50% 80.90%     7230ms 19.73%  github.com/darjun/fib.BenchmarkFib3
(pprof)

内存：

$ go tool pprof ./mem.prof
Type: alloc_space
Time: Aug 4, 2021 at 10:30am (CST)
Entering interactive mode (type "help" for commands, "o" for options)
(pprof) top10
Showing nodes accounting for 8.69GB, 100% of 8.69GB total
Dropped 12 nodes (cum <= 0.04GB)
      flat  flat%   sum%        cum   cum%
    8.69GB   100%   100%     8.69GB   100%  github.com/darjun/fib.fibHelper
         0     0%   100%     8.69GB   100%  github.com/darjun/fib.BenchmarkFib2
         0     0%   100%     8.69GB   100%  github.com/darjun/fib.Fib2 (inline)
         0     0%   100%     8.69GB   100%  testing.(*B).launch
         0     0%   100%     8.69GB   100%  testing.(*B).runN
(pprof)

示例测试

示例测试用于演示模块或函数的使用。同样地，示例测试也在文件_test.go中编写，并且示例测试函数名必须是ExampleXxx的形式。在Example*函数中编写代码，然后在注释中编写期望的输出，go test会运行该函数，然后将实际输出与期望的做比较。下面摘取自 Go 源码net/url/example_test.go文件中的代码演示了url.Values的用法：

func ExampleValuesGet() {
  v := url.Values{}
  v.Set("name", "Ava")
  v.Add("friend", "Jess")
  v.Add("friend", "Sarah")
  v.Add("friend", "Zoe")
  fmt.Println(v.Get("name"))
  fmt.Println(v.Get("friend"))
  fmt.Println(v["friend"])
  // Output:
  // Ava
  // Jess
  // [Jess Sarah Zoe]
}

注释中Output:后是期望的输出结果，go test会运行这些函数并与期望的结果做比较，比较会忽略空格。

有时候我们输出的顺序是不确定的，这时就需要使用Unordered Output。我们知道url.Values底层类型为map[string][]string，所以可以遍历输出所有的键值，但是输出顺序不确定：

func ExampleValuesAll() {
  v := url.Values{}
  v.Set("name", "Ava")
  v.Add("friend", "Jess")
  v.Add("friend", "Sarah")
  v.Add("friend", "Zoe")
  for key, values := range v {
    fmt.Println(key, values)
  }
  // Unordered Output:
  // name [Ava]
  // friend [Jess Sarah Zoe]
}

运行：

$ go test -v
$ go test -v
=== RUN   ExampleValuesGet
--- PASS: ExampleValuesGet (0.00s)
=== RUN   ExampleValuesAll
--- PASS: ExampleValuesAll (0.00s)
PASS
ok      github.com/darjun/url   0.172s

没有注释，或注释中无Output/Unordered Output的函数会被忽略。

总结

本文介绍了 Go 中的 3 种测试：单元测试，性能测试和示例测试。为了让程序更可靠，让以后的重构更安全、更放心，单元测试必不可少。排查程序中的性能问题，性能测试能派上大用场。示例测试主要是为了演示如何使用某个功能。

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

参考

testing 官方文档: https://golang.google.cn/pkg/testing/
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 goth

Mon, 26 Jul 2021 00:32:11 +0000

简介

当前很多网站直接采用第三方认证登录，例如支付宝/微信/ Github 等。goth封装了接入第三方认证的方法，并且内置实现了很多第三方认证的实现：

图中截取的只是goth支持的一部分，完整列表可在其GitHub 首页查看。

快速使用

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir goth && cd goth
$ go mod init github.com/darjun/go-daily-lib/goth

安装goth库：

`1`	`$ go get -u github.com/markbates/goth`

我们设计了两个页面，一个登录页面：

1
2

// login.tpl
<a href="/auth/github?provider=github">Login With GitHub</a>

点击登录链接会请求/auth/github?provider=github。

一个主界面：

// home.tpl
<p><a href="/logout/github">logout</a></p>
<p>Name: {{.Name}} [{{.LastName}}, {{.FirstName}}]</p>
<p>Email: {{.Email}}</p>
<p>NickName: {{.NickName}}</p>
<p>Location: {{.Location}}</p>
<p>AvatarURL: {{.AvatarURL}} <img src="{{.AvatarURL}}"></p>
<p>Description: {{.Description}}</p>
<p>UserID: {{.UserID}}</p>
<p>AccessToken: {{.AccessToken}}</p>
<p>ExpiresAt: {{.ExpiresAt}}</p>
<p>RefreshToken: {{.RefreshToken}}</p>

显示用户的基本信息。

同样地，我们使用html/template标准模板库来加载和管理页面模板：

var (
  ptTemplate *template.Template
)

func init() {
  ptTemplate = template.Must(template.New("").ParseGlob("tpls/*.tpl"))
}

主页面处理如下：

func HomeHandler(w http.ResponseWriter, r *http.Request) {
  user, err := gothic.CompleteUserAuth(w, r)
  if err != nil {
    http.Redirect(w, r, "/login/github", http.StatusTemporaryRedirect)
    return
  }
  ptTemplate.ExecuteTemplate(w, "home.tpl", user)
}

如果用户登录了，gothic.CompleteUserAuth(w, r)会返回一个非空的User对象，该类型有如下字段：

type User struct {
  RawData           map[string]interface{}
  Provider          string
  Email             string
  Name              string
  FirstName         string
  LastName          string
  NickName          string
  Description       string
  UserID            string
  AvatarURL         string
  Location          string
  AccessToken       string
  AccessTokenSecret string
  RefreshToken      string
  ExpiresAt         time.Time
  IDToken           string
}

如果已登录，显示主界面信息。如果未登录，重定向到登录界面：

1
2
3

func LoginHandler(w http.ResponseWriter, r *http.Request) {
  ptTemplate.ExecuteTemplate(w, "login.tpl", nil)
}

点击登录，由AuthHandler处理请求：

1
2
3

func AuthHandler(w http.ResponseWriter, r *http.Request) {
  gothic.BeginAuthHandler(w, r)
}

调用gothic.BeginAuthHandler(w, r)开始跳转到 GitHub 的验证界面。GitHub 验证完成后，浏览器会重定向到/auth/github/callback处理：

func CallbackHandler(w http.ResponseWriter, r *http.Request) {
  user, err := gothic.CompleteUserAuth(w, r)
  if err != nil {
    fmt.Fprintln(w, err)
    return
  }
  ptTemplate.ExecuteTemplate(w, "home.tpl", user)
}

如果登录成功，在 CallbackHandler 中，我们可以调用gothic.CompleteUserAuth(w, r)取出User对象，然后显示主页面。最后是消息路由设置：

r := mux.NewRouter()
r.HandleFunc("/", HomeHandler)
r.HandleFunc("/login/github", LoginHandler)
r.HandleFunc("/logout/github", LogoutHandler)
r.HandleFunc("/auth/github", AuthHandler)
r.HandleFunc("/auth/github/callback", CallbackHandler)

log.Println("listening on localhost:8080")
log.Fatal(http.ListenAndServe(":8080", r))

goth为我们封装了 GitHub 的验证过程，但是我们需要在 GitHub 上新增一个 OAuth App，生成 Client ID 和 Client Secret。

首先，登录 GitHub 账号，在右侧头像下拉框选择 Settings：

选择左侧 Developer Settings：

左侧选择 OAuth App，右侧点击 New OAuth App：

输入信息，重点是Authorization callback URL，这是 GitHub 验证成功之后的回调：

生成 App 之后，Client ID 会自动生成，但是 Client Secret 需要再点击右侧的按钮Generate a new client token生成：

生成了 Client Secret：

想要在程序中使用 Github，首先要创建一个 GitHub 的 Provider，调用github子包的New()方法：

`1`	`githubProvider := github.New(clientKey, clientSecret, "http://localhost:8080/auth/github/callback")`

第一个参数为 Client ID，第二个参数为 Client Secret，这两个是由上面的 OAuth App 生成的，第三个参数为回调的链接，这个必须与 OAuth App 创建时设置的一样。

然后应用这个 Provider：

`1`	`goth.UseProviders(githubProvider)`

准备工作完成，长吁一口气。现在运行程序：

`1`	`$ SECRET_KEY="secret" go run main.go`

浏览器访问localhost:8080，由于没有登录，重定向到localhost:8080/login/github：

点击Login with GitHub，会重定向到 GitHub 授权页面：

点击授权，成功之后用户信息会保存在 session 中。跳转到主页面，显示我的信息：

更换 store

goth底层使用上一篇文章中介绍的gorilla/sessions库来存储登录信息，而默认采用的是 cookie 作为存储。另外选项默认采用：

&Options{
  Path:   "/",
  Domain: "",
  MaxAge: 86400 * 30,
  HttpOnly: true,
  Secure: false,
}

如果需要更改存储方式或选项，我们可以在程序启动前，设置gothic.Store字段。例如我们要更换为 redistore：

store, _ = redistore.NewRediStore(10, "tcp", ":6379", "", []byte("redis-key"))

key := ""
maxAge := 86400 * 30  // 30 days
isProd := false

store := sessions.NewCookieStore([]byte(key))
store.MaxAge(maxAge)
store.Options.Path = "/"
store.Options.HttpOnly = true
store.Options.Secure = isProd

gothic.Store = store

总结

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

参考

goth GitHub：github.com/markbates/goth
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 gorilla/sessions

Sun, 25 Jul 2021 12:30:23 +0000

简介

上一篇文章《Go 每日一库之 securecookie》中，我们介绍了 cookie。同时提到 cookie 有两个缺点，一是数据不宜过大，二是安全问题。session 是服务器端的存储方案，可以存储大量的数据，而且不需要向客户端传输，从而解决了这两个问题。但是 session 需要一个能唯一标识用户的 ID，这个 ID 一般存放在 cookie 中发送到客户端保存，随每次请求一起发送到服务器。cookie 和 session 通常配套使用。

gorilla/sessions是 gorilla web 开发工具包中管理 session 的库。它提供了基于 cookie 和本地文件系统的 session。同时预留扩展接口，可以使用其它的后端存储 session 数据。

本文先介绍sessions提供的两种 session 存储方式，然后通过第三方扩展介绍在多个 Web 服务器实例间如何保持登录状态。

快速使用

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir -p gorilla/sessions && cd gorilla/sessions
$ go mod init github.com/darjun/go-daily-lib/gorilla/sessions

安装gorilla/sessions库：

`1`	`$ go get -u github.com/valyala/gorilla/sessions`

现在我们实现在服务器端通过 session 存储一些信息的功能：

package main

import (
  "fmt"
  "github.com/gorilla/mux"
  "github.com/gorilla/sessions"
  "log"
  "net/http"
  "os"
)

var (
  store = sessions.NewFilesystemStore("./", securecookie.GenerateRandomKey(32), securecookie.GenerateRandomKey(32))
)

func set(w http.ResponseWriter, r *http.Request) {
  session, _ := store.Get(r, "user")
  session.Values["name"] = "dj"
  session.Values["age"] = 18
  err := sessions.Save(r, w)
  if err != nil {
    http.Error(w, err.Error(), http.StatusInternalServerError)
    return
  }
  fmt.Fprintln(w, "Hello World")
}

func read(w http.ResponseWriter, r *http.Request) {
  session, _ := store.Get(r, "user")
  fmt.Fprintf(w, "name:%s age:%d\n", session.Values["name"], session.Values["age"])
}

func main() {
  r := mux.NewRouter()
  r.HandleFunc("/set", set)
  r.HandleFunc("/read", read)
  log.Fatal(http.ListenAndServe(":8080", r))
}

整个程序逻辑比较清晰，分别在/set和/read路径下挂上设置和读取的处理函数。重点是变量store。我们调用session.NewFilesystemStore()方法创建了一个*sessions.FilesystemStore类型的对象，它会将我们的 session 内容存储到文件系统（即本地磁盘上）。我们需要给NewFilesytemStore()方法传入至少 2 个参数，第一个参数指定 session 存储的本地磁盘路径。后续参数依次指定hashKey和blockKey（可省略），前者用于验证，后者用于加密，我们可以使用securecookie生成足够随机的 key，详情见前一篇介绍securecookie的文章。

sessions为所有的 session 存储抽象了一个接口Store：

type Store interface {
  Get(r *http.Request, name string) (*Session, error)
  New(r *http.Request, name string) (*Session, error)
  Save(r *http.Request, w http.ResponseWriter, s *Session) error
}

实现这个接口可以自定义我们存储 session 的位置和格式。

在set处理函数中，我们调用store.Get(r, "user")获取名为user的 session，如果 session 不存在，则创建一个新的。sessions库支持为同一个用户创建多个 session，store.Get()方法的第二个参数指定名字。获取到的*Session结构如下：

type Session struct {
  ID string
  Values  map[interface{}]interface{}
  Options *Options
  IsNew   bool
  store   Store
  name    string
}

数据直接存放在Session.Values字段中，这是一个类型为map[interface{}]interface{}的字段，几乎能保存任何类型的数据（之所以我这里要说几乎，因为还要考虑序列化到存储的限制，有些数据类型无法序列化为字节流保存，如chan）。

在set处理函数中，我们直接操作Values字段，最后我们调用store.Save(r, w, session)将 session数据保存到对应的存储中。

在get处理函数中，同样地我们先调用store.Get(r, "user")获取*Session对象，然后读取里面的name和age值。

运行：

`1`	`$ go run main.go`

首先访问localhost:8080/set，通过浏览器的开发者工具Application页签查看 cookie：

我们发现 session 的名字会作为 cookie 名发送到客户端，session ID 被保存为 cookie 的值。

然后我们访问localhost:8080/read，读取到 session 保存的数据：

另前面说过FilesystemStore数据是存储在本地硬盘上的，在运行程序的本地目录我们看到有以 session 开头的文件，文件名 session 后面的部分就是 session ID：

除了默认的将本地文件系统作为存储外，sessions还支持将 cookie 作为存储，也就是将 session 的数据直接通过 cookie 在客户端和服务器之间传输。cookie 存储的创建方式与文件系统存储的创建方式类似：

`1`	`var store = sessions.NewCookieStore(securecookie.GenerateRandomKey(32), securecookie.GenerateRandomKey(32))`

sessions.NewCookieStore()方法的第一个参数为 hashKey 用于验证，第二个参数为 blockKey 用于加密，与sessions.NewFilesystemStore()一样。

其他部分的代码完全不用修改，运行程序的结果与上面的一致。session 数据保存在 cookie 中，随每次请求由客户端传给服务器。这种方式其实就是之前文章中介绍的 cookie 用法。

记录登录状态

之前我们介绍gorilla/mux时介绍过使用 cookie 保存登录状态。当时将用户名和密码经过简单的 Base64 编码后就直接存放在 cookie 中了，基本处于“裸露”状态。只要有意，很容易就能窃取用户名和密码。现在我们将用户关键信息存储在 session 中，cookie 中只存储一个 session ID。

首先，我们设计 3 个页面，登录页面，主页面，授权才能访问的 secret 页面。登录页面只需要用户名&密码的输入框和登录按钮即可：

// login.tpl
<form action="/login" method="post">
  <label>Username:</label>
  <input name="username"><br>
  <label>Password:</label>
  <input name="password" type="password"><br>
  <button type="submit">登录</button>
</form>

登录请求根据方法不同需要执行不同的操作，GET 方法表示请求登录的页面，POST 方法表示执行登录操作。我们使用handlers.MethodHandler这个中间件来处理同一个路径的不同方法的请求：

r.Handle("/login", handlers.MethodHandler{
  "GET":  http.HandlerFunc(Login),
  "POST": http.HandlerFunc(DoLogin),
})

Login处理函数很简单，只是展示页面：

1
2
3

func Login(w http.ResponseWriter, r *http.Request) {
  ptTemplate.ExecuteTemplate(w, "login.tpl", nil)
}

这里我使用 Go 标准库html/template模版库来加载和管理各个页面的模板：

var (
  ptTemplate *template.Template
)

func init() {
  template.Must(template.New("").ParseGlob("./tpls/*.tpl"))
}

DoLogin处理函数，需要验证登录请求，然后创建User对象，保存在 session 中，接着重定向到主页面：

func DoLogin(w http.ResponseWriter, r *http.Request) {
  r.ParseForm()
  username := r.Form.Get("username")
  password := r.Form.Get("password")
  if username != "darjun" || password != "handsome" {
    http.Redirect(w, r, "/login", http.StatusFound)
    return
  }

  SaveSessionUser(w, r, &User{Username: username})
  http.Redirect(w, r, "/", http.StatusFound)
}

下面是主页面的处理，我们可以从 session 中取出保存的User对象，根据是否有User对象显示不同的页面：

// home.tpl
{% if . %}
<p>Hi, {% .Username %}</p><br>
<a href="/secret">Goto secret?</a>
{% else %}
<p>Hi, stranger</p><br>
<a href="/login">Goto login?</a>
{% end %}

HomeHandler代码如下：

func HomeHandler(w http.ResponseWriter, r *http.Request) {
  u := GetSessionUser(r)
  ptTemplate.ExecuteTemplate(w, "home.tpl", u)
}

最后是 secret 页面：

// secret.tpl
<p>
Lorem ipsum dolor sit amet consectetur adipisicing elit.
Inventore a cumque sunt pariatur nihil doloremque tempore,
consectetur ipsum sapiente id excepturi enim velit,
quis nisi esse doloribus aliquid. Incidunt, dolore.
</p>
<p>You have visited this page {% .Count %} times.</p>

显示访问了该页面多少次。

SecretHandler如下：

func SecretHandler(w http.ResponseWriter, r *http.Request) {
  u := GetSessionUser(r)
  if u == nil {
    http.Redirect(w, r, "/login", http.StatusFound)
    return
  }
  u.Count++
  SaveSessionUser(w, r, u)
  ptTemplate.ExecuteTemplate(w, "secret.tpl", u)
}

如果没有 session，则重定向到登录页面。反之显示该页面。这里每次成功访问 secret 页面，都会增加计数器，保存在 session 中。

上面代码中需要注意一点，由于 session 内容的序列化使用了标准库中的encoding/gob，所以不支持直接序列化结构体，我封装了两个函数，将User对象序列化为 JSON，然后保存到 session 中和从 session 中取出字符串反序列化为User对象：

func GetSessionUser(r *http.Request) *User {
  session, _ := store.Get(r, "user")
  s, ok := session.Values["user"]
  if !ok {
    return nil
  }
  u := &User{}
  json.Unmarshal([]byte(s.(string)), u)
  return u
}

func SaveSessionUser(w http.ResponseWriter, r *http.Request, u *User) {
  session, _ := store.Get(r, "user")
  data, _ := json.Marshal(u)
  session.Values["user"] = string(data)
  store.Save(r, w, session)
}

现在运行我们的程序，首先访问localhost:8080，由于没有登录，显示欢迎陌生人，去登录：

点击去登录，跳转到登录界面，输入用户名和密码：

点击登录，跳转到主页，这时由于记录了登录状态，会显示欢迎 darjun：

点击去隐秘链接：

不停刷新页面，发现访问次数一直累加。

如果未登录时，直接访问localhost:8080/secret，会直接重定向到登录界面。

上面程序有一个缺点，程序重启启动后，就需要重新登录。因为每次启动我们都重新随机 hashKey 和 blockKey，只需要固定这两个值即可实现重启也能保存登录状态。

登录验证类的功能非常适合放在中间件中处理，之前的文章已经介绍过如何编写中间件了，这里就不赘述了。

第三方后端存储

将 session 存储在本地文件系统，不利于水平扩展。一般稍微上点规模的网站，Web 服务器都会部署很多个实例，请求通过 Nginx 之类的反向代理转发到一个后端实例处理。不能保证后面的请求与之前的请求在同一个实例中处理，故 session 一般需要存储在一个公共的地方，例如 redis。

sessions提供了扩展接口，方便扩展使用其他的后端存储 session 内容。目前 GitHub 上已经有很多的第三方后端扩展了，详细 list 见sessions库的 GitHub 首页：

我们只介绍基于 redis 的后端存储，其他的扩展感兴趣可自行研究。首先安装扩展：

`1`	`$ go get gopkg.in/boj/redistore.v1`

创建一个 redistore 的实例：

`1`	`store, _ = redistore.NewRediStore(10, "tcp", ":6379", "", []byte("redis-key"))`

参数依次为：

size：最大空闲连接数；
network：连接类型，一般是 TCP；
addr：网络地址+端口；
password：redis 的密码，如果未启用，填空；
keyPairs：依次是 hashKey 和 blockKey（可省略），不再赘述。

为了验证，我们开启多个服务器，所以将端口通过命令行参数传入，使用标准库flag：

port = flag.Int("port", 8080, "port to listen")

func init() {
  flag.Parse()
}

func main() {
  // ...
  log.Fatal(http.ListenAndServe(fmt.Sprintf(":%d", *port), nil))
}

为了运行服务器，我们需要先开启一个 redis-server。redis 的安装就不多说了，在 windows 下，建议使用 chocolatey 安装，chocolatey 类似于 Ubutnu 的 apt-get，Mac 的 brew，非常方便，强烈推荐。

为了演示反向代理的效果，即通过一个地址可以随机访问部署的多个 Web 服务器，我们开启 3 个 Web 服务器。终端1：

1
2

$ go build 
$ ./redis -port 8080

终端2:

`1`	`$ ./redis -port 8081`

终端3:

`1`	`$ ./redis -port 8082`

可以使用nginx做反向代理，安装 nginx，配置：

upstream mysvr {
  server localhost:8080;
  server localhost:8081;
  server localhost:8082;
}

server {
  listen       80;
  server_name  localhost;

  location / {
    proxy_pass http://mysvr;
  }
}

这里表示将localhost随机转发到mysvr这个组中的 3 个服务器上，启动 nginx：

`1`	`$ nginx -c nginx.conf`

万事俱备，现在使用浏览器访问localhost，通过控制台日志发现是 server3 处理了这个请求：

点击去登录，server1 处理了展示页面的请求：

点击登录，server3 处理了 POST 类型的登录请求：

登录成功之后，重定向到主界面的请求又是 server1 处理的：

点击私密链接，展示页面的请求是 server2 处理的：

虽然每次处理的 server 不同，但是登录状态一直保存着。因为我们使用了 redis 保存 session。

注意，我这里每次都是随机一个 server 去处理，你运行的结果不一定一样。

总结

session 为了解决存储用户大量数据和安全性的问题。sessions库为 Go Web 开发中处理 session 提供了简单，灵活的方法。它依赖较少，可以即插即用，非常方便。

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

参考

gorilla/sessions GitHub：github.com/gorilla/sessions
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 gorilla/securecookie

Fri, 23 Jul 2021 00:13:32 +0000

简介

cookie 是用于在 Web 客户端（一般是浏览器）和服务器之间传输少量数据的一种机制。由服务器生成，发送到客户端保存，客户端后续的每次请求都会将 cookie 带上。cookie 现在已经被多多少少地滥用了。很多公司使用 cookie 来收集用户信息、投放广告等。

cookie 有两大缺点：

每次请求都需要传输，故不能用来存放大量数据；
安全性较低，通过浏览器工具，很容易看到由网站服务器设置的 cookie。

gorilla/securecookie提供了一种安全的 cookie，通过在服务端给 cookie 加密，让其内容不可读，也不可伪造。当然，敏感信息还是强烈建议不要放在 cookie 中。

快速使用

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir -p gorilla/securecookie && cd gorilla/securecookie
$ go mod init github.com/darjun/go-daily-lib/gorilla/securecookie

安装gorilla/securecookie库：

`1`	`$ go get github.com/gorilla/securecookie`

package main

import (
  "fmt"
  "github.com/gorilla/mux"
  "github.com/gorilla/securecookie"
  "log"
  "net/http"
)

type User struct {
  Name string
  Age int
}

var (
  hashKey = securecookie.GenerateRandomKey(16)
  blockKey = securecookie.GenerateRandomKey(16)
  s = securecookie.New(hashKey, blockKey)
)

func SetCookieHandler(w http.ResponseWriter, r *http.Request) {
  u := &User {
    Name: "dj",
    Age: 18,
  }
  if encoded, err := s.Encode("user", u); err == nil {
    cookie := &http.Cookie{
      Name: "user",
      Value: encoded,
      Path: "/",
      Secure: true,
      HttpOnly: true,
    }
    http.SetCookie(w, cookie)
  }
  fmt.Fprintln(w, "Hello World")
}

func ReadCookieHandler(w http.ResponseWriter, r *http.Request) {
  if cookie, err := r.Cookie("user"); err == nil {
    u := &User{}
    if err = s.Decode("user", cookie.Value, u); err == nil {
      fmt.Fprintf(w, "name:%s age:%d", u.Name, u.Age)
    }
  }
}

func main() {
  r := mux.NewRouter()
  r.HandleFunc("/set_cookie", SetCookieHandler)
  r.HandleFunc("/read_cookie", ReadCookieHandler)
  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

首先需要创建一个SecureCookie对象：

`1`	`var s = securecookie.New(hashKey, blockKey)`

其中hashKey是必填的，它用来验证 cookie 是否是伪造的，底层使用 HMAC（Hash-based message authentication code）算法。推荐hashKey使用 32/64 字节的 Key。

blockKey是可选的，它用来加密 cookie，如不需要加密，可以传nil。如果设置了，它的长度必须与对应的加密算法的块大小（block size）一致。例如对于 AES 系列算法，AES-128/AES-192/AES-256 对应的块大小分别为 16/24/32 字节。

为了方便也可以使用GenerateRandomKey()函数生成一个安全性足够强的随机 key。每次调用该函数都会返回不同的 key。上面代码就是通过这种方式创建 key 的。

调用s.Encode("user", u)将对象u编码成字符串，内部实际上使用了标准库encoding/gob。所以gob支持的类型都可以编码。

调用s.Decode("user", cookie.Value, u)将 cookie 值解码到对应的u对象中。

运行：

`1`	`$ go run main.go`

首先使用浏览器访问localhost:8080/set_cookie，这时可以在 Chrome 开发者工具的 Application 页签中看到 cookie 内容：

访问localhost:8080/read_cookie，页面显示name: dj age: 18。

使用 JSON

securecookie默认使用encoding/gob编码 cookie 值，我们也可以改用encoding/json。securecookie将编解码器封装成一个Serializer接口：

type Serializer interface {
  Serialize(src interface{}) ([]byte, error)
  Deserialize(src []byte, dst interface{}) error
}

securecookie提供了GobEncoder和JSONEncoder的实现：

func (e GobEncoder) Serialize(src interface{}) ([]byte, error) {
  buf := new(bytes.Buffer)
  enc := gob.NewEncoder(buf)
  if err := enc.Encode(src); err != nil {
    return nil, cookieError{cause: err, typ: usageError}
  }
  return buf.Bytes(), nil
}

func (e GobEncoder) Deserialize(src []byte, dst interface{}) error {
  dec := gob.NewDecoder(bytes.NewBuffer(src))
  if err := dec.Decode(dst); err != nil {
    return cookieError{cause: err, typ: decodeError}
  }
  return nil
}

func (e JSONEncoder) Serialize(src interface{}) ([]byte, error) {
  buf := new(bytes.Buffer)
  enc := json.NewEncoder(buf)
  if err := enc.Encode(src); err != nil {
    return nil, cookieError{cause: err, typ: usageError}
  }
  return buf.Bytes(), nil
}

func (e JSONEncoder) Deserialize(src []byte, dst interface{}) error {
  dec := json.NewDecoder(bytes.NewReader(src))
  if err := dec.Decode(dst); err != nil {
    return cookieError{cause: err, typ: decodeError}
  }
  return nil
}

我们可以调用securecookie.SetSerializer(JSONEncoder{})设置使用 JSON 编码：

var (
  hashKey = securecookie.GenerateRandomKey(16)
  blockKey = securecookie.GenerateRandomKey(16)
  s = securecookie.New(hashKey, blockKey)
)

func init() {
  s.SetSerializer(securecookie.JSONEncoder{})
}

自定义编解码

我们可以定义一个类型实现Serializer接口，那么该类型的对象可以用作securecookie的编解码器。我们实现一个简单的 XML 编解码器：

package main

type XMLEncoder struct{}

func (x XMLEncoder) Serialize(src interface{}) ([]byte, error) {
  buf := &bytes.Buffer{}
  encoder := xml.NewEncoder(buf)
  if err := encoder.Encode(buf); err != nil {
    return nil, err
  }
  return buf.Bytes(), nil
}

func (x XMLEncoder) Deserialize(src []byte, dst interface{}) error {
  dec := xml.NewDecoder(bytes.NewBuffer(src))
  if err := dec.Decode(dst); err != nil {
    return err
  }
  return nil
}

func init() {
  s.SetSerializer(XMLEncoder{})
}

由于securecookie.cookieError未导出，XMLEncoder与GobEncoder/JSONEncoder返回的错误有些不一致，不过不影响使用。

Hash/Block 函数

securecookie默认使用sha256.New作为 Hash 函数（用于 HMAC 算法），使用aes.NewCipher作为 Block 函数（用于加解密）：

// securecookie.go
func New(hashKey, blockKey []byte) *SecureCookie {
  s := &SecureCookie{
    hashKey:   hashKey,
    blockKey:  blockKey,
    // 这里设置 Hash 函数
    hashFunc:  sha256.New,
    maxAge:    86400 * 30,
    maxLength: 4096,
    sz:        GobEncoder{},
  }
  if hashKey == nil {
    s.err = errHashKeyNotSet
  }
  if blockKey != nil {
    // 这里设置 Block 函数
    s.BlockFunc(aes.NewCipher)
  }
  return s
}

可以通过securecookie.HashFunc()修改 Hash 函数，传入一个func () hash.Hash类型：

func (s *SecureCookie) HashFunc(f func() hash.Hash) *SecureCookie {
  s.hashFunc = f
  return s
}

通过securecookie.BlockFunc()修改 Block 函数，传入一个f func([]byte) (cipher.Block, error)：

func (s *SecureCookie) BlockFunc(f func([]byte) (cipher.Block, error)) *SecureCookie {
  if s.blockKey == nil {
    s.err = errBlockKeyNotSet
  } else if block, err := f(s.blockKey); err == nil {
    s.block = block
  } else {
    s.err = cookieError{cause: err, typ: usageError}
  }
  return s
}

更换这两个函数更多的是处于安全性的考虑，例如选用更安全的sha512算法：

`1`	`s.HashFunc(sha512.New512_256)`

更换 Key

为了防止 cookie 泄露造成安全风险，有个常用的安全策略：定期更换 Key。更换 Key，让之前获得的 cookie 失效。对应securecookie库，就是更换SecureCookie对象：

var (
  prevCookie    unsafe.Pointer
  currentCookie unsafe.Pointer
)

func init() {
  prevCookie = unsafe.Pointer(securecookie.New(
    securecookie.GenerateRandomKey(64),
    securecookie.GenerateRandomKey(32),
  ))
  currentCookie = unsafe.Pointer(securecookie.New(
    securecookie.GenerateRandomKey(64),
    securecookie.GenerateRandomKey(32),
  ))
}

程序启动时，我们先生成两个SecureCookie对象，然后每隔一段时间就生成一个新的对象替换旧的。

由于每个请求都是在一个独立的 goroutine 中处理的（读），更换 key 也是在一个单独的 goroutine（写）。为了并发安全，我们必须增加同步措施。但是这种情况下使用锁又太重了，毕竟这里更新的频率很低。我这里将securecookie.SecureCookie对象存储为unsafe.Pointer类型，然后就可以使用atomic原子操作来同步读取和更新了：

func rotateKey() {
  newcookie := securecookie.New(
    securecookie.GenerateRandomKey(64),
    securecookie.GenerateRandomKey(32),
  )

  atomic.StorePointer(&prevCookie, currentCookie)
  atomic.StorePointer(&currentCookie, unsafe.Pointer(newcookie))
}

rotateKey()需要在一个新的 goroutine 中定期调用，我们在main函数中启动这个 goroutine

func main() {
  ctx, cancel := context.WithCancel(context.Background())
  defer cancel()
  go RotateKey(ctx)
}

func RotateKey(ctx context.Context) {
  ticker := time.NewTicker(30 * time.Second)
  defer ticker.Stop()

  for {
    select {
    case <-ctx.Done():
      break
    case <-ticker.C:
    }

    rotateKey()
  }
}

这里为了方便测试，我设置每隔 30s 就轮换一次。同时为了防止 goroutine 泄漏，我们传入了一个可取消的Context。还需要注意time.NewTicker()创建的*time.Ticker对象不使用时需要手动调用Stop()关闭，否则会造成资源泄漏。

使用两个SecureCookie对象之后，我们编解码可以调用EncodeMulti/DecodeMulti这组方法，它们可以接受多个SecureCookie对象：

func SetCookieHandler(w http.ResponseWriter, r *http.Request) {
  u := &User{
    Name: "dj",
    Age:  18,
  }

  if encoded, err := securecookie.EncodeMulti(
    "user", u,
    // 看这里 🐒
    (*securecookie.SecureCookie)(atomic.LoadPointer(&currentCookie)),
  ); err == nil {
    cookie := &http.Cookie{
      Name:     "user",
      Value:    encoded,
      Path:     "/",
      Secure:   true,
      HttpOnly: true,
    }
    http.SetCookie(w, cookie)
  }
  fmt.Fprintln(w, "Hello World")
}

使用unsafe.Pointer保存SecureCookie对象后，使用时需要类型转换。并且由于并发问题，需要使用atomic.LoadPointer()访问。

解码时调用DecodeMulti依次传入currentCookie和prevCookie，让prevCookie不会立刻失效：

func ReadCookieHandler(w http.ResponseWriter, r *http.Request) {
  if cookie, err := r.Cookie("user"); err == nil {
    u := &User{}
    if err = securecookie.DecodeMulti(
      "user", cookie.Value, u,
      // 看这里 🐒
      (*securecookie.SecureCookie)(atomic.LoadPointer(&currentCookie)),
      (*securecookie.SecureCookie)(atomic.LoadPointer(&prevCookie)),
    ); err == nil {
      fmt.Fprintf(w, "name:%s age:%d", u.Name, u.Age)
    } else {
      fmt.Fprintf(w, "read cookie error:%v", err)
    }
  }
}

运行程序：

`1`	`$ go run main.go`

先请求localhost:8080/set_cookie，然后请求localhost:8080/read_cookie读取 cookie。等待 1 分钟后，再次请求，发现之前的 cookie 失效了：

`1`	`read cookie error:securecookie: the value is not valid (and 1 other error)`

总结

securecookie为 cookie 添加了一层保护罩，让 cookie 不能轻易地被读取和伪造。还是需要强调一下：

敏感数据不要放在 cookie 中！敏感数据不要放在 cookie 中！敏感数据不要放在 cookie 中！敏感数据不要放在 cookie 中！

重要的事情说 4 遍。在使用 cookie 存放数据时需要仔细权衡。

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

参考

gorilla/securecookie GitHub：github.com/gorilla/securecookie
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 gorilla/schema

Thu, 22 Jul 2021 07:48:33 +0000

简介

gorilla/schema 是 gorilla 开发工具包中用于处理表单的库。它提供了一个简单的方式，可以很方便地将表单数据转为结构体对象，或者将结构体对象转为表单数据。

快速使用

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir -p gorilla/schema && cd gorilla/schema
$ go mod init github.com/darjun/go-daily-lib/gorilla/schema

安装gorilla/schema库：

`1`	`$ go get -u github.com/gorilla/schema`

我们还是拿前面登录的例子：

func index(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintln(w, "Hello World")
}

func login(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintln(w, `<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Login</title>
</head>
<body>
<form action="/login" method="post">
  <label>Username:</label>
  <input name="username"><br>
  <label>Password:</label>
  <input name="password" type="password"><br>
  <button type="submit">登录</button>
</form>
</body>
</html>`)
}

type User struct {
  Username string `schema:"username"`
  Password string `schema:"password"`
}

var (
  decoder = schema.NewDecoder()
)

func dologin(w http.ResponseWriter, r *http.Request) {
  r.ParseForm()
  u := User{}
  decoder.Decode(&u, r.PostForm)
  if u.Username == "dj" && u.Password == "handsome" {
    http.Redirect(w, r, "/", 301)
    return
  }

  http.Redirect(w, r, "/login", 301)
}

func main() {
  r := mux.NewRouter()
  r.HandleFunc("/", index)
  r.Handle("/login", handlers.MethodHandler{
    "GET":  http.HandlerFunc(login),
    "POST": http.HandlerFunc(dologin),
  })
  log.Fatal(http.ListenAndServe(":8080", r))
}

首先调用schema.NewDecoder()方法创建一个解码器decoder。在处理器中，先调用r.ParseForm()解析表单数据，然后创建用户对象u，调用decoder.Decode(&u, r.PostForm)通过表单数据填充该对象。

schema使用反射来对应表单和结构体字段，我们可以通过结构体标签来指定表单数据和字段的对应关系。

上面我们将解码器作为一个包内的全局变量，因为decoder中会缓存一些结构体的元数据，并且它是并发安全的。

在main函数中，我们创建了gorilla/mux路由，注册/根处理函数，使用中间件handlers.MethodHandler分别注册路径/login的 GET 和 POST 方法的处理器。然后调用http.Handle("/", r)将所有请求交由gorilla/mux路由处理。最后启动 Web 服务器接受请求。

编码

除了用于服务器解码表单数据外，schema还可用于客户端，将结构体对象编码到表单数据中发送给服务器。我们编写一个程序登录上面的服务器：

var (
  encoder = schema.NewEncoder()
)

func main() {
  client := &http.Client{}
  form := url.Values{}

  u := &User{
    Username: "dj",
    Password: "handsome",
  }
  encoder.Encode(u, form)

  res, _ := client.PostForm("http://localhost:8080/login", form)
  data, _ := ioutil.ReadAll(res.Body)
  fmt.Println(string(data))
  res.Body.Close()
}

与解码器的用法类似，首先调用schema.NewEncoder()创建一个编码器encoder，创建一个User类型的对象u和表单数据对象form，调用encoder.Encode(u, form)将u编码到form中。然后使用http.Client的PostForm方法发送请求。读取响应。

自定义类型转换

目前schema支持以下类型：

布尔类型：bool
浮点数：float32/float64
有符号整数：int/int8/int32/int64
无符号整数：uint/uint8/uint32/uint64
字符串：string
结构体：由以上类型组成的结构体
指针：指向以上类型的指针
切片：元素为以上类型的切片，或指向切片的指针

有时候客户端会将一个切片拼成一个字符串传到服务器，服务器收到之后需要解析成切片：

type Person struct {
  Name    string   `schema:"name"`
  Age     int      `schema:"age"`
  Hobbies []string `schema:"hobbies"`
}

var (
  decoder = schema.NewDecoder()
)

func init() {
  decoder.RegisterConverter([]string{}, func(s string) reflect.Value {
    return reflect.ValueOf(strings.Split(s, ","))
  })
}

func doinfo(w http.ResponseWriter, r *http.Request) {
  r.ParseForm()
  p := Person{}
  decoder.Decode(&p, r.PostForm)

  fmt.Println(p)
  fmt.Fprintf(w, "Name:%s Age:%d Hobbies:%v", p.Name, p.Age, p.Hobbies)
}

调用decoder.RegisterConverter()注册对应类型的转换函数，转换函数类型为：

`1`	`func(s string) reflect.Value`

即将请求中的字符串值转为满足我们格式的值。

客户端请求：

type Person struct {
  Name    string `schema:"name"`
  Age     int    `schema:"age"`
  Hobbies string `schema:"hobbies"`
}

var (
  encoder = schema.NewEncoder()
)

func main() {
  client := &http.Client{}
  form := url.Values{}

  p := &Person{
    Name:    "dj",
    Age:     18,
    Hobbies: "Game,Programming",
  }
  encoder.Encode(p, form)

  res, _ := client.PostForm("http://localhost:8080/info", form)
  data, _ := ioutil.ReadAll(res.Body)
  fmt.Println(string(data))
  res.Body.Close()
}

客户端故意将Hobbies字段设置为字符串，发送请求。服务器将使用注册的func (s string) reflect.Value函数将该字符串切割为[]string返回。

总结

schema提供了一个简单的获取表单数据的方式，通过将数据填充到结构体对象中，我们可以很方便的进行后续操作。schema库比较小巧，对特性没太多要求的可以试试~

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

参考

gorilla/schema GitHub：github.com/gorilla/schema
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 gorilla/handlers

Wed, 21 Jul 2021 06:30:23 +0000

简介

上一篇文章中，我们介绍了 gorilla web 开发工具包中的路由管理库gorilla/mux，在文章最后我们介绍了如何使用中间件处理通用的逻辑。在日常 Go Web 开发中，开发者遇到了很多相同的中间件需求，gorilla/handlers（后文简称为handlers）收集了一些比较常用的中间件。一起来看看吧~

关于中间件，前面几篇文章已经介绍的很多了。这里就不赘述了。handlers库提供的中间件可用于标准库net/http和所有支持http.Handler接口的框架。由于gorilla/mux也支持http.Handler接口，所以也可以与handlers库结合使用。这就是兼容标准的好处。

项目初始化&安装

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir -p gorilla/handlers && cd gorilla/handlers
$ go mod init github.com/darjun/go-daily-lib/gorilla/handlers

安装gorilla/handlers库：

`1`	`$ go get -u github.com/gorilla/handlers`

下面依次介绍各个中间件和相应的源码。

日志

handlers提供了两个日志中间件：

LoggingHandler：以 Apache 的Common Log Format日志格式记录 HTTP 请求日志；
CombinedLoggingHandler：以 Apache的Combined Log Format日志格式记录 HTTP 请求日志，Apache 和 Nginx 默认都使用这种日志格式。

两种日志格式差别很小，Common Log Format格式如下：

`1`	`%h %l %u %t "%r" %>s %b`

各个指示符含义如下：

%h：客户端的 IP 地址或主机名；
%l：RFC 1413定义的客户端标识，由客户端机器上的identd程序生成。如果不存在，则该字段为-；
%u：已验证的用户名。如果不存在，该字段为-；
%t：时间，格式为day/month/year:hour:minute:second zone，其中：
- day： 2位数字；
- month：月份缩写，3个字母，如Jan；
- year：4位数字；
- hour：2位数字；
- minute：2位数字；
- second：2位数字；
- zone：+或-后跟4位数字；
- 例如：21/Jul/2021:06:27:33 +0800
%r：包含 HTTP 请求行信息，例GET /index.html HTTP/1.1；
%>s：服务器发送给客户端的状态码，例如200；
%b：响应长度（字节数）。

Combined Log Format格式如下：

`1`	`%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i"`

可见相比Common Log Format只是多了：

%{Referer}i：HTTP 首部中的Referer信息；
%{User-Agent}i：HTTP 首部中的User-Agent信息。

对中间件，我们可以让它作用于全局，即全部处理器，也可以让它只对某些处理器生效。如果要对所有处理器生效，可以调用Use()方法。如果只需要作用于特定的处理器，在注册时用中间件将处理器包装一层：

func index(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintln(w, "Hello World")
}

type greeting string

func (g greeting) ServeHTTP(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintf(w, "Welcome, %s", g)
}

func main() {
  r := mux.NewRouter()
  r.Handle("/", handlers.LoggingHandler(os.Stdout, http.HandlerFunc(index)))
  r.Handle("/greeting", handlers.CombinedLoggingHandler(os.Stdout, greeting("dj")))

  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

上面代码中LoggingHandler只作用于处理函数index，CombinedLoggingHandler只作用于处理器greeting("dj")。

运行代码，通过浏览器访问localhost:8080和localhost:8080/greeting：

1
2

::1 - - [21/Jul/2021:06:39:45 +0800] "GET / HTTP/1.1" 200 12
::1 - - [21/Jul/2021:06:39:54 +0800] "GET /greeting HTTP/1.1" 200 11 "" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.164 Safari/537.36"

对照前面分析的指示符，很容易看出各个部分。

由于*mux.Router的Use()方法接受类型为MiddlewareFunc的中间件：

`1`	`type MiddlewareFunc func(http.Handler) http.Handler`

而handlers.LoggingHandler/CombinedLoggingHandler并不满足，所以还需要包装一层才能传给Use()方法：

func Logging(handler http.Handler) http.Handler {
  return handlers.CombinedLoggingHandler(os.Stdout, handler)
}

func main() {
  r := mux.NewRouter()
  r.Use(Logging)
  r.HandleFunc("/", index)
  r.Handle("/greeting/", greeting("dj"))

  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

另外handlers还提供了CustomLoggingHandler，我们可以利用它定义自己的日志中间件：

`1`	`func CustomLoggingHandler(out io.Writer, h http.Handler, f LogFormatter) http.Handler`

最关键的LogFormatter类型定义：

type LogFormatterParams struct {
  Request    *http.Request
  URL        url.URL
  TimeStamp  time.Time
  StatusCode int
  Size       int
}

type LogFormatter func(writer io.Writer, params LogFormatterParams)

我们实现一个简单的LogFormatter，记录时间 + 请求行 + 响应码：

func myLogFormatter(writer io.Writer, params handlers.LogFormatterParams) {
  var buf bytes.Buffer
  buf.WriteString(time.Now().Format("2006-01-02 15:04:05 -0700"))
  buf.WriteString(fmt.Sprintf(` "%s %s %s" `, params.Request.Method, params.URL.Path, params.Request.Proto))
  buf.WriteString(strconv.Itoa(params.StatusCode))
  buf.WriteByte('\n')

  writer.Write(buf.Bytes())
}

func Logging(handler http.Handler) http.Handler {
  return handlers.CustomLoggingHandler(os.Stdout, handler, myLogFormatter)
}

使用：

func main() {
  r := mux.NewRouter()
  r.Use(Logging)
  r.HandleFunc("/", index)
  r.Handle("/greeting/", greeting("dj"))

  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

现在记录的日志是下面这种格式：

`1`	`2021-07-21 07:03:18 +0800 "GET /greeting/ HTTP/1.1" 200`

翻看源码，我们可以发现LoggingHandler/CombinedLoggingHandler/CustomLoggingHandler都是基于底层的loggingHandler实现的，不同的是LoggingHandler使用了预定义的writeLog作为LogFormatter，CombinedLoggingHandler使用了预定义的writeCombinedLog作为LogFormatter，而CustomLoggingHandler使用我们自己定义的LogFormatter：

func CombinedLoggingHandler(out io.Writer, h http.Handler) http.Handler {
  return loggingHandler{out, h, writeCombinedLog}
}

func LoggingHandler(out io.Writer, h http.Handler) http.Handler {
  return loggingHandler{out, h, writeLog}
}

func CustomLoggingHandler(out io.Writer, h http.Handler, f LogFormatter) http.Handler {
  return loggingHandler{out, h, f}
}

预定义的writeLog/writeCombinedLog实现如下：

func writeLog(writer io.Writer, params LogFormatterParams) {
  buf := buildCommonLogLine(params.Request, params.URL, params.TimeStamp, params.StatusCode, params.Size)
  buf = append(buf, '\n')
  writer.Write(buf)
}

func writeCombinedLog(writer io.Writer, params LogFormatterParams) {
  buf := buildCommonLogLine(params.Request, params.URL, params.TimeStamp, params.StatusCode, params.Size)
  buf = append(buf, ` "`...)
  buf = appendQuoted(buf, params.Request.Referer())
  buf = append(buf, `" "`...)
  buf = appendQuoted(buf, params.Request.UserAgent())
  buf = append(buf, '"', '\n')
  writer.Write(buf)
}

它们都是基于buildCommonLogLine构造基本信息，writeCombinedLog还分别调用http.Request.Referer()和http.Request.UserAgent获取了Referer和User-Agent信息。

loggingHandler定义如下：

type loggingHandler struct {
  writer    io.Writer
  handler   http.Handler
  formatter LogFormatter
}

loggingHandler实现有一个比较巧妙的地方：为了记录响应码和响应大小，定义了一个类型responseLogger包装原来的http.ResponseWriter，在写入时记录信息：

type responseLogger struct {
  w      http.ResponseWriter
  status int
  size   int
}

func (l *responseLogger) Write(b []byte) (int, error) {
  size, err := l.w.Write(b)
  l.size += size
  return size, err
}

func (l *responseLogger) WriteHeader(s int) {
  l.w.WriteHeader(s)
  l.status = s
}

func (l *responseLogger) Status() int {
  return l.status
}

func (l *responseLogger) Size() int {
  return l.size
}

loggingHandler的关键方法ServeHTTP()：

func (h loggingHandler) ServeHTTP(w http.ResponseWriter, req *http.Request) {
  t := time.Now()
  logger, w := makeLogger(w)
  url := *req.URL

  h.handler.ServeHTTP(w, req)
  if req.MultipartForm != nil {
    req.MultipartForm.RemoveAll()
  }

  params := LogFormatterParams{
    Request:    req,
    URL:        url,
    TimeStamp:  t,
    StatusCode: logger.Status(),
    Size:       logger.Size(),
  }

  h.formatter(h.writer, params)
}

构造LogFormatterParams对象，调用对应的LogFormatter函数。

压缩

如果客户端请求中有Accept-Encoding首部，服务器可以使用该首部指示的算法将响应压缩，以节省网络流量。handlers.CompressHandler中间件启用压缩功能。还有一个CompressHandlerLevel可以指定压缩级别。实际上CompressHandler就是使用gzip.DefaultCompression调用的CompressHandlerLevel：

1
2
3

func CompressHandler(h http.Handler) http.Handler {
  return CompressHandlerLevel(h, gzip.DefaultCompression)
}

看代码：

func index(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintln(w, "Hello World")
}

type greeting string

func (g greeting) ServeHTTP(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintf(w, "Welcome, %s", g)
}

func main() {
  r := mux.NewRouter()
  r.Use(handlers.CompressHandler)
  r.HandleFunc("/", index)
  r.Handle("/greeting/", greeting("dj"))

  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

运行，请求localhost:8080，通过 Chrome 开发者工具的 Network 页签可以看到响应采用了 gzip 压缩：

忽略一些细节处理，CompressHandlerLevel函数代码如下：

func CompressHandlerLevel(h http.Handler, level int) http.Handler {
  const (
    gzipEncoding  = "gzip"
    flateEncoding = "deflate"
  )

  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    var encoding string
    for _, curEnc := range strings.Split(r.Header.Get(acceptEncoding), ",") {
      curEnc = strings.TrimSpace(curEnc)
      if curEnc == gzipEncoding || curEnc == flateEncoding {
        encoding = curEnc
        break
      }
    }

    if encoding == "" {
      h.ServeHTTP(w, r)
      return
    }

    if r.Header.Get("Upgrade") != "" {
      h.ServeHTTP(w, r)
      return
    }

    var encWriter io.WriteCloser
    if encoding == gzipEncoding {
      encWriter, _ = gzip.NewWriterLevel(w, level)
    } else if encoding == flateEncoding {
      encWriter, _ = flate.NewWriter(w, level)
    }
    defer encWriter.Close()

    w.Header().Set("Content-Encoding", encoding)
    r.Header.Del(acceptEncoding)

    cw := &compressResponseWriter{
      w:          w,
      compressor: encWriter,
    }

    w = httpsnoop.Wrap(w, httpsnoop.Hooks{
      Write: func(httpsnoop.WriteFunc) httpsnoop.WriteFunc {
        return cw.Write
      },
      WriteHeader: func(httpsnoop.WriteHeaderFunc) httpsnoop.WriteHeaderFunc {
        return cw.WriteHeader
      },
      Flush: func(httpsnoop.FlushFunc) httpsnoop.FlushFunc {
        return cw.Flush
      },
      ReadFrom: func(rff httpsnoop.ReadFromFunc) httpsnoop.ReadFromFunc {
        return cw.ReadFrom
      },
    })

    h.ServeHTTP(w, r)
  })
}

从请求Accept-Encoding首部中获取客户端指示的压缩算法。如果客户端未指定，或请求首部中有Upgrade，则不压缩。反之，则压缩。根据识别的压缩算法，创建对应gzip或flate的io.Writer实现对象。

与前面的日志中间件一样，为了压缩写入的内容，新增类型compressResponseWriter封装http.ResponseWriter，重写Write()方法，将写入的字节流传入前面创建的io.Writer实现压缩：

type compressResponseWriter struct {
  compressor io.Writer
  w          http.ResponseWriter
}

func (cw *compressResponseWriter) Write(b []byte) (int, error) {
  h := cw.w.Header()
  if h.Get("Content-Type") == "" {
    h.Set("Content-Type", http.DetectContentType(b))
  }
  h.Del("Content-Length")

  return cw.compressor.Write(b)
}

内容类型

我们可以通过handler.ContentTypeHandler指定请求的Content-Type必须在我们给出的类型中，只对POST/PUT/PATCH方法生效。例如我们限制登录请求必须通过application/x-www-form-urlencoded的形式发送：

func main() {
  r := mux.NewRouter()
  r.HandleFunc("/", index)
  r.Methods("GET").Path("/login").HandlerFunc(login)
  r.Methods("POST").Path("/login").
    Handler(handlers.ContentTypeHandler(http.HandlerFunc(dologin), "application/x-www-form-urlencoded"))

  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

这样，只要请求/login的Content-Type不是application/x-www-form-urlencoded就会返回 415 错误。我们可以故意写错，再请求看看表现：

`1`	`Unsupported content type "application/x-www-form-urlencoded"; expected one of ["application/x-www-from-urlencoded"]`

ContentTypeHandler的实现非常简单：

func ContentTypeHandler(h http.Handler, contentTypes ...string) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    if !(r.Method == "PUT" || r.Method == "POST" || r.Method == "PATCH") {
      h.ServeHTTP(w, r)
      return
    }

    for _, ct := range contentTypes {
      if isContentType(r.Header, ct) {
        h.ServeHTTP(w, r)
        return
      }
    }
    http.Error(w, fmt.Sprintf("Unsupported content type %q; expected one of %q", r.Header.Get("Content-Type"), contentTypes), http.StatusUnsupportedMediaType)
  })
}

就是读取Content-Type首部，判断是否在我们指定的类型中。

方法分发器

在上面的例子中，我们注册路径/login的GET和POST方法处理采用r.Methods("GET").Path("/login").HandlerFunc(login)这种冗长的写法。handlers.MethodHandler可以简化这种写法：

func main() {
  r := mux.NewRouter()
  r.HandleFunc("/", index)
  r.Handle("/login", handlers.MethodHandler{
    "GET":  http.HandlerFunc(login),
    "POST": http.HandlerFunc(dologin),
  })

  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

MethodHandler底层是一个map[string]http.Handler类型，它的ServeHTTP()方法根据请求的 Method 调用不同的处理：

type MethodHandler map[string]http.Handler

func (h MethodHandler) ServeHTTP(w http.ResponseWriter, req *http.Request) {
  if handler, ok := h[req.Method]; ok {
    handler.ServeHTTP(w, req)
  } else {
    allow := []string{}
    for k := range h {
      allow = append(allow, k)
    }
    sort.Strings(allow)
    w.Header().Set("Allow", strings.Join(allow, ", "))
    if req.Method == "OPTIONS" {
      w.WriteHeader(http.StatusOK)
    } else {
      http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
    }
  }
}

方法如果未注册，则返回405 Method Not Allowed。有一个方法除外，OPTIONS。该方法通过Allow首部返回支持哪些方法。

重定向

handlers.CanonicalHost可以将请求重定向到指定的域名，同时指定重定向响应码。在同一个服务器对应多个域名时比较有用：

func index(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintln(w, "hello world")
}

func main() {
  r := mux.NewRouter()
  r.Use(handlers.CanonicalHost("http://www.gorillatoolkit.org", 302))
  r.HandleFunc("/", index)
  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

上面将所有请求以 302 重定向到http://www.gorillatoolkit.org。

CanonicalHost的实现也很简单：

func CanonicalHost(domain string, code int) func(h http.Handler) http.Handler {
  fn := func(h http.Handler) http.Handler {
    return canonical{h, domain, code}
  }

  return fn
}

关键类型canonical：

type canonical struct {
  h      http.Handler
  domain string
  code   int
}

核心方法：

func (c canonical) ServeHTTP(w http.ResponseWriter, r *http.Request) {
  dest, err := url.Parse(c.domain)
  if err != nil {
    c.h.ServeHTTP(w, r)
    return
  }

  if dest.Scheme == "" || dest.Host == "" {
    c.h.ServeHTTP(w, r)
    return
  }

  if !strings.EqualFold(cleanHost(r.Host), dest.Host) {
    dest := dest.Scheme + "://" + dest.Host + r.URL.Path
    if r.URL.RawQuery != "" {
      dest += "?" + r.URL.RawQuery
    }
    http.Redirect(w, r, dest, c.code)
    return
  }

  c.h.ServeHTTP(w, r)
}

由源码可知，域名不合法或未指定协议（Scheme）或域名（Host）的请求下不转发。

Recovery

之前我们自己实现了PanicRecover中间件，避免请求处理时 panic。handlers提供了一个RecoveryHandler可以直接使用：

func PANIC(w http.ResponseWriter, r *http.Request) {
  panic(errors.New("unexpected error"))
}

func main() {
  r := mux.NewRouter()
  r.Use(handlers.RecoveryHandler(handlers.PrintRecoveryStack(true)))
  r.HandleFunc("/", PANIC)
  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

选项PrintRecoveryStack表示 panic 时输出堆栈信息。

RecoveryHandler的实现与之前我们自己编写的基本一样：

type recoveryHandler struct {
  handler    http.Handler
  logger     RecoveryHandlerLogger
  printStack bool
}

func (h recoveryHandler) ServeHTTP(w http.ResponseWriter, req *http.Request) {
  defer func() {
    if err := recover(); err != nil {
      w.WriteHeader(http.StatusInternalServerError)
      h.log(err)
    }
  }()

  h.handler.ServeHTTP(w, req)
}

总结

GitHub 上有很多开源的 Go Web 中间件实现，可以直接拿来使用，避免重复造轮子。handlers很轻量，容易与标准库net/http和 gorilla 路由库mux结合使用。

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

参考

gorilla/handlers GitHub：github.com/gorilla/handlers
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 gorilla/mux

Mon, 19 Jul 2021 20:22:34 +0000

简介

gorilla/mux是 gorilla Web 开发工具包中的路由管理库。gorilla Web 开发包是 Go 语言中辅助开发 Web 服务器的工具包。它包括 Web 服务器开发的各个方面，有表单数据处理包gorilla/schema，有 websocket 通信包gorilla/websocket，有各种中间件的包gorilla/handlers，有 session 管理包gorilla/sessions，有安全的 cookie 包gorilla/securecookie。本文先介绍gorilla/mux（下文简称mux），后续文章会依次介绍上面列举的 gorilla 包。

mux有以下优势：

实现了标准的http.Handler接口，所以可以与net/http标准库结合使用，非常轻量；
可以根据请求的主机名、路径、路径前缀、协议、HTTP 首部、查询字符串和 HTTP 方法匹配处理器，还可以自定义匹配逻辑；
可以在主机名、路径和请求参数中使用变量，还可以为之指定一个正则表达式；
可以传入参数给指定的处理器让其构造出完整的 URL；
支持路由分组，方便管理和维护。

快速使用

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir -p gorilla/mux && cd gorilla/mux
$ go mod init github.com/darjun/go-daily-lib/gorilla/mux

安装gorilla/mux库：

`1`	`$ go get -u github.com/gorilla/gorilla/mux`

我现在身边有几本 Go 语言的经典著作：

下面我们编写一个管理图书信息的 Web 服务。图书由 ISBN 唯一标识，ISBN 意为国际标准图书编号（International Standard Book Number）。

首先定义图书的结构：

type Book struct {
  ISBN        string   `json:"isbn"`
  Name        string   `json:"name"`
  Authors     []string `json:"authors"`
  Press       string   `json:"press"`
  PublishedAt string   `json:"published_at"`
}

var (
  mapBooks map[string]*Book
  slcBooks []*Book
)

定义init()函数，从文件中加载数据：

func init() {
  mapBooks = make(map[string]*Book)
  slcBooks = make([]*Book, 0, 1)

  data, err := ioutil.ReadFile("../data/books.json")
  if err != nil {
    log.Fatalf("failed to read book.json:%v", err)
  }

  err = json.Unmarshal(data, &slcBooks)
  if err != nil {
    log.Fatalf("failed to unmarshal books:%v", err)
  }

  for _, book := range slcBooks {
    mapBooks[book.ISBN] = book
  }
}

然后是两个处理函数，分别用于返回整个列表和某一本具体的图书：

func BooksHandler(w http.ResponseWriter, r *http.Request) {
  enc := json.NewEncoder(w)
  enc.Encode(slcBooks)
}

func BookHandler(w http.ResponseWriter, r *http.Request) {
  book, ok := mapBooks[mux.Vars(r)["isbn"]]
  if !ok {
    http.NotFound(w, r)
    return
  }

  enc := json.NewEncoder(w)
  enc.Encode(book)
}

注册处理器：

func main() {
  r := mux.NewRouter()
  r.HandleFunc("/", BooksHandler)
  r.HandleFunc("/books/{isbn}", BookHandler)
  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

mux的使用与net/http非常类似。首先调用mux.NewRouter()创建一个类型为*mux.Router的路由对象，该路由对象注册处理器的方式与标准库的*http.ServeMux完全相同，即调用HandleFunc()方法注册类型为func(http.ResponseWriter, *http.Request)的处理函数，调用Handle()方法注册实现了http.Handler接口的处理器对象。上面注册了两个处理函数，一个是显示图书信息列表，一个显示具体某本书的信息。

注意到路径/books/{isbn}使用了变量，在{}中间指定变量名，它可以匹配路径中的特定部分。在处理函数中通过mux.Vars(r)获取请求r的路由变量，返回map[string]string，后续可以用变量名访问。如上面的BookHandler中对变量isbn的访问。

由于*mux.Router也实现了http.Handler接口，所以可以直接将它作为http.Handle("/", r)的处理器对象参数注册。这里注册的是根路径/，相当于把所有请求的处理都托管给了*mux.Router。

最后还是http.ListenAndServe(":8080", nil)开启一个 Web 服务器，等待接收请求。

运行，在浏览器中键入localhost:8080，显示书籍列表：

键入localhost:8080/books/978-7-111-55842-2，显示图书《Go 程序设计语言》的详细信息：

从上面的使用过程中可以看出，mux库非常轻量，能很好的与标准库net/http结合使用。

我们还可以使用正则表达式限定变量的模式。ISBN 有固定的模式，现在使用的模式大概是这样：978-7-111-55842-2（这就是《Go 程序设计语言》一书的 ISBN），即 3个数字-1个数字-3个数字-5个数字-1个数字，用正则表达式表示为\d{3}-\d-\d{3}-\d{5}-\d。在变量名后添加一个:分隔变量和正则表达式：

`1`	`r.HandleFunc("/books/{isbn:\\d{3}-\\d-\\d{3}-\\d{5}-\\d}", BookHandler)`

灵活的匹配方式

mux提供了丰富的匹配请求的方式。相比之下，net/http只能指定具体的路径，稍显笨拙。

我们可以指定路由的域名或子域名：

1
2

r.Host("github.io")
r.Host("{subdomain:[a-zA-Z0-9]+}.github.io")

上面的路由只接受域名github.io或其子域名的请求，例如我的博客地址darjun.github.io就是它的一个子域名。指定域名时可以使用正则表达式，上面第二行代码限制子域名的第一部分必须是若干个字母或数字。

指定路径前缀：

1
2

// 只处理路径前缀为`/books/`的请求
r.PathPrefix("/books/")

指定请求的方法：

1
2

// 只处理 GET/POST 请求
r.Methods("GET", "POST")

使用的协议（HTTP/HTTPS）：

1
2

// 只处理 https 的请求
r.Schemes("https")

首部：

1
2

// 只处理首部 X-Requested-With 的值为 XMLHTTPRequest 的请求
r.Headers("X-Requested-With", "XMLHTTPRequest")

查询参数（即 URL 中?后的部分）：

1
2

// 只处理查询参数包含key=value的请求
r.Queries("key", "value")

最后我们可以组合这些条件：

r.HandleFunc("/", HomeHandler)
 .Host("bookstore.com")
 .Methods("GET")
 .Schemes("http")

除此之外，mux还允许自定义匹配器。自定义的匹配器就是一个类型为func(r *http.Request, rm *RouteMatch) bool的函数，根据请求r中的信息判断是否能否匹配成功。http.Request结构中包含了非常多的信息：HTTP 方法、HTTP 版本号、URL、首部等。例如，如果我们要求只处理 HTTP/1.1 的请求可以这么写：

1
2
3

r.MatchrFunc(func(r *http.Request, rm *RouteMatch) bool {
  return r.ProtoMajor == 1 && r.ProtoMinor == 1
})

需要注意的是，mux会根据路由注册的顺序依次匹配。所以，通常是将特殊的路由放在前面，一般的路由放在后面。如果反过来了，特殊的路由就不会被匹配到了：

1
2

r.HandleFunc("/specific", specificHandler)
r.PathPrefix("/").Handler(catchAllHandler)

子路由

有时候对路由进行分组管理，能让程序模块更清晰，更易于维护。现在网站扩展业务，加入了电影相关信息。我们可以定义两个子路由分别管理：

r := mux.NewRouter()
bs := r.PathPrefix("/books").Subrouter()
bs.HandleFunc("/", BooksHandler)
bs.HandleFunc("/{isbn}", BookHandler)

ms := r.PathPrefix("/movies").Subrouter()
ms.HandleFunc("/", MoviesHandler)
ms.HandleFunc("/{imdb}", MovieHandler)

子路由一般通过路径前缀来限定，r.PathPrefix()会返回一个*mux.Route对象，调用它的Subrouter()方法创建一个子路由对象*mux.Router，然后通过该对象的HandleFunc/Handle方法注册处理函数。

电影没有类似图书的 ISBN 国际统一标准，只有一个民间“准标准”：IMDB。我们采用豆瓣电影中的信息：

定义电影的结构：

type Movie struct {
  IMDB        string `json:"imdb"`
  Name        string `json:"name"`
  PublishedAt string `json:"published_at"`
  Duration    uint32 `json:"duration"`
  Lang        string `json:"lang"`
}

加载：

var (
  mapMovies map[string]*Movie
  slcMovies []*Movie
)

func init() {
  mapMovies = make(map[string]*Movie)
  slcMovies = make([]*Movie, 0, 1)

  data,  := ioutil.ReadFile("../../data/movies.json")
  json.Unmarshal(data, &slcMovies)
  for _, movie := range slcMovies {
    mapMovies[movie.IMDB] = movie
  }
}

使用子路由的方式，还可以将各个部分的路由分散到各自的模块去加载，在文件book.go中定义一个InitBooksRouter()方法负责注册图书相关的路由：

func InitBooksRouter(r *mux.Router) {
  bs := r.PathPrefix("/books").Subrouter()
  bs.HandleFunc("/", BooksHandler)
  bs.HandleFunc("/{isbn}", BookHandler)
}

在文件movie.go中定义一个InitMoviesRouter()方法负责注册电影相关的路由：

func InitMoviesRouter(r *mux.Router) {
  ms := r.PathPrefix("/movies").Subrouter()
  ms.HandleFunc("/", MoviesHandler)
  ms.HandleFunc("/{imdb}", MovieHandler)
}

在main.go的主函数中：

func main() {
  r := mux.NewRouter()
  InitBooksRouter(r)
  InitMoviesRouter(r)

  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

需要注意的是，子路由匹配是需要包含路径前缀的，也就是说/books/才能匹配BooksHandler。

构造路由 URL

我们可以为一个路由起一个名字，例如：

`1`	`r.HandleFunc("/books/{isbn}", BookHandler).Name("book")`

上面的路由中有参数，我们可以传入参数值来构造一个完整的路径：

1
2

fmt.Println(r.Get("book").URL("isbn", "978-7-111-55842-2"))
// /books/978-7-111-55842-2 <nil>

返回的是一个*url.URL对象，其路径部分为/books/978-7-111-55842-2。这同样适用于主机名和查询参数：

r := mux.Router()
r.Host("{name}.github.io").
 Path("/books/{isbn}").
 HandlerFunc(BookHandler).
 Name("book")

url, err := r.Get("book").URL("name", "darjun", "isbn", "978-7-111-55842-2")

路径中所有的参数都需要指定，并且值需要满足指定的正则表达式（如果有的话）。运行输出：

1
2

$ go run main.go
http://darjun.github.io/books/978-7-111-55842-2

可以调用URLHost()只生成主机名部分，URLPath()只生成路径部分。

中间件

mux定义了中间件类型MiddlewareFunc：

`1`	`type MiddlewareFunc func(http.Handler) http.Handler`

所有满足该类型的函数都可以作为mux的中间件使用，通过调用路由对象*mux.Router的Use()方法应用中间件。如果看过我上一篇文章《Go 每日一库之 net/http（基础和中间件）》应该对这种中间件不陌生了。编写中间件一般会将原处理器传入，中间件中会手动调用原处理函数，然后在前后增加通用处理逻辑：

func loggingMiddleware(next http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    log.Println(r.RequestURI)
    next.ServeHTTP(w, r)
  })
}

我在上篇文章中写的 3 个中间件可以直接使用，这就是兼容net/http的好处：

func main() {
  logger = log.New(os.Stdout, "[goweb]", log.Lshortfile|log.LstdFlags)

  r := mux.NewRouter()
  // 直接使用上一篇文章中定义的中间件
  r.Use(PanicRecover, WithLogger, Metric)
  InitBooksRouter(r)
  InitMoviesRouter(r)

  http.Handle("/", r)
  log.Fatal(http.ListenAndServe(":8080", nil))
}

如果不手动调用原处理函数，那么原处理函数就不会执行，这可以用来在校验不通过时直接返回错误。例如，网站需要登录才能访问，而 HTTP 是一个无状态的协议。所以发明了 Cookie 机制用于在客户端和服务器之间记录一些信息。

我们在登录成功之后生成一个键为token的 Cookie 表示已登录成功，我们可以编写一个中间件来出来这块逻辑，如果 Cookie 不存在或者非法，则重定向到登录界面：

func login(w http.ResponseWriter, r *http.Request) {
  ptTemplate.ExecuteTemplate(w, "login.tpl", nil)
}

func doLogin(w http.ResponseWriter, r *http.Request) {
  r.ParseForm()
  username := r.Form.Get("username")
  password := r.Form.Get("password")
  if username != "darjun" || password != "handsome" {
    http.Redirect(w, r, "/login", http.StatusFound)
    return
  }

  token := fmt.Sprintf("username=%s&password=%s", username, password)
  data := base64.StdEncoding.EncodeToString([]byte(token))
  http.SetCookie(w, &http.Cookie{
    Name:     "token",
    Value:    data,
    Path:     "/",
    HttpOnly: true,
    Expires:  time.Now().Add(24 * time.Hour),
  })
  http.Redirect(w, r, "/", http.StatusFound)
}

上面为了记录登录状态，我将登录的用户名和密码组合成username=xxx&password=xxx形式的字符串，对这个字符串进行base64编码，然后设置到 Cookie 中。Cookie 有效期为 24 小时。同时为了安全只允许 HTTP 访问此 Cookie（JS 脚本不可访问）。当然这种方式安全性很低，这里只是为了演示。登录成功之后重定向到/。

为了展示登录界面，我创建了几个template模板文件，使用html/template解析：

登录展示页面：

// login.tpl
<form action="/login" method="post">
  <label>Username:</label>
  <input name="username"><br>
  <label>Password:</label>
  <input name="password" type="password"><br>
  <button type="submit">登录</button>
</form>

主页面

<ul>
  <li><a href="/books/">图书</a></li>
  <li><a href="/movies/">电影</a></li>
</ul>

同时也创建了图书和电影的页面：

// movies.tpl
<ol>
  {{ range . }}
  <li>
    <p>书名: <a href="/movies/{{ .IMDB }}">{{ .Name }}</a></p>
    <p>上映日期: {{ .PublishedAt }}</p>
    <p>时长: {{ .Duration }}分</p>
    <p>语言: {{ .Lang }}</p>
  </li>
  {{ end }}
</ol>

// movie.tpl
<p>IMDB: {{ .IMDB }}</p>
<p>电影名: {{ .Name }}</p>
<p>上映日期: {{ .PublishedAt }}</p>
<p>时长: {{ .Duration }}分</p>
<p>语言: {{ .Lang }}</p>

图书页面类似。接下来要解析模板：

var (
  ptTemplate *template.Template
)

func init() {
  var err error
  ptTemplate, err = template.New("").ParseGlob("./tpls/*.tpl")
  if err != nil {
    log.Fatalf("load templates failed:%v", err)
  }
}

访问对应的页面逻辑：

func MoviesHandler(w http.ResponseWriter, r *http.Request) {
  ptTemplate.ExecuteTemplate(w, "movies.tpl", slcMovies)
}

func MovieHandler(w http.ResponseWriter, r *http.Request) {
  movie, ok := mapMovies[mux.Vars(r)["imdb"]]
  if !ok {
    http.NotFound(w, r)
    return
  }

  ptTemplate.ExecuteTemplate(w, "movie.tpl", movie)
}

执行对应的模板，传入电影列表或某个具体的电影信息即可。现在页面没有限制访问，我们来编写一个中间件限制只有登录用户才能访问，未登录用户访问时跳转到登录界面：

func authenticateMiddleware(next http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    cookie, err := r.Cookie("token")
    if err != nil {
      // no cookie
      http.Redirect(w, r, "/login", http.StatusFound)
      return
    }

    data, _ := base64.StdEncoding.DecodeString(cookie.Value)
    values, _ := url.ParseQuery(string(data))
    if values.Get("username") != "dj" && values.Get("password") != "handsome" {
      // failed
      http.Redirect(w, r, "/login", http.StatusFound)
      return
    }

    next.ServeHTTP(w, r)
  })
}

再次强调，这里只是为了演示，这种验证方式安全性很低。

然后，我们让books和movies子路由应用中间件authenticateMiddleware（需要登录验证），而login子路由不用：

func InitBooksRouter(r *mux.Router) {
  bs := r.PathPrefix("/books").Subrouter()
  // 这里
  bs.Use(authenticateMiddleware)
  bs.HandleFunc("/", BooksHandler)
  bs.HandleFunc("/{isbn}", BookHandler)
}

func InitMoviesRouter(r *mux.Router) {
  ms := r.PathPrefix("/movies").Subrouter()
  // 这里
  ms.Use(authenticateMiddleware)
  ms.HandleFunc("/", MoviesHandler)
  ms.HandleFunc("/{id}", MovieHandler)
}

func InitLoginRouter(r *mux.Router) {
  ls := r.PathPrefix("/login").Subrouter()
  ls.Methods("GET").HandlerFunc(login)
  ls.Methods("POST").HandlerFunc(doLogin)
}

运行程序（注意多文件程序运行方式）：

`1`	`$ go run .`

访问localhost:8080/movies/，会重定向到localhost:8080/login。输入用户名darjun，密码handsome，登录成功显示主页面。后面的请求都不需要验证了，请随意点击点击吧😀

总结

本文介绍了轻量级的，功能强大的路由库gorilla/mux。它支持丰富的请求匹配方法，子路由能极大地方便我们管理路由。由于兼容标准库net/http，所以可以无缝集成到使用net/http的程序中，利用为net/http编写的中间件资源。下一篇我们介绍gorilla/handlers——一些常用的中间件。

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

参考

gorilla/mux GitHub：github.com/gorilla/gorilla/mux
Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 net/http（基础和中间件）

Tue, 13 Jul 2021 06:12:35 +0000

简介

几乎所有的编程语言都以Hello World作为入门程序的示例，其中有一部分以编写一个 Web 服务器作为实战案例的开始。每种编程语言都有很多用于编写 Web 服务器的库，或以标准库，或通过第三方库的方式提供。Go 语言也不例外。本文及后续的文章就去探索 Go 语言中的各个Web 编程框架，它们的基本使用，阅读它们的源码，比较它们优缺点。让我们先从 Go 语言的标准库net/http开始。标准库net/http让编写 Web 服务器的工作变得非常简单。我们一起探索如何使用net/http库实现一些常见的功能或模块，了解这些对我们学习其他的库或框架将会很有帮助。

Hello World

使用net/http编写一个简单的 Web 服务器非常简单：

package main

import (
  "fmt"
  "net/http"
)

func index(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintln(w, "Hello World")
}

func main() {
  http.HandleFunc("/", index)
  http.ListenAndServe(":8080", nil)
}

首先，我们调用http.HandleFunc("/", index)注册路径处理函数，这里将路径/的处理函数设置为index。处理函数的类型必须是：

`1`	`func (http.ResponseWriter, *http.Request)`

其中*http.Request表示 HTTP 请求对象，该对象包含请求的所有信息，如 URL、首部、表单内容、请求的其他内容等。

http.ResponseWriter是一个接口类型：

// net/http/server.go
type ResponseWriter interface {
  Header() Header
  Write([]byte) (int, error)
  WriteHeader(statusCode int)
}

用于向客户端发送响应，实现了ResponseWriter接口的类型显然也实现了io.Writer接口。所以在处理函数index中，可以调用fmt.Fprintln()向ResponseWriter写入响应信息。

仔细阅读net/http包中HandleFunc()函数的源码：

1
2
3

func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) {
  DefaultServeMux.HandleFunc(pattern, handler)
}

我们发现它直接调用了一个名为DefaultServeMux对象的HandleFunc()方法。DefaultServeMux是ServeMux类型的实例：

type ServeMux struct {
  mu    sync.RWMutex
  m     map[string]muxEntry
  es    []muxEntry // slice of entries sorted from longest to shortest.
  hosts bool       // whether any patterns contain hostnames
}

var DefaultServeMux = &defaultServeMux
var defaultServeMux ServeMux

像这种提供默认类型实例的用法在 Go 语言的各个库中非常常见，在默认参数就已经足够的场景中使用默认实现很方便。ServeMux保存了注册的所有路径和处理函数的对应关系。ServeMux.HandleFunc()方法如下：

1
2
3

func (mux *ServeMux) HandleFunc(pattern string, handler func(ResponseWriter, *Request)) {
  mux.Handle(pattern, HandlerFunc(handler))
}

这里将处理函数handler转为HandlerFunc类型，然后调用ServeMux.Handle()方法注册。注意这里的HandlerFunc(handler)是类型转换，而非函数调用，类型HandlerFunc的定义如下：

type HandlerFunc func(ResponseWriter, *Request)

func (f HandlerFunc) ServeHTTP(w ResponseWriter, r *Request) {
  f(w, r)
}

HandlerFunc实际上是以函数类型func(ResponseWriter, *Request)为底层类型，为HandlerFunc类型定义了方法ServeHTTP。是的，Go 语言允许为（基于）函数的类型定义方法。Serve.Handle()方法只接受类型为接口Handler的参数：

type Handler interface {
  ServeHTTP(ResponseWriter, *Request)
}

func (mux *ServeMux) Handle(pattern string, handler Handler) {
  if mux.m == nil {
    mux.m = make(map[string]muxEntry)
  }
  e := muxEntry{h: handler, pattern: pattern}
  if pattern[len(pattern)-1] == '/' {
    mux.es = appendSorted(mux.es, e)
  }
  mux.m[pattern] = e
}

显然HandlerFunc实现了接口Handler。HandlerFunc类型只是为了方便注册函数类型的处理器。我们当然可以直接定义一个实现Handler接口的类型，然后注册该类型的实例：

type greeting string

func (g greeting) ServeHTTP(w http.ResponseWriter, r *http.Request) {
  fmt.Fprintln(w, g)
}

http.Handle("/greeting", greeting("Welcome, dj"))

我们基于string类型定义了一个新类型greeting，然后为它定义一个方法ServeHTTP()（实现接口Handler），最后调用http.Handle()方法注册该处理器。

为了便于区分，我们将通过HandleFunc()注册的称为处理函数，将通过Handle()注册的称为处理器。通过上面的源码分析不难看出，它们在底层本质上是一回事。

注册了处理逻辑后，调用http.ListenAndServe(":8080", nil)监听本地计算机的 8080 端口，开始处理请求。下面看源码的处理：

func ListenAndServe(addr string, handler Handler) error {
  server := &Server{Addr: addr, Handler: handler}
  return server.ListenAndServe()
}

ListenAndServe创建了一个Server类型的对象：

type Server struct {
  Addr string
  Handler Handler
  TLSConfig *tls.Config
  ReadTimeout time.Duration
  ReadHeaderTimeout time.Duration
  WriteTimeout time.Duration
  IdleTimeout time.Duration
}

Server结构体有比较多的字段，我们可以使用这些字段来调节 Web 服务器的参数，如上面的ReadTimeout/ReadHeaderTimeout/WriteTimeout/IdleTimeout用于控制读写和空闲超时。在该方法中，先调用net.Listen()监听端口，将返回的net.Listener作为参数调用Server.Serve()方法：

func (srv *Server) ListenAndServe() error {
  addr := srv.Addr
  ln, err := net.Listen("tcp", addr)
  if err != nil {
    return err
  }
  return srv.Serve(ln)
}

在Server.Serve()方法中，使用一个无限的for循环，不停地调用Listener.Accept()方法接受新连接，开启新 goroutine 处理新连接：

func (srv *Server) Serve(l net.Listener) error {
  var tempDelay time.Duration // how long to sleep on accept failure
  for {
    rw, err := l.Accept()
    if err != nil {
      if ne, ok := err.(net.Error); ok && ne.Temporary() {
        if tempDelay == 0 {
          tempDelay = 5 * time.Millisecond
        } else {
          tempDelay *= 2
        }
        if max := 1 * time.Second; tempDelay > max {
          tempDelay = max
        }
        srv.logf("http: Accept error: %v; retrying in %v", err, tempDelay)
        time.Sleep(tempDelay)
        continue
      }
      return err
    }
    tempDelay = 0
    c := srv.newConn(rw)
    go c.serve(connCtx)
  }
}

这里有一个指数退避策略的用法。如果l.Accept()调用返回错误，我们判断该错误是不是临时性地（ne.Temporary()）。如果是临时性错误，Sleep一小段时间后重试，每发生一次临时性错误，Sleep的时间翻倍，最多Sleep 1s。获得新连接后，将其封装成一个conn对象（srv.newConn(rw)），创建一个 goroutine 运行其serve()方法。省略无关逻辑的代码如下：

func (c *conn) serve(ctx context.Context) {
  for {
    w, err := c.readRequest(ctx)
    serverHandler{c.server}.ServeHTTP(w, w.req)
    w.finishRequest()
  }
}

serve()方法其实就是不停地读取客户端发送地请求，创建serverHandler对象调用其ServeHTTP()方法去处理请求，然后做一些清理工作。serverHandler只是一个中间的辅助结构，代码如下：

type serverHandler struct {
  srv *Server
}

func (sh serverHandler) ServeHTTP(rw ResponseWriter, req *Request) {
  handler := sh.srv.Handler
  if handler == nil {
    handler = DefaultServeMux
  }
  handler.ServeHTTP(rw, req)
}

从Server对象中获取Handler，这个Handler就是调用http.ListenAndServe()时传入的第二个参数。在Hello World的示例代码中，我们传入了nil。所以这里handler会取默认值DefaultServeMux。调用DefaultServeMux.ServeHTTP()方法处理请求：

func (mux *ServeMux) ServeHTTP(w ResponseWriter, r *Request) {
  h, _ := mux.Handler(r)
  h.ServeHTTP(w, r)
}

mux.Handler(r)通过请求的路径信息查找处理器，然后调用处理器的ServeHTTP()方法处理请求：

func (mux *ServeMux) Handler(r *Request) (h Handler, pattern string) {
  host := stripHostPort(r.Host)
  return mux.handler(host, r.URL.Path)
}

func (mux *ServeMux) handler(host, path string) (h Handler, pattern string) {
  h, pattern = mux.match(path)
  return
}

func (mux *ServeMux) match(path string) (h Handler, pattern string) {
  v, ok := mux.m[path]
  if ok {
    return v.h, v.pattern
  }

  for _, e := range mux.es {
    if strings.HasPrefix(path, e.pattern) {
      return e.h, e.pattern
    }
  }
  return nil, ""
}

上面的代码省略了大量的无关代码，在match方法中，首先会检查路径是否精确匹配mux.m[path]。如果不能精确匹配，后面的for循环会匹配路径的最长前缀。只要注册了/根路径处理，所有未匹配到的路径最终都会交给/路径处理。为了保证最长前缀优先，在注册时，会对路径进行排序。所以mux.es中存放的是按路径排序的处理列表：

func appendSorted(es []muxEntry, e muxEntry) []muxEntry {
  n := len(es)
  i := sort.Search(n, func(i int) bool {
    return len(es[i].pattern) < len(e.pattern)
  })
  if i == n {
    return append(es, e)
  }
  es = append(es, muxEntry{})
  copy(es[i+1:], es[i:])
  es[i] = e
  return es
}

运行，在浏览器中键入网址localhost:8080，可以看到网页显示Hello World。键入网址localhost:8080/greeting，看到网页显示Welcome, dj。

思考题：根据最长前缀的逻辑，如果键入localhost:8080/greeting/a/b/c，应该会匹配/greeting路径。如果键入localhost:8080/a/b/c，应该会匹配/路径。是这样么？答案放在后面😀。

创建`ServeMux`

调用http.HandleFunc()/http.Handle()都是将处理器/函数注册到ServeMux的默认对象DefaultServeMux上。使用默认对象有一个问题：不可控。

一来Server参数都使用了默认值，二来第三方库也可能使用这个默认对象注册一些处理，容易冲突。更严重的是，我们在不知情中调用http.ListenAndServe()开启 Web 服务，那么第三方库注册的处理逻辑就可以通过网络访问到，有极大的安全隐患。所以，除非在示例程序中，否则建议不要使用默认对象。

我们可以使用http.NewServeMux()创建一个新的ServeMux对象，然后创建http.Server对象定制参数，用ServeMux对象初始化Server的Handler字段，最后调用Server.ListenAndServe()方法开启 Web 服务：

func main() {
  mux := http.NewServeMux()
  mux.HandleFunc("/", index)
  mux.Handle("/greeting", greeting("Welcome to go web frameworks"))

  server := &http.Server{
    Addr:         ":8080",
    Handler:      mux,
    ReadTimeout:  20 * time.Second,
    WriteTimeout: 20 * time.Second,
  }
  server.ListenAndServe()
}

这个程序与上面的Hello World功能基本相同，我们还额外设置了读写超时。

为了便于理解，我画了两幅图，其实整理下来整个流程也不复杂：

中间件

有时候需要在请求处理代码中增加一些通用的逻辑，如统计处理耗时、记录日志、捕获宕机等等。如果在每个请求处理函数中添加这些逻辑，代码很快就会变得不可维护，添加新的处理函数也会变得非常繁琐。所以就有了中间件的需求。

中间件有点像面向切面的编程思想，但是与 Java 语言不同。在 Java 中，通用的处理逻辑（也可以称为切面）可以通过反射插入到正常逻辑的处理流程中，在 Go 语言中基本不这样做。

在 Go 中，中间件是通过函数闭包来实现的。Go 语言中的函数是第一类值，既可以作为参数传给其他函数，也可以作为返回值从其他函数返回。我们前面介绍了处理器/函数的使用和实现。那么可以利用闭包封装已有的处理函数。

首先，基于函数类型func(http.Handler) http.Handler定义一个中间件类型：

`1`	`type Middleware func(http.Handler) http.Handler`

接下来我们来编写中间件，最简单的中间件就是在请求前后各输出一条日志：

func WithLogger(handler http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    logger.Printf("path:%s process start...\n", r.URL.Path)
    defer func() {
      logger.Printf("path:%s process end...\n", r.URL.Path)
    }()
    handler.ServeHTTP(w, r)
  })
}

实现很简单，通过中间件封装原来的处理器对象，然后返回一个新的处理函数。在新的处理函数中，先输出开始处理的日志，然后用defer语句在函数结束后输出处理结束的日志。接着调用原处理器对象的ServeHTTP()方法执行原处理逻辑。

类似地，我们再来实现一个统计处理耗时的中间件：

func Metric(handler http.Handler) http.HandlerFunc {
  return func (w http.ResponseWriter, r *http.Request) {
    start := time.Now()
    defer func() {
      logger.Printf("path:%s elapsed:%fs\n", r.URL.Path, time.Since(start).Seconds())
    }()
    time.Sleep(1 * time.Second)
    handler.ServeHTTP(w, r)
  }
}

Metric中间件封装原处理器对象，开始执行前记录时间，执行完成后输出耗时。为了能方便看到结果，我在上面代码中添加了一个time.Sleep()调用。

最后，由于请求的处理逻辑都是由功能开发人员（而非库作者）自己编写的，所以为了 Web 服务器的稳定，我们需要捕获可能出现的 panic。PanicRecover中间件如下：

func PanicRecover(handler http.Handler) http.Handler {
  return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    defer func() {
      if err := recover(); err != nil {
        logger.Println(string(debug.Stack()))
      }
    }()

    handler.ServeHTTP(w, r)
  })
}

调用recover()函数捕获 panic，输出堆栈信息，为了防止程序异常退出。实际上，在conn.serve()方法中也有recover()，程序一般不会异常退出。但是自定义的中间件可以添加我们自己的定制逻辑。

现在我们可以这样来注册处理函数：

1
2

mux.Handle("/", PanicRecover(WithLogger(Metric(http.HandlerFunc(index)))))
mux.Handle("/greeting", PanicRecover(WithLogger(Metric(greeting("welcome, dj")))))

这种方式略显繁琐，我们可以编写一个帮助函数，它接受原始的处理器对象，和可变的多个中间件。对处理器对象应用这些中间件，返回新的处理器对象：

func applyMiddlewares(handler http.Handler, middlewares ...Middleware) http.Handler {
  for i := len(middlewares)-1; i >= 0; i-- {
    handler = middlewares[i](handler)
  }

  return handler
}

注意应用顺序是从右到左的，即右结合，越靠近原处理器的越晚执行。

利用帮助函数，注册可以简化为：

middlewares := []Middleware{
  PanicRecover,
  WithLogger,
  Metric,
}
mux.Handle("/", applyMiddlewares(http.HandlerFunc(index), middlewares...))
mux.Handle("/greeting", applyMiddlewares(greeting("welcome, dj"), middlewares...))

上面每次注册处理逻辑都需要调用一次applyMiddlewares()函数，还是略显繁琐。我们可以这样来优化，封装一个自己的ServeMux结构，然后定义一个方法Use()将中间件保存下来，重写Handle/HandleFunc将传入的http.HandlerFunc/http.Handler处理器包装中间件之后再传给底层的ServeMux.Handle()方法：

type MyMux struct {
  *http.ServeMux
  middlewares []Middleware
}

func NewMyMux() *MyMux {
  return &MyMux{
    ServeMux: http.NewServeMux(),
  }
}

func (m *MyMux) Use(middlewares ...Middleware) {
  m.middlewares = append(m.middlewares, middlewares...)
}

func (m *MyMux) Handle(pattern string, handler http.Handler) {
  handler = applyMiddlewares(handler, m.middlewares...)
  m.ServeMux.Handle(pattern, handler)
}

func (m *MyMux) HandleFunc(pattern string, handler http.HandlerFunc) {
  newHandler := applyMiddlewares(handler, m.middlewares...)
  m.ServeMux.Handle(pattern, newHandler)
}

注册时只需要创建MyMux对象，调用其Use()方法传入要应用的中间件即可：

middlewares := []Middleware{
  PanicRecover,
  WithLogger,
  Metric,
}
mux := NewMyMux()
mux.Use(middlewares...)
mux.HandleFunc("/", index)
mux.Handle("/greeting", greeting("welcome, dj"))

这种方式简单易用，但是也有它的问题，最大的问题是必须先设置好中间件，然后才能调用Handle/HandleFunc注册，后添加的中间件不会对之前注册的处理器/函数生效。

为了解决这个问题，我们可以改写ServeHTTP方法，在确定了处理器之后再应用中间件。这样后续添加的中间件也能生效。很多第三方库都是采用这种方式。http.ServeMux默认的ServeHTTP()方法如下：

func (m *ServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request) {
  if r.RequestURI == "*" {
    if r.ProtoAtLeast(1, 1) {
      w.Header().Set("Connection", "close")
    }
    w.WriteHeader(http.StatusBadRequest)
    return
  }
  h, _ := m.Handler(r)
  h.ServeHTTP(w, r)
}

改造这个方法定义MyMux类型的ServeHTTP()方法也很简单，只需要在m.Handler(r)获取处理器之后，应用当前的中间件即可：

func (m *MyMux) ServeHTTP(w http.ResponseWriter, r *http.Request) {
  // ...
  h, _ := m.Handler(r)
  // 只需要加这一行即可
  h = applyMiddlewares(h, m.middlewares...)
  h.ServeHTTP(w, r)
}

后面我们分析其他 Web 框架的源码时会发现，很多都是类似的做法。为了测试宕机恢复，编写一个会触发 panic 的处理函数：

func panics(w http.ResponseWriter, r *http.Request) {
  panic("not implemented")
}

mux.HandleFunc("/panic", panics)

运行，在浏览器中请求localhost:8080/和localhost:8080/greeting，最后请求localhost:8080/panic触发 panic：

思考题

思考题：

这其实就是看阅读代码是不是仔细，最长前缀的排序列表在ServeMux.Handle()方法中生成：

func (mux *ServeMux) Handle(pattern string, handler Handler) {
  if pattern[len(pattern)-1] == '/' {
    mux.es = appendSorted(mux.es, e)
  }
}

这里明显有个限制条件，即注册路径最后必须以/结尾才会触发。所以localhost:8080/greeting/a/b/c和localhost:8080/a/b/c都只会匹配/路径。如果想要让localhost:8080/greeting/a/b/c匹配路径/greeting，注册路径需要改为/greeting/：

`1`	`http.Handle("/greeting/", greeting("Welcome to go web frameworks"))`

这时请求路径/greeting会自动重定向（301）到/greeting/。

总结

本文介绍了使用标准库net/http创建 Web 服务器的基本流程，一步步分析源码。然后介绍了如何使用中间件简化通用的处理逻辑。学习并理解了net/http库的内容对于学习其他的 Go Web 框架非常有帮助。第三方的 Go Web 框架大多也是基于net/http实现自己的ServeMux对象而已。

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

参考

Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib

我

我的博客：https://darjun.github.io

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

Go 每日一库之 colly

Thu, 01 Jul 2021 07:09:00 +0000

简介

colly是用 Go 语言编写的功能强大的爬虫框架。它提供简洁的 API，拥有强劲的性能，可以自动处理 cookie&session，还有提供灵活的扩展机制。

首先，我们介绍colly的基本概念。然后通过几个案例来介绍colly的用法和特性：拉取 GitHub Treading，拉取百度小说热榜，下载 Unsplash 网站上的图片。

快速使用

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir colly && cd colly
$ go mod init github.com/darjun/go-daily-lib/colly

安装colly库：

`1`	`$ go get -u github.com/gocolly/colly/v2`

使用：

package main

import (
  "fmt"

  "github.com/gocolly/colly/v2"
)

func main() {
  c := colly.NewCollector(
    colly.AllowedDomains("www.baidu.com" ),
  )

  c.OnHTML("a[href]", func(e *colly.HTMLElement) {
    link := e.Attr("href")
    fmt.Printf("Link found: %q -> %s\n", e.Text, link)
    c.Visit(e.Request.AbsoluteURL(link))
  })

  c.OnRequest(func(r *colly.Request) {
    fmt.Println("Visiting", r.URL.String())
  })

  c.OnResponse(func(r *colly.Response) {
    fmt.Printf("Response %s: %d bytes\n", r.Request.URL, len(r.Body))
  })

  c.OnError(func(r *colly.Response, err error) {
    fmt.Printf("Error %s: %v\n", r.Request.URL, err)
  })

  c.Visit("http://www.baidu.com/")
}

colly的使用比较简单：

首先，调用colly.NewCollector()创建一个类型为*colly.Collector的爬虫对象。由于每个网页都有很多指向其他网页的链接。如果不加限制的话，运行可能永远不会停止。所以上面通过传入一个选项colly.AllowedDomains("www.baidu.com")限制只爬取域名为www.baidu.com的网页。

然后我们调用c.OnHTML方法注册HTML回调，对每个有href属性的a元素执行回调函数。这里继续访问href指向的 URL。也就是说解析爬取到的网页，然后继续访问网页中指向其他页面的链接。

调用c.OnRequest()方法注册请求回调，每次发送请求时执行该回调，这里只是简单打印请求的 URL。

调用c.OnResponse()方法注册响应回调，每次收到响应时执行该回调，这里也只是简单的打印 URL 和响应大小。

调用c.OnError()方法注册错误回调，执行请求发生错误时执行该回调，这里简单打印 URL 和错误信息。

最后我们调用c.Visit()开始访问第一个页面。

运行：

$ go run main.go
Visiting http://www.baidu.com/
Response http://www.baidu.com/: 303317 bytes
Link found: "百度首页" -> /
Link found: "设置" -> javascript:;
Link found: "登录" -> https://passport.baidu.com/v2/?login&tpl=mn&u=http%3A%2F%2Fwww.baidu.com%2F&sms=5
Link found: "新闻" -> http://news.baidu.com
Link found: "hao123" -> https://www.hao123.com
Link found: "地图" -> http://map.baidu.com
Link found: "直播" -> https://live.baidu.com/
Link found: "视频" -> https://haokan.baidu.com/?sfrom=baidu-top
Link found: "贴吧" -> http://tieba.baidu.com
...

colly爬取到页面之后，会使用goquery解析这个页面。然后查找注册的 HTML 回调对应元素选择器（element-selector），将goquery.Selection封装成一个colly.HTMLElement执行回调。

colly.HTMLElement其实就是对goquery.Selection的简单封装：

type HTMLElement struct {
  Name string
  Text string
  Request *Request
  Response *Response
  DOM *goquery.Selection
  Index int
}

并提供了简单易用的方法：

Attr(k string)：返回当前元素的属性，上面示例中我们使用e.Attr("href")获取了href属性；
ChildAttr(goquerySelector, attrName string)：返回goquerySelector选择的第一个子元素的attrName属性；
ChildAttrs(goquerySelector, attrName string)：返回goquerySelector选择的所有子元素的attrName属性，以[]string返回；
ChildText(goquerySelector string)：拼接goquerySelector选择的子元素的文本内容并返回；
ChildTexts(goquerySelector string)：返回goquerySelector选择的子元素的文本内容组成的切片，以[]string返回。
ForEach(goquerySelector string, callback func(int, *HTMLElement))：对每个goquerySelector选择的子元素执行回调callback；
Unmarshal(v interface{})：通过给结构体字段指定 goquerySelector 格式的 tag，可以将一个 HTMLElement 对象 Unmarshal 到一个结构体实例中。

这些方法会被频繁地用到。下面我们就通过一些示例来介绍colly的特性和用法。

GitHub Treading

我之前写过一个拉取GitHub Treading 的 API，用colly更方便：

type Repository struct {
  Author  string
  Name    string
  Link    string
  Desc    string
  Lang    string
  Stars   int
  Forks   int
  Add     int
  BuiltBy []string
}

func main() {
  c := colly.NewCollector(
    colly.MaxDepth(1),
  )


  repos := make([]*Repository, 0, 15)
  c.OnHTML(".Box .Box-row", func (e *colly.HTMLElement) {
    repo := &Repository{}

    // author & repository name
    authorRepoName := e.ChildText("h1.h3 > a")
    parts := strings.Split(authorRepoName, "/")
    repo.Author = strings.TrimSpace(parts[0])
    repo.Name = strings.TrimSpace(parts[1])

    // link
    repo.Link = e.Request.AbsoluteURL(e.ChildAttr("h1.h3 >a", "href"))

    // description
    repo.Desc = e.ChildText("p.pr-4")

    // language
    repo.Lang = strings.TrimSpace(e.ChildText("div.mt-2 > span.mr-3 > span[itemprop]"))

    // star & fork
    starForkStr := e.ChildText("div.mt-2 > a.mr-3")
    starForkStr = strings.Replace(strings.TrimSpace(starForkStr), ",", "", -1)
    parts = strings.Split(starForkStr, "\n")
    repo.Stars , _=strconv.Atoi(strings.TrimSpace(parts[0]))
    repo.Forks , _=strconv.Atoi(strings.TrimSpace(parts[len(parts)-1]))

    // add
    addStr := e.ChildText("div.mt-2 > span.float-sm-right")
    parts = strings.Split(addStr, " ")
    repo.Add, _ = strconv.Atoi(parts[0])

    // built by
    e.ForEach("div.mt-2 > span.mr-3  img[src]", func (index int, img *colly.HTMLElement) {
      repo.BuiltBy = append(repo.BuiltBy, img.Attr("src"))
    })

    repos = append(repos, repo)
  })

  c.Visit("https://github.com/trending")
  
  fmt.Printf("%d repositories\n", len(repos))
  fmt.Println("first repository:")
  for _, repo := range repos {
      fmt.Println("Author:", repo.Author)
      fmt.Println("Name:", repo.Name)
      break
  }
}

我们用ChildText获取作者、仓库名、语言、星数和 fork 数、今日新增等信息，用ChildAttr获取仓库链接，这个链接是一个相对路径，通过调用e.Request.AbsoluteURL()方法将它转为一个绝对路径。

运行：

$ go run main.go
25 repositories
first repository:
Author: Shopify
Name: dawn

百度小说热榜

网页结构如下：

各部分结构如下：

每条热榜各自在一个div.category-wrap_iQLoo中；
a元素下div.index_1Ew5p是排名；
内容在div.content_1YWBm中；
内容中a.title_dIF3B是标题；
内容中两个div.intro_1l0wp，前一个是作者，后一个是类型；
内容中div.desc_3CTjT是描述。

由此我们定义结构：

type Hot struct {
  Rank   string `selector:"a > div.index_1Ew5p"`
  Name   string `selector:"div.content_1YWBm > a.title_dIF3B"`
  Author string `selector:"div.content_1YWBm > div.intro_1l0wp:nth-child(2)"`
  Type   string `selector:"div.content_1YWBm > div.intro_1l0wp:nth-child(3)"`
  Desc   string `selector:"div.desc_3CTjT"`
}

tag 中是 CSS 选择器语法，添加这个是为了可以直接调用HTMLElement.Unmarshal()方法填充Hot对象。

然后创建Collector对象：

`1`	`c := colly.NewCollector()`

注册回调：

c.OnHTML("div.category-wrap_iQLoo", func(e *colly.HTMLElement) {
  hot := &Hot{}

  err := e.Unmarshal(hot)
  if err != nil {
    fmt.Println("error:", err)
    return
  }

  hots = append(hots, hot)
})

c.OnRequest(func(r *colly.Request) {
  fmt.Println("Requesting:", r.URL)
})

c.OnResponse(func(r *colly.Response) {
  fmt.Println("Response:", len(r.Body))
})

OnHTML对每个条目执行Unmarshal生成Hot对象。

OnRequest/OnResponse只是简单输出调试信息。

然后，调用c.Visit()访问网址：

err := c.Visit("https://top.baidu.com/board?tab=novel")
if err != nil {
  fmt.Println("Visit error:", err)
  return
}

最后添加一些调试打印：

fmt.Printf("%d hots\n", len(hots))
for _, hot := range hots {
  fmt.Println("first hot:")
  fmt.Println("Rank:", hot.Rank)
  fmt.Println("Name:", hot.Name)
  fmt.Println("Author:", hot.Author)
  fmt.Println("Type:", hot.Type)
  fmt.Println("Desc:", hot.Desc)
  break
}

运行输出：

Requesting: https://top.baidu.com/board?tab=novel
Response: 118083
30 hots
first hot:
Rank: 1
Name: 逆天邪神
Author: 作者：火星引力
Type: 类型：玄幻
Desc: 掌天毒之珠，承邪神之血，修逆天之力，一代邪神，君临天下！  查看更多>

Unsplash

我写公众号文章，背景图片基本都是从 unsplash 这个网站获取。unsplash 提供了大量的、丰富的、免费的图片。这个网站有个问题，就是访问速度比较慢。既然学习爬虫，刚好利用程序自动下载图片。

unsplash 首页如下图所示：

网页结构如下：

但是首页上显示的都是尺寸较小的图片，我们点开某张图片的链接：

网页结构如下：

由于涉及三层网页结构（img最后还需要访问一次），使用一个colly.Collector对象，OnHTML回调设置需要格外小心，给编码带来比较大的心智负担。colly支持多个Collector，我们采用这种方式来编码：

func main() {
  c1 := colly.NewCollector()
  c2 := c1.Clone()
  c3 := c1.Clone()

  c1.OnHTML("figure[itemProp] a[itemProp]", func(e *colly.HTMLElement) {
    href := e.Attr("href")
    if href == "" {
      return
    }

    c2.Visit(e.Request.AbsoluteURL(href))
  })

  c2.OnHTML("div._1g5Lu > img[src]", func(e *colly.HTMLElement) {
    src := e.Attr("src")
    if src == "" {
      return
    }

    c3.Visit(src)
  })

  c1.OnRequest(func(r *colly.Request) {
    fmt.Println("Visiting", r.URL)
  })

  c1.OnError(func(r *colly.Response, err error) {
    fmt.Println("Visiting", r.Request.URL, "failed:", err)
  })
}

我们使用 3 个Collector对象，第一个Collector用于收集首页上对应的图片链接，然后使用第二个Collector去访问这些图片链接，最后让第三个Collector去下载图片。上面我们还为第一个Collector注册了请求和错误回调。

第三个Collector下载到具体的图片内容后，保存到本地：

func main() {
  // ... 省略
  var count uint32
  c3.OnResponse(func(r *colly.Response) {
    fileName := fmt.Sprintf("images/img%d.jpg", atomic.AddUint32(&count, 1))
    err := r.Save(fileName)
    if err != nil {
      fmt.Printf("saving %s failed:%v\n", fileName, err)
    } else {
      fmt.Printf("saving %s success\n", fileName)
    }
  })

  c3.OnRequest(func(r *colly.Request) {
    fmt.Println("visiting", r.URL)
  })
}

上面使用atomic.AddUint32()为图片生成序号。

运行程序，爬取结果：

异步

默认情况下，colly爬取网页是同步的，即爬完一个接着爬另一个，上面的 unplash 程序就是如此。这样需要很长时间，colly提供了异步爬取的特性，我们只需要在构造Collector对象时传入选项colly.Async(true)即可开启异步：

1
2
3

c1 := colly.NewCollector(
  colly.Async(true),
)

但是，由于是异步爬取，所以程序最后需要等待Collector处理完成，否则早早地退出main，程序会退出：

1
2
3

c1.Wait()
c2.Wait()
c3.Wait()

再次运行，速度快了很多😀。

第二版

向下滑动 unsplash 的网页，我们发现后面的图片是异步加载的。滚动页面，通过 chrome 浏览器的 network 页签查看请求：

请求路径/photos，设置per_page和page参数，返回的是一个 JSON 数组。所以有了另一种方式：

定义每一项的结构体，我们只保留必要的字段：

type Item struct {
  Id     string
  Width  int
  Height int
  Links  Links
}

type Links struct {
  Download string
}

然后在OnResponse回调中解析 JSON，对每一项的Download链接调用负责下载图像的Collector的Visit()方法：

c.OnResponse(func(r *colly.Response) {
  var items []*Item
  json.Unmarshal(r.Body, &items)
  for _, item := range items {
    d.Visit(item.Links.Download)
  }
})

初始化访问，我们设置拉取 3 页，每页 12 个（和页面请求的个数一致）：

1
2
3

for page := 1; page <= 3; page++ {
  c.Visit(fmt.Sprintf("https://unsplash.com/napi/photos?page=%d&per_page=12", page))
}

运行，查看下载的图片：

限速

有时候并发请求太多，网站会限制访问。这时就需要使用LimitRule了。说白了，LimitRule就是限制访问速度和并发量的：

type LimitRule struct {
  DomainRegexp string
  DomainGlob string
  Delay time.Duration
  RandomDelay time.Duration
  Parallelism    int
}

常用的就Delay/RandomDelay/Parallism这几个，分别表示请求与请求之间的延迟，随机延迟，和并发数。另外必须指定对哪些域名施行限制，通过DomainRegexp或DomainGlob设置，如果这两个字段都未设置Limit()方法会返回错误。用在上面的例子中：

err := c.Limit(&colly.LimitRule{
  DomainRegexp: `unsplash\.com`,
  RandomDelay:  500 * time.Millisecond,
  Parallelism:  12,
})
if err != nil {
  log.Fatal(err)
}

我们设置针对unsplash.com这个域名，请求与请求之间的随机最大延迟 500ms，最多同时并发 12 个请求。

设置超时

有时候网速较慢，colly中使用的http.Client有默认超时机制，我们可以通过colly.WithTransport()选项改写：

c.WithTransport(&http.Transport{
  Proxy: http.ProxyFromEnvironment,
  DialContext: (&net.Dialer{
    Timeout:   30 * time.Second,
    KeepAlive: 30 * time.Second,
  }).DialContext,
  MaxIdleConns:          100,
  IdleConnTimeout:       90 * time.Second,
  TLSHandshakeTimeout:   10 * time.Second,
  ExpectContinueTimeout: 1 * time.Second,
})

扩展

colly在子包extension中提供了一些扩展特性，最最常用的就是随机 User-Agent 了。通常网站会通过 User-Agent 识别请求是否是浏览器发出的，爬虫一般会设置这个 Header 把自己伪装成浏览器。使用也比较简单：

import "github.com/gocolly/colly/v2/extensions"

func main() {
  c := colly.NewCollector()
  extensions.RandomUserAgent(c)
}

随机 User-Agent 实现也很简单，就是从一些预先定义好的 User-Agent 数组中随机一个设置到 Header 中：

func RandomUserAgent(c *colly.Collector) {
  c.OnRequest(func(r *colly.Request) {
    r.Headers.Set("User-Agent", uaGens[rand.Intn(len(uaGens))]())
  })
}

实现自己的扩展也不难，例如我们每次请求时需要设置一个特定的 Header，扩展可以这么写：

func MyHeader(c *colly.Collector) {
  c.OnRequest(func(r *colly.Request) {
    r.Headers.Set("My-Header", "dj")
  })
}

用Collector对象调用MyHeader()函数即可：

`1`	`MyHeader(c)`

总结

colly是 Go 语言中最流行的爬虫框架，支持丰富的特性。本文对一些常用特性做了介绍，并辅之以实例。限于篇幅，一些高级特性未能涉及，例如队列，存储等。对爬虫感兴趣的可去深入了解。

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

参考

Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib
Go 每日一库之 goquery：https://darjun.github.io/2020/10/11/godailylib/goquery/
用 Go 实现一个 GitHub Trending API：https://darjun.github.io/2021/06/16/github-trending-api/
colly GitHub：https://github.com/gocolly/colly

我

我的博客：https://darjun.github.io

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

Go 每日一库之 termtables

Tue, 29 Jun 2021 22:18:23 +0000

简介

今天学个简单点的😀，termtables处理表格形式数据的输出。适用于随时随地的输出一些状态或统计数据，便于观察和调试。是一个很小巧的工具库。我在学习dateparse库时偶尔见遇到了这个库。

快速使用

本文代码使用 Go Modules。

创建目录并初始化：

1
2

$ mkdir termtables && cd termtables
$ go mod init github.com/darjun/go-daily-lib/termtables

安装termtables库：

`1`	`$ go get -u github.com/scylladb/termtables`

最原始的termtables库为github.com/apcera/termtables，然后原始仓库已经被删除了。目前使用的都是其他人 fork 的仓库。

使用：

package main

import (
  "fmt"
  "github.com/scylladb/termtables"
)

func main() {
  t := termtables.CreateTable()
  t.AddHeaders("User", "Age")
  t.AddRow("dj", 18)
  t.AddRow("darjun", 30)
  fmt.Println(t.Render())
}

运行：

$ go run main.go
+--------+-----+
| User   | Age |
+--------+-----+
| dj     | 18  |
| darjun | 30  |
+--------+-----+

使用很方便，首先调用termtables.CreateTable()创建一个表格对象，调用该对象的AddHeader()方法添加头部信息，然后调用AddRow()逐行添加数据。最后调用Render()返回渲染后的表格字符串。

模式

处理普通的文本表格，termtables还支持输出 HTML 和 Markdown 格式的表格。只需要调用表格对象的SetModeHTML()/SetModeMarkdown()方法设置一些模式即可。

func main() {
  t := termtables.CreateTable()
  t.AddHeaders("User", "Age")
  t.AddRow("dj", 18)
  t.AddRow("darjun", 30)
  fmt.Println("HTML:")
  t.SetModeHTML()
  fmt.Println(t.Render())

  fmt.Println("Markdown:")
  t.SetModeMarkdown()
  fmt.Println(t.Render())
}

运行：

$ go run main.go
HTML:
<table class="termtable">
<thead>
<tr><th>User</th><th>Age</th></tr>
</thead>
<tbody>
<tr><td>dj</td><td>18</td></tr>
<tr><td>darjun</td><td>30</td></tr>
</tbody>
</table>

Markdown:
| User   | Age |
| ------ | --- |
| dj     | 18  |
| darjun | 30  |

输出的格式可以直接用在 Markdown/HTML 文件中。

总结

今天轻松一下，了解了一个小巧的工具库termtables。虽然自己实现一个类似的也不复杂，termtables库额外帮我们处理了编码、字宽等比较繁琐的细节。有需要在写示例程序中打印类似表格之类的数据不妨试一试termtables。

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

参考

Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib
termtables GitHub：github.com/scylladb/termtables

我

我的博客：https://darjun.github.io

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

Go 每日一库之 resty

Fri, 25 Jun 2021 10:56:23 +0000

简介

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

快速使用

本文代码使用 Go Modules。

创建目录并初始化：

1
2

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

安装resty库：

`1`	`$ go get -u github.com/go-resty/resty/v2`

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

package main

import (
  "fmt"
  "log"

  "github.com/go-resty/resty/v2"
)

func main() {
  client := resty.New()

  resp, err := client.R().Get("https://baidu.com")

  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.com BIDUPSID=BF2EE47AAAF7A20C6971F1E897ABDD43; expires=Thu, 31-Dec-37 23:55:55 GMT; max-age=2147483647; path=/; domain=.baidu.com PSTM=1624678965; expires=Thu, 31-Dec-37 23:55:55 GMT; max-age=2147483647; path=/; domain=.baidu.com BAIDUID=BF2EE47AAAF7A20C716E90B86906D6B0:FG=1; max-age=31536000; expires=Sun, 26-Jun-22 03:42:45 GMT; domain=.baidu.com; 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.com]
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.com/libraries获取这些库的基本信息，返回一个 JSON 数据，格式如下：

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

type Library struct {
  Name   string
  Latest string
}

type Libraries struct {
  Results []*Library
}

func main() {
  client := resty.New()

  libraries := &Libraries{}
  client.R().SetResult(libraries).Get("https://api.cdnjs.com/libraries")
  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:https://cdnjs.cloudflare.com/ajax/libs/vue/3.1.2/vue.min.js

一共 4040 个库，第一个就是 Vue✌️。我们请求https://api.cdnjs.com/libraries/vue就能获取 Vue 的详细信息：

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

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

1
2
3

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

请求信息

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

1
2
3

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

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

设置首部：

1
2
3

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：

1
2
3

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

案例

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

`1`	`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 []*Repository
  client.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("https://api.github.com/orgs/{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，发起请求：

`1`	`client.R().EnableTrace().Get("https://baidu.com")`

在完成请求之后，我们通过调用请求对象的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.11
  DNSStart func(DNSStartInfo)
  DNSDone func(DNSDoneInfo)
  ConnectStart func(network, addr string)
  ConnectDone func(network, addr string, err error)
  TLSHandshakeStart func() // Go 1.8
  TLSHandshakeDone func(tls.ConnectionState, error) // Go 1.8
  WroteHeaderField func(key string, value []string) // Go 1.11
  WroteHeaders func()
  Wait100Continue func()
  WroteRequest func(WroteRequestInfo)
}

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

// src/github.com/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.com/go-resty/resty/request.go
func (r *Request) TraceInfo() TraceInfo {
  ct := r.clientTrace

  if 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😄

参考

Go 每日一库 GitHub：https://github.com/darjun/go-daily-lib
resty GitHub：github.com/go-resty/resty
GitHub API：https://docs.github.com/en/rest/overview/resources-in-the-rest-api

我

我的博客：https://darjun.github.io

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