The Go Programming Language（10-13）

说明

本文为Go语言编程圣经中文版内容，本人在阅读时将其制作为思维导图及博客文章形式，仅供学习，若侵权请及时与我联系。

源码、PDF版、Markdown、xmind版下载链接

https://1tnt1.lanzous.com/b00o36ytc

密码：

1ch0

ch10 包和工具

ch10.0 简介

• 现在随便一个小程序的实现都可能包含超过10000个函数。然而作者一般只需要考虑其中很小的一部分和做很少的设计，因为绝大部分代码都是由他人编写的，它们通过类似包或模块的方式被重用。
• Go语言有超过100个的标准包（译注：可以用go list std | wc -l命令查看标准包的具体数目），标准库为大多数的程序提供了必要的基础构件。在Go的社区，有很多成熟的包被设计、共享、重用和改进，目前互联网上已经发布了非常多的Go语言开源包，它们可以通过 http://godoc.org 检索。在本章，我们将演示如何使用已有的包和创建新的包。
• Go还自带了工具箱，里面有很多用来简化工作区和包管理的小工具。在本书开始的时候，我们已经见识过如何使用工具箱自带的工具来下载、构建和运行我们的演示程序了。在本章，我们将看看这些工具的基本设计理论和尝试更多的功能，例如打印工作区中包的文档和查询相关的元数据等。在下一章，我们将探讨testing包的单元测试用法。

ch10.1 包简介

• 任何包系统设计的目的都是为了简化大型程序的设计和维护工作，通过将一组相关的特性放进一个独立的单元以便于理解和更新，在每个单元更新的同时保持和程序中其它单元的相对独立性。这种模块化的特性允许每个包可以被其它的不同项目共享和重用，在项目范围内、甚至全球范围统一的分发和复用。

• 每个包一般都定义了一个不同的名字空间用于它内部的每个标识符的访问。每个名字空间关联到一个特定的包，让我们给类型、函数等选择简短明了的名字，这样可以在使用它们的时候减少和其它部分名字的冲突。

• 每个包还通过控制包内名字的可见性和是否导出来实现封装特性。通过限制包成员的可见性并隐藏包API的具体实现，将允许包的维护者在不影响外部包用户的前提下调整包的内部实现。通过限制包内变量的可见性，还可以强制用户通过某些特定函数来访问和更新内部变量，这样可以保证内部变量的一致性和并发时的互斥约束。

• 当我们修改了一个源文件，我们必须重新编译该源文件对应的包和所有依赖该包的其他包。即使是从头构建，Go语言编译器的编译速度也明显快于其它编译语言。Go语言的闪电般的编译速度主要得益于三个语言特性。

  • 第一点，所有导入的包必须在每个文件的开头显式声明，这样的话编译器就没有必要读取和分析整个源文件来判断包的依赖关系。
  • 第二点，禁止包的环状依赖，因为没有循环依赖，包的依赖关系形成一个有向无环图，每个包可以被独立编译，而且很可能是被并发编译。
  • 第三点，编译后包的目标文件不仅仅记录包本身的导出信息，目标文件同时还记录了包的依赖关系。
  • 因此，在编译一个包的时候，编译器只需要读取每个直接导入包的目标文件，而不需要遍历所有依赖的的文件

ch10.2 导入路径

• 每个包是由一个全局唯一的字符串所标识的导入路径定位。出现在import语句中的导入路径也是字符串。

  import (
  	"fmt"
  	"math/rand"
  	"encoding/json"
  
  	"golang.org/x/net/html"
  
  	"github.com/go-sql-driver/mysql"
  )
  

• 就像我们在2.6.1节提到过的，Go语言的规范并没有指明包的导入路径字符串的具体含义，导入路径的具体含义是由构建工具来解释的。在本章，我们将深入讨论Go语言工具箱的功能，包括大家经常使用的构建测试等功能。当然，也有第三方扩展的工具箱存在。例如，Google公司内部的Go语言码农，他们就使用内部的多语言构建系统，用不同的规则来处理包名字和定位包，用不同的规则来处理单元测试等等，因为这样可以更紧密适配他们内部环境。

  • 译注：Google公司使用的是类似Bazel的构建系统，支持多种编程语言，目前该构件系统还不能完整支持Windows环境

• 如果你计划分享或发布包，那么导入路径最好是全球唯一的。为了避免冲突，所有非标准库包的导入路径建议以所在组织的互联网域名为前缀；而且这样也有利于包的检索。例如，上面的import语句导入了Go团队维护的HTML解析器和一个流行的第三方维护的MySQL驱动。

ch10.3 包声明

• 在每个Go语言源文件的开头都必须有包声明语句。包声明语句的主要目的是确定当前包被其它包导入时默认的标识符（也称为包名）。

• 例如，math/rand包的每个源文件的开头都包含package rand包声明语句，所以当你导入这个包，你就可以用rand.Int、rand.Float64类似的方式访问包的成员。

  package main
  
  import (
  	"fmt"
  	"math/rand"
  )
  
  func main() {
  	fmt.Println(rand.Int())
  }
  

• 通常来说，默认的包名就是包导入路径名的最后一段，因此即使两个包的导入路径不同，它们依然可能有一个相同的包名。例如，math/rand包和crypto/rand包的包名都是rand。稍后我们将看到如何同时导入两个有相同包名的包。

• 关于默认包名一般采用导入路径名的最后一段的约定也有三种例外情况。第一个例外，包对应一个可执行程序，也就是main包，这时候main包本身的导入路径是无关紧要的。名字为main的包是给go build（§10.7.3）构建命令一个信息，这个包编译完之后必须调用连接器生成一个可执行程序。

• 第二个例外，包所在的目录中可能有一些文件名是以_test.go为后缀的Go源文件（译注：前面必须有其它的字符，因为以_或.开头的源文件会被构建工具忽略），并且这些源文件声明的包名也是以_test为后缀名的。这种目录可以包含两种包：一种是普通包，另一种则是测试的外部扩展包。所有以_test为后缀包名的测试外部扩展包都由go test命令独立编译，普通包和测试的外部扩展包是相互独立的。测试的外部扩展包一般用来避免测试代码中的循环导入依赖，具体细节我们将在11.2.4节中介绍。

• 第三个例外，一些依赖版本号的管理工具会在导入路径后追加版本号信息，例如“gopkg.in/yaml.v2”。这种情况下包的名字并不包含版本号后缀，而是yaml。

ch10.4 导入声明

• 可以在一个Go语言源文件包声明语句之后，其它非导入声明语句之前，包含零到多个导入包声明语句。每个导入声明可以单独指定一个导入路径，也可以通过圆括号同时导入多个导入路径。下面两个导入形式是等价的，但是第二种形式更为常见。

  import "fmt"
  import "os"
  
  import (
  	"fmt"
  	"os"
  )
  

• 导入的包之间可以通过添加空行来分组；通常将来自不同组织的包独自分组。包的导入顺序无关紧要，但是在每个分组中一般会根据字符串顺序排列。（gofmt和goimports工具都可以将不同分组导入的包独立排序。）

  import (
  	"fmt"
  	"html/template"
  	"os"
  
  	"golang.org/x/net/html"
  	"golang.org/x/net/ipv4"
  )
  

• 如果我们想同时导入两个有着名字相同的包，例如math/rand包和crypto/rand包，那么导入声明必须至少为一个同名包指定一个新的包名以避免冲突。这叫做导入包的重命名。

  import (
  	"crypto/rand"
  	mrand "math/rand" // alternative name mrand avoids conflict
  )
  

• 导入包的重命名只影响当前的源文件。其它的源文件如果导入了相同的包，可以用导入包原本默认的名字或重命名为另一个完全不同的名字。

• 导入包重命名是一个有用的特性，它不仅仅只是为了解决名字冲突。如果导入的一个包名很笨重，特别是在一些自动生成的代码中，这时候用一个简短名称会更方便。选择用简短名称重命名导入包时候最好统一，以避免包名混乱。选择另一个包名称还可以帮助避免和本地普通变量名产生冲突。例如，如果文件中已经有了一个名为path的变量，那么我们可以将“path”标准包重命名为pathpkg。

• 每个导入声明语句都明确指定了当前包和被导入包之间的依赖关系。如果遇到包循环导入的情况，Go语言的构建工具将报告错误。

ch10.5 包的匿名导入

• 如果只是导入一个包而并不使用导入的包将会导致一个编译错误。但是有时候我们只是想利用导入包而产生的副作用：它会计算包级变量的初始化表达式和执行导入包的init初始化函数（§2.6.2）。这时候我们需要抑制“unused import”编译错误，我们可以用下划线_来重命名导入的包。像往常一样，下划线_为空白标识符，并不能被访问。

  import _ "image/png" // register PNG decoder
  

• 这个被称为包的匿名导入。它通常是用来实现一个编译时机制，然后通过在main主程序入口选择性地导入附加的包。首先，让我们看看如何使用该特性，然后再看看它是如何工作的。

• 标准库的image图像包包含了一个Decode函数，用于从io.Reader接口读取数据并解码图像，它调用底层注册的图像解码器来完成任务，然后返回image.Image类型的图像。使用image.Decode很容易编写一个图像格式的转换工具，读取一种格式的图像，然后编码为另一种图像格式：

  gopl.io/ch10/jpeg

  // The jpeg command reads a PNG image from the standard input
  // and writes it as a JPEG image to the standard output.
  package main
  
  import (
  	"fmt"
  	"image"
  	"image/jpeg"
  	_ "image/png" // register PNG decoder
  	"io"
  	"os"
  )
  
  func main() {
  	if err := toJPEG(os.Stdin, os.Stdout); err != nil {
  		fmt.Fprintf(os.Stderr, "jpeg: %v\n", err)
  		os.Exit(1)
  	}
  }
  
  func toJPEG(in io.Reader, out io.Writer) error {
  	img, kind, err := image.Decode(in)
  	if err != nil {
  		return err
  	}
  	fmt.Fprintln(os.Stderr, "Input format =", kind)
  	return jpeg.Encode(out, img, &jpeg.Options{Quality: 95})
  }
  

• 如果我们将gopl.io/ch3/mandelbrot（§3.3）的输出导入到这个程序的标准输入，它将解码输入的PNG格式图像，然后转换为JPEG格式的图像输出（图3.3）。

  $ go build gopl.io/ch3/mandelbrot
  $ go build gopl.io/ch10/jpeg
  $ ./mandelbrot | ./jpeg >mandelbrot.jpg
  Input format = png
  

• 要注意image/png包的匿名导入语句。如果没有这一行语句，程序依然可以编译和运行，但是它将不能正确识别和解码PNG格式的图像：

  $ go build gopl.io/ch10/jpeg
  $ ./mandelbrot | ./jpeg >mandelbrot.jpg
  jpeg: image: unknown format
  

• 下面的代码演示了它的工作机制。标准库还提供了GIF、PNG和JPEG等格式图像的解码器，用户也可以提供自己的解码器，但是为了保持程序体积较小，很多解码器并没有被全部包含，除非是明确需要支持的格式。image.Decode函数在解码时会依次查询支持的格式列表。

• 每个格式驱动列表的每个入口指定了四件事情：格式的名称；一个用于描述这种图像数据开头部分模式的字符串，用于解码器检测识别；一个Decode函数用于完成解码图像工作；一个DecodeConfig函数用于解码图像的大小和颜色空间的信息。每个驱动入口是通过调用image.RegisterFormat函数注册，一般是在每个格式包的init初始化函数中调用，例如image/png包是这样注册的：

  package png // image/png
  
  func Decode(r io.Reader) (image.Image, error)
  func DecodeConfig(r io.Reader) (image.Config, error)
  
  func init() {
  	const pngHeader = "\x89PNG\r\n\x1a\n"
  	image.RegisterFormat("png", pngHeader, Decode, DecodeConfig)
  }
  

• 最终的效果是，主程序只需要匿名导入特定图像驱动包就可以用image.Decode解码对应格式的图像了。

• 数据库包database/sql也是采用了类似的技术，让用户可以根据自己需要选择导入必要的数据库驱动。例如：

  import (
  	"database/sql"
  	_ "github.com/lib/pq"              // enable support for Postgres
  	_ "github.com/go-sql-driver/mysql" // enable support for MySQL
  )
  
  db, err = sql.Open("postgres", dbname) // OK
  db, err = sql.Open("mysql", dbname)    // OK
  db, err = sql.Open("sqlite3", dbname)  // returns error: unknown driver "sqlite3"
  

ch10.6 包和命名

• 在本节中，我们将提供一些关于Go语言独特的包和成员命名的约定。

• 当创建一个包，一般要用短小的包名，但也不能太短导致难以理解。标准库中最常用的包有bufio、bytes、flag、fmt、http、io、json、os、sort、sync和time等包。

• 尽可能让命名有描述性且无歧义。例如，类似imageutil或ioutilis的工具包命名已经足够简洁了，就无须再命名为util了。要尽量避免包名使用可能被经常用于局部变量的名字，这样可能导致用户重命名导入包，例如前面看到的path包。

• 包名一般采用单数的形式。标准库的bytes、errors和strings使用了复数形式，这是为了避免和预定义的类型冲突，同样还有go/types是为了避免和type关键字冲突。

• 要避免包名有其它的含义。例如，2.5节中我们的温度转换包最初使用了temp包名，虽然并没有持续多久。但这是一个糟糕的尝试，因为temp几乎是临时变量的同义词。然后我们有一段时间使用了temperature作为包名，显然名字并没有表达包的真实用途。最后我们改成了和strconv标准包类似的tempconv包名，这个名字比之前的就好多了。

• 现在让我们看看如何命名包的成员。由于是通过包的导入名字引入包里面的成员，例如fmt.Println，同时包含了包名和成员名信息。因此，我们一般并不需要关注Println的具体内容，因为fmt包名已经包含了这个信息。当设计一个包的时候，需要考虑包名和成员名两个部分如何很好地配合。下面有一些例子：

  bytes.Equal    flag.Int    http.Get    json.Marshal
  

• 我们可以看到一些常用的命名模式。strings包提供了和字符串相关的诸多操作：

  package strings
  
  func Index(needle, haystack string) int
  
  type Replacer struct{ /* ... */ }
  func NewReplacer(oldnew ...string) *Replacer
  
  type Reader struct{ /* ... */ }
  func NewReader(s string) *Reader
  

• 包名strings并没有出现在任何成员名字中。因为用户会这样引用这些成员strings.Index、strings.Replacer等。

• 其它一些包，可能只描述了单一的数据类型，例如html/template和math/rand等，只暴露一个主要的数据结构和与它相关的方法，还有一个以New命名的函数用于创建实例。

  package rand // "math/rand"
  
  type Rand struct{ /* ... */ }
  func New(source Source) *Rand
  

• 这可能导致一些名字重复，例如template.Template或rand.Rand，这就是为什么这些种类的包名往往特别短的原因之一。

• 在另一个极端，还有像net/http包那样含有非常多的名字和种类不多的数据类型，因为它们都是要执行一个复杂的复合任务。尽管有将近二十种类型和更多的函数，但是包中最重要的成员名字却是简单明了的：Get、Post、Handle、Error、Client、Server等。

ch10.7 工具

• ch10.7.0 简介

  • 本章剩下的部分将讨论Go语言工具箱的具体功能，包括如何下载、格式化、构建、测试和安装Go语言编写的程序。

  • Go语言的工具箱集合了一系列功能的命令集。它可以看作是一个包管理器（类似于Linux中的apt和rpm工具），用于包的查询、计算包的依赖关系、从远程版本控制系统下载它们等任务。它也是一个构建系统，计算文件的依赖关系，然后调用编译器、汇编器和链接器构建程序，虽然它故意被设计成没有标准的make命令那么复杂。它也是一个单元测试和基准测试的驱动程序，我们将在第11章讨论测试话题。

  • Go语言工具箱的命令有着类似“瑞士军刀”的风格，带着一打的子命令，有一些我们经常用到，例如get、run、build和fmt等。你可以运行go或go help命令查看内置的帮助文档，为了查询方便，我们列出了最常用的命令：

    $ go
    ...
    	build            compile packages and dependencies
    	clean            remove object files
    	doc              show documentation for package or symbol
    	env              print Go environment information
    	fmt              run gofmt on package sources
    	get              download and install packages and dependencies
    	install          compile and install packages and dependencies
    	list             list packages
    	run              compile and run Go program
    	test             test packages
    	version          print Go version
    	vet              run go tool vet on packages
    
    Use "go help [command]" for more information about a command.
    ...
    

  • 为了达到零配置的设计目标，Go语言的工具箱很多地方都依赖各种约定。例如，根据给定的源文件的名称，Go语言的工具可以找到源文件对应的包，因为每个目录只包含了单一的包，并且包的导入路径和工作区的目录结构是对应的。给定一个包的导入路径，Go语言的工具可以找到与之对应的存储着实体文件的目录。它还可以根据导入路径找到存储代码的仓库的远程服务器URL。

• ch10.7.1 工作区结构

  • 对于大多数的Go语言用户，只需要配置一个名叫GOPATH的环境变量，用来指定当前工作目录即可。当需要切换到不同工作区的时候，只要更新GOPATH就可以了。例如，我们在编写本书时将GOPATH设置为$HOME/gobook：

    $ export GOPATH=$HOME/gobook
    $ go get gopl.io/...
    

  • 当你用前面介绍的命令下载本书全部的例子源码之后，你的当前工作区的目录结构应该是这样的：

    GOPATH/
    	src/
    		gopl.io/
    			.git/
    			ch1/
    				helloworld/
    					main.go
    				dup/
    					main.go
    				...
    		golang.org/x/net/
    			.git/
    			html/
    				parse.go
    				node.go
    				...
    	bin/
    		helloworld
    		dup
    	pkg/
    		darwin_amd64/
    		...
    

  • GOPATH对应的工作区目录有三个子目录。其中src子目录用于存储源代码。每个包被保存在与$GOPATH/src的相对路径为包导入路径的子目录中，例如gopl.io/ch1/helloworld相对应的路径目录。我们看到，一个GOPATH工作区的src目录中可能有多个独立的版本控制系统，例如gopl.io和golang.org分别对应不同的Git仓库。其中pkg子目录用于保存编译后的包的目标文件，bin子目录用于保存编译后的可执行程序，例如helloworld可执行程序。

  • 第二个环境变量GOROOT用来指定Go的安装目录，还有它自带的标准库包的位置。GOROOT的目录结构和GOPATH类似，因此存放fmt包的源代码对应目录应该为$GOROOT/src/fmt。用户一般不需要设置GOROOT，默认情况下Go语言安装工具会将其设置为安装的目录路径。

  • 其中go env命令用于查看Go语言工具涉及的所有环境变量的值，包括未设置环境变量的默认值。GOOS环境变量用于指定目标操作系统（例如android、linux、darwin或windows），GOARCH环境变量用于指定处理器的类型，例如amd64、386或arm等。虽然GOPATH环境变量是唯一必须要设置的，但是其它环境变量也会偶尔用到。

    $ go env
    GOPATH="/home/gopher/gobook"
    GOROOT="/usr/local/go"
    GOARCH="amd64"
    GOOS="darwin"
    ...
    

• ch10.7.2 下载包

  • 使用Go语言工具箱的go命令，不仅可以根据包导入路径找到本地工作区的包，甚至可以从互联网上找到和更新包。

  • 使用命令go get可以下载一个单一的包或者用...下载整个子目录里面的每个包。Go语言工具箱的go命令同时计算并下载所依赖的每个包，这也是前一个例子中golang.org/x/net/html自动出现在本地工作区目录的原因。

  • 一旦go get命令下载了包，然后就是安装包或包对应的可执行的程序。我们将在下一节再关注它的细节，现在只是展示整个下载过程是如何的简单。第一个命令是获取golint工具，它用于检测Go源代码的编程风格是否有问题。第二个命令是用golint命令对2.6.2节的gopl.io/ch2/popcount包代码进行编码风格检查。它友好地报告了忘记了包的文档：

    $ go get github.com/golang/lint/golint
    $ $GOPATH/bin/golint gopl.io/ch2/popcount
    src/gopl.io/ch2/popcount/main.go:1:1:
      package comment should be of the form "Package popcount ..."
    

  • go get命令支持当前流行的托管网站GitHub、Bitbucket和Launchpad，可以直接向它们的版本控制系统请求代码。对于其它的网站，你可能需要指定版本控制系统的具体路径和协议，例如 Git或Mercurial。运行go help importpath获取相关的信息。

  • go get命令获取的代码是真实的本地存储仓库，而不仅仅只是复制源文件，因此你依然可以使用版本管理工具比较本地代码的变更或者切换到其它的版本。例如golang.org/x/net包目录对应一个Git仓库：

    $ cd $GOPATH/src/golang.org/x/net
    $ git remote -v
    origin  https://go.googlesource.com/net (fetch)
    origin  https://go.googlesource.com/net (push)
    

  • 需要注意的是导入路径含有的网站域名和本地Git仓库对应远程服务地址并不相同，真实的Git地址是go.googlesource.com。这其实是Go语言工具的一个特性，可以让包用一个自定义的导入路径，但是真实的代码却是由更通用的服务提供，例如googlesource.com或github.com。因为页面 https://golang.org/x/net/html 包含了如下的元数据，它告诉Go语言的工具当前包真实的Git仓库托管地址：

    $ go build gopl.io/ch1/fetch
    $ ./fetch https://golang.org/x/net/html | grep go-import
    <meta name="go-import"
          content="golang.org/x/net git https://go.googlesource.com/net">
    

  • 如果指定-u命令行标志参数，go get命令将确保所有的包和依赖的包的版本都是最新的，然后重新编译和安装它们。如果不包含该标志参数的话，而且如果包已经在本地存在，那么代码将不会被自动更新。

  • go get -u命令只是简单地保证每个包是最新版本，如果是第一次下载包则是比较方便的；但是对于发布程序则可能是不合适的，因为本地程序可能需要对依赖的包做精确的版本依赖管理。通常的解决方案是使用vendor的目录用于存储依赖包的固定版本的源代码，对本地依赖的包的版本更新也是谨慎和持续可控的。在Go1.5之前，一般需要修改包的导入路径，所以复制后golang.org/x/net/html导入路径可能会变为gopl.io/vendor/golang.org/x/net/html。最新的Go语言命令已经支持vendor特性，但限于篇幅这里并不讨论vendor的具体细节。不过可以通过go help gopath命令查看Vendor的帮助文档。

• ch10.7.3 构建包

  • go build命令编译命令行参数指定的每个包。如果包是一个库，则忽略输出结果；这可以用于检测包是可以正确编译的。如果包的名字是main，go build将调用链接器在当前目录创建一个可执行程序；以导入路径的最后一段作为可执行程序的名字。

  • 由于每个目录只包含一个包，因此每个对应可执行程序或者叫Unix术语中的命令的包，会要求放到一个独立的目录中。这些目录有时候会放在名叫cmd目录的子目录下面，例如用于提供Go文档服务的golang.org/x/tools/cmd/godoc命令就是放在cmd子目录（§10.7.4）。

  • 每个包可以由它们的导入路径指定，就像前面看到的那样，或者用一个相对目录的路径名指定，相对路径必须以.或..开头。如果没有指定参数，那么默认指定为当前目录对应的包。下面的命令用于构建同一个包，虽然它们的写法各不相同：

    $ cd $GOPATH/src/gopl.io/ch1/helloworld
    $ go build
    

    • 或者：

      $ cd anywhere
      $ go build gopl.io/ch1/helloworld
      

    • 或者：

      $ cd $GOPATH
      $ go build ./src/gopl.io/ch1/helloworld
      

    • 但不能这样：

      $ cd $GOPATH
      $ go build src/gopl.io/ch1/helloworld
      Error: cannot find package "src/gopl.io/ch1/helloworld".
      

  • 也可以指定包的源文件列表，这一般只用于构建一些小程序或做一些临时性的实验。如果是main包，将会以第一个Go源文件的基础文件名作为最终的可执行程序的名字。

    $ cat quoteargs.go
    package main
    
    import (
    	"fmt"
    	"os"
    )
    
    func main() {
    	fmt.Printf("%q\n", os.Args[1:])
    }
    $ go build quoteargs.go
    $ ./quoteargs one "two three" four\ five
    ["one" "two three" "four five"]
    

  • 特别是对于这类一次性运行的程序，我们希望尽快的构建并运行它。go run命令实际上是结合了构建和运行的两个步骤：

    $ go run quoteargs.go one "two three" four\ five
    ["one" "two three" "four five"]
    

    • 译注：其实也可以偷懒，直接go run *.go
    • 第一行的参数列表中，第一个不是以.go结尾的将作为可执行程序的参数运行。

  • 默认情况下，go build命令构建指定的包和它依赖的包，然后丢弃除了最后的可执行文件之外所有的中间编译结果。依赖分析和编译过程虽然都是很快的，但是随着项目增加到几十个包和成千上万行代码，依赖关系分析和编译时间的消耗将变的可观，有时候可能需要几秒种，即使这些依赖项没有改变。

  • go install命令和go build命令很相似，但是它会保存每个包的编译成果，而不是将它们都丢弃。被编译的包会被保存到$GOPATH/pkg目录下，目录路径和 src目录路径对应，可执行程序被保存到$GOPATH/bin目录。（很多用户会将$GOPATH/bin添加到可执行程序的搜索列表中。）还有，go install命令和go build命令都不会重新编译没有发生变化的包，这可以使后续构建更快捷。为了方便编译依赖的包，go build -i命令将安装每个目标所依赖的包。

  • 因为编译对应不同的操作系统平台和CPU架构，go install命令会将编译结果安装到GOOS和GOARCH对应的目录。例如，在Mac系统，golang.org/x/net/html包将被安装到$GOPATH/pkg/darwin_amd64目录下的golang.org/x/net/html.a文件。

  • 针对不同操作系统或CPU的交叉构建也是很简单的。只需要设置好目标对应的GOOS和GOARCH，然后运行构建命令即可。下面交叉编译的程序将输出它在编译时的操作系统和CPU类型：

    gopl.io/ch10/cross

    func main() {
    	fmt.Println(runtime.GOOS, runtime.GOARCH)
    }
    

    • 下面以64位和32位环境分别编译和执行：

      $ go build gopl.io/ch10/cross
      $ ./cross
      darwin amd64
      $ GOARCH=386 go build gopl.io/ch10/cross
      $ ./cross
      darwin 386
      

  • 有些包可能需要针对不同平台和处理器类型使用不同版本的代码文件，以便于处理底层的可移植性问题或为一些特定代码提供优化。如果一个文件名包含了一个操作系统或处理器类型名字，例如net_linux.go或asm_amd64.s，Go语言的构建工具将只在对应的平台编译这些文件。还有一个特别的构建注释参数可以提供更多的构建过程控制。例如，文件中可能包含下面的注释：

    // +build linux darwin
    

  • 在包声明和包注释的前面，该构建注释参数告诉go build只在编译程序对应的目标操作系统是Linux或Mac OS X时才编译这个文件。下面的构建注释则表示不编译这个文件：

    // +build ignore
    

  • 更多细节，可以参考go/build包的构建约束部分的文档。

    $ go doc go/build
    

• ch10.7.4 包文档

  • Go语言的编码风格鼓励为每个包提供良好的文档。包中每个导出的成员和包声明前都应该包含目的和用法说明的注释。

  • Go语言中的文档注释一般是完整的句子，第一行通常是摘要说明，以被注释者的名字开头。注释中函数的参数或其它的标识符并不需要额外的引号或其它标记注明。例如，下面是fmt.Fprintf的文档注释。

    // Fprintf formats according to a format specifier and writes to w.
    // It returns the number of bytes written and any write error encountered.
    func Fprintf(w io.Writer, format string, a ...interface{}) (int, error)
    

  • Fprintf函数格式化的细节在fmt包文档中描述。如果注释后紧跟着包声明语句，那注释对应整个包的文档。包文档对应的注释只能有一个（译注：其实可以有多个，它们会组合成一个包文档注释），包注释可以出现在任何一个源文件中。如果包的注释内容比较长，一般会放到一个独立的源文件中；fmt包注释就有300行之多。这个专门用于保存包文档的源文件通常叫doc.go。

  • 好的文档并不需要面面俱到，文档本身应该是简洁但不可忽略的。事实上，Go语言的风格更喜欢简洁的文档，并且文档也是需要像代码一样维护的。对于一组声明语句，可以用一个精炼的句子描述，如果是显而易见的功能则并不需要注释。

  • 在本书中，只要空间允许，我们之前很多包声明都包含了注释文档，但你可以从标准库中发现很多更好的例子。有两个工具可以帮到你。

  • 首先是go doc命令，该命令打印其后所指定的实体的声明与文档注释，该实体可能是一个包：

    $ go doc time
    package time // import "time"
    
    Package time provides functionality for measuring and displaying time.
    
    const Nanosecond Duration = 1 ...
    func After(d Duration) <-chan Time
    func Sleep(d Duration)
    func Since(t Time) Duration
    func Now() Time
    type Duration int64
    type Time struct { ... }
    ...many more...
    

    • 或者是某个具体的包成员：

      $ go doc time.Since
      func Since(t Time) Duration
      
      	Since returns the time elapsed since t.
      	It is shorthand for time.Now().Sub(t).
      

    • 或者是一个方法：

      $ go doc time.Duration.Seconds
      func (d Duration) Seconds() float64
      
      	Seconds returns the duration as a floating-point number of seconds.
      

    • 该命令并不需要输入完整的包导入路径或正确的大小写。下面的命令将打印encoding/json包的(*json.Decoder).Decode方法的文档：

      $ go doc json.decode
      func (dec *Decoder) Decode(v interface{}) error
      
      	Decode reads the next JSON-encoded value from its input and stores
      	it in the value pointed to by v.
      

  • 第二个工具，名字也叫godoc，它提供可以相互交叉引用的HTML页面，但是包含和go doc命令相同以及更多的信息。图10.1演示了time包的文档，11.6节将看到godoc演示可以交互的示例程序。godoc的在线服务 https://godoc.org ，包含了成千上万的开源包的检索工具。

    • 你也可以在自己的工作区目录运行godoc服务。运行下面的命令，然后在浏览器查看 http://localhost:8000/pkg 页面：

      $ godoc -http :8000
      

    • 其中-analysis=type和-analysis=pointer命令行标志参数用于打开文档和代码中关于静态分析的结果。

• ch10.7.5 内部包

  • 在Go语言程序中，包是最重要的封装机制。没有导出的标识符只在同一个包内部可以访问，而导出的标识符则是面向全宇宙都是可见的。

  • 有时候，一个中间的状态可能也是有用的，标识符对于一小部分信任的包是可见的，但并不是对所有调用者都可见。例如，当我们计划将一个大的包拆分为很多小的更容易维护的子包，但是我们并不想将内部的子包结构也完全暴露出去。同时，我们可能还希望在内部子包之间共享一些通用的处理包，或者我们只是想实验一个新包的还并不稳定的接口，暂时只暴露给一些受限制的用户使用。

  • 为了满足这些需求，Go语言的构建工具对包含internal名字的路径段的包导入路径做了特殊处理。这种包叫internal包，一个internal包只能被和internal目录有同一个父目录的包所导入。例如，net/http/internal/chunked内部包只能被net/http/httputil或net/http包导入，但是不能被net/url包导入。不过net/url包却可以导入net/http/httputil包。

    net/http
    net/http/internal/chunked
    net/http/httputil
    net/url
    

• ch10.7.6 查询包

  • go list命令可以查询可用包的信息。其最简单的形式，可以测试包是否在工作区并打印它的导入路径：

    $ go list github.com/go-sql-driver/mysql
    github.com/go-sql-driver/mysql
    

  • go list命令的参数还可以用"..."表示匹配任意的包的导入路径。我们可以用它来列出工作区中的所有包：

    $ go list ...
    archive/tar
    archive/zip
    bufio
    bytes
    cmd/addr2line
    cmd/api
    ...many more...
    

  • 或者是特定子目录下的所有包：

    $ go list gopl.io/ch3/...
    gopl.io/ch3/basename1
    gopl.io/ch3/basename2
    gopl.io/ch3/comma
    gopl.io/ch3/mandelbrot
    gopl.io/ch3/netflag
    gopl.io/ch3/printints
    gopl.io/ch3/surface
    

  • 或者是和某个主题相关的所有包:

    $ go list ...xml...
    encoding/xml
    gopl.io/ch7/xmlselect
    

  • go list命令还可以获取每个包完整的元信息，而不仅仅只是导入路径，这些元信息可以以不同格式提供给用户。其中-json命令行参数表示用JSON格式打印每个包的元信息。

    $ go list -json hash
    {
    	"Dir": "/home/gopher/go/src/hash",
    	"ImportPath": "hash",
    	"Name": "hash",
    	"Doc": "Package hash provides interfaces for hash functions.",
    	"Target": "/home/gopher/go/pkg/darwin_amd64/hash.a",
    	"Goroot": true,
    	"Standard": true,
    	"Root": "/home/gopher/go",
    	"GoFiles": [
    			"hash.go"
    	],
    	"Imports": [
    		"io"
    	],
    	"Deps": [
    		"errors",
    		"io",
    		"runtime",
    		"sync",
    		"sync/atomic",
    		"unsafe"
    	]
    }
    

  • 命令行参数-f则允许用户使用text/template包（§4.6）的模板语言定义输出文本的格式。下面的命令将打印strconv包的依赖的包，然后用join模板函数将结果链接为一行，连接时每个结果之间用一个空格分隔：

    {% raw %}

    $ go list -f '{{join .Deps " "}}' strconv
    errors math runtime unicode/utf8 unsafe
    

    {% endraw %}

    • 上面的命令在Windows的命令行运行会遇到template: main:1: unclosed action的错误。产生这个错误的原因是因为命令行对命令中的" "参数进行了转义处理。可以按照下面的方法解决转义字符串的问题：

      {% raw %}

      $ go list -f "{{join .Deps \" \"}}" strconv
      

      {% endraw %}

  • 下面的命令打印compress子目录下所有包的导入包列表：

    {% raw %}

    $ go list -f '{{.ImportPath}} -> {{join .Imports " "}}' compress/...
    compress/bzip2 -> bufio io sort
    compress/flate -> bufio fmt io math sort strconv
    compress/gzip -> bufio compress/flate errors fmt hash hash/crc32 io time
    compress/lzw -> bufio errors fmt io
    compress/zlib -> bufio compress/flate errors fmt hash hash/adler32 io
    

    {% endraw %}

    • 译注：Windows下有同样有问题，要避免转义字符串的干扰：

      {% raw %}

      $ go list -f "{{.ImportPath}} -> {{join .Imports \" \"}}" compress/...
      

      {% endraw %}

  • go list命令对于一次性的交互式查询或自动化构建或测试脚本都很有帮助。我们将在11.2.4节中再次使用它。每个子命令的更多信息，包括可设置的字段和意义，可以用go help list命令查看。

  • 在本章，我们解释了Go语言工具中除了测试命令之外的所有重要的子命令。在下一章，我们将看到如何用go test命令去运行Go语言程序中的测试代码。

ch11 测试

ch11.0 简介

• Maurice Wilkes，第一个存储程序计算机EDSAC的设计者，1949年他在实验室爬楼梯时有一个顿悟。在《计算机先驱回忆录》（Memoirs of a Computer Pioneer）里，他回忆到：“忽然间有一种醍醐灌顶的感觉，我整个后半生的美好时光都将在寻找程序BUG中度过了”。肯定从那之后的大部分正常的码农都会同情Wilkes过分悲观的想法，虽然也许会有人困惑于他对软件开发的难度的天真看法。
• 现在的程序已经远比Wilkes时代的更大也更复杂，也有许多技术可以让软件的复杂性可得到控制。其中有两种技术在实践中证明是比较有效的。第一种是代码在被正式部署前需要进行代码评审。第二种则是测试，也就是本章的讨论主题。
• 我们说测试的时候一般是指自动化测试，也就是写一些小的程序用来检测被测试代码（产品代码）的行为和预期的一样，这些通常都是精心设计的执行某些特定的功能或者是通过随机性的输入待验证边界的处理。
• 软件测试是一个巨大的领域。测试的任务可能已经占据了一些程序员的部分时间和另一些程序员的全部时间。和软件测试技术相关的图书或博客文章有成千上万之多。对于每一种主流的编程语言，都会有一打的用于测试的软件包，同时也有大量的测试相关的理论，而且每种都吸引了大量技术先驱和追随者。这些都足以说服那些想要编写有效测试的程序员重新学习一套全新的技能。
• Go语言的测试技术是相对低级的。它依赖一个go test测试命令和一组按照约定方式编写的测试函数，测试命令可以运行这些测试函数。编写相对轻量级的纯测试代码是有效的，而且它很容易延伸到基准测试和示例文档。
• 在实践中，编写测试代码和编写程序本身并没有多大区别。我们编写的每一个函数也是针对每个具体的任务。我们必须小心处理边界条件，思考合适的数据结构，推断合适的输入应该产生什么样的结果输出。编写测试代码和编写普通的Go代码过程是类似的；它并不需要学习新的符号、规则和工具。

ch11.1 go test

• go test命令是一个按照一定的约定和组织来测试代码的程序。在包目录内，所有以_test.go为后缀名的源文件在执行go build时不会被构建成包的一部分，它们是go test测试的一部分。

• 在*_test.go文件中，有三种类型的函数：测试函数、基准测试（benchmark）函数、示例函数。

  • 一个测试函数是以Test为函数名前缀的函数，用于测试程序的一些逻辑行为是否正确；go test命令会调用这些测试函数并报告测试结果是PASS或FAIL。
  • 基准测试函数是以Benchmark为函数名前缀的函数，它们用于衡量一些函数的性能；go test命令会多次运行基准测试函数以计算一个平均的执行时间。
  • 示例函数是以Example为函数名前缀的函数，提供一个由编译器保证正确性的示例文档。

• 我们将在11.2节讨论测试函数的所有细节，并在11.4节讨论基准测试函数的细节，然后在11.6节讨论示例函数的细节。

• go test命令会遍历所有的*_test.go文件中符合上述命名规则的函数，生成一个临时的main包用于调用相应的测试函数，接着构建并运行、报告测试结果，最后清理测试中生成的临时文件。

ch11.2 测试函数

• ch11.2.0 简介

  • 每个测试函数必须导入testing包。测试函数有如下的签名：

    func TestName(t *testing.T) {
    	// ...
    }
    

  • 测试函数的名字必须以Test开头，可选的后缀名必须以大写字母开头：

    func TestSin(t *testing.T) { /* ... */ }
    func TestCos(t *testing.T) { /* ... */ }
    func TestLog(t *testing.T) { /* ... */ }
    

    • 其中t参数用于报告测试失败和附加的日志信息。让我们定义一个实例包gopl.io/ch11/word1，其中只有一个函数IsPalindrome用于检查一个字符串是否从前向后和从后向前读都是一样的。

  • 下面这个实现对于一个字符串是否是回文字符串前后重复测试了两次；我们稍后会再讨论这个问题。

    gopl.io/ch11/word1

    // Package word provides utilities for word games.
    package word
    
    // IsPalindrome reports whether s reads the same forward and backward.
    // (Our first attempt.)
    func IsPalindrome(s string) bool {
    	for i := range s {
    		if s[i] != s[len(s)-1-i] {
    			return false
    		}
    	}
    	return true
    }
    

  • 在相同的目录下，word_test.go测试文件中包含了TestPalindrome和TestNonPalindrome两个测试函数。每一个都是测试IsPalindrome是否给出正确的结果，并使用t.Error报告失败信息：

    package word
    
    import "testing"
    
    func TestPalindrome(t *testing.T) {
    	if !IsPalindrome("detartrated") {
    		t.Error(`IsPalindrome("detartrated") = false`)
    	}
    	if !IsPalindrome("kayak") {
    		t.Error(`IsPalindrome("kayak") = false`)
    	}
    }
    
    func TestNonPalindrome(t *testing.T) {
    	if IsPalindrome("palindrome") {
    		t.Error(`IsPalindrome("palindrome") = true`)
    	}
    }
    

  • go test命令如果没有参数指定包那么将默认采用当前目录对应的包（和go build命令一样）。我们可以用下面的命令构建和运行测试。

    $ cd $GOPATH/src/gopl.io/ch11/word1
    $ go test
    ok   gopl.io/ch11/word1  0.008s
    

  • 结果还比较满意，我们运行了这个程序，不过没有提前退出是因为还没有遇到BUG报告。不过一个法国名为“Noelle Eve Elleon”的用户会抱怨IsPalindrome函数不能识别“été”。另外一个来自美国中部用户的抱怨则是不能识别“A man, a plan, a canal: Panama.”。执行特殊和小的BUG报告为我们提供了新的更自然的测试用例。

    func TestFrenchPalindrome(t *testing.T) {
    	if !IsPalindrome("été") {
    		t.Error(`IsPalindrome("été") = false`)
    	}
    }
    
    func TestCanalPalindrome(t *testing.T) {
    	input := "A man, a plan, a canal: Panama"
    	if !IsPalindrome(input) {
    		t.Errorf(`IsPalindrome(%q) = false`, input)
    	}
    }
    

  • 为了避免两次输入较长的字符串，我们使用了提供了有类似Printf格式化功能的 Errorf函数来汇报错误结果。

  • 当添加了这两个测试用例之后，go test返回了测试失败的信息。

    $ go test
    --- FAIL: TestFrenchPalindrome (0.00s)
        word_test.go:28: IsPalindrome("été") = false
    --- FAIL: TestCanalPalindrome (0.00s)
        word_test.go:35: IsPalindrome("A man, a plan, a canal: Panama") = false
    FAIL
    FAIL    gopl.io/ch11/word1  0.014s
    

  • 先编写测试用例并观察到测试用例触发了和用户报告的错误相同的描述是一个好的测试习惯。只有这样，我们才能定位我们要真正解决的问题。

  • 先写测试用例的另外的好处是，运行测试通常会比手工描述报告的处理更快，这让我们可以进行快速地迭代。如果测试集有很多运行缓慢的测试，我们可以通过只选择运行某些特定的测试来加快测试速度。

    • 参数-v可用于打印每个测试函数的名字和运行时间：

      $ go test -v
      === RUN TestPalindrome
      --- PASS: TestPalindrome (0.00s)
      === RUN TestNonPalindrome
      --- PASS: TestNonPalindrome (0.00s)
      === RUN TestFrenchPalindrome
      --- FAIL: TestFrenchPalindrome (0.00s)
          word_test.go:28: IsPalindrome("été") = false
      === RUN TestCanalPalindrome
      --- FAIL: TestCanalPalindrome (0.00s)
          word_test.go:35: IsPalindrome("A man, a plan, a canal: Panama") = false
      FAIL
      exit status 1
      FAIL    gopl.io/ch11/word1  0.017s
      

    • 参数-run对应一个正则表达式，只有测试函数名被它正确匹配的测试函数才会被go test测试命令运行：

      $ go test -v -run="French|Canal"
      === RUN TestFrenchPalindrome
      --- FAIL: TestFrenchPalindrome (0.00s)
          word_test.go:28: IsPalindrome("été") = false
      === RUN TestCanalPalindrome
      --- FAIL: TestCanalPalindrome (0.00s)
          word_test.go:35: IsPalindrome("A man, a plan, a canal: Panama") = false
      FAIL
      exit status 1
      FAIL    gopl.io/ch11/word1  0.014s
      

  • 当然，一旦我们已经修复了失败的测试用例，在我们提交代码更新之前，我们应该以不带参数的go test命令运行全部的测试用例，以确保修复失败测试的同时没有引入新的问题。

  • 我们现在的任务就是修复这些错误。简要分析后发现第一个BUG的原因是我们采用了 byte而不是rune序列，所以像“été”中的é等非ASCII字符不能正确处理。第二个BUG是因为没有忽略空格和字母的大小写导致的。

    • 针对上述两个BUG，我们仔细重写了函数：

      gopl.io/ch11/word2

      // Package word provides utilities for word games.
      package word
      
      import "unicode"
      
      // IsPalindrome reports whether s reads the same forward and backward.
      // Letter case is ignored, as are non-letters.
      func IsPalindrome(s string) bool {
      	var letters []rune
      	for _, r := range s {
      		if unicode.IsLetter(r) {
      			letters = append(letters, unicode.ToLower(r))
      		}
      	}
      	for i := range letters {
      		if letters[i] != letters[len(letters)-1-i] {
      			return false
      		}
      	}
      	return true
      }
      

    • 同时我们也将之前的所有测试数据合并到了一个测试中的表格中。

      func TestIsPalindrome(t *testing.T) {
      	var tests = []struct {
      		input string
      		want  bool
      	}{
      		{"", true},
      		{"a", true},
      		{"aa", true},
      		{"ab", false},
      		{"kayak", true},
      		{"detartrated", true},
      		{"A man, a plan, a canal: Panama", true},
      		{"Evil I did dwell; lewd did I live.", true},
      		{"Able was I ere I saw Elba", true},
      		{"été", true},
      		{"Et se resservir, ivresse reste.", true},
      		{"palindrome", false}, // non-palindrome
      		{"desserts", false},   // semi-palindrome
      	}
      	for _, test := range tests {
      		if got := IsPalindrome(test.input); got != test.want {
      			t.Errorf("IsPalindrome(%q) = %v", test.input, got)
      		}
      	}
      }
      

    • 现在我们的新测试都通过了：

      $ go test gopl.io/ch11/word2
      ok      gopl.io/ch11/word2      0.015s
      

  • 这种表格驱动的测试在Go语言中很常见。我们可以很容易地向表格添加新的测试数据，并且后面的测试逻辑也没有冗余，这样我们可以有更多的精力去完善错误信息。

  • 失败测试的输出并不包括调用t.Errorf时刻的堆栈调用信息。和其他编程语言或测试框架的assert断言不同，t.Errorf调用也没有引起panic异常或停止测试的执行。即使表格中前面的数据导致了测试的失败，表格后面的测试数据依然会运行测试，因此在一个测试中我们可能了解多个失败的信息。

  • 如果我们真的需要停止测试，或许是因为初始化失败或可能是早先的错误导致了后续错误等原因，我们可以使用t.Fatal或t.Fatalf停止当前测试函数。它们必须在和测试函数同一个goroutine内调用。

  • 测试失败的信息一般的形式是“f(x) = y, want z”，其中f(x)解释了失败的操作和对应的输入，y是实际的运行结果，z是期望的正确的结果。就像前面检查回文字符串的例子，实际的函数用于f(x)部分。显示x是表格驱动型测试中比较重要的部分，因为同一个断言可能对应不同的表格项执行多次。要避免无用和冗余的信息。在测试类似IsPalindrome返回布尔类型的函数时，可以忽略并没有额外信息的z部分。如果x、y或z是y的长度，输出一个相关部分的简明总结即可。测试的作者应该要努力帮助程序员诊断测试失败的原因。

• ch11.2.1 随机测试

  • 表格驱动的测试便于构造基于精心挑选的测试数据的测试用例。另一种测试思路是随机测试，也就是通过构造更广泛的随机输入来测试探索函数的行为。

  • 那么对于一个随机的输入，我们如何能知道希望的输出结果呢？这里有两种处理策略。第一个是编写另一个对照函数，使用简单和清晰的算法，虽然效率较低但是行为和要测试的函数是一致的，然后针对相同的随机输入检查两者的输出结果。第二种是生成的随机输入的数据遵循特定的模式，这样我们就可以知道期望的输出的模式。

  • 下面的例子使用的是第二种方法：randomPalindrome函数用于随机生成回文字符串。

    import "math/rand"
    
    // randomPalindrome returns a palindrome whose length and contents
    // are derived from the pseudo-random number generator rng.
    func randomPalindrome(rng *rand.Rand) string {
    	n := rng.Intn(25) // random length up to 24
    	runes := make([]rune, n)
    	for i := 0; i < (n+1)/2; i++ {
    		r := rune(rng.Intn(0x1000)) // random rune up to '\u0999'
    		runes[i] = r
    		runes[n-1-i] = r
    	}
    	return string(runes)
    }
    
    func TestRandomPalindromes(t *testing.T) {
    	// Initialize a pseudo-random number generator.
    	seed := time.Now().UTC().UnixNano()
    	t.Logf("Random seed: %d", seed)
    	rng := rand.New(rand.NewSource(seed))
    
    	for i := 0; i < 1000; i++ {
    		p := randomPalindrome(rng)
    		if !IsPalindrome(p) {
    			t.Errorf("IsPalindrome(%q) = false", p)
    		}
    	}
    }
    

  • 虽然随机测试会有不确定因素，但是它也是至关重要的，我们可以从失败测试的日志获取足够的信息。在我们的例子中，输入IsPalindrome的p参数将告诉我们真实的数据，但是对于函数将接受更复杂的输入，不需要保存所有的输入，只要日志中简单地记录随机数种子即可（像上面的方式）。有了这些随机数初始化种子，我们可以很容易修改测试代码以重现失败的随机测试。

  • 通过使用当前时间作为随机种子，在整个过程中的每次运行测试命令时都将探索新的随机数据。如果你使用的是定期运行的自动化测试集成系统，随机测试将特别有价值。

• ch11.2.2 测试一个命令

  • 对于测试包go test是一个有用的工具，但是稍加努力我们也可以用它来测试可执行程序。如果一个包的名字是 main，那么在构建时会生成一个可执行程序，不过main包可以作为一个包被测试器代码导入。

  • 让我们为2.3.2节的echo程序编写一个测试。我们先将程序拆分为两个函数：echo函数完成真正的工作，main函数用于处理命令行输入参数和echo可能返回的错误。

    gopl.io/ch11/echo

    // Echo prints its command-line arguments.
    package main
    
    import (
    	"flag"
    	"fmt"
    	"io"
    	"os"
    	"strings"
    )
    
    var (
    	n = flag.Bool("n", false, "omit trailing newline")
    	s = flag.String("s", " ", "separator")
    )
    
    var out io.Writer = os.Stdout // modified during testing
    
    func main() {
    	flag.Parse()
    	if err := echo(!*n, *s, flag.Args()); err != nil {
    		fmt.Fprintf(os.Stderr, "echo: %v\n", err)
    		os.Exit(1)
    	}
    }
    
    func echo(newline bool, sep string, args []string) error {
    	fmt.Fprint(out, strings.Join(args, sep))
    	if newline {
    		fmt.Fprintln(out)
    	}
    	return nil
    }
    

  • 在测试中我们可以用各种参数和标志调用echo函数，然后检测它的输出是否正确，我们通过增加参数来减少echo函数对全局变量的依赖。我们还增加了一个全局名为out的变量来替代直接使用os.Stdout，这样测试代码可以根据需要将out修改为不同的对象以便于检查。下面就是echo_test.go文件中的测试代码：

    package main
    
    import (
    	"bytes"
    	"fmt"
    	"testing"
    )
    
    func TestEcho(t *testing.T) {
    	var tests = []struct {
    		newline bool
    		sep     string
    		args    []string
    		want    string
    	}{
    		{true, "", []string{}, "\n"},
    		{false, "", []string{}, ""},
    		{true, "\t", []string{"one", "two", "three"}, "one\ttwo\tthree\n"},
    		{true, ",", []string{"a", "b", "c"}, "a,b,c\n"},
    		{false, ":", []string{"1", "2", "3"}, "1:2:3"},
    	}
    	for _, test := range tests {
    		descr := fmt.Sprintf("echo(%v, %q, %q)",
    			test.newline, test.sep, test.args)
    
    		out = new(bytes.Buffer) // captured output
    		if err := echo(test.newline, test.sep, test.args); err != nil {
    			t.Errorf("%s failed: %v", descr, err)
    			continue
    		}
    		got := out.(*bytes.Buffer).String()
    		if got != test.want {
    			t.Errorf("%s = %q, want %q", descr, got, test.want)
    		}
    	}
    }
    

  • 要注意的是测试代码和产品代码在同一个包。虽然是main包，也有对应的main入口函数，但是在测试的时候main包只是TestEcho测试函数导入的一个普通包，里面main函数并没有被导出，而是被忽略的。

  • 通过将测试放到表格中，我们很容易添加新的测试用例。让我通过增加下面的测试用例来看看失败的情况是怎么样的：

    {true, ",", []string{"a", "b", "c"}, "a b c\n"}, // NOTE: wrong expectation!
    

  • go test输出如下：

    $ go test gopl.io/ch11/echo
    --- FAIL: TestEcho (0.00s)
        echo_test.go:31: echo(true, ",", ["a" "b" "c"]) = "a,b,c", want "a b c\n"
    FAIL
    FAIL        gopl.io/ch11/echo         0.006s
    

  • 错误信息描述了尝试的操作（使用Go类似语法），实际的结果和期望的结果。通过这样的错误信息，你可以在检视代码之前就很容易定位错误的原因。

  • 要注意的是在测试代码中并没有调用log.Fatal或os.Exit，因为调用这类函数会导致程序提前退出；调用这些函数的特权应该放在main函数中。如果真的有意外的事情导致函数发生panic异常，测试驱动应该尝试用recover捕获异常，然后将当前测试当作失败处理。如果是可预期的错误，例如非法的用户输入、找不到文件或配置文件不当等应该通过返回一个非空的error的方式处理。幸运的是（上面的意外只是一个插曲），我们的echo示例是比较简单的也没有需要返回非空error的情况。

• ch11.2.3 白盒测试

  • 一种测试分类的方法是基于测试者是否需要了解被测试对象的内部工作原理。黑盒测试只需要测试包公开的文档和API行为，内部实现对测试代码是透明的。相反，白盒测试有访问包内部函数和数据结构的权限，因此可以做到一些普通客户端无法实现的测试。例如，一个白盒测试可以在每个操作之后检测不变量的数据类型。

    • 白盒测试只是一个传统的名称，其实称为clear box测试会更准确。

  • 黑盒和白盒这两种测试方法是互补的。黑盒测试一般更健壮，随着软件实现的完善测试代码很少需要更新。它们可以帮助测试者了解真实客户的需求，也可以帮助发现API设计的一些不足之处。相反，白盒测试则可以对内部一些棘手的实现提供更多的测试覆盖。

  • 我们已经看到两种测试的例子。TestIsPalindrome测试仅仅使用导出的IsPalindrome函数，因此这是一个黑盒测试。TestEcho测试则调用了内部的echo函数，并且更新了内部的out包级变量，这两个都是未导出的，因此这是白盒测试。

  • 当我们准备TestEcho测试的时候，我们修改了echo函数使用包级的out变量作为输出对象，因此测试代码可以用另一个实现代替标准输出，这样可以方便对比echo输出的数据。使用类似的技术，我们可以将产品代码的其他部分也替换为一个容易测试的伪对象。使用伪对象的好处是我们可以方便配置，容易预测，更可靠，也更容易观察。同时也可以避免一些不良的副作用，例如更新生产数据库或信用卡消费行为。

  • 下面的代码演示了为用户提供网络存储的web服务中的配额检测逻辑。当用户使用了超过90%的存储配额之后将发送提醒邮件。

    gopl.io/ch11/storage1

    package storage
    
    import (
    	"fmt"
    	"log"
    	"net/smtp"
    )
    
    func bytesInUse(username string) int64 { return 0 /* ... */ }
    
    // Email sender configuration.
    // NOTE: never put passwords in source code!
    const sender = "notifications@example.com"
    const password = "correcthorsebatterystaple"
    const hostname = "smtp.example.com"
    
    const template = `Warning: you are using %d bytes of storage,
    %d%% of your quota.`
    
    func CheckQuota(username string) {
    	used := bytesInUse(username)
    	const quota = 1000000000 // 1GB
    	percent := 100 * used / quota
    	if percent < 90 {
    		return // OK
    	}
    	msg := fmt.Sprintf(template, used, percent)
    	auth := smtp.PlainAuth("", sender, password, hostname)
    	err := smtp.SendMail(hostname+":587", auth, sender,
    		[]string{username}, []byte(msg))
    	if err != nil {
    		log.Printf("smtp.SendMail(%s) failed: %s", username, err)
    	}
    }
    

    • 译注：一般在实现业务机器监控，包括磁盘、cpu、网络等的时候，需要类似的到达阈值=>触发报警的逻辑，所以是很实用的案例。

  • 我们想测试这段代码，但是我们并不希望发送真实的邮件。因此我们将邮件处理逻辑放到一个私有的notifyUser函数中。

    gopl.io/ch11/storage2

    var notifyUser = func(username, msg string) {
    	auth := smtp.PlainAuth("", sender, password, hostname)
    	err := smtp.SendMail(hostname+":587", auth, sender,
    		[]string{username}, []byte(msg))
    	if err != nil {
    		log.Printf("smtp.SendEmail(%s) failed: %s", username, err)
    	}
    }
    
    func CheckQuota(username string) {
    	used := bytesInUse(username)
    	const quota = 1000000000 // 1GB
    	percent := 100 * used / quota
    	if percent < 90 {
    		return // OK
    	}
    	msg := fmt.Sprintf(template, used, percent)
    	notifyUser(username, msg)
    }
    

  • 现在我们可以在测试中用伪邮件发送函数替代真实的邮件发送函数。它只是简单记录要通知的用户和邮件的内容。

    package storage
    
    import (
    	"strings"
    	"testing"
    )
    func TestCheckQuotaNotifiesUser(t *testing.T) {
    	var notifiedUser, notifiedMsg string
    	notifyUser = func(user, msg string) {
    		notifiedUser, notifiedMsg = user, msg
    	}
    
    	// ...simulate a 980MB-used condition...
    
    	const user = "joe@example.org"
    	CheckQuota(user)
    	if notifiedUser == "" && notifiedMsg == "" {
    		t.Fatalf("notifyUser not called")
    	}
    	if notifiedUser != user {
    		t.Errorf("wrong user (%s) notified, want %s",
    			notifiedUser, user)
    	}
    	const wantSubstring = "98% of your quota"
    	if !strings.Contains(notifiedMsg, wantSubstring) {
    		t.Errorf("unexpected notification message <<%s>>, "+
    			"want substring %q", notifiedMsg, wantSubstring)
    	}
    }
    

  • 这里有一个问题：当测试函数返回后，CheckQuota将不能正常工作，因为notifyUsers依然使用的是测试函数的伪发送邮件函数（当更新全局对象的时候总会有这种风险）。 我们必须修改测试代码恢复notifyUsers原先的状态以便后续其他的测试没有影响，要确保所有的执行路径后都能恢复，包括测试失败或panic异常的情形。在这种情况下，我们建议使用defer语句来延后执行处理恢复的代码。

    func TestCheckQuotaNotifiesUser(t *testing.T) {
    	// Save and restore original notifyUser.
    	saved := notifyUser
    	defer func() { notifyUser = saved }()
    
    	// Install the test's fake notifyUser.
    	var notifiedUser, notifiedMsg string
    	notifyUser = func(user, msg string) {
    		notifiedUser, notifiedMsg = user, msg
    	}
    	// ...rest of test...
    }
    

  • 这种处理模式可以用来暂时保存和恢复所有的全局变量，包括命令行标志参数、调试选项和优化参数；安装和移除导致生产代码产生一些调试信息的钩子函数；还有有些诱导生产代码进入某些重要状态的改变，比如超时、错误，甚至是一些刻意制造的并发行为等因素。

  • 以这种方式使用全局变量是安全的，因为go test命令并不会同时并发地执行多个测试。

• ch11.2.4 外部测试包

  • 考虑下这两个包：net/url包，提供了URL解析的功能；net/http包，提供了web服务和HTTP客户端的功能。如我们所料，上层的net/http包依赖下层的net/url包。然后，net/url包中的一个测试是演示不同URL和HTTP客户端的交互行为。也就是说，一个下层包的测试代码导入了上层的包。

  • 这样的行为在net/url包的测试代码中会导致包的循环依赖，正如图11.1中向上箭头所示，同时正如我们在10.1节所讲的，Go语言规范是禁止包的循环依赖的。

  • 不过我们可以通过外部测试包的方式解决循环依赖的问题，也就是在net/url包所在的目录声明一个独立的url_test测试包。其中包名的_test后缀告诉go test工具它应该建立一个额外的包来运行测试。我们将这个外部测试包的导入路径视作是net/url_test会更容易理解，但实际上它并不能被其他任何包导入。

  • 因为外部测试包是一个独立的包，所以能够导入那些依赖待测代码本身的其他辅助包；包内的测试代码就无法做到这点。在设计层面，外部测试包是在所有它依赖的包的上层，正如图11.2所示。

  • 通过避免循环的导入依赖，外部测试包可以更灵活地编写测试，特别是集成测试（需要测试多个组件之间的交互），可以像普通应用程序那样自由地导入其他包。

  • 我们可以用go list命令查看包对应目录中哪些Go源文件是产品代码，哪些是包内测试，还有哪些是外部测试包。我们以fmt包作为一个例子：GoFiles表示产品代码对应的Go源文件列表；也就是go build命令要编译的部分。

    {% raw %}

    $ go list -f={{.GoFiles}} fmt
    [doc.go format.go print.go scan.go]
    

    {% endraw %}

  • TestGoFiles表示的是fmt包内部测试代码，以_test.go为后缀文件名，不过只在测试时被构建：

    {% raw %}

    $ go list -f={{.TestGoFiles}} fmt
    [export_test.go]
    

    {% endraw %}

  • 包的测试代码通常都在这些文件中，不过fmt包并非如此；稍后我们再解释export_test.go文件的作用。

  • XTestGoFiles表示的是属于外部测试包的测试代码，也就是fmt_test包，因此它们必须先导入fmt包。同样，这些文件也只是在测试时被构建运行：

    {% raw %}

    $ go list -f={{.XTestGoFiles}} fmt
    [fmt_test.go scan_test.go stringer_test.go]
    

    {% endraw %}

  • 有时候外部测试包也需要访问被测试包内部的代码，例如在一个为了避免循环导入而被独立到外部测试包的白盒测试。在这种情况下，我们可以通过一些技巧解决：我们在包内的一个_test.go文件中导出一个内部的实现给外部测试包。因为这些代码只有在测试时才需要，因此一般会放在export_test.go文件中。

  • 例如，fmt包的fmt.Scanf函数需要unicode.IsSpace函数提供的功能。但是为了避免太多的依赖，fmt包并没有导入包含巨大表格数据的unicode包；相反fmt包有一个叫isSpace内部的简易实现。

  • 为了确保fmt.isSpace和unicode.IsSpace函数的行为保持一致，fmt包谨慎地包含了一个测试。一个在外部测试包内的白盒测试，是无法直接访问到isSpace内部函数的，因此fmt通过一个后门导出了isSpace函数。export_test.go文件就是专门用于外部测试包的后门。

    package fmt
    
    var IsSpace = isSpace
    

  • 这个测试文件并没有定义测试代码；它只是通过fmt.IsSpace简单导出了内部的isSpace函数，提供给外部测试包使用。这个技巧可以广泛用于位于外部测试包的白盒测试。

• ch11.2.5 编写有效的测试

  • 许多Go语言新人会惊异于Go语言极简的测试框架。很多其它语言的测试框架都提供了识别测试函数的机制（通常使用反射或元数据），通过设置一些“setup”和“teardown”的钩子函数来执行测试用例运行的初始化和之后的清理操作，同时测试工具箱还提供了很多类似assert断言、值比较函数、格式化输出错误信息和停止一个失败的测试等辅助函数（通常使用异常机制）。虽然这些机制可以使得测试非常简洁，但是测试输出的日志却会像火星文一般难以理解。此外，虽然测试最终也会输出PASS或FAIL的报告，但是它们提供的信息格式却非常不利于代码维护者快速定位问题，因为失败信息的具体含义非常隐晦，比如“assert: 0 == 1”或成页的海量跟踪日志。

  • Go语言的测试风格则形成鲜明对比。它期望测试者自己完成大部分的工作，定义函数避免重复，就像普通编程那样。编写测试并不是一个机械的填空过程；一个测试也有自己的接口，尽管它的维护者也是测试仅有的一个用户。一个好的测试不应该引发其他无关的错误信息，它只要清晰简洁地描述问题的症状即可，有时候可能还需要一些上下文信息。在理想情况下，维护者可以在不看代码的情况下就能根据错误信息定位错误产生的原因。一个好的测试不应该在遇到一点小错误时就立刻退出测试，它应该尝试报告更多的相关的错误信息，因为我们可能从多个失败测试的模式中发现错误产生的规律。

  • 下面的断言函数比较两个值，然后生成一个通用的错误信息，并停止程序。它很好用也确实有效，但是当测试失败的时候，打印的错误信息却几乎是没有价值的。它并没有为快速解决问题提供一个很好的入口。

    import (
    	"fmt"
    	"strings"
    	"testing"
    )
    // A poor assertion function.
    func assertEqual(x, y int) {
    	if x != y {
    		panic(fmt.Sprintf("%d != %d", x, y))
    	}
    }
    func TestSplit(t *testing.T) {
    	words := strings.Split("a:b:c", ":")
    	assertEqual(len(words), 3)
    	// ...
    }
    

  • 从这个意义上说，断言函数犯了过早抽象的错误：仅仅测试两个整数是否相同，而没能根据上下文提供更有意义的错误信息。我们可以根据具体的错误打印一个更有价值的错误信息，就像下面例子那样。只有在测试中出现重复模式时才采用抽象。

    func TestSplit(t *testing.T) {
    	s, sep := "a:b:c", ":"
    	words := strings.Split(s, sep)
    	if got, want := len(words), 3; got != want {
    		t.Errorf("Split(%q, %q) returned %d words, want %d",
    			s, sep, got, want)
    	}
    	// ...
    }
    

  • 现在的测试不仅报告了调用的具体函数、它的输入和结果的意义；并且打印的真实返回的值和期望返回的值；并且即使断言失败依然会继续尝试运行更多的测试。一旦我们写了这样结构的测试，下一步自然不是用更多的if语句来扩展测试用例，我们可以用像IsPalindrome的表驱动测试那样来准备更多的s和sep测试用例。

  • 前面的例子并不需要额外的辅助函数，如果有可以使测试代码更简单的方法我们也乐意接受。（我们将在13.3节看到一个类似reflect.DeepEqual辅助函数。）一个好的测试的关键是首先实现你期望的具体行为，然后才是考虑简化测试代码、避免重复。如果直接从抽象、通用的测试库着手，很难取得良好结果。

• ch11.2.6 避免脆弱的测试

  • 如果一个应用程序对于新出现的但有效的输入经常失败说明程序容易出bug（不够稳健）；同样，如果一个测试仅仅对程序做了微小变化就失败则称为脆弱。就像一个不够稳健的程序会挫败它的用户一样，一个脆弱的测试同样会激怒它的维护者。最脆弱的测试代码会在程序没有任何变化的时候产生不同的结果，时好时坏，处理它们会耗费大量的时间但是并不会得到任何好处。
  • 当一个测试函数会产生一个复杂的输出如一个很长的字符串、一个精心设计的数据结构或一个文件时，人们很容易想预先写下一系列固定的用于对比的标杆数据。但是随着项目的发展，有些输出可能会发生变化，尽管很可能是一个改进的实现导致的。而且不仅仅是输出部分，函数复杂的输入部分可能也跟着变化了，因此测试使用的输入也就不再有效了。
  • 避免脆弱测试代码的方法是只检测你真正关心的属性。保持测试代码的简洁和内部结构的稳定。特别是对断言部分要有所选择。不要对字符串进行全字匹配，而是针对那些在项目的发展中是比较稳定不变的子串。很多时候值得花力气来编写一个从复杂输出中提取用于断言的必要信息的函数，虽然这可能会带来很多前期的工作，但是它可以帮助迅速及时修复因为项目演化而导致的不合逻辑的失败测试。

ch11.3 测试覆盖率

• 就其性质而言，测试不可能是完整的。计算机科学家Edsger Dijkstra曾说过：“测试能证明缺陷存在，而无法证明没有缺陷。”再多的测试也不能证明一个程序没有BUG。在最好的情况下，测试可以增强我们的信心：代码在很多重要场景下是可以正常工作的。

• 对待测程序执行的测试的程度称为测试的覆盖率。测试覆盖率并不能量化——即使最简单的程序的动态也是难以精确测量的——但是有启发式方法来帮助我们编写有效的测试代码。

• 这些启发式方法中，语句的覆盖率是最简单和最广泛使用的。语句的覆盖率是指在测试中至少被运行一次的代码占总代码数的比例。在本节中，我们使用go test命令中集成的测试覆盖率工具，来度量下面代码的测试覆盖率，帮助我们识别测试和我们期望间的差距。

• 下面的代码是一个表格驱动的测试，用于测试第七章的表达式求值程序：

  gopl.io/ch7/eval

  func TestCoverage(t *testing.T) {
  	var tests = []struct {
  		input string
  		env   Env
  		want  string // expected error from Parse/Check or result from Eval
  	}{
  		{"x % 2", nil, "unexpected '%'"},
  		{"!true", nil, "unexpected '!'"},
  		{"log(10)", nil, `unknown function "log"`},
  		{"sqrt(1, 2)", nil, "call to sqrt has 2 args, want 1"},
  		{"sqrt(A / pi)", Env{"A": 87616, "pi": math.Pi}, "167"},
  		{"pow(x, 3) + pow(y, 3)", Env{"x": 9, "y": 10}, "1729"},
  		{"5 / 9 * (F - 32)", Env{"F": -40}, "-40"},
  	}
  
  	for _, test := range tests {
  		expr, err := Parse(test.input)
  		if err == nil {
  			err = expr.Check(map[Var]bool{})
  		}
  		if err != nil {
  			if err.Error() != test.want {
  				t.Errorf("%s: got %q, want %q", test.input, err, test.want)
  			}
  			continue
  		}
  		got := fmt.Sprintf("%.6g", expr.Eval(test.env))
  		if got != test.want {
  			t.Errorf("%s: %v => %s, want %s",
  				test.input, test.env, got, test.want)
  		}
  	}
  }
  

  • 首先，我们要确保所有的测试都正常通过：

    $ go test -v -run=Coverage gopl.io/ch7/eval
    === RUN TestCoverage
    --- PASS: TestCoverage (0.00s)
    PASS
    ok      gopl.io/ch7/eval         0.011s
    

  • 下面这个命令可以显示测试覆盖率工具的使用用法：

    $ go tool cover
    Usage of 'go tool cover':
    Given a coverage profile produced by 'go test':
        go test -coverprofile=c.out
    
    Open a web browser displaying annotated source code:
        go tool cover -html=c.out
    ...
    

• 现在我们可以用-coverprofile标志参数重新运行测试：

  $ go test -run=Coverage -coverprofile=c.out gopl.io/ch7/eval
  ok      gopl.io/ch7/eval         0.032s      coverage: 68.5% of statements
  

  • 这个标志参数通过在测试代码中插入生成钩子来统计覆盖率数据。也就是说，在运行每个测试前，它将待测代码拷贝一份并做修改，在每个词法块都会设置一个布尔标志变量。当被修改后的被测试代码运行退出时，将统计日志数据写入c.out文件，并打印一部分执行的语句的一个总结。（如果你需要的是摘要，使用go test -cover。）
  • 如果使用了-covermode=count标志参数，那么将在每个代码块插入一个计数器而不是布尔标志量。在统计结果中记录了每个块的执行次数，这可以用于衡量哪些是被频繁执行的热点代码。

• 为了收集数据，我们运行了测试覆盖率工具，打印了测试日志，生成一个HTML报告，然后在浏览器中打开（图11.3）。

  $ go tool cover -html=c.out
  

  • 绿色的代码块被测试覆盖到了，红色的则表示没有被覆盖到。为了清晰起见，我们将背景红色文本的背景设置成了阴影效果。我们可以马上发现unary操作的Eval方法并没有被执行到。如果我们针对这部分未被覆盖的代码添加下面的测试用例，然后重新运行上面的命令，那么我们将会看到那个红色部分的代码也变成绿色了：

    {"-x * -x", eval.Env{"x": 2}, "4"}
    

• 不过两个panic语句依然是红色的。这是没有问题的，因为这两个语句并不会被执行到。

• 实现100%的测试覆盖率听起来很美，但是在具体实践中通常是不可行的，也不是值得推荐的做法。因为那只能说明代码被执行过而已，并不意味着代码就是没有BUG的；因为对于逻辑复杂的语句需要针对不同的输入执行多次。有一些语句，例如上面的panic语句则永远都不会被执行到。

• 另外，还有一些隐晦的错误在现实中很少遇到也很难编写对应的测试代码。测试从本质上来说是一个比较务实的工作，编写测试代码和编写应用代码的成本对比是需要考虑的。测试覆盖率工具可以帮助我们快速识别测试薄弱的地方，但是设计好的测试用例和编写应用代码一样需要严密的思考。

ch11.4 基准测试

• 基准测试是测量一个程序在固定工作负载下的性能。在Go语言中，基准测试函数和普通测试函数写法类似，但是以Benchmark为前缀名，并且带有一个*testing.B类型的参数；*testing.B参数除了提供和*testing.T类似的方法，还有额外一些和性能测量相关的方法。它还提供了一个整数N，用于指定操作执行的循环次数。

• 下面是IsPalindrome函数的基准测试，其中循环将执行N次。

  import "testing"
  
  func BenchmarkIsPalindrome(b *testing.B) {
  	for i := 0; i < b.N; i++ {
  		IsPalindrome("A man, a plan, a canal: Panama")
  	}
  }
  

• 我们用下面的命令运行基准测试。和普通测试不同的是，默认情况下不运行任何基准测试。我们需要通过-bench命令行标志参数手工指定要运行的基准测试函数。该参数是一个正则表达式，用于匹配要执行的基准测试函数的名字，默认值是空的。其中“.”模式将可以匹配所有基准测试函数，但因为这里只有一个基准测试函数，因此和-bench=IsPalindrome参数是等价的效果。

  $ cd $GOPATH/src/gopl.io/ch11/word2
  $ go test -bench=.
  PASS
  BenchmarkIsPalindrome-8 1000000                1035 ns/op
  ok      gopl.io/ch11/word2      2.179s
  

• 结果中基准测试名的数字后缀部分，这里是8，表示运行时对应的GOMAXPROCS的值，这对于一些与并发相关的基准测试是重要的信息。

• 报告显示每次调用IsPalindrome函数花费1.035微秒，是执行1,000,000次的平均时间。因为基准测试驱动器开始时并不知道每个基准测试函数运行所花的时间，它会尝试在真正运行基准测试前先尝试用较小的N运行测试来估算基准测试函数所需要的时间，然后推断一个较大的时间保证稳定的测量结果。

• 循环在基准测试函数内实现，而不是放在基准测试框架内实现，这样可以让每个基准测试函数有机会在循环启动前执行初始化代码，这样并不会显著影响每次迭代的平均运行时间。如果还是担心初始化代码部分对测量时间带来干扰，那么可以通过testing.B参数提供的方法来临时关闭或重置计时器，不过这些一般很少会用到。

• 现在我们有了一个基准测试和普通测试，我们可以很容易测试改进程序运行速度的想法。也许最明显的优化是在IsPalindrome函数中第二个循环的停止检查，这样可以避免每个比较都做两次：

  n := len(letters)/2
  for i := 0; i < n; i++ {
  	if letters[i] != letters[len(letters)-1-i] {
  		return false
  	}
  }
  return true
  

  • 不过很多情况下，一个显而易见的优化未必能带来预期的效果。这个改进在基准测试中只带来了4%的性能提升。

    $ go test -bench=.
    PASS
    BenchmarkIsPalindrome-8 1000000              992 ns/op
    ok      gopl.io/ch11/word2      2.093s
    

• 另一个改进想法是在开始为每个字符预先分配一个足够大的数组，这样就可以避免在append调用时可能会导致内存的多次重新分配。声明一个letters数组变量，并指定合适的大小，像下面这样，

  letters := make([]rune, 0, len(s))
  for _, r := range s {
  	if unicode.IsLetter(r) {
  		letters = append(letters, unicode.ToLower(r))
  	}
  }
  

  • 这个改进提升性能约35%，报告结果是基于2,000,000次迭代的平均运行时间统计。

    $ go test -bench=.
    PASS
    BenchmarkIsPalindrome-8 2000000                      697 ns/op
    ok      gopl.io/ch11/word2      1.468s
    

• 如这个例子所示，快的程序往往是伴随着较少的内存分配。-benchmem命令行标志参数将在报告中包含内存的分配数据统计。我们可以比较优化前后内存的分配情况：

  $ go test -bench=. -benchmem
  PASS
  BenchmarkIsPalindrome    1000000   1026 ns/op    304 B/op  4 allocs/op
  

  • 这是优化之后的结果：

    $ go test -bench=. -benchmem
    PASS
    BenchmarkIsPalindrome    2000000    807 ns/op    128 B/op  1 allocs/op
    

  • 用一次内存分配代替多次的内存分配节省了75%的分配调用次数和减少近一半的内存需求。

• 这个基准测试告诉了我们某个具体操作所需的绝对时间，但我们往往想知道的是两个不同的操作的时间对比。

  • 例如，如果一个函数需要1ms处理1,000个元素，那么处理10000或1百万将需要多少时间呢？这样的比较揭示了渐近增长函数的运行时间。
  • 另一个例子：I/O缓存该设置为多大呢？基准测试可以帮助我们选择在性能达标情况下所需的最小内存。
  • 第三个例子：对于一个确定的工作哪种算法更好？基准测试可以评估两种不同算法对于相同的输入在不同的场景和负载下的优缺点。

• 比较型的基准测试就是普通程序代码。它们通常是单参数的函数，由几个不同数量级的基准测试函数调用，就像这样：

  func benchmark(b *testing.B, size int) { /* ... */ }
  func Benchmark10(b *testing.B)         { benchmark(b, 10) }
  func Benchmark100(b *testing.B)        { benchmark(b, 100) }
  func Benchmark1000(b *testing.B)       { benchmark(b, 1000) }
  

  • 通过函数参数来指定输入的大小，但是参数变量对于每个具体的基准测试都是固定的。要避免直接修改b.N来控制输入的大小。除非你将它作为一个固定大小的迭代计算输入，否则基准测试的结果将毫无意义。

• 比较型的基准测试反映出的模式在程序设计阶段是很有帮助的，但是即使程序完工了也应当保留基准测试代码。因为随着项目的发展，或者是输入的增加，或者是部署到新的操作系统或不同的处理器，我们可以再次用基准测试来帮助我们改进设计。

ch11.5 剖析

• 基准测试（Benchmark）对于衡量特定操作的性能是有帮助的，但是当我们试图让程序跑的更快的时候，我们通常并不知道从哪里开始优化。每个码农都应该知道Donald Knuth在1974年的“Structured Programming with go to Statements”上所说的格言。虽然经常被解读为不重视性能的意思，但是从原文我们可以看到不同的含义：

  毫无疑问，对效率的片面追求会导致各种滥用。程序员会浪费大量的时间在非关键程序的速度上，实际上这些尝试提升效率的行为反倒可能产生很大的负面影响，特别是当调试和维护的时候。我们不应该过度纠结于细节的优化，应该说约97%的场景：过早的优化是万恶之源。

  当然我们也不应该放弃对那关键3%的优化。一个好的程序员不会因为这个比例小就裹足不前，他们会明智地观察和识别哪些是关键的代码；但是仅当关键代码已经被确认的前提下才会进行优化。对于很多程序员来说，判断哪部分是关键的性能瓶颈，是很容易犯经验上的错误的，因此一般应该借助测量工具来证明。

• 当我们想仔细观察我们程序的运行速度的时候，最好的方法是性能剖析。剖析技术是基于程序执行期间一些自动抽样，然后在收尾时进行推断；最后产生的统计结果就称为剖析数据。

• Go语言支持多种类型的剖析性能分析，每一种关注不同的方面，但它们都涉及到每个采样记录的感兴趣的一系列事件消息，每个事件都包含函数调用时函数调用堆栈的信息。内建的go test工具对几种分析方式都提供了支持。

• CPU剖析数据标识了最耗CPU时间的函数。在每个CPU上运行的线程在每隔几毫秒都会遇到操作系统的中断事件，每次中断时都会记录一个剖析数据然后恢复正常的运行。

• 堆剖析则标识了最耗内存的语句。剖析库会记录调用内部内存分配的操作，平均每512KB的内存申请会触发一个剖析数据。

• 阻塞剖析则记录阻塞goroutine最久的操作，例如系统调用、管道发送和接收，还有获取锁等。每当goroutine被这些操作阻塞时，剖析库都会记录相应的事件。

• 只需要开启下面其中一个标志参数就可以生成各种分析文件。当同时使用多个标志参数时需要当心，因为一项分析操作可能会影响其他项的分析结果。

  $ go test -cpuprofile=cpu.out
  $ go test -blockprofile=block.out
  $ go test -memprofile=mem.out
  

• 对于一些非测试程序也很容易进行剖析，具体的实现方式，与程序是短时间运行的小工具还是长时间运行的服务会有很大不同。剖析对于长期运行的程序尤其有用，因此可以通过调用Go的runtime API来启用运行时剖析。

• 一旦我们已经收集到了用于分析的采样数据，我们就可以使用pprof来分析这些数据。这是Go工具箱自带的一个工具，但并不是一个日常工具，它对应go tool pprof命令。该命令有许多特性和选项，但是最基本的是两个参数：生成这个概要文件的可执行程序和对应的剖析数据。

• 为了提高分析效率和减少空间，分析日志本身并不包含函数的名字；它只包含函数对应的地址。也就是说pprof需要对应的可执行程序来解读剖析数据。虽然go test通常在测试完成后就丢弃临时用的测试程序，但是在启用分析的时候会将测试程序保存为foo.test文件，其中foo部分对应待测包的名字。

• 下面的命令演示了如何收集并展示一个CPU分析文件。我们选择net/http包的一个基准测试为例。通常最好是对业务关键代码的部分设计专门的基准测试。因为简单的基准测试几乎没法代表业务场景，因此我们用-run=NONE参数禁止那些简单测试。

  $ go test -run=NONE -bench=ClientServerParallelTLS64 \
      -cpuprofile=cpu.log net/http
   PASS
   BenchmarkClientServerParallelTLS64-8  1000
      3141325 ns/op  143010 B/op  1747 allocs/op
  ok       net/http       3.395s
  
  $ go tool pprof -text -nodecount=10 ./http.test cpu.log
  2570ms of 3590ms total (71.59%)
  Dropped 129 nodes (cum <= 17.95ms)
  Showing top 10 nodes out of 166 (cum >= 60ms)
      flat  flat%   sum%     cum   cum%
    1730ms 48.19% 48.19%  1750ms 48.75%  crypto/elliptic.p256ReduceDegree
     230ms  6.41% 54.60%   250ms  6.96%  crypto/elliptic.p256Diff
     120ms  3.34% 57.94%   120ms  3.34%  math/big.addMulVVW
     110ms  3.06% 61.00%   110ms  3.06%  syscall.Syscall
      90ms  2.51% 63.51%  1130ms 31.48%  crypto/elliptic.p256Square
      70ms  1.95% 65.46%   120ms  3.34%  runtime.scanobject
      60ms  1.67% 67.13%   830ms 23.12%  crypto/elliptic.p256Mul
      60ms  1.67% 68.80%   190ms  5.29%  math/big.nat.montgomery
      50ms  1.39% 70.19%    50ms  1.39%  crypto/elliptic.p256ReduceCarry
      50ms  1.39% 71.59%    60ms  1.67%  crypto/elliptic.p256Sum
  

  • 参数-text用于指定输出格式，在这里每行是一个函数，根据使用CPU的时间长短来排序。其中-nodecount=10参数限制了只输出前10行的结果。对于严重的性能问题，这个文本格式基本可以帮助查明原因了。
  • 这个概要文件告诉我们，HTTPS基准测试中crypto/elliptic.p256ReduceDegree函数占用了将近一半的CPU资源，对性能占很大比重。相比之下，如果一个概要文件中主要是runtime包的内存分配的函数，那么减少内存消耗可能是一个值得尝试的优化策略。

• 对于一些更微妙的问题，你可能需要使用pprof的图形显示功能。这个需要安装GraphViz工具，可以从 http://www.graphviz.org 下载。参数-web用于生成函数的有向图，标注有CPU的使用和最热点的函数等信息。

• 这一节我们只是简单看了下Go语言的数据分析工具。如果想了解更多，可以阅读Go官方博客的“Profiling Go Programs”一文。

ch11.6 示例函数

• 第三种被go test特别对待的函数是示例函数，以Example为函数名开头。示例函数没有函数参数和返回值。下面是IsPalindrome函数对应的示例函数：

  func ExampleIsPalindrome() {
  	fmt.Println(IsPalindrome("A man, a plan, a canal: Panama"))
  	fmt.Println(IsPalindrome("palindrome"))
  	// Output:
  	// true
  	// false
  }
  

• 示例函数有三个用处。

  • 最主要的一个是作为文档：一个包的例子可以更简洁直观的方式来演示函数的用法，比文字描述更直接易懂，特别是作为一个提醒或快速参考时。一个示例函数也可以方便展示属于同一个接口的几种类型或函数之间的关系，所有的文档都必须关联到一个地方，就像一个类型或函数声明都统一到包一样。同时，示例函数和注释并不一样，示例函数是真实的Go代码，需要接受编译器的编译时检查，这样可以保证源代码更新时，示例代码不会脱节。

    • 根据示例函数的后缀名部分，godoc这个web文档服务器会将示例函数关联到某个具体函数或包本身，因此ExampleIsPalindrome示例函数将是IsPalindrome函数文档的一部分，Example示例函数将是包文档的一部分。

  • 示例函数的第二个用处是，在go test执行测试的时候也会运行示例函数测试。如果示例函数内含有类似上面例子中的// Output:格式的注释，那么测试工具会执行这个示例函数，然后检查示例函数的标准输出与注释是否匹配。

  • 示例函数的第三个目的提供一个真实的演练场。 http://golang.org 就是由godoc提供的文档服务，它使用了Go Playground让用户可以在浏览器中在线编辑和运行每个示例函数，就像图11.4所示的那样。这通常是学习函数使用或Go语言特性最快捷的方式。

• 本书最后的两章是讨论reflect和unsafe包，一般的Go程序员很少使用它们，事实上也很少需要用到。因此，如果你还没有写过任何真实的Go程序的话，现在可以先去写些代码了。

ch12 反射

ch12.0 简介

• Go语言提供了一种机制，能够在运行时更新变量和检查它们的值、调用它们的方法和它们支持的内在操作，而不需要在编译时就知道这些变量的具体类型。这种机制被称为反射。反射也可以让我们将类型本身作为第一类的值类型处理。
• 在本章，我们将探讨Go语言的反射特性，看看它可以给语言增加哪些表达力，以及在两个至关重要的API是如何使用反射机制的：一个是fmt包提供的字符串格式化功能，另一个是类似encoding/json和encoding/xml提供的针对特定协议的编解码功能。对于我们在4.6节中看到过的text/template和html/template包，它们的实现也是依赖反射技术的。然后，反射是一个复杂的内省技术，不应该随意使用，因此，尽管上面这些包内部都是用反射技术实现的，但是它们自己的API都没有公开反射相关的接口。

ch12.1 为何需要反射

• 有时候我们需要编写一个函数能够处理一类并不满足普通公共接口的类型的值，也可能是因为它们并没有确定的表示方式，或者是在我们设计该函数的时候这些类型可能还不存在。

• 个大家熟悉的例子是fmt.Fprintf函数提供的字符串格式化处理逻辑，它可以用来对任意类型的值格式化并打印，甚至支持用户自定义的类型。让我们也来尝试实现一个类似功能的函数。为了简单起见，我们的函数只接收一个参数，然后返回和fmt.Sprint类似的格式化后的字符串。我们实现的函数名也叫Sprint。

• 我们首先用switch类型分支来测试输入参数是否实现了String方法，如果是的话就调用该方法。然后继续增加类型测试分支，检查这个值的动态类型是否是string、int、bool等基础类型，并在每种情况下执行相应的格式化操作。

  func Sprint(x interface{}) string {
  	type stringer interface {
  		String() string
  	}
  	switch x := x.(type) {
  	case stringer:
  		return x.String()
  	case string:
  		return x
  	case int:
  		return strconv.Itoa(x)
  	// ...similar cases for int16, uint32, and so on...
  	case bool:
  		if x {
  			return "true"
  		}
  		return "false"
  	default:
  		// array, chan, func, map, pointer, slice, struct
  		return "???"
  	}
  }
  

• 但是我们如何处理其它类似[]float64、map[string][]string等类型呢？我们当然可以添加更多的测试分支，但是这些组合类型的数目基本是无穷的。还有如何处理类似url.Values这样的具名类型呢？即使类型分支可以识别出底层的基础类型是map[string][]string，但是它并不匹配url.Values类型，因为它们是两种不同的类型，而且switch类型分支也不可能包含每个类似url.Values的类型，这会导致对这些库的依赖。

• 没有办法来检查未知类型的表示方式，我们被卡住了。这就是我们为何需要反射的原因。

ch12.2 reflect.Type和reflect.Value

• 反射是由 reflect 包提供的。它定义了两个重要的类型，Type 和 Value。一个 Type 表示一个Go类型。它是一个接口，有许多方法来区分类型以及检查它们的组成部分，例如一个结构体的成员或一个函数的参数等。唯一能反映 reflect.Type 实现的是接口的类型描述信息（§7.5），也正是这个实体标识了接口值的动态类型。

• 函数 reflect.TypeOf 接受任意的 interface{} 类型，并以 reflect.Type 形式返回其动态类型：

  t := reflect.TypeOf(3)  // a reflect.Type
  fmt.Println(t.String()) // "int"
  fmt.Println(t)          // "int"
  

• 其中 TypeOf(3) 调用将值 3 传给 interface{} 参数。回到 7.5节 的将一个具体的值转为接口类型会有一个隐式的接口转换操作，它会创建一个包含两个信息的接口值：操作数的动态类型（这里是 int）和它的动态的值（这里是 3）。

• 因为 reflect.TypeOf 返回的是一个动态类型的接口值，它总是返回具体的类型。因此，下面的代码将打印 “*os.File” 而不是 “io.Writer”。稍后，我们将看到能够表达接口类型的 reflect.Type。

  var w io.Writer = os.Stdout
  fmt.Println(reflect.TypeOf(w)) // "*os.File"
  

• 要注意的是 reflect.Type 接口是满足 fmt.Stringer 接口的。因为打印一个接口的动态类型对于调试和日志是有帮助的， fmt.Printf 提供了一个缩写 %T 参数，内部使用 reflect.TypeOf 来输出：

  fmt.Printf("%T\n", 3) // "int"
  

• reflect 包中另一个重要的类型是 Value。一个 reflect.Value 可以装载任意类型的值。函数 reflect.ValueOf 接受任意的 interface{} 类型，并返回一个装载着其动态值的 reflect.Value。和 reflect.TypeOf 类似，reflect.ValueOf 返回的结果也是具体的类型，但是 reflect.Value 也可以持有一个接口值。

  v := reflect.ValueOf(3) // a reflect.Value
  fmt.Println(v)          // "3"
  fmt.Printf("%v\n", v)   // "3"
  fmt.Println(v.String()) // NOTE: "<int Value>"
  

• 和 reflect.Type 类似，reflect.Value 也满足 fmt.Stringer 接口，但是除非 Value 持有的是字符串，否则 String 方法只返回其类型。而使用 fmt 包的 %v 标志参数会对 reflect.Values 特殊处理。

• 对 Value 调用 Type 方法将返回具体类型所对应的 reflect.Type：

  t := v.Type()           // a reflect.Type
  fmt.Println(t.String()) // "int"
  

• reflect.ValueOf 的逆操作是 reflect.Value.Interface 方法。它返回一个 interface{} 类型，装载着与 reflect.Value 相同的具体值：

  v := reflect.ValueOf(3) // a reflect.Value
  x := v.Interface()      // an interface{}
  i := x.(int)            // an int
  fmt.Printf("%d\n", i)   // "3"
  

• reflect.Value 和 interface{} 都能装载任意的值。所不同的是，一个空的接口隐藏了值内部的表示方式和所有方法，因此只有我们知道具体的动态类型才能使用类型断言来访问内部的值（就像上面那样），内部值我们没法访问。相比之下，一个 Value 则有很多方法来检查其内容，无论它的具体类型是什么。让我们再次尝试实现我们的格式化函数 format.Any。

• 我们使用 reflect.Value 的 Kind 方法来替代之前的类型 switch。虽然还是有无穷多的类型，但是它们的 kinds 类型却是有限的：Bool、String 和 所有数字类型的基础类型；Array 和 Struct 对应的聚合类型；Chan、Func、Ptr、Slice 和 Map 对应的引用类型；interface 类型；还有表示空值的 Invalid 类型。（空的 reflect.Value 的 kind 即为 Invalid。）

  gopl.io/ch12/format

  package format
  
  import (
  	"reflect"
  	"strconv"
  )
  
  // Any formats any value as a string.
  func Any(value interface{}) string {
  	return formatAtom(reflect.ValueOf(value))
  }
  
  // formatAtom formats a value without inspecting its internal structure.
  func formatAtom(v reflect.Value) string {
  	switch v.Kind() {
  	case reflect.Invalid:
  		return "invalid"
  	case reflect.Int, reflect.Int8, reflect.Int16,
  		reflect.Int32, reflect.Int64:
  		return strconv.FormatInt(v.Int(), 10)
  	case reflect.Uint, reflect.Uint8, reflect.Uint16,
  		reflect.Uint32, reflect.Uint64, reflect.Uintptr:
  		return strconv.FormatUint(v.Uint(), 10)
  	// ...floating-point and complex cases omitted for brevity...
  	case reflect.Bool:
  		return strconv.FormatBool(v.Bool())
  	case reflect.String:
  		return strconv.Quote(v.String())
  	case reflect.Chan, reflect.Func, reflect.Ptr, reflect.Slice, reflect.Map:
  		return v.Type().String() + " 0x" +
  			strconv.FormatUint(uint64(v.Pointer()), 16)
  	default: // reflect.Array, reflect.Struct, reflect.Interface
  		return v.Type().String() + " value"
  	}
  }
  

• 到目前为止，我们的函数将每个值视作一个不可分割没有内部结构的物品，因此它叫 formatAtom。对于聚合类型（结构体和数组）和接口，只是打印值的类型，对于引用类型（channels、functions、pointers、slices 和 maps），打印类型和十六进制的引用地址。虽然还不够理想，但是依然是一个重大的进步，并且 Kind 只关心底层表示，format.Any 也支持具名类型。例如：

  var x int64 = 1
  var d time.Duration = 1 * time.Nanosecond
  fmt.Println(format.Any(x))                  // "1"
  fmt.Println(format.Any(d))                  // "1"
  fmt.Println(format.Any([]int64{x}))         // "[]int64 0x8202b87b0"
  fmt.Println(format.Any([]time.Duration{d})) // "[]time.Duration 0x8202b87e0"