[ { "path": ".gitignore", "content": "# Compiled Object files, Static and Dynamic libs (Shared Objects)\n*.o\n*.a\n*.so\n\n# Folders\n_obj\n_test\n\n# Architecture specific extensions/prefixes\n*.[568vq]\n[568vq].out\n\n*.cgo1.go\n*.cgo2.c\n_cgo_defun.c\n_cgo_gotypes.go\n_cgo_export.*\n\n_testmain.go\n\n*.exe\n.DS_Store\n" }, { "path": "README.md", "content": "# 《Go语言标准库》The Golang Standard Library by Example #\r\n\r\nGolang标准库。对于程序员而言，标准库与语言本身同样重要，它好比一个百宝箱，能为各种常见的任务提供完美的解决方案。以示例驱动的方式讲解Golang的标准库。\r\n\r\n标准库基于最新版本Go。注：目前 Go 标准库文档并没有标识某个 API 基于哪个版本的 Go，将来会加上这部分 [issue](https://github.com/golang/go/issues/5778)。\r\n\r\n讲解中涉及到特定操作系统时，针对的都是 Linux/amd64。Go 中相关系统调用在 Linux 下，对于同一个系统调用，如果有对应的 `at` 版本，使用的都是 `at` 版本，如 `open` 系统调用使用都是 `openat`。更多信息参考 [Go语言中文网博客中关于系统调用的文章](http://blog.studygolang.com)。\r\n\r\n## 交流 ##\r\n\r\n欢迎大家加入QQ群：192706294 《Go语言实现与标准库》交流群\r\n\r\nGo语言构建的 Go语言中文网：[http://studygolang.com](http://studygolang.com)\r\n\r\n关注作者公众号，加微信好友、进微信交流群。\r\n\r\n![](polarisxu-qrcode-small.jpg)\r\n\r\n## 阅读 ##\r\n\r\n为了更方便阅读，Go语言中文网搭建了阅读平台，可以更友好的在线阅读。\r\n\r\n[Go语言中文网——Go语言标准库](http://books.studygolang.com/The-Golang-Standard-Library-by-Example)\r\n\r\n## 捐赠 ##\r\n\r\n如果您觉得本书对您有帮助，通过微信或支付宝捐赠作者，金额随意！\r\n\r\n**由于无法从支付方获取支付者信息，请在支付的留言备注功能中附上 Go语言中文网账户的昵称等信息，以便我们记录！**\r\n\r\n## 目录 ##\r\n[目录](directory.md)\r\n## 贡献者 ##\r\n\r\n[hikerell](https://github.com/hikerell)\r\n\r\n## 反馈 ##\r\n\r\n由于本人能力有限，书中难免有写的不对之处，且目前所写内容没有经过校正。如果阅读过程中有任何疑问或觉得不对之处，欢迎提出，谢谢！\r\n\r\n## 版权声明 ##\r\n\r\n本书所有内容遵循 [CC-BY-SA 3.0协议（署名-相同方式共享）](http://zh.wikipedia.org/wiki/Wikipedia:CC-by-sa-3.0%E5%8D%8F%E8%AE%AE%E6%96%87%E6%9C%AC)\r\n\r\n1. 常见误解\r\n\r\n2. 常用手法\r\n\r\n3. 如何理解，使用\r\n\r\n4. 为什么接口如此组织\r\n\r\n5. 和其它语言对比优缺点\r\n" }, { "path": "SUMMARY.md", "content": "* [简介](README.md)\n* [第一章 输入输出 (Input/Output)](chapter01/01.0.md)\n - 1.1 [io — 基本的 IO 接口](chapter01/01.1.md)\n - 1.2 [ioutil — 方便的 IO 操作函数集](chapter01/01.2.md)\n - 1.3 [fmt — 格式化 IO](chapter01/01.3.md)\n - 1.4 [bufio — 缓存 IO](chapter01/01.4.md)\n* [第二章 文本](chapter02/02.0.md)\n - 2.1 [strings — 字符串操作](chapter02/02.1.md)\n - 2.2 [bytes — byte slice 便利操作](chapter02/02.2.md)\n - 2.3 [strconv — 字符串和基本数据类型之间转换](chapter02/02.3.md)\n - 2.4 [regexp — 正则表达式](chapter02/02.4.md)\n - 2.5 [unicode — Unicode 码点、UTF-8/16 编码](chapter02/02.5.md)\n* [第三章 数据结构与算法](chapter03/03.0.md)\n - 3.1 [sort — 排序算法](chapter03/03.1.md)\n - 3.2 index/suffixarray — 后缀数组实现子字符串查询\n - 3.3 [container — 容器数据类型：heap、list 和 ring](chapter03/03.3.md)\n* [第四章 日期与时间](chapter04/04.0.md)\n - 4.1 [主要类型概述](chapter04/04.1.md)\n - 4.2 [时区](chapter04/04.2.md)\n - 4.3 [Time类型详解](chapter04/04.3.md)\n - 4.4 [定时器](chapter04/04.4.md)\n* 第五章 数学计算\n - 5.1 [math — 基本数学函数](chapter05/05.1.md)\n - 5.2 math/big — 大数实现\n - 5.3 math/cmplx — 复数基本函数操作\n - 5.4 math/rand — 伪随机数生成器\n* [第六章 文件系统](chapter06/06.0.md)\n - 6.1 [os — 平台无关的操作系统功能实现](chapter06/06.1.md)\n - 6.2 [path/filepath — 操作路径](chapter06/06.2.md)\n - 6.3 [io/fs - 抽象文件系统](chapter06/06.3.md)\n* [第七章 数据持久存储与交换](chapter07/07.0.md)\n - 7.1 [database/sql — SQL/SQL-Like 数据库操作接口](chapter07/07.1.md)\n - 7.2 encoding/json — json 解析\n - 7.3 encoding/xml — xml 解析\n - 7.4 encoding/gob — golang 自定义二进制格式\n - 7.5 encoding/csv — 逗号分隔值文件\n* [第八章 数据压缩与归档](chapter08/08.0.md)\n - 8.1 [flate - DEFLATE 压缩算法](chapter08/08.1.md)\n - 8.2 compress/zlib — gnu zlib 压缩\n - 8.3 compress/gzip — 读写 gnu zip 文件\n - 8.4 compress/bzip2 — bzip2 压缩\n - 8.5 archive/tar — tar 档案读写\n - 8.6 archive/zip — zip 归档访问\n* [第九章 测试](chapter09/09.0.md)\n - 9.1 [testing - 单元测试](chapter09/09.1.md)\n - 9.2 [testing - 基准测试](chapter09/09.2.md)\n - 9.3 [testing - 子测试与子基准测试](chapter09/09.3.md)\n - 9.4 [testing - 运行并验证示例](chapter09/09.4.md)\n - 9.5 [testing - 其他功能](chapter09/09.5.md)\n - 9.6 [httptest - HTTP 测试辅助工具](chapter09/09.6.md)\n - 9.7 [总结](chapter09/09.7.md)\n* [第十章 进程、线程与 goroutine](chapter10/10.0.md)\n - 10.1 [创建进程](chapter10/10.1.md)\n - 10.2 [进程属性和控制](chapter10/10.2.md)\n - 10.3 [线程](chapter10/10.3.md)\n - 10.4 [进程间通信](chapter10/10.4.md)\n* 第十一章 网络通信与互联网 (Internet)\n* 第十二章 email\n* [第十三章 应用构建 与 debug](chapter13/13.0.md)\n - 13.1 [flag - 命令行参数解析](chapter13/13.1.md)\n - 13.2 [log - 日志记录](chapter13/13.2.md)\n - 13.3 [expvar - 公共变量的标准化接口](chapter13/13.3.md)\n - 13.4 [runtime/debug - 运行时的调试工具](chapter13/13.4.md)\n* 第十四章 运行时特性\n* 第十五章 底层库介绍\n - 15.1 builtin\n - 15.2 [unsafe — 非类型安全操作](chapter15/15.02.md)\n* 第十六章 同步\n - 16.1 [sync - 处理同步需求](chapter16/16.01.md)\n - 16.2 [sync/atomic - 原子操作](chapter16/16.02.md)\n - 16.3 [os/signal - 信号](chapter16/16.03.md)\n* 第十七章 加解密\n" }, { "path": "book.json", "content": "{\n \"title\": \"Go语言标准库\",\n \"description\": \"通过例子学习标准库\",\n \"author\": \"徐新华\",\n \"language\": \"zh-hans\",\n \"root\": \".\",\n \"links\": {\n \"sidebar\": {\n \"Go语言中文网\": \"http://studygolang.com\"\n }\n },\n \"plugins\": [\n \"-lunr\",\n \"-search\",\n \"-livereload\",\n \"highlight\",\n \"search-plus@^0.0.11\",\n \"simple-page-toc@^0.1.1\",\n \"github@^2.0.0\",\n \"github-buttons@2.1.0\",\n \"edit-link@^2.0.2\",\n \"disqus@^0.1.0\",\n \"anchors@^0.7.1\",\n \"include-codeblock@^3.0.2\",\n \"emphasize@^1.1.0\",\n \"mermaid@^0.0.9\",\n \"tbfed-pagefooter@^0.0.1\",\n \"expandable-chapters-small@^0.1.7\",\n \"sectionx@^3.1.0\",\n \"donate@^1.0.2\",\n \"sitemap-general\",\n \"anchor-navigation-ex\",\n \"favicon@^0.0.2\",\n \"todo@^0.1.3\",\n \"ba\",\n\t\t\"pageview-count\",\n\t\t\"qrcode-list\"\n ],\n \"pluginsConfig\": {\n \"theme-default\": {\n \"showLevel\": false\n },\n \"ba\": {\n \"token\": \"224c227cd9239761ec770bc8c1fb134c\"\n },\n \"disqus\": {\n \"shortName\": \"Go语言中文网\"\n },\n \"github\": {\n \"url\": \"https://github.com/polaris1119/The-Golang-Standard-Library-by-Example\"\n },\n \"github-buttons\": {\n \"repo\": \"polaris1119/The-Golang-Standard-Library-by-Example\",\n \"types\": [\n \"star\"\n ],\n \"size\": \"small\"\n },\n \"include-codeblock\": {\n \"template\": \"ace\",\n \"unindent\": true,\n \"edit\": true\n },\n \"sharing\": {\n \"weibo\": true,\n \"facebook\": true,\n \"twitter\": true,\n \"google\": false,\n \"instapaper\": false,\n \"vk\": false,\n \"all\": [\n \"facebook\",\n \"google\",\n \"twitter\",\n \"weibo\",\n \"instapaper\"\n ]\n },\n \"tbfed-pagefooter\": {\n \"copyright\": \"Copyright © studygolang.com 2013\",\n \"modify_label\": \"该文件修订时间：\",\n \"modify_format\": \"YYYY-MM-DD HH:mm:ss\"\n },\n \"donate\": {\n \"wechat\": \"https://static.studygolang.com/img/wxpay.png\",\n \"alipay\": \"https://static.studygolang.com/170605/9d11b43988fbbb42a5da9f970a0f6818.png\",\n \"title\": \"\",\n \"button\": \"赏\",\n \"alipayText\": \"支付宝打赏\",\n \"wechatText\": \"微信打赏\"\n },\n \"simple-page-toc\": {\n \"maxDepth\": 3,\n \"skipFirstH1\": true\n },\n \"edit-link\": {\n \"base\": \"https://github.com/polaris1119/The-Golang-Standard-Library-by-Example/edit/master\",\n \"label\": \"编辑该页面\"\n },\n \"sitemap-general\": {\n \"prefix\": \"https://books.studygolang.com\"\n },\n \"anchor-navigation-ex\": {\n \"isRewritePageTitle\": false,\n \"tocLevel1Icon\": \"fa fa-hand-o-right\",\n \"tocLevel2Icon\": \"fa fa-hand-o-right\",\n \"tocLevel3Icon\": \"fa fa-hand-o-right\"\n },\n \"sectionx\": {\n \"tag\": \"b\"\n },\n \"favicon\": {\n \"shortcut\": \"favicon.ico\",\n \"bookmark\": \"favicon.ico\"\n },\n\t\t\"qrcode-list\": {\n\t\t \"title\": \"交流学习\",\n\t\t \"description\": \"如果有疑问或想和我交流，欢迎扫码下方二维码\",\n\t\t \"except\": [ ],\n\t\t \"lists\": [\n\t\t\t{\n\t\t\t \"src\": \"https://static.studygolang.com/static/img/polarisxu-qrcode-m.jpg\",\n\t\t\t \"content\": \"polarisxu\",\n\t\t\t \"alt\": \"polarisxu\"\n\t\t\t},\n\t\t\t{\n\t\t\t \"src\": \"https://static.studygolang.com/static/img/gopherstudio2.png\",\n\t\t\t \"content\": \"gopherstudio\",\n\t\t\t \"alt\": \"gopherstudio\"\n\t\t\t}\n\t\t ]\n\t\t}\n }\n}\n" }, { "path": "chapter01/01.0.md", "content": "# 第一章 输入输出 (Input/Output) #\n\n一般的，计算机程序是：输入 (Input) 经过算法处理产生输出 (Output)。各种语言一般都会提供IO库供开发者使用。Go语言也不例外。\n\nGo 语言中，为了方便开发者使用，将 IO 操作封装在了如下几个包中：\n\n- [io](http://docs.studygolang.com/pkg/io/) 为 IO 原语（I/O primitives）提供基本的接口\n- [io/ioutil](http://docs.studygolang.com/pkg/io/ioutil/) 封装一些实用的 I/O 函数\n- [fmt](http://docs.studygolang.com/pkg/fmt/) 实现格式化 I/O，类似 C 语言中的 printf 和 scanf\n- [bufio](http://docs.studygolang.com/pkg/bufio/) 实现带缓冲I/O\n\n本章会详细介绍这些 IO 包提供的函数、类型和方法，同时通过实例讲解这些包的使用方法。\n\n# 导航 #\n\n- [简介](/README.md)\n- 下一节：[io — 基本的 IO 接口](01.1.md)\n" }, { "path": "chapter01/01.1.md", "content": "# 1.1 io — 基本的 IO 接口 #\n\nio 包为 I/O 原语提供了基本的接口。它主要包装了这些原语的已有实现。\n\n由于这些被接口包装的I/O原语是由不同的低级操作实现，因此，在另有声明之前不该假定它们的并发执行是安全的。\n\n在 io 包中最重要的是两个接口：Reader 和 Writer 接口。本章所提到的各种 IO 包，都跟这两个接口有关，也就是说，只要满足这两个接口，它就可以使用 IO 包的功能。\n\n## Reader 接口 ##\n\nReader 接口的定义如下：\n\n```go\ntype Reader interface {\n Read(p []byte) (n int, err error)\n}\n```\n\n官方文档中关于该接口方法的说明：\n\n> Read 将 len(p) 个字节读取到 p 中。它返回读取的字节数 n（0 <= n <= len(p)） 以及任何遇到的错误。即使 Read 返回的 n < len(p)，它也会在调用过程中占用 len(p) 个字节作为暂存空间。若可读取的数据不到 len(p) 个字节，Read 会返回可用数据，而不是等待更多数据。\n\n> 当 Read 在成功读取 n > 0 个字节后遇到一个错误或 EOF (end-of-file)，它会返回读取的字节数。它可能会同时在本次的调用中返回一个non-nil错误,或在下一次的调用中返回这个错误（且 n 为 0）。 一般情况下, Reader会返回一个非0字节数n, 若 n = len(p) 个字节从输入源的结尾处由 Read 返回，Read可能返回 err == EOF 或者 err == nil。并且之后的 Read() 都应该返回 (n:0, err:EOF)。\n\n> 调用者在考虑错误之前应当首先处理返回的数据。这样做可以正确地处理在读取一些字节后产生的 I/O 错误，同时允许EOF的出现。\n\n根据 Go 语言中关于接口和满足了接口的类型的定义（[Interface_types](http://golang.org/ref/spec#Interface_types)），我们知道 Reader 接口的方法集（[Method_sets](http://golang.org/ref/spec#Method_sets)）只包含一个 Read 方法，因此，所有实现了 Read 方法的类型都满足 io.Reader 接口，也就是说，在所有需要 io.Reader 的地方，可以传递实现了 Read() 方法的类型的实例。\n\n下面，我们通过具体例子来谈谈该接口的用法。\n\n```go\nfunc ReadFrom(reader io.Reader, num int) ([]byte, error) {\n\tp := make([]byte, num)\n\tn, err := reader.Read(p)\n\tif n > 0 {\n\t\treturn p[:n], nil\n\t}\n\treturn p, err\n}\n```\n\nReadFrom 函数将 io.Reader 作为参数，也就是说，ReadFrom 可以从任意的地方读取数据，只要来源实现了 io.Reader 接口。比如，我们可以从标准输入、文件、字符串等读取数据，示例代码如下：\n\n```go\n// 从标准输入读取\ndata, err = ReadFrom(os.Stdin, 11)\n\n// 从普通文件读取，其中 file 是 os.File 的实例\ndata, err = ReadFrom(file, 9)\n\n// 从字符串读取\ndata, err = ReadFrom(strings.NewReader(\"from string\"), 12)\n```\n\n完整的演示例子源码见 [code/src/chapter01/io/reader.go](/code/src/chapter01/io/reader.go)\n\n**小贴士**\n\nio.EOF 变量的定义：`var EOF = errors.New(\"EOF\")`，是 error 类型。根据 reader 接口的说明，在 n > 0 且数据被读完了的情况下，返回的 error 有可能是 EOF 也有可能是 nil。\n\n## Writer 接口 ##\n\nWriter 接口的定义如下：\n\n```go\ntype Writer interface {\n Write(p []byte) (n int, err error)\n}\n```\n\n官方文档中关于该接口方法的说明：\n\n> Write 将 len(p) 个字节从 p 中写入到基本数据流中。它返回从 p 中被写入的字节数 n（0 <= n <= len(p)）以及任何遇到的引起写入提前停止的错误。若 Write 返回的 n < len(p)，它就必须返回一个 非nil 的错误。\n\n同样的，所有实现了Write方法的类型都实现了 io.Writer 接口。\n\n在上个例子中，我们是自己实现一个函数接收一个 io.Reader 类型的参数。这里，我们通过标准库的例子来学习。\n\n在fmt标准库中，有一组函数：Fprint/Fprintf/Fprintln，它们接收一个 io.Wrtier 类型参数（第一个参数），也就是说它们将数据格式化输出到 io.Writer 中。那么，调用这组函数时，该如何传递这个参数呢？\n\n我们以 fmt.Fprintln 为例，同时看一下 fmt.Println 函数的源码。\n\n```go\nfunc Println(a ...interface{}) (n int, err error) {\n\treturn Fprintln(os.Stdout, a...)\n}\n```\n\n很显然，fmt.Println会将内容输出到标准输出中。下一节我们将详细介绍fmt包。\n\n关于 io.Writer 的更多说明，可以查看笔者之前写的博文[《以io.Writer为例看go中的interface{}》](http://blog.studygolang.com/2013/02/%e4%bb%a5io-writer%e4%b8%ba%e4%be%8b%e7%9c%8bgo%e4%b8%ad%e7%9a%84interface/)。\n\n## 实现了 io.Reader 接口或 io.Writer 接口的类型 ##\n\n初学者看到函数参数是一个接口类型，很多时候有些束手无策，不知道该怎么传递参数。还有人问：标准库中有哪些类型实现了 io.Reader 或 io.Writer 接口？\n\n通过本节上面的例子，我们可以知道，os.File 同时实现了这两个接口。我们还看到 os.Stdin/Stdout 这样的代码，它们似乎分别实现了 io.Reader/io.Writer 接口。没错，实际上在 os 包中有这样的代码：\n\n```go\nvar (\n Stdin = NewFile(uintptr(syscall.Stdin), \"/dev/stdin\")\n Stdout = NewFile(uintptr(syscall.Stdout), \"/dev/stdout\")\n Stderr = NewFile(uintptr(syscall.Stderr), \"/dev/stderr\")\n)\n```\n\n也就是说，Stdin/Stdout/Stderr 只是三个特殊的文件类型的标识（即都是 os.File 的实例），自然也实现了 io.Reader 和 io.Writer。\n\n目前，Go 文档中还没有直接列出实现了某个接口的所有类型。不过，我们可以通过查看标准库文档，列出实现了 io.Reader 或 io.Writer 接口的类型（导出的类型）：（注：godoc 命令支持额外参数 -analysis ，能列出都有哪些类型实现了某个接口，相关参考 `godoc -h` 或 [Static analysis features of godoc](https://golang.org/lib/godoc/analysis/help.html)。另外，我做了一个官网镜像，能查看接口所有的实现类型，地址：http://docs.studygolang.com。\n\n- os.File 同时实现了 io.Reader 和 io.Writer\n- strings.Reader 实现了 io.Reader\n- bufio.Reader/Writer 分别实现了 io.Reader 和 io.Writer\n- bytes.Buffer 同时实现了 io.Reader 和 io.Writer\n- bytes.Reader 实现了 io.Reader\n- compress/gzip.Reader/Writer 分别实现了 io.Reader 和 io.Writer\n- crypto/cipher.StreamReader/StreamWriter 分别实现了 io.Reader 和 io.Writer\n- crypto/tls.Conn 同时实现了 io.Reader 和 io.Writer\n- encoding/csv.Reader/Writer 分别实现了 io.Reader 和 io.Writer\n- mime/multipart.Part 实现了 io.Reader\n- net/conn 分别实现了 io.Reader 和 io.Writer(Conn接口定义了Read/Write)\n\n除此之外，io 包本身也有这两个接口的实现类型。如：\n\n\t实现了 Reader 的类型：LimitedReader、PipeReader、SectionReader\n\t实现了 Writer 的类型：PipeWriter\n\n以上类型中，常用的类型有：os.File、strings.Reader、bufio.Reader/Writer、bytes.Buffer、bytes.Reader\n\n**小贴士**\n\n从接口名称很容易猜到，一般地， Go 中接口的命名约定：接口名以 er 结尾。注意，这里并非强行要求，你完全可以不以 er 结尾。标准库中有些接口也不是以 er 结尾的。\n\n## ReaderAt 和 WriterAt 接口 ##\n\n**ReaderAt 接口**的定义如下：\n\n```go\ntype ReaderAt interface {\n ReadAt(p []byte, off int64) (n int, err error)\n}\n```\n\n官方文档中关于该接口方法的说明：\n\n> ReadAt 从基本输入源的偏移量 off 处开始，将 len(p) 个字节读取到 p 中。它返回读取的字节数 n（0 <= n <= len(p)）以及任何遇到的错误。\n\n> 当 ReadAt 返回的 n < len(p) 时，它就会返回一个 非nil 的错误来解释 为什么没有返回更多的字节。在这一点上，ReadAt 比 Read 更严格。\n\n> 即使 ReadAt 返回的 n < len(p)，它也会在调用过程中使用 p 的全部作为暂存空间。若可读取的数据不到 len(p) 字节，ReadAt 就会阻塞,直到所有数据都可用或一个错误发生。 在这一点上 ReadAt 不同于 Read。\n\n> 若 n = len(p) 个字节从输入源的结尾处由 ReadAt 返回，Read可能返回 err == EOF 或者 err == nil\n\n> 若 ReadAt 携带一个偏移量从输入源读取，ReadAt 应当既不影响偏移量也不被它所影响。\n\n> 可对相同的输入源并行执行 ReadAt 调用。\n\n可见，ReaderAt 接口使得可以从指定偏移量处开始读取数据。\n\n简单示例代码如下：\n\n```go\nreader := strings.NewReader(\"Go语言中文网\")\np := make([]byte, 6)\nn, err := reader.ReadAt(p, 2)\nif err != nil {\n panic(err)\n}\nfmt.Printf(\"%s, %d\\n\", p, n)\n```\n\n输出：\n\n\t语言, 6\n\n**WriterAt 接口**的定义如下：\n\n```go\ntype WriterAt interface {\n WriteAt(p []byte, off int64) (n int, err error)\n}\n```\n\n官方文档中关于该接口方法的说明：\n\n> WriteAt 从 p 中将 len(p) 个字节写入到偏移量 off 处的基本数据流中。它返回从 p 中被写入的字节数 n（0 <= n <= len(p)）以及任何遇到的引起写入提前停止的错误。若 WriteAt 返回的 n < len(p)，它就必须返回一个 非nil 的错误。\n\n> 若 WriteAt 携带一个偏移量写入到目标中，WriteAt 应当既不影响偏移量也不被它所影响。\n\n> 若被写区域没有重叠，可对相同的目标并行执行 WriteAt 调用。\n\n我们可以通过该接口将数据写入到数据流的特定偏移量之后。\n\n通过简单示例来演示 WriteAt 方法的使用（os.File 实现了 WriterAt 接口）：\n\n```go\nfile, err := os.Create(\"writeAt.txt\")\nif err != nil {\n panic(err)\n}\ndefer file.Close()\nfile.WriteString(\"Golang中文社区——这里是多余\")\nn, err := file.WriteAt([]byte(\"Go语言中文网\"), 24)\nif err != nil {\n panic(err)\n}\nfmt.Println(n)\n```\n\n打开文件 WriteAt.txt，内容是：`Golang中文社区——Go语言中文网`。\n\n分析：\n\n`file.WriteString(\"Golang中文社区——这里是多余\")` 往文件中写入 `Golang中文社区——这里是多余`，之后 `file.WriteAt([]byte(\"Go语言中文网\"), 24)` 在文件流的 offset=24 处写入 `Go语言中文网`（会覆盖该位置的内容）。\n\n## ReaderFrom 和 WriterTo 接口 ##\n\n**ReaderFrom** 的定义如下：\n\n```go\ntype ReaderFrom interface {\n ReadFrom(r Reader) (n int64, err error)\n}\n```\n\n官方文档中关于该接口方法的说明：\n\n> ReadFrom 从 r 中读取数据，直到 EOF 或发生错误。其返回值 n 为读取的字节数。除 io.EOF 之外，在读取过程中遇到的任何错误也将被返回。\n\n> 如果 ReaderFrom 可用，Copy 函数就会使用它。\n\n注意：ReadFrom 方法不会返回 err == EOF。\n\n下面的例子简单的实现将文件中的数据全部读取（显示在标准输出）：\n\n```go\nfile, err := os.Open(\"writeAt.txt\")\nif err != nil {\n panic(err)\n}\ndefer file.Close()\nwriter := bufio.NewWriter(os.Stdout)\nwriter.ReadFrom(file)\nwriter.Flush()\n```\n\n当然，我们可以通过 ioutil 包的 ReadFile 函数获取文件全部内容。其实，跟踪一下 ioutil.ReadFile 的源码，会发现其实也是通过 ReadFrom 方法实现（用的是 bytes.Buffer，它实现了 ReaderFrom 接口）。\n\n如果不通过 ReadFrom 接口来做这件事，而是使用 io.Reader 接口，我们有两种思路：\n\n1. 先获取文件的大小（File 的 Stat 方法），之后定义一个该大小的 []byte，通过 Read 一次性读取\n2. 定义一个小的 []byte，不断的调用 Read 方法直到遇到 EOF，将所有读取到的 []byte 连接到一起\n\n这里不给出实现代码了，有兴趣的可以实现一下。\n\n**提示**\n\n通过查看 bufio.Writer 或 strings.Buffer 类型的 ReadFrom 方法实现，会发现，其实它们的实现和上面说的第 2 种思路类似。\n\n**WriterTo**的定义如下：\n\n```go\ntype WriterTo interface {\n WriteTo(w Writer) (n int64, err error)\n}\n```\n\n官方文档中关于该接口方法的说明：\n\n> WriteTo 将数据写入 w 中，直到没有数据可写或发生错误。其返回值 n 为写入的字节数。 在写入过程中遇到的任何错误也将被返回。\n\n> 如果 WriterTo 可用，Copy 函数就会使用它。\n\n读者是否发现，其实 ReaderFrom 和 WriterTo 接口的方法接收的参数是 io.Reader 和 io.Writer 类型。根据 io.Reader 和 io.Writer 接口的讲解，对该接口的使用应该可以很好的掌握。\n\n这里只提供简单的一个示例代码：将一段文本输出到标准输出\n\n```go\nreader := bytes.NewReader([]byte(\"Go语言中文网\"))\nreader.WriteTo(os.Stdout)\n```\n\n通过 io.ReaderFrom 和 io.WriterTo 的学习，我们知道，如果这样的需求，可以考虑使用这两个接口：“一次性从某个地方读或写到某个地方去。”\n\n## Seeker 接口 ##\n\n接口定义如下：\n\n```go\ntype Seeker interface {\n Seek(offset int64, whence int) (ret int64, err error)\n}\n```\n\n官方文档中关于该接口方法的说明：\n\n> Seek 设置下一次 Read 或 Write 的偏移量为 offset，它的解释取决于 whence： 0 表示相对于文件的起始处，1 表示相对于当前的偏移，而 2 表示相对于其结尾处。 Seek 返回新的偏移量和一个错误，如果有的话。\n\n也就是说，Seek 方法是用于设置偏移量的，这样可以从某个特定位置开始操作数据流。听起来和 ReaderAt/WriteAt 接口有些类似，不过 Seeker 接口更灵活，可以更好的控制读写数据流的位置。\n\n简单的示例代码：获取倒数第二个字符（需要考虑 UTF-8 编码，这里的代码只是一个示例）\n\n```go\nreader := strings.NewReader(\"Go语言中文网\")\nreader.Seek(-6, io.SeekEnd)\nr, _, _ := reader.ReadRune()\nfmt.Printf(\"%c\\n\", r)\n```\n\n**小贴士**\n\nwhence 的值，在 io 包中定义了相应的常量，应该使用这些常量\n\n```go\nconst (\n SeekStart = 0 // seek relative to the origin of the file\n SeekCurrent = 1 // seek relative to the current offset\n SeekEnd = 2 // seek relative to the end\n)\n```\n\n而原先 os 包中的常量已经被标注为Deprecated\n\n```go\n// Deprecated: Use io.SeekStart, io.SeekCurrent, and io.SeekEnd.\nconst (\n SEEK_SET int = 0 // seek relative to the origin of the file\n SEEK_CUR int = 1 // seek relative to the current offset\n SEEK_END int = 2 // seek relative to the end\n)\n```\n\n## Closer接口 ##\n\n接口定义如下：\n\n```go\ntype Closer interface {\n Close() error\n}\n```\n\n该接口比较简单，只有一个 Close() 方法，用于关闭数据流。\n\n文件 (os.File)、归档（压缩包）、数据库连接、Socket 等需要手动关闭的资源都实现了 Closer 接口。\n\n实际编程中，经常将 Close 方法的调用放在 defer 语句中。\n\n**小提示**\n\n初学者容易写出这样的代码：\n\n```go\nfile, err := os.Open(\"studygolang.txt\")\ndefer file.Close()\nif err != nil {\n\t...\n}\n```\n\n当文件 studygolang.txt 不存在或找不到时，file.Close() 会 panic，因为 file 是 nil。因此，应该将 defer file.Close() 放在错误检查之后。\n\n经过 [issue40](https://github.com/polaris1119/The-Golang-Standard-Library-by-Example/issues/40) 提醒，查看源码：\n\n```go\nfunc (f *File) Close() error {\n\tif f == nil {\n\t\treturn ErrInvalid\n\t}\n\treturn f.file.close()\n}\n```\n可见并不会 panic，但在 Close 之前校验错误是个好习惯！\n\n## 其他接口 ##\n\n### ByteReader 和 ByteWriter ###\n\n通过名称大概也能猜出这组接口的用途：读或写一个字节。接口定义如下：\n\n```go\ntype ByteReader interface {\n ReadByte() (c byte, err error)\n}\n\ntype ByteWriter interface {\n WriteByte(c byte) error\n}\n```\n\n在标准库中，有如下类型实现了 io.ByteReader 或 io.ByteWriter:\n\n- bufio.Reader/Writer 分别实现了io.ByteReader 和 io.ByteWriter\n- bytes.Buffer 同时实现了 io.ByteReader 和 io.ByteWriter\n- bytes.Reader 实现了 io.ByteReader\n- strings.Reader 实现了 io.ByteReader\n\n接下来的示例中，我们通过 bytes.Buffer 来一次读取或写入一个字节（主要代码）：\n\n```go\nvar ch byte\nfmt.Scanf(\"%c\\n\", &ch)\n\nbuffer := new(bytes.Buffer)\nerr := buffer.WriteByte(ch)\nif err == nil {\n\tfmt.Println(\"写入一个字节成功！准备读取该字节……\")\n\tnewCh, _ := buffer.ReadByte()\n\tfmt.Printf(\"读取的字节：%c\\n\", newCh)\n} else {\n\tfmt.Println(\"写入错误\")\n}\n```\n\n程序从标准输入接收一个字节（ASCII 字符），调用 buffer 的 WriteByte 将该字节写入 buffer 中，之后通过 ReadByte 读取该字节。完整的代码见：[code/src/chapter01/io/byterwer.go](/code/src/chapter01/io/byterwer.go)\n\n一般地，我们不会使用 bytes.Buffer 来一次读取或写入一个字节。那么，这两个接口有哪些用处呢？\n\n在标准库 encoding/binary 中，实现[Google-ProtoBuf](https://code.google.com/p/protobuf/)中的 Varints 读取，[ReadVarint](http://docs.studygolang.com/pkg/encoding/binary/#ReadVarint) 就需要一个 io.ByteReader 类型的参数，也就是说，它需要一个字节一个字节的读取。关于 encoding/binary 包在后面会详细介绍。\n\n在标准库 image/jpeg 中，[Encode](http://docs.studygolang.com/pkg/image/jpeg/#Encode)函数的内部实现使用了 ByteWriter 写入一个字节。\n\n**小贴士**\n\n可以通过在 Go 语言源码 src/pkg 中搜索 \"io.ByteReader\" 或 \"io.ByteWiter\"，获得哪些地方用到了这两个接口。你会发现，这两个接口在二进制数据或归档压缩时用的比较多。\n\n### ByteScanner、RuneReader 和 RuneScanner ###\n\n将这三个接口放在一起，是考虑到与 ByteReader 相关或相应。\n\nByteScanner 接口的定义如下：\n\n```go\ntype ByteScanner interface {\n ByteReader\n UnreadByte() error\n}\n```\n\n可见，它内嵌了 ByteReader 接口（可以理解为继承了 ByteReader 接口），UnreadByte 方法的意思是：将上一次 ReadByte 的字节还原，使得再次调用 ReadByte 返回的结果和上一次调用相同，也就是说，UnreadByte 是重置上一次的 ReadByte。注意，UnreadByte 调用之前必须调用了 ReadByte，且不能连续调用 UnreadByte。即：\n\n```go\nbuffer := bytes.NewBuffer([]byte{'a', 'b'})\nerr := buffer.UnreadByte()\n```\n\n和\n\n```go\nbuffer := bytes.NewBuffer([]byte{'a', 'b'})\nbuffer.ReadByte()\nerr := buffer.UnreadByte()\nerr = buffer.UnreadByte()\n```\n\nerr 都 非nil，错误为：`bytes.Buffer: UnreadByte: previous operation was not a read`\n\nRuneReader 接口和 ByteReader 类似，只是 ReadRune 方法读取单个 UTF-8 字符，返回其 rune 和该字符占用的字节数。该接口在 [regexp](http://docs.studygolang.com/pkg/regexp) 包有用到。\n\n之前有人在QQ群中问道：\n\n> strings.Index(\"行业交流群\", \"交流\") 返回的是单字节字符的位置：6。但是想要的是 unicode 字符的位置：2。\n\n这里借助utf8的RuneCountInString函数,实现代码如下：\n\n```go\n// strings.Index 的 UTF-8 版本\n// 即 Utf8Index(\"Go语言中文网\", \"中文\") 返回 4，而不是 strings.Index 的 8\nfunc Utf8Index(str, substr string) int {\n\tindex := strings.Index(str, substr)\n\tif index < 0{\n\t\treturn -1\n\t}\n\treturn utf8.RuneCountInString(str[:index])\n}\n```\n\nRuneScanner 接口和 ByteScanner 类似，就不赘述了。\n\n### ReadCloser、ReadSeeker、ReadWriteCloser、ReadWriteSeeker、ReadWriter、WriteCloser 和 WriteSeeker 接口 ###\n\n这些接口是上面介绍的接口的两个或三个组合而成的新接口。例如 ReadWriter 接口：\n\n```go\ntype ReadWriter interface {\n Reader\n Writer\n}\n```\n\n这是 Reader 接口和 Writer 接口的简单组合（内嵌）。\n\n这些接口的作用是：有些时候同时需要某两个接口的所有功能，即必须同时实现了某两个接口的类型才能够被传入使用。可见，io 包中有大量的“小接口”，这样方便组合为“大接口”。\n\n## SectionReader 类型 ##\n\nSectionReader 是一个 struct（没有任何导出的字段），实现了 Read, Seek 和 ReadAt，同时，内嵌了 ReaderAt 接口。结构定义如下：\n\n```go\ntype SectionReader struct {\n\tr ReaderAt\t// 该类型最终的 Read/ReadAt 最终都是通过 r 的 ReadAt 实现\n\tbase int64\t\t// NewSectionReader 会将 base 设置为 off\n\toff int64\t\t// 从 r 中的 off 偏移处开始读取数据\n\tlimit int64\t\t// limit - off = SectionReader 流的长度\n}\n```\n\n从名称我们可以猜到，该类型读取数据流中部分数据。看一下\n\n```go\nfunc NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader\n```\n\n的文档说明就知道了：\n\n> NewSectionReader 返回一个 SectionReader，它从 r 中的偏移量 off 处读取 n 个字节后以 EOF 停止。\n\n也就是说，SectionReader 只是内部（内嵌）ReaderAt 表示的数据流的一部分：从 off 开始后的 n 个字节。\n\n这个类型的作用是：方便重复操作某一段 (section) 数据流；或者同时需要 ReadAt 和 Seek 的功能。\n\n由于该类型所支持的操作，前面都有介绍，因此不提供示例代码了。\n\n关于该类型在标准库中的使用，我们在 [8.5 archive/zip — zip归档访问]() 会讲到。\n\n## LimitedReader 类型 ##\n\nLimitedReader 结构定义如下：\n\n```go\ntype LimitedReader struct {\n R Reader // underlying reader，最终的读取操作通过 R.Read 完成\n N int64 // max bytes remaining\n}\n```\n\n文档说明如下：\n\n> 从 R 读取但将返回的数据量限制为 N 字节。每调用一次 Read 都将更新 N 来反应新的剩余数量。\n\n也就是说，最多只能返回 N 字节数据。\n\nLimitedReader 只实现了 Read 方法（Reader 接口）。\n\n使用示例如下：\n\n```go\ncontent := \"This Is LimitReader Example\"\nreader := strings.NewReader(content)\nlimitReader := &io.LimitedReader{R: reader, N: 8}\nfor limitReader.N > 0 {\n\ttmp := make([]byte, 2)\n\tlimitReader.Read(tmp)\n\tfmt.Printf(\"%s\", tmp)\n}\n```\n\n输出：\n\n\tThis Is\n\n可见，通过该类型可以达到 *只允许读取一定长度数据* 的目的。\n\n在 io 包中，LimitReader 函数的实现其实就是调用 LimitedReader：\n\n```go\nfunc LimitReader(r Reader, n int64) Reader { return &LimitedReader{r, n} }\n```\n\n## PipeReader 和 PipeWriter 类型 ##\n\nPipeReader（一个没有任何导出字段的 struct）是管道的读取端。它实现了 io.Reader 和 io.Closer 接口。结构定义如下：\n```go\ntype PipeReader struct {\n\tp *pipe\n}\n```\n\n**关于 PipeReader.Read 方法的说明**：从管道中读取数据。该方法会堵塞，直到管道写入端开始写入数据或写入端被关闭。如果写入端关闭时带有 error（即调用 CloseWithError 关闭），该Read返回的 err 就是写入端传递的error；否则 err 为 EOF。\n\nPipeWriter（一个没有任何导出字段的 struct）是管道的写入端。它实现了 io.Writer 和 io.Closer 接口。结构定义如下：\n```go\ntype PipeWriter struct {\n\tp *pipe\n}\n```\n\n**关于 PipeWriter.Write 方法的说明**：写数据到管道中。该方法会堵塞，直到管道读取端读完所有数据或读取端被关闭。如果读取端关闭时带有 error（即调用 CloseWithError 关闭），该Write返回的 err 就是读取端传递的error；否则 err 为 ErrClosedPipe。\n\n使用示例如下：\n\n```go\nfunc main() {\n pipeReader, pipeWriter := io.Pipe()\n go PipeWrite(pipeWriter)\n go PipeRead(pipeReader)\n time.Sleep(30 * time.Second)\n}\n\nfunc PipeWrite(writer *io.PipeWriter){\n\tdata := []byte(\"Go语言中文网\")\n\tfor i := 0; i < 3; i++{\n\t\tn, err := writer.Write(data)\n\t\tif err != nil{\n\t\t\tfmt.Println(err)\n\t\t\treturn\n\t\t}\n\t\tfmt.Printf(\"写入字节 %d\\n\",n)\n\t}\n\twriter.CloseWithError(errors.New(\"写入段已关闭\"))\n}\n\nfunc PipeRead(reader *io.PipeReader){\n\tbuf := make([]byte, 128)\n\tfor{\n\t\tfmt.Println(\"接口端开始阻塞5秒钟...\")\n\t\ttime.Sleep(5 * time.Second)\n\t\tfmt.Println(\"接收端开始接受\")\n\t\tn, err := reader.Read(buf)\n\t\tif err != nil{\n\t\t\tfmt.Println(err)\n\t\t\treturn\n\t\t}\n\t\tfmt.Printf(\"收到字节: %d\\n buf内容: %s\\n\",n,buf)\n\t}\n}\n```\n\nio.Pipe() 用于创建一个同步的内存管道 (synchronous in-memory pipe)，函数签名：\n\n```go\nfunc Pipe() (*PipeReader, *PipeWriter)\n```\n\n它将 io.Reader 连接到 io.Writer。一端的读取匹配另一端的写入，直接在这两端之间复制数据；它没有内部缓存。它对于并行调用 Read 和 Write 以及其它函数或 Close 来说都是安全的。一旦等待的 I/O 结束，Close 就会完成。并行调用 Read 或并行调用 Write 也同样安全：同种类的调用将按顺序进行控制。\n\n正因为是*同步*的，因此不能在一个 goroutine 中进行读和写。\n\n另外，对于管道的 close 方法（非 CloseWithError 时），err 会被置为 EOF。\n\n## Copy 和 CopyN 函数 ##\n\n**Copy 函数**的签名：\n\n```go\nfunc Copy(dst Writer, src Reader) (written int64, err error)\n```\n\n函数文档：\n\n> Copy 将 src 复制到 dst，直到在 src 上到达 EOF 或发生错误。它返回复制的字节数，如果有错误的话，还会返回在复制时遇到的第一个错误。\n\n> 成功的 Copy 返回 err == nil，而非 err == EOF。由于 Copy 被定义为从 src 读取直到 EOF 为止，因此它不会将来自 Read 的 EOF 当做错误来报告。\n\n> 若 dst 实现了 ReaderFrom 接口，其复制操作可通过调用 dst.ReadFrom(src) 实现。此外，若 src 实现了 WriterTo 接口，其复制操作可通过调用 src.WriteTo(dst) 实现。\n\n代码：\n\n```go\nio.Copy(os.Stdout, strings.NewReader(\"Go语言中文网\"))\n```\n\n直接将内容输出（写入 Stdout 中）。\n\n我们甚至可以这么做：\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"os\"\n)\n\nfunc main() {\n\tio.Copy(os.Stdout, os.Stdin)\n\tfmt.Println(\"Got EOF -- bye\")\n}\n```\n\n执行：`echo \"Hello, World\" | go run main.go`\n\n\n**CopyN 函数**的签名：\n\n```go\nfunc CopyN(dst Writer, src Reader, n int64) (written int64, err error)\n```\n\n函数文档：\n\n> CopyN 将 n 个字节(或到一个error)从 src 复制到 dst。 它返回复制的字节数以及在复制时遇到的最早的错误。当且仅当err == nil时,written == n 。\n\n> 若 dst 实现了 ReaderFrom 接口，复制操作也就会使用它来实现。\n\n代码：\n\n```go\nio.CopyN(os.Stdout, strings.NewReader(\"Go语言中文网\"), 8)\n```\n\n会输出：\n\n\tGo语言\n\n## ReadAtLeast 和 ReadFull 函数 ##\n\n**ReadAtLeast 函数**的签名：\n\n```go\nfunc ReadAtLeast(r Reader, buf []byte, min int) (n int, err error)\n```\n\n函数文档：\n\n> ReadAtLeast 将 r 读取到 buf 中，直到读了最少 min 个字节为止。它返回复制的字节数，如果读取的字节较少，还会返回一个错误。若没有读取到字节，错误就只是 EOF。如果一个 EOF 发生在读取了少于 min 个字节之后，ReadAtLeast 就会返回 ErrUnexpectedEOF。若 min 大于 buf 的长度，ReadAtLeast 就会返回 ErrShortBuffer。对于返回值，当且仅当 err == nil 时，才有 n >= min。\n\n一般可能不太会用到这个函数。使用时需要注意返回的 error 判断。\n\n**ReadFull 函数**的签名：\n\n```go\nfunc ReadFull(r Reader, buf []byte) (n int, err error)\n```\n\n函数文档：\n\n> ReadFull 精确地从 r 中将 len(buf) 个字节读取到 buf 中。它返回复制的字节数，如果读取的字节较少，还会返回一个错误。若没有读取到字节，错误就只是 EOF。如果一个 EOF 发生在读取了一些但不是所有的字节后，ReadFull 就会返回 ErrUnexpectedEOF。对于返回值，当且仅当 err == nil 时，才有 n == len(buf)。\n\n注意该函数和 ReadAtLeast 的区别：ReadFull 将 buf 读满；而 ReadAtLeast 是最少读取 min 个字节。\n\n## WriteString 函数 ##\n\n这是为了方便写入 string 类型提供的函数，函数签名：\n\n```go\nfunc WriteString(w Writer, s string) (n int, err error)\n```\n\n函数文档：\n\n>WriteString 将s的内容写入w中，当 w 实现了 WriteString 方法时，会直接调用该方法，否则执行 w.Write([]byte(s))。\n\n## MultiReader 和 MultiWriter 函数 ##\n\n这两个函数的定义分别是：\n\n```go\nfunc MultiReader(readers ...Reader) Reader\nfunc MultiWriter(writers ...Writer) Writer\n```\n\n它们接收多个 Reader 或 Writer，返回一个 Reader 或 Writer。我们可以猜想到这两个函数就是操作多个 Reader 或 Writer 就像操作一个。\n\n事实上，在 io 包中定义了两个非导出类型：mutilReader 和 multiWriter，它们分别实现了 io.Reader 和 io.Writer 接口。类型定义为：\n\n```go\ntype multiReader struct {\n\treaders []Reader\n}\n\ntype multiWriter struct {\n\twriters []Writer\n}\n```\n\n对于这两种类型对应的实现方法（Read 和 Write 方法）的使用，我们通过例子来演示。\n\n**MultiReader 的使用**：\n\n```go\nreaders := []io.Reader{\n\tstrings.NewReader(\"from strings reader\"),\n\tbytes.NewBufferString(\"from bytes buffer\"),\n}\nreader := io.MultiReader(readers...)\ndata := make([]byte, 0, 128)\nbuf := make([]byte, 10)\n\t\nfor n, err := reader.Read(buf); err != io.EOF ; n, err = reader.Read(buf){\n\tif err != nil{\n\t\tpanic(err)\n\t}\n\tdata = append(data,buf[:n]...)\n}\nfmt.Printf(\"%s\\n\", data)\n```\n\n输出：\n\n\tfrom strings readerfrom bytes buffer\n\n代码中首先构造了一个 io.Reader 的 slice，由 strings.Reader 和 bytes.Buffer 两个实例组成，然后通过 MultiReader 得到新的 Reader，循环读取新 Reader 中的内容。从输出结果可以看到，第一次调用 Reader 的 Read 方法获取到的是 slice 中第一个元素的内容……也就是说，MultiReader 只是逻辑上将多个 Reader 组合起来，并不能通过调用一次 Read 方法获取所有 Reader 的内容。在所有的 Reader 内容都被读完后，Reader 会返回 EOF。\n\n**MultiWriter 的使用**：\n\n```go\nfile, err := os.Create(\"tmp.txt\")\nif err != nil {\n panic(err)\n}\ndefer file.Close()\nwriters := []io.Writer{\n\tfile,\n\tos.Stdout,\n}\nwriter := io.MultiWriter(writers...)\nwriter.Write([]byte(\"Go语言中文网\"))\n```\n\n这段程序执行后在生成 tmp.txt 文件，同时在文件和屏幕中都输出：`Go语言中文网`。这和 Unix 中的 tee 命令类似。\n\n\n**动手试试**\n\nGo 实现 Unix 中 tee 命令的功能很简单吧。MultiWriter 的 Write 方法是如何实现的？有兴趣可以自己实现一个，然后对着源码比较一下。\n\n## TeeReader函数 ##\n\n函数签名如下：\n\n```go\nfunc TeeReader(r Reader, w Writer) Reader\n```\n\nTeeReader 返回一个 Reader，它将从 r 中读到的数据写入 w 中。所有经由它处理的从 r 的读取都匹配于对应的对 w 的写入。它没有内部缓存，即写入必须在读取完成前完成。任何在写入时遇到的错误都将作为读取错误返回。\n\n也就是说，我们通过 Reader 读取内容后，会自动写入到 Writer 中去。例子代码如下：\n\n```go\nreader := io.TeeReader(strings.NewReader(\"Go语言中文网\"), os.Stdout)\nreader.Read(make([]byte, 20))\n```\n\n输出结果：\n\n\tGo语言中文网\n\n这种功能的实现其实挺简单，无非是在 Read 完后执行 Write。\n\n至此，io 所有接口、类型和函数都讲解完成。\n\n# 导航 #\n\n- [目录](/preface.md)\n- 下一节：[ioutil — 方便的 IO 操作函数集](01.2.md)\n" }, { "path": "chapter01/01.2.md", "content": "# 1.2 ioutil — 方便的IO操作函数集 #\n\n虽然 io 包提供了不少类型、方法和函数，但有时候使用起来不是那么方便。比如读取一个文件中的所有内容。为此，标准库中提供了一些常用、方便的IO操作函数。\n\n说明：这些函数使用都相对简单，一般就不举例子了。\n\n## NopCloser 函数 ##\n\n有时候我们需要传递一个 io.ReadCloser 的实例，而我们现在有一个 io.Reader 的实例，比如：strings.Reader ，这个时候 NopCloser 就派上用场了。它包装一个io.Reader，返回一个 io.ReadCloser ，而相应的 Close 方法啥也不做，只是返回 nil。\n\n比如，在标准库 net/http 包中的 NewRequest，接收一个 io.Reader 的 body，而实际上，Request 的 Body 的类型是 io.ReadCloser，因此，代码内部进行了判断，如果传递的 io.Reader 也实现了 io.ReadCloser 接口，则转换，否则通过ioutil.NopCloser 包装转换一下。相关代码如下：\n```go\n rc, ok := body.(io.ReadCloser)\n if !ok && body != nil {\n\t\trc = ioutil.NopCloser(body)\n }\n```\n如果没有这个函数，我们得自己实现一个。当然，实现起来很简单，读者可以看看 [NopCloser](http://docscn.studygolang.com/src/io/ioutil/ioutil.go?s=5557:5598#L145) 的实现。\n\n## ReadAll 函数 ##\n\n很多时候，我们需要一次性读取 io.Reader 中的数据，通过上一节的讲解，我们知道有很多种实现方式。考虑到读取所有数据的需求比较多，Go 提供了 ReadAll 这个函数，用来从io.Reader 中一次读取所有数据。\n```go\n\tfunc ReadAll(r io.Reader) ([]byte, error)\n```\n阅读该函数的源码发现，它是通过 bytes.Buffer 中的 [ReadFrom](http://docscn.studygolang.com/src/bytes/buffer.go?s=5385:5444#L144) 来实现读取所有数据的。该函数成功调用后会返回 err == nil 而不是 err == EOF。(成功读取完毕应该为 err == io.EOF，这里返回 nil 由于该函数成功期望 err == io.EOF，符合无错误不处理的理念)\n\n## ReadDir 函数 ##\n\n笔试题：编写程序输出某目录下的所有文件（包括子目录）\n\n是否见过这样的笔试题？\n\n在 Go 中如何输出目录下的所有文件呢？首先，我们会想到查 os 包，看 File 类型是否提供了相关方法（关于 os 包，后面会讲解）。\n\n其实在 ioutil 中提供了一个方便的函数：ReadDir，它读取目录并返回排好序的文件和子目录名（ []os.FileInfo ）。通过这个方法，我们可以很容易的实现“面试题”。\n\n```go\t\nfunc main() {\n\tdir := os.Args[1]\n\tlistAll(dir,0)\n}\n\nfunc listAll(path string, curHier int){\n\tfileInfos, err := ioutil.ReadDir(path)\n\tif err != nil{fmt.Println(err); return}\n\n\tfor _, info := range fileInfos{\n\t\tif info.IsDir(){\n\t\t\tfor tmpHier := curHier; tmpHier > 0; tmpHier--{\n\t\t\t\tfmt.Printf(\"|\\t\")\n\t\t\t}\n\t\t\tfmt.Println(info.Name(),\"\\\\\")\n\t\t\tlistAll(path + \"/\" + info.Name(),curHier + 1)\n\t\t}else{\n\t\t\tfor tmpHier := curHier; tmpHier > 0; tmpHier--{\n\t\t\t\tfmt.Printf(\"|\\t\")\n\t\t\t}\n\t\t\tfmt.Println(info.Name())\n\t\t}\n\t}\n}\n```\n\n## ReadFile 和 WriteFile 函数 ##\n\nReadFile 读取整个文件的内容，在上一节我们自己实现了一个函数读取文件整个内容，由于这种需求很常见，因此 Go 提供了 ReadFile 函数，方便使用。ReadFile 的实现和ReadAll 类似，不过，ReadFile 会先判断文件的大小，给 bytes.Buffer 一个预定义容量，避免额外分配内存。\n\nReadFile 函数的签名如下:\n```go\n\tfunc ReadFile(filename string) ([]byte, error)\n```\n函数文档：\n\n> ReadFile 从 filename 指定的文件中读取数据并返回文件的内容。成功的调用返回的err 为 nil 而非 EOF。因为本函数定义为读取整个文件，它不会将读取返回的 EOF 视为应报告的错误。(同 ReadAll )\n\nWriteFile 函数的签名如下：\n```go \n\tfunc WriteFile(filename string, data []byte, perm os.FileMode) error\n```\n函数文档:\n\n> WriteFile 将data写入filename文件中，当文件不存在时会根据perm指定的权限进行创建一个,文件存在时会先清空文件内容。对于 perm 参数，我们一般可以指定为：0666，具体含义 os 包中讲解。\n\n**小提示**\n\nReadFile 源码中先获取了文件的大小，当大小 < 1e9 时，才会用到文件的大小。按源码中注释的说法是 FileInfo 不会很精确地得到文件大小。\n\n## TempDir 和 TempFile 函数 ##\n\n操作系统中一般都会提供临时目录，比如 linux 下的 /tmp 目录（通过 os.TempDir() 可以获取到)。有时候，我们自己需要创建临时目录，比如 Go 工具链源码中（src/cmd/go/build.go），通过 TempDir 创建一个临时目录，用于存放编译过程的临时文件：\n```go\n\tb.work, err = ioutil.TempDir(\"\", \"go-build\")\n```\n第一个参数如果为空，表明在系统默认的临时目录（ os.TempDir ）中创建临时目录；第二个参数指定临时目录名的前缀，该函数返回临时目录的路径。\n\n相应的，TempFile 用于创建临时文件。如 gofmt 命令的源码中创建临时文件：\n```go\n\tf1, err := ioutil.TempFile(\"\", \"gofmt\")\n```\n参数和 ioutil.TempDir 参数含义类似。\n\n这里需要**注意**：创建者创建的临时文件和临时目录要负责删除这些临时目录和文件。如删除临时文件：\n```go\n\tdefer func() {\n\t\tf.Close()\n\t\tos.Remove(f.Name())\n\t}()\n```\n## Discard 变量 ##\n\nDiscard 对应的类型（`type devNull int`）实现了 io.Writer 接口，同时，为了优化 io.Copy 到 Discard，避免不必要的工作，实现了 io.ReaderFrom 接口。\n\ndevNull 在实现 io.Writer 接口时，只是简单的返回（标准库文件：[src/pkg/io/ioutil.go](http://docscn.studygolang.com/pkg/io/ioutil/#pkg-variables))。\n```go\n\tfunc (devNull) Write(p []byte) (int, error) {\n\t\treturn len(p), nil\n\t}\n```\n而 ReadFrom 的实现是读取内容到一个 buf 中，最大也就 8192 字节，其他的会丢弃（当然，这个也不会读取）。\n\n# 导航 #\n\n- [目录](/preface.md)\n- 上一节：[io — 基本的IO接口](01.1.md)\n- 下一节：[fmt — 格式化IO](01.3.md)\n" }, { "path": "chapter01/01.3.md", "content": "# 1.3 fmt — 格式化IO #\n\nfmt 包实现了格式化I/O函数，类似于C的 printf 和 scanf. 格式“占位符”衍生自C，但比C更简单。\n\nfmt 包的官方文档对 Printing 和 Scanning 有很详细的说明。这里就直接引用文档进行说明，同时附上额外的说明或例子，之后再介绍具体的函数使用。\n\n以下例子中用到的类型或变量定义：\n```go\n\ttype Website struct {\n\t Name string\n\t}\n\t\n\t// 定义结构体变量\n\tvar site = Website{Name:\"studygolang\"}\n```\n## Printing ##\n### Sample\n```go\n\ntype user struct {\n\tname string\n}\n\nfunc main() {\n\tu := user{\"tang\"}\n\t//Printf 格式化输出\n\tfmt.Printf(\"% + v\\n\", u) //格式化输出结构\n\tfmt.Printf(\"%#v\\n\", u) //输出值的 Go 语言表示方法\n\tfmt.Printf(\"%T\\n\", u) //输出值的类型的 Go 语言表示\n\tfmt.Printf(\"%t\\n\", true) //输出值的 true 或 false\n\tfmt.Printf(\"%b\\n\", 1024) //二进制表示\n\tfmt.Printf(\"%c\\n\", 11111111) //数值对应的 Unicode 编码字符\n\tfmt.Printf(\"%d\\n\", 10) //十进制表示\n\tfmt.Printf(\"%o\\n\", 8) //八进制表示\n\tfmt.Printf(\"%q\\n\", 22) //转化为十六进制并附上单引号\n\tfmt.Printf(\"%x\\n\", 1223) //十六进制表示，用a-f表示\n\tfmt.Printf(\"%X\\n\", 1223) //十六进制表示，用A-F表示\n\tfmt.Printf(\"%U\\n\", 1233) //Unicode表示\n\tfmt.Printf(\"%b\\n\", 12.34) //无小数部分，两位指数的科学计数法6946802425218990p-49\n\tfmt.Printf(\"%e\\n\", 12.345) //科学计数法，e表示\n\tfmt.Printf(\"%E\\n\", 12.34455) //科学计数法，E表示\n\tfmt.Printf(\"%f\\n\", 12.3456) //有小数部分，无指数部分\n\tfmt.Printf(\"%g\\n\", 12.3456) //根据实际情况采用%e或%f输出\n\tfmt.Printf(\"%G\\n\", 12.3456) //根据实际情况采用%E或%f输出\n\tfmt.Printf(\"%s\\n\", \"wqdew\") //直接输出字符串或者[]byte\n\tfmt.Printf(\"%q\\n\", \"dedede\") //双引号括起来的字符串\n\tfmt.Printf(\"%x\\n\", \"abczxc\") //每个字节用两字节十六进制表示，a-f表示\n\tfmt.Printf(\"%X\\n\", \"asdzxc\") //每个字节用两字节十六进制表示，A-F表示\n\tfmt.Printf(\"%p\\n\", 0x123) //0x开头的十六进制数表示\n}\n```\n### 占位符 ###\n\n**普通占位符**\n\t\n\t占位符\t\t\t\t\t\t说明\t\t\t\t\t\t举例\t\t\t\t\t\t\t\t\t\t输出\n\t%v\t\t相应值的默认格式。\t\t\t\t\t\t\t\tPrintf(\"%v\", site)，Printf(\"%+v\", site)\t{studygolang}，{Name:studygolang}\n\t\t\t在打印结构体时，“加号”标记（%+v）会添加字段名\n\t%#v\t\t相应值的Go语法表示\t\t\t\t\t\t\tPrintf(\"#v\", site)\t\t\t\t\t\tmain.Website{Name:\"studygolang\"}\n\t%T\t\t相应值的类型的Go语法表示\t\t\t\t\t\tPrintf(\"%T\", site)\t\t\t\t\t\tmain.Website\n\t%%\t\t字面上的百分号，并非值的占位符\t\t\t\t\tPrintf(\"%%\")\t\t\t\t\t\t\t%\n\n**布尔占位符**\n\n\t占位符\t\t\t\t\t\t说明\t\t\t\t\t\t举例\t\t\t\t\t\t\t\t\t\t输出\n\t%t\t\t单词 true 或 false。\t\t\t\t\t\t\tPrintf(\"%t\", true)\t\t\t\t\t\ttrue\n\n**整数占位符**\n\n\t占位符\t\t\t\t\t\t说明\t\t\t\t\t\t举例\t\t\t\t\t\t\t\t\t输出\n\t%b\t\t二进制表示\t\t\t\t\t\t\t\t\tPrintf(\"%b\", 5)\t\t\t\t\t\t101\n\t%c\t\t相应Unicode码点所表示的字符\t\t\t\t\tPrintf(\"%c\", 0x4E2D)\t\t\t\t中\n\t%d\t\t十进制表示\t\t\t\t\t\t\t\t\tPrintf(\"%d\", 0x12)\t\t\t\t\t18\n\t%o\t\t八进制表示\t\t\t\t\t\t\t\t\tPrintf(\"%o\", 10)\t\t\t\t\t12\n\t%q\t\t单引号围绕的字符字面值，由Go语法安全地转义\t\tPrintf(\"%q\", 0x4E2D)\t\t\t\t'中'\n\t%x\t\t十六进制表示，字母形式为小写 a-f\t\t\t\tPrintf(\"%x\", 13)\t\t\t\t\td\n\t%X\t\t十六进制表示，字母形式为大写 A-F\t\t\t\tPrintf(\"%x\", 13)\t\t\t\t\tD\n\t%U\t\tUnicode格式：U+1234，等同于 \"U+%04X\"\t\t\tPrintf(\"%U\", 0x4E2D)\t\t\t\tU+4E2D\n\n**浮点数和复数的组成部分（实部和虚部）**\n\n\t占位符\t\t\t\t\t\t说明\t\t\t\t\t\t\t\t\t\t\t\t举例\t\t\t\t\t\t\t\t\t输出\n\t%b\t\t无小数部分的，指数为二的幂的科学计数法，与 strconv.FormatFloat\t\n\t\t\t的 'b' 转换格式一致。例如 -123456p-78\n\t%e\t\t科学计数法，例如 -1234.456e+78\t\t\t\t\t\t\t\t\tPrintf(\"%e\", 10.2)\t\t\t\t\t\t\t1.020000e+01\n\t%E\t\t科学计数法，例如 -1234.456E+78\t\t\t\t\t\t\t\t\tPrintf(\"%e\", 10.2)\t\t\t\t\t\t\t1.020000E+01\n\t%f\t\t有小数点而无指数，例如 123.456\t\t\t\t\t\t\t\t\tPrintf(\"%f\", 10.2)\t\t\t\t\t\t\t10.200000\n\t%g\t\t根据情况选择 %e 或 %f 以产生更紧凑的（无末尾的0）输出\t\t\t\tPrintf(\"%g\", 10.20)\t\t\t\t\t\t\t10.2\n\t%G\t\t根据情况选择 %E 或 %f 以产生更紧凑的（无末尾的0）输出\t\t\t\tPrintf(\"%G\", 10.20+2i)\t\t\t\t\t\t(10.2+2i)\n\n**字符串与字节切片**\n\n\t占位符\t\t\t\t\t\t说明\t\t\t\t\t\t\t\t\t\t\t\t举例\t\t\t\t\t\t\t\t\t输出\n\t%s\t\t输出字符串表示（string类型或[]byte)\t\t\t\t\t\t\tPrintf(\"%s\", []byte(\"Go语言中文网\"))\t\tGo语言中文网\n\t%q\t\t双引号围绕的字符串，由Go语法安全地转义\t\t\t\t\t\t\tPrintf(\"%q\", \"Go语言中文网\")\t\t\t\t\"Go语言中文网\"\n\t%x\t\t十六进制，小写字母，每字节两个字符\t\t\t\t\t\t\t\tPrintf(\"%x\", \"golang\")\t\t\t\t\t\t676f6c616e67\n\t%X\t\t十六进制，大写字母，每字节两个字符\t\t\t\t\t\t\t\tPrintf(\"%X\", \"golang\")\t\t\t\t\t\t676F6C616E67\n\n**指针**\n\n\t占位符\t\t\t\t\t\t说明\t\t\t\t\t\t\t\t\t\t\t\t举例\t\t\t\t\t\t\t\t\t输出\n\t%p\t\t十六进制表示，前缀 0x\t\t\t\t\t\t\t\t\t\t\tPrintf(\"%p\", &site)\t\t\t\t\t\t\t0x4f57f0\n\t\n这里没有 'u' 标记。若整数为无符号类型，他们就会被打印成无符号的。类似地，这里也不需要指定操作数的大小（int8，int64）。\n\n宽度与精度的控制格式以 Unicode 码点为单位。（这点与C的 printf 不同，它以字节数为单位）二者或其中之一均可用字符 '*' 表示，此时它们的值会从下一个操作数中获取，该操作数的类型必须为 int。\n\n对数值而言，宽度为该数值占用区域的最小宽度；精度为小数点之后的位数。 但对于 %g/%G 而言，精度为所有数字的总数。例如，对于123.45，格式 %6.2f 会打印123.45，而 %.4g 会打印123.5。%e 和 %f 的默认精度为6；但对于 %g 而言，它的默认精度为确定该值所必须的最小位数。\n\n对大多数的值而言，宽度为输出的最小字符数，如果必要的话会为已格式化的形式填充空格。对字符串而言，精度为输出的最大字符数，如果必要的话会直接截断。\n\n**其它标记**\n\n\t占位符\t\t\t\t\t\t说明\t\t\t\t\t\t\t\t\t\t\t\t举例\t\t\t\t\t\t\t\t\t输出\n\t+\t\t总打印数值的正负号；对于%q（%+q）保证只输出ASCII编码的字符。\t\t\tPrintf(\"%+q\", \"中文\")\t\t\t\t\t\"\\u4e2d\\u6587\"\n\t-\t\t在右侧而非左侧填充空格（左对齐该区域）\n\t#\t\t备用格式：为八进制添加前导 0（%#o），为十六进制添加前导 0x（%#x）或\tPrintf(\"%#U\", '中')\t\t\t\t\t\tU+4E2D '中'\n\t\t\t0X（%#X），为 %p（%#p）去掉前导 0x；如果可能的话，%q（%#q）会打印原始\n\t\t\t（即反引号围绕的）字符串；如果是可打印字符，%U（%#U）会写出该字符的\n\t\t\tUnicode 编码形式（如字符 x 会被打印成 U+0078 'x'）。\n\t' '\t\t（空格）为数值中省略的正负号留出空白（% d）；\n\t\t\t以十六进制（% x, % X）打印字符串或切片时，在字节之间用空格隔开\n\t0\t\t填充前导的0而非空格；对于数字，这会将填充移到正负号之后\n\n标记有时会被占位符忽略，所以不要指望它们。例如十进制没有备用格式，因此 %#d 与 %d 的行为相同。\n\n对于每一个 Printf 类的函数，都有一个 Print 函数，该函数不接受任何格式化，它等价于对每一个操作数都应用 %v。另一个变参函数 Println 会在操作数之间插入空白，并在末尾追加一个换行符。\n\n不考虑占位符的话，如果操作数是接口值，就会使用其内部的具体值，而非接口本身。 因此：\n```go\n\tvar i interface{} = 23\n\tfmt.Printf(\"%v\\n\", i)\n```\n会打印 23。\n\n若一个操作数实现了 Formatter 接口，该接口就能更好地用于控制格式化。\n\n若其格式（它对于 Println 等函数是隐式的 %v）对于字符串是有效的 （%s %q %v %x %X），以下两条规则也适用：\n```go\n\t1. 若一个操作数实现了 error 接口，Error 方法就能将该对象转换为字符串，随后会根据占位符的需要进行格式化。\n\t2. 若一个操作数实现了 String() string 方法，该方法能将该对象转换为字符串，随后会根据占位符的需要进行格式化。\n```\n为避免以下这类递归的情况：\n```go\n\ttype X string\n\tfunc (x X) String() string { return Sprintf(\"<%s>\", x) }\n```\n需要在递归前转换该值：\n```go\n\tfunc (x X) String() string { return Sprintf(\"<%s>\", string(x)) }\n```\n**格式化错误**\n\n如果给占位符提供了无效的实参（例如将一个字符串提供给 %d），所生成的字符串会包含该问题的描述，如下例所示：\n```bash\n\t类型错误或占位符未知：%!verb(type=value)\n\t\tPrintf(\"%d\", hi): %!d(string=hi)\n\t实参太多：%!(EXTRA type=value)\n\t\tPrintf(\"hi\", \"guys\"): hi%!(EXTRA string=guys)\n\t实参太少： %!verb(MISSING)\n\t\tPrintf(\"hi%d\"): hi %!d(MISSING)\n\t宽度或精度不是int类型: %!(BADWIDTH) 或 %!(BADPREC)\n\t\tPrintf(\"%*s\", 4.5, \"hi\"): %!(BADWIDTH)hi\n\t\tPrintf(\"%.*s\", 4.5, \"hi\"): %!(BADPREC)hi\n\t所有错误都始于“%!”，有时紧跟着单个字符（占位符），并以小括号括住的描述结尾。\n```\n## Scanning ##\n\n一组类似的函数通过扫描已格式化的文本来产生值。\nScan、Scanf 和 Scanln 从 os.Stdin 中读取；\nFscan、Fscanf 和 Fscanln 从指定的 io.Reader 中读取； \nSscan、Sscanf 和 Sscanln 从实参字符串中读取。\nScanln、Fscanln 和 Sscanln 在换行符处停止扫描，且需要条目紧随换行符之后；\nScanf、Fscanf 和 Sscanf 需要输入换行符来匹配格式中的换行符；其它函数则将换行符视为空格。\n\nScanf、Fscanf 和 Sscanf 根据格式字符串解析实参，类似于 Printf。例如，%x 会将一个整数扫描为十六进制数，而 %v 则会扫描该值的默认表现格式。\n\n格式化行为类似于 Printf，但也有如下例外：\n\n\t%p 没有实现\n\t%T 没有实现\n\t%e %E %f %F %g %G 都完全等价，且可扫描任何浮点数或复数数值\n\t%s 和 %v 在扫描字符串时会将其中的空格作为分隔符\n\t标记 # 和 + 没有实现\n\n在使用 %v 占位符扫描整数时，可接受友好的进制前缀0（八进制）和0x（十六进制）。\n\n宽度被解释为输入的文本（%5s 意为最多从输入中读取5个 rune 来扫描成字符串），而扫描函数则没有精度的语法（没有 %5.2f，只有 %5f）。\n\n当以某种格式进行扫描时，无论在格式中还是在输入中，所有非空的连续空白字符 （除换行符外）都等价于单个空格。由于这种限制，格式字符串文本必须匹配输入的文本，如果不匹配，扫描过程就会停止，并返回已扫描的实参数。\n\n在所有的扫描参数中，若一个操作数实现了 Scan 方法（即它实现了 Scanner 接口）， 该操作数将使用该方法扫描其文本。此外，若已扫描的实参数少于所提供的实参数，就会返回一个错误。\n\n所有需要被扫描的实参都必须是基本类型或 Scanner 接口的实现。\n\n注意：Fscan 等函数会从输入中多读取一个字符（rune），因此，如果循环调用扫描函数，可能会跳过输入中的某些数据。一般只有在输入的数据中没有空白符时该问题才会出现。若提供给 Fscan 的读取器实现了 ReadRune，就会用该方法读取字符。若此读取器还实现了 UnreadRune 方法，就会用该方法保存字符，而连续的调用将不会丢失数据。若要为没有 ReadRune 和 UnreadRune 方法的读取器加上这些功能，需使用 bufio.NewReader。\n\n## Print 序列函数 ##\n\n这里说的 Print 序列函数包括：Fprint/Fprintf/Fprintln/Sprint/Sprintf/Sprintln/Print/Printf/Println。之所以将放在一起介绍，是因为它们的使用方式类似、参数意思也类似。\n\n一般的，我们将 Fprint/Fprintf/Fprintln 归为一类；Sprint/Sprintf/Sprintln 归为一类；Print/Printf/Println 归为另一类。其中，Print/Printf/Println 会调用相应的F开头一类函数。如：\n```go\n\tfunc Print(a ...interface{}) (n int, err error) {\n\t\treturn Fprint(os.Stdout, a...)\n\t}\n```\nFprint/Fprintf/Fprintln 函数的第一个参数接收一个io.Writer类型，会将内容输出到 io.Writer 中去。而 Print/Printf/Println 函数是将内容输出到标准输出中，因此，直接调用 F类函数 做这件事，并将 os.Stdout 作为第一个参数传入。\n\nSprint/Sprintf/Sprintln 是格式化内容为 string 类型，而并不输出到某处，需要格式化字符串并返回时，可以用这组函数。\n\n在这三组函数中，`S/F/Printf`函数通过指定的格式输出或格式化内容；`S/F/Print`函数只是使用默认的格式输出或格式化内容；`S/F/Println`函数使用默认的格式输出或格式化内容，同时会在最后加上\"换行符\"。\n\nPrint 序列函数的最后一个参数都是 `a ...interface{}` 这种不定参数。对于`S/F/Printf`序列，这个不定参数的实参个数应该和`formt`参数的占位符个数一致，否则会出现格式化错误；而对于其他函数，当不定参数的实参个数为多个时，它们之间会直接（对于`S/F/Print`）或通过\" \"（空格）（对于`S/F/Println`）连接起来（注：对于`S/F/Print`，当两个参数都不是字符串时，会自动添加一个空格，否则不会加。感谢guoshanhe1983 反馈。[官方 effective_go](http://docs.studygolang.com/doc/effective_go.html#Printing) 也有说明）。利用这一点，我们可以做如下事情：\n\n\tresult1 := fmt.Sprintln(\"studygolang.com\", 2013)\n\tresult2 := fmt.Sprint(\"studygolang.com\", 2013)\n\t\nresult1的值是：`studygolang.com 2013`，result2的值是：`studygolang.com2013`。这起到了连接字符串的作用，而不需要通过`strconv.Itoa()`转换。\n\nPrint 序列函数用的较多，而且也易于使用（可能需要掌握一些常用的占位符用法），接下来我们结合 fmt 包中几个相关的接口来掌握更多关于 Print 的内容。\n\n## Stringer 接口 ##\n\nStringer接口的定义如下：\n```go\n\ttype Stringer interface {\n\t String() string\n\t}\n```\n根据 Go 语言中实现接口的定义，一个类型只要有 `String() string` 方法，我们就说它实现了 Stringer 接口。而在本节开始已经说到，如果格式化输出某种类型的值，只要它实现了 String() 方法，那么会调用 String() 方法进行处理。\n\n我们定义如下struct：\n```go\n\ttype Person struct {\n\t\tName string\n\t\tAge int\n\t\tSex int\n\t}\n```\n我们给Person实现String方法，这个时候，我们输出Person的实例：\n```go\n\tp := &Person{\"polaris\", 28, 0}\n\tfmt.Println(p)\n```\n输出：\n```bash\n\t&{polaris 28 0}\n```\n接下来，为Person增加String方法。\n```go\n\tfunc (this *Person) String() string {\n\t\tbuffer := bytes.NewBufferString(\"This is \")\n\t\tbuffer.WriteString(this.Name + \", \")\n\t\tif this.Sex == 0 {\n\t\t\tbuffer.WriteString(\"He \")\n\t\t} else {\n\t\t\tbuffer.WriteString(\"She \")\n\t\t}\n\n\t\tbuffer.WriteString(\"is \")\n\t\tbuffer.WriteString(strconv.Itoa(this.Age))\n\t\tbuffer.WriteString(\" years old.\")\n\t\treturn buffer.String()\n\t}\n```\n这个时候运行：\n```go\n\tp := &Person{\"polaris\", 28, 0}\n\tfmt.Println(p)\n```\n输出变为：\n```bash\n\tThis is polaris, He is 28 years old\n```\n可见，Stringer接口和Java中的ToString方法类似。\n\n## Formatter 接口 ##\n\nFormatter 接口的定义如下：\n```go\n\ttype Formatter interface {\n\t Format(f State, c rune)\n\t}\n```\n官方文档中关于该接口方法的说明：\n\n> Formatter 接口由带有定制的格式化器的值所实现。 Format 的实现可调用 Sprintf 或 Fprintf(f) 等函数来生成其输出。\n\n也就是说，通过实现 Formatter 接口可以做到自定义输出格式（自定义占位符）。\n\n接着上面的例子，我们为 Person 增加一个方法：\n```go\n\tfunc (this *Person) Format(f fmt.State, c rune) {\n\t\tif c == 'L' {\n\t\t\tf.Write([]byte(this.String()))\n\t\t\tf.Write([]byte(\" Person has three fields.\"))\n\t\t} else {\n\t\t\t// 没有此句，会导致 fmt.Printf(\"%s\", p) 啥也不输出\n\t\t f.Write([]byte(fmt.Sprintln(this.String())))\n\t\t}\n\t}\n```\n这样，Person便实现了Formatter接口。这时再运行：\n```go\n\tp := &Person{\"polaris\", 28, 0}\n\tfmt.Printf(\"%L\", p)\n```\n输出为：\n```bash\n\tThis is polaris, He is 28 years old. Person has three fields.\n```\n这里需要解释以下几点：\n\n1）fmt.State 是一个接口。由于 Format 方法是被 fmt 包调用的，它内部会实例化好一个 fmt.State 接口的实例，我们不需要关心该接口；\n\n2）可以实现自定义占位符，同时 fmt 包中和类型相对应的预定义占位符会无效。因此例子中 Format 的实现加上了 else 子句；\n\n3）实现了 Formatter 接口，相应的 Stringer 接口不起作用。但实现了 Formatter 接口的类型应该实现 Stringer 接口，这样方便在 Format 方法中调用 String() 方法。就像本例的做法；\n\n4）Format 方法的第二个参数是占位符中%后的字母（有精度和宽度会被忽略，只保留字母）；\n\n一般地，我们不需要实现 Formatter 接口。如果对 Formatter 接口的实现感兴趣，可以看看标准库 [math/big](http://docscn.studygolang.com/src/math/big/floatconv.go?s=7989:8041#L261) 包中 Int 类型的 Formatter 接口实现。\n\n**小贴士**\n\nState接口相关说明：\n```go\n\ttype State interface {\n\t // Write is the function to call to emit formatted output to be printed.\n\t // Write 函数用于打印出已格式化的输出。\n\t Write(b []byte) (ret int, err error)\n\t // Width returns the value of the width option and whether it has been set.\n\t // Width 返回宽度选项的值以及它是否已被设置。\n\t Width() (wid int, ok bool)\n\t // Precision returns the value of the precision option and whether it has been set.\n\t // Precision 返回精度选项的值以及它是否已被设置。\n\t Precision() (prec int, ok bool)\n\t\n\t // Flag returns whether the flag c, a character, has been set.\n\t // Flag 返回标记 c（一个字符）是否已被设置。\n\t Flag(c int) bool\n\t}\n```\nfmt 包中的 print.go 文件中的`type pp struct`实现了 State 接口。由于 State 接口有 Write 方法，因此，实现了 State 接口的类型必然实现了 io.Writer 接口。\n\n## GoStringer 接口 ##\n\nGoStringer 接口定义如下；\n```go\n\ttype GoStringer interface {\n\t GoString() string\n\t}\n```\n该接口定义了类型的Go语法格式。用于打印(Printf)格式化占位符为 %#v 的值。\n\n用前面的例子演示。执行：\n```go\n\tp := &Person{\"polaris\", 28, 0}\n\tfmt.Printf(\"%#v\", p)\n```\n输出：\n```bash\n\t&main.Person{Name:\"polaris\", Age:28, Sex:0}\n```\n接着为Person增加方法：\n```go\n\tfunc (this *Person) GoString() string {\n\t\treturn \"&Person{Name is \"+this.Name+\", Age is \"+strconv.Itoa(this.Age)+\", Sex is \"+strconv.Itoa(this.Sex)+\"}\"\n\t}\n```\n这个时候再执行\n```go\n\tp := &Person{\"polaris\", 28, 0}\n\tfmt.Printf(\"%#v\", p)\n```\n输出：\n```bash\n\t&Person{Name is polaris, Age is 28, Sex is 0}\n```\n一般的，我们不需要实现该接口。\n\n## Scan 序列函数 ##\n\n该序列函数和 Print 序列函数相对应，包括：Fscan/Fscanf/Fscanln/Sscan/Sscanf/Sscanln/Scan/Scanf/Scanln。\n\n一般的，我们将Fscan/Fscanf/Fscanln归为一类；Sscan/Sscanf/Sscanln归为一类；Scan/Scanf/Scanln归为另一类。其中，Scan/Scanf/Scanln会调用相应的F开头一类函数。如：\n```go\n\tfunc Scan(a ...interface{}) (n int, err error) {\n\t\treturn Fscan(os.Stdin, a...)\n\t}\n```\nFscan/Fscanf/Fscanln 函数的第一个参数接收一个 io.Reader 类型，从其读取内容并赋值给相应的实参。而 Scan/Scanf/Scanln 正是从标准输入获取内容，因此，直接调用 F类函数 做这件事，并将 os.Stdin 作为第一个参数传入。\n\nSscan/Sscanf/Sscanln 则直接从字符串中获取内容。\n\n对于Scan/Scanf/Scanln三个函数的区别，我们通过例子来说明，为了方便讲解，我们使用Sscan/Sscanf/Sscanln这组函数。\n\n1) Scan/FScan/Sscan\n```go\n\tvar (\n\t\tname string\n\t\tage int\n\t)\n\tn, _ := fmt.Sscan(\"polaris 28\", &name, &age)\n\t// 可以将\"polaris 28\"中的空格换成\"\\n\"试试\n\t// n, _ := fmt.Sscan(\"polaris\\n28\", &name, &age)\n\tfmt.Println(n, name, age)\n```\n输出为：\n```bash\n\t2 polaris 28\n```\n不管\"polaris 28\"是用空格分隔还是\"\\n\"分隔，输出一样。也就是说，`Scan/FScan/Sscan` 这组函数将连续由空格分隔的值存储为连续的实参（换行符也记为空格）。\n\n2) Scanf/FScanf/Sscanf\n```go\n\tvar (\n\t\tname string\n\t\tage int\n\t)\n\tn, _ := fmt.Sscanf(\"polaris 28\", \"%s%d\", &name, &age)\n\t// 可以将\"polaris 28\"中的空格换成\"\\n\"试试\n\t// n, _ := fmt.Sscanf(\"polaris\\n28\", \"%s%d\", &name, &age)\n\tfmt.Println(n, name, age)\n```\n输出：\n```bash\n\t2 polaris 28\n```\n如果将\"空格\"分隔改为\"\\n\"分隔，则输出为：1 polaris 0。可见，`Scanf/FScanf/Sscanf` 这组函数将连续由空格分隔的值存储为连续的实参， 其格式由 `format` 决定，换行符处停止扫描(Scan)。\n\n3) Scanln/FScanln/Sscanln\n```go\n\tvar (\n\t\tname string\n\t\tage int\n\t)\n\tn, _ := fmt.Sscanln(\"polaris 28\", &name, &age)\n\t// 可以将\"polaris 28\"中的空格换成\"\\n\"试试\n\t// n, _ := fmt.Sscanln(\"polaris\\n28\", &name, &age)\n\tfmt.Println(n, name, age)\n```\n输出：\n```bash\t\n\t2 polaris 28\n```\n`Scanln/FScanln/Sscanln`表现和上一组一样，遇到\"\\n\"停止（对于Scanln，表示从标准输入获取内容，最后需要回车）。\n\n一般地，我们使用 `Scan/Scanf/Scanln` 这组函数。\n\n**提示**\n\n如果你是Windows系统，在使用 `Scanf` 时，有一个地方需要注意。看下面的代码：\n```go\n\tfor i := 0; i < 2; i++ {\n\t\tvar name string\n\t\tfmt.Print(\"Input Name:\")\n\t\tn, err := fmt.Scanf(\"%s\", &name)\n\t\tfmt.Println(n, err, name)\n\t}\n```\n编译、运行（或直接 go run )，输入：polaris 回车。控制台内如下：\n```bash\n\tInput Name:polaris\n\t1 polaris\n\tInput Name:0 unexpected newline\n```\n为什么不是让输入两次？第二次好像有默认值一样。\n\n同样的代码在Linux下正常。个人认为这是go在Windows下的一个bug，已经向官方提出：[issue5391](https://code.google.com/p/go/issues/detail?id=5391)。\n\n目前的解决方法是：换用Scanln或者改为Scanf(\"%s\\n\", &name)。\n\n## Scanner 和 ScanState 接口 ##\n\n基本上，我们不会去自己实现这两个接口，只需要使用上文中相应的 Scan 函数就可以了。这里只是简单的介绍一下这两个接口的作用。\n\n任何实现了 Scan 方法的对象都实现了 Scanner 接口，Scan 方法会从输入读取数据并将处理结果存入接收端，接收端必须是有效的指针。Scan 方法会被任何 Scan、Scanf、Scanln 等函数调用，只要对应的参数实现了该方法。Scan 方法接收的第一个参数为`ScanState`接口类型。\n\nScanState 是一个交给用户定制的 Scanner 接口的参数的接口。Scanner 接口可能会进行一次一个字符的扫描或者要求 ScanState 去探测下一个空白分隔的 token。该接口的方法基本上在 io 包中都有讲解，这里不赘述。\n\n在fmt包中，scan.go 文件中的 ss 结构实现了 ScanState 接口。\n## fmt/print.go 阅读\n\n### Fprint\n```go\nfunc Fprint(w io.Writer, a ...interface{}) (n int, err error) {\n\tp := newPrinter() // 实际工作结构\n\tp.doPrint(a)\n\tn, err = w.Write(p.buf)\n\tp.free()\n\treturn\n}\n```\n### newPrinter\n```go\n// printer 状态结构\ntype pp struct {\n\tbuf buffer\n\n\targ interface{}\n\n\tvalue reflect.Value\n\n\tfmt fmt\n\n\treordered bool\n\t\n\tgoodArgNum bool\n\t\n\tpanicking bool\n\t\n\terroring bool\n}\n\n// 通过 sync.Pool 复用，避免回收造成 GC\nvar ppFree = sync.Pool{\n\tNew: func() interface{} { return new(pp) },\n}\n\n// 分配或重用 pp 结构\nfunc newPrinter() *pp {\n\tp := ppFree.Get().(*pp)\n\tp.panicking = false\n\tp.erroring = false\n\tp.fmt.init(&p.buf)\n\treturn p\n}\n```\n\n### doPrint\n```go\nfunc (p *pp) doPrint(a []interface{}) {\n\tprevString := false\n\t\n\t// 获取可变参数索引及参数\n\tfor argNum, arg := range a {\n\t // reflect.TypeOf.Kind\n\t\tisString := arg != nil && reflect.TypeOf(arg).Kind() == reflect.String\n\t\t\n\t // 判断是否需要一个空格\n\t\tif argNum > 0 && !isString && !prevString {\n\t\t\tp.buf.WriteByte(' ')\n\t\t}\n\t\tp.printArg(arg, 'v')\n\t\tprevString = isString\n\t}\n}\n```\n\n### printArg\n```go\nfunc (p *pp) printArg(arg interface{}, verb rune) {\n\tp.arg = arg\n\tp.value = reflect.Value{}\n\n\tif arg == nil {\n\t\tswitch verb {\n\t\tcase 'T', 'v':\n\t\t\tp.fmt.padString(nilAngleString)\n\t\tdefault:\n\t\t\tp.badVerb(verb)\n\t\t}\n\t\treturn\n\t}\n\n\tswitch verb {\n\tcase 'T':\n\t\tp.fmt.fmt_s(reflect.TypeOf(arg).String())\n\t\treturn\n\tcase 'p':\n\t\tp.fmtPointer(reflect.ValueOf(arg), 'p')\n\t\treturn\n\t}\n\n\t// 类型判断\n\tswitch f := arg.(type) {\n\tcase bool:\n\t\tp.fmtBool(f, verb)\n\tcase float32:\n\t\tp.fmtFloat(float64(f), 32, verb)\n\tcase float64:\n\t\tp.fmtFloat(f, 64, verb)\n\tcase complex64:\n\t\tp.fmtComplex(complex128(f), 64, verb)\n\tcase complex128:\n\t\tp.fmtComplex(f, 128, verb)\n\tcase int:\n\t\tp.fmtInteger(uint64(f), signed, verb)\n\tcase int8:\n\t\tp.fmtInteger(uint64(f), signed, verb)\n\tcase int16:\n\t\tp.fmtInteger(uint64(f), signed, verb)\n\tcase int32:\n\t\tp.fmtInteger(uint64(f), signed, verb)\n\tcase int64:\n\t\tp.fmtInteger(uint64(f), signed, verb)\n\tcase uint:\n\t\tp.fmtInteger(uint64(f), unsigned, verb)\n\tcase uint8:\n\t\tp.fmtInteger(uint64(f), unsigned, verb)\n\tcase uint16:\n\t\tp.fmtInteger(uint64(f), unsigned, verb)\n\tcase uint32:\n\t\tp.fmtInteger(uint64(f), unsigned, verb)\n\tcase uint64:\n\t\tp.fmtInteger(f, unsigned, verb)\n\tcase uintptr:\n\t\tp.fmtInteger(uint64(f), unsigned, verb)\n\tcase string:\n\t\tp.fmtString(f, verb)\n\tcase []byte:\n\t\tp.fmtBytes(f, verb, \"[]byte\")\n\tcase reflect.Value:\n\t\t// Handle extractable values with special methods\n\t\t// since printValue does not handle them at depth 0.\n\t\tif f.IsValid() && f.CanInterface() {\n\t\t\tp.arg = f.Interface()\n\t\t\tif p.handleMethods(verb) {\n\t\t\t\treturn\n\t\t\t}\n\t\t}\n\t\tp.printValue(f, verb, 0)\n\tdefault:\n\t\t// If the type is not simple, it might have methods.\n\t\tif !p.handleMethods(verb) {\n\t\t\t// Need to use reflection, since the type had no\n\t\t\t// interface methods that could be used for formatting.\n\t\t\tp.printValue(reflect.ValueOf(f), verb, 0)\n\t\t}\n\t}\n}\n```\n\n# 导航 #\n\n- [目录](/preface.md)\n- 上一节：[ioutil — 方便的IO操作函数集](01.2.md)\n- 下一节：[bufio — 缓存IO](01.4.md)" }, { "path": "chapter01/01.4.md", "content": "# 1.4 bufio — 缓存IO #\n\nbufio 包实现了缓存IO。它包装了 io.Reader 和 io.Writer 对象，创建了另外的Reader和Writer对象，它们也实现了 io.Reader 和 io.Writer 接口，不过它们是有缓存的。该包同时为文本I/O提供了一些便利操作。\n\n## 1.4.1 Reader 类型和方法 ##\n\nbufio.Reader 结构包装了一个 io.Reader 对象，提供缓存功能，同时实现了 io.Reader 接口。\n\nReader 结构没有任何导出的字段，结构定义如下：\n```go\n\ttype Reader struct {\n\t\tbuf []byte\t\t// 缓存\n\t\trd io.Reader\t// 底层的io.Reader\n\t\t// r:从buf中读走的字节（偏移）；w:buf中填充内容的偏移；\n\t\t// w - r 是buf中可被读的长度（缓存数据的大小），也是Buffered()方法的返回值\n\t\tr, w int\n\t\terr error\t\t// 读过程中遇到的错误\n\t\tlastByte int\t\t// 最后一次读到的字节（ReadByte/UnreadByte)\n\t\tlastRuneSize int\t\t// 最后一次读到的Rune的大小 (ReadRune/UnreadRune)\n\t}\n```\n\n### 1.4.1.1 实例化 ###\n\nbufio 包提供了两个实例化 bufio.Reader 对象的函数：NewReader 和 NewReaderSize。其中，NewReader 函数是调用 NewReaderSize 函数实现的：\n```go\n\tfunc NewReader(rd io.Reader) *Reader {\n\t\t// 默认缓存大小：defaultBufSize=4096\n\t\treturn NewReaderSize(rd, defaultBufSize)\n\t}\n```\n我们看一下NewReaderSize的源码：\n```go\n\tfunc NewReaderSize(rd io.Reader, size int) *Reader {\n\t\t// 已经是bufio.Reader类型，且缓存大小不小于 size，则直接返回\n\t\tb, ok := rd.(*Reader)\n\t\tif ok && len(b.buf) >= size {\n\t\t\treturn b\n\t\t}\n\t\t// 缓存大小不会小于 minReadBufferSize （16字节）\n\t\tif size < minReadBufferSize {\n\t\t\tsize = minReadBufferSize\n\t\t}\n\t\t// 构造一个bufio.Reader实例\n\t\treturn &Reader{\n\t\t\tbuf: make([]byte, size),\n\t\t\trd: rd,\n\t\t\tlastByte: -1,\n\t\t\tlastRuneSize: -1,\n\t\t}\n\t}\n```\n### 1.4.1.2 ReadSlice、ReadBytes、ReadString 和 ReadLine 方法 ###\n\n之所以将这几个方法放在一起，是因为他们有着类似的行为。事实上，后三个方法最终都是调用ReadSlice来实现的。所以，我们先来看看ReadSlice方法。(感觉这一段直接看源码较好)\n\n**ReadSlice方法签名**如下：\n```go\n\tfunc (b *Reader) ReadSlice(delim byte) (line []byte, err error)\n```\nReadSlice 从输入中读取，直到遇到第一个界定符（delim）为止，返回一个指向缓存中字节的 slice，在下次调用读操作（read）时，这些字节会无效。举例说明：\n```go\n\treader := bufio.NewReader(strings.NewReader(\"http://studygolang.com. \\nIt is the home of gophers\"))\n\tline, _ := reader.ReadSlice('\\n')\n\tfmt.Printf(\"the line:%s\\n\", line)\n\t// 这里可以换上任意的 bufio 的 Read/Write 操作\n\tn, _ := reader.ReadSlice('\\n')\n\tfmt.Printf(\"the line:%s\\n\", line)\n\tfmt.Println(string(n))\n```\n输出：\n```bash\n\tthe line:http://studygolang.com. \n\t\n\tthe line:It is the home of gophers\n\tIt is the home of gophers\n```\n从结果可以看出，第一次ReadSlice的结果（line），在第二次调用读操作后，内容发生了变化。也就是说，ReadSlice 返回的 []byte 是指向 Reader 中的 buffer ，而不是 copy 一份返回。正因为ReadSlice 返回的数据会被下次的 I/O 操作重写，因此许多的客户端会选择使用 ReadBytes 或者 ReadString 来代替。读者可以将上面代码中的 ReadSlice 改为 ReadBytes 或 ReadString ，看看结果有什么不同。\n\n注意，这里的界定符可以是任意的字符，可以将上面代码中的'\\n'改为'm'试试。同时，返回的结果是包含界定符本身的，上例中，输出结果有一空行就是'\\n'本身(line携带一个'\\n',printf又追加了一个'\\n')。\n\n如果 ReadSlice 在找到界定符之前遇到了 error ，它就会返回缓存中所有的数据和错误本身（经常是 io.EOF）。如果在找到界定符之前缓存已经满了，ReadSlice 会返回 bufio.ErrBufferFull 错误。当且仅当返回的结果（line）没有以界定符结束的时候，ReadSlice 返回err != nil，也就是说，如果ReadSlice 返回的结果 line 不是以界定符 delim 结尾，那么返回的 er r也一定不等于 nil（可能是bufio.ErrBufferFull或io.EOF）。\n例子代码：\n```go\n\treader := bufio.NewReaderSize(strings.NewReader(\"http://studygolang.com\"),16)\n\tline, err := reader.ReadSlice('\\n')\n\tfmt.Printf(\"line:%s\\terror:%s\\n\", line, err)\n\tline, err = reader.ReadSlice('\\n')\n\tfmt.Printf(\"line:%s\\terror:%s\\n\", line, err)\n```\n输出：\n```bash\n\tline:http://studygola\terror:bufio: buffer full\n\tline:ng.com\terror:EOF\n```\n**ReadBytes方法签名**如下：\n```go\n\tfunc (b *Reader) ReadBytes(delim byte) (line []byte, err error)\n```\n该方法的参数和返回值类型与 ReadSlice 都一样。 ReadBytes 从输入中读取直到遇到界定符（delim）为止，返回的 slice 包含了从当前到界定符的内容 **（包括界定符）**。如果 ReadBytes 在遇到界定符之前就捕获到一个错误，它会返回遇到错误之前已经读取的数据，和这个捕获到的错误（经常是 io.EOF）。跟 ReadSlice 一样，如果 ReadBytes 返回的结果 line 不是以界定符 delim 结尾，那么返回的 err 也一定不等于 nil（可能是bufio.ErrBufferFull 或 io.EOF）。\n\n从这个说明可以看出，ReadBytes和ReadSlice功能和用法都很像，那他们有什么不同呢？\n\n在讲解ReadSlice时说到，它返回的 []byte 是指向 Reader 中的 buffer，而不是 copy 一份返回，也正因为如此，通常我们会使用 ReadBytes 或 ReadString。很显然，ReadBytes 返回的 []byte 不会是指向 Reader 中的 buffer，通过[查看源码](http://docscn.studygolang.com/src/bufio/bufio.go?s=10277:10340#L338)可以证实这一点。\n\n还是上面的例子，我们将 ReadSlice 改为 ReadBytes：\n```go\n\treader := bufio.NewReader(strings.NewReader(\"http://studygolang.com. \\nIt is the home of gophers\"))\n\tline, _ := reader.ReadBytes('\\n')\n\tfmt.Printf(\"the line:%s\\n\", line)\n\t// 这里可以换上任意的 bufio 的 Read/Write 操作\n\tn, _ := reader.ReadBytes('\\n')\n\tfmt.Printf(\"the line:%s\\n\", line)\n\tfmt.Println(string(n))\n```\n输出：\n```bash\n\tthe line:http://studygolang.com. \n\n\tthe line:http://studygolang.com. \n\t\n\tIt is the home of gophers\n```\n**ReadString方法**\n\n看一下该方法的源码：\n```go\n\tfunc (b *Reader) ReadString(delim byte) (line string, err error) {\n\t\tbytes, err := b.ReadBytes(delim)\n\t\treturn string(bytes), err\n\t}\n```\n它调用了 ReadBytes 方法，并将结果的 []byte 转为 string 类型。\n\n**ReadLine方法签名**如下\n```go\n\tfunc (b *Reader) ReadLine() (line []byte, isPrefix bool, err error)\n```\nReadLine 是一个底层的原始行读取命令。许多调用者或许会使用 ReadBytes('\\n') 或者 ReadString('\\n') 来代替这个方法。\n\nReadLine 尝试返回单独的行，不包括行尾的换行符。如果一行大于缓存，isPrefix 会被设置为 true，同时返回该行的开始部分（等于缓存大小的部分）。该行剩余的部分就会在下次调用的时候返回。当下次调用返回该行剩余部分时，isPrefix 将会是 false 。跟 ReadSlice 一样，返回的 line 只是 buffer 的引用，在下次执行IO操作时，line 会无效。可以将 ReadSlice 中的例子该为 ReadLine 试试。\n\n注意，返回值中，要么 line 不是 nil，要么 err 非 nil，两者不会同时非 nil。\n\nReadLine 返回的文本不会包含行结尾（\"\\r\\n\"或者\"\\n\"）。如果输入中没有行尾标识符，不会返回任何指示或者错误。\n\n从上面的讲解中，我们知道，读取一行，通常会选择 ReadBytes 或 ReadString。不过，正常人的思维，应该用 ReadLine，只是不明白为啥 ReadLine 的实现不是通过 ReadBytes，然后清除掉行尾的\\\\n（或\\r\\n），它现在的实现，用不好会出现意想不到的问题，比如丢数据。个人建议可以这么实现读取一行：\n```go\n\tline, err := reader.ReadBytes('\\n')\n\tline = bytes.TrimRight(line, \"\\r\\n\")\n```\n这样既读取了一行，也去掉了行尾结束符（当然，如果你希望留下行尾结束符，只用ReadBytes即可）。\n\n### 1.4.1.3 Peek 方法 ###\n\n从方法的名称可以猜到，该方法只是“窥探”一下 Reader 中没有读取的 n 个字节。好比栈数据结构中的取栈顶元素，但不出栈。\n\n方法的签名如下：\n```go\n\tfunc (b *Reader) Peek(n int) ([]byte, error)\n```\n同上面介绍的 ReadSlice一样，返回的 []byte 只是 buffer 中的引用，在下次IO操作后会无效，可见该方法（以及ReadSlice这样的，返回buffer引用的方法）对多 goroutine 是不安全的，也就是在多并发环境下，不能依赖其结果。\n\n我们通过例子来证明一下：\n```go\n\tpackage main\n\n\timport (\n\t \"bufio\"\n\t \"fmt\"\n\t \"strings\"\n\t \"time\"\n\t)\n\t\n\tfunc main() {\n\t reader := bufio.NewReaderSize(strings.NewReader(\"http://studygolang.com.\\t It is the home of gophers\"), 14)\n\t go Peek(reader)\n\t go reader.ReadBytes('\\t')\n\t time.Sleep(1e8)\n\t}\n\t\n\tfunc Peek(reader *bufio.Reader) {\n\t line, _ := reader.Peek(14)\n\t fmt.Printf(\"%s\\n\", line)\n\t // time.Sleep(1)\n\t fmt.Printf(\"%s\\n\", line)\n\t}\n```\n输出：\n```bash\n\thttp://studygo\n\thttp://studygo\n```\n输出结果和预期的一致。然而，这是由于目前的 goroutine 调度方式导致的结果。如果我们将例子中注释掉的 time.Sleep(1) 取消注释（这样调度其他 goroutine 执行），再次运行，得到的结果为：\n```bash\n\thttp://studygo\n\tng.com.\t It is\n```\n另外，Reader 的 Peek 方法如果返回的 []byte 长度小于 n，这时返回的 `err != nil` ，用于解释为啥会小于 n。如果 n 大于 reader 的 buffer 长度，err 会是 ErrBufferFull。\n\n### 1.4.1.4 其他方法 ###\n\nReader 的其他方法都是实现了 io 包中的接口，它们的使用方法在io包中都有介绍，在此不赘述。\n\n这些方法包括：\n```go\n\tfunc (b *Reader) Read(p []byte) (n int, err error)\n\tfunc (b *Reader) ReadByte() (c byte, err error)\n\tfunc (b *Reader) ReadRune() (r rune, size int, err error)\n\tfunc (b *Reader) UnreadByte() error\n\tfunc (b *Reader) UnreadRune() error\n\tfunc (b *Reader) WriteTo(w io.Writer) (n int64, err error)\n```\n你应该知道它们都是哪个接口的方法吧。\n\n## 1.4.2 Scanner 类型和方法 ##\n\n对于简单的读取一行，在 Reader 类型中，感觉没有让人特别满意的方法。于是，Go1.1增加了一个类型：Scanner。官方关于**Go1.1**增加该类型的说明如下：\n\n> 在 bufio 包中有多种方式获取文本输入，ReadBytes、ReadString 和独特的 ReadLine，对于简单的目的这些都有些过于复杂了。在 Go 1.1 中，添加了一个新类型，Scanner，以便更容易的处理如按行读取输入序列或空格分隔单词等，这类简单的任务。它终结了如输入一个很长的有问题的行这样的输入错误，并且提供了简单的默认行为：基于行的输入，每行都剔除分隔标识。这里的代码展示一次输入一行：\n```go\n\tscanner := bufio.NewScanner(os.Stdin)\n\tfor scanner.Scan() {\n\t fmt.Println(scanner.Text()) // Println will add back the final '\\n'\n\t}\n\tif err := scanner.Err(); err != nil {\n\t fmt.Fprintln(os.Stderr, \"reading standard input:\", err)\n\t}\n```\n> 输入的行为可以通过一个函数控制，来控制输入的每个部分（参阅 SplitFunc 的文档），但是对于复杂的问题或持续传递错误的，可能还是需要原有接口。\n\nScanner 类型和 Reader 类型一样，没有任何导出的字段，同时它也包装了一个 io.Reader 对象，但它没有实现 io.Reader 接口。\n\nScanner 的结构定义如下：\n\n\ttype Scanner struct {\n\t\tr io.Reader // The reader provided by the client.\n\t\tsplit SplitFunc // The function to split the tokens.\n\t\tmaxTokenSize int // Maximum size of a token; modified by tests.\n\t\ttoken []byte // Last token returned by split.\n\t\tbuf []byte // Buffer used as argument to split.\n\t\tstart int // First non-processed byte in buf.\n\t\tend int // End of data in buf.\n\t\terr error // Sticky error.\n\t}\n\n这里 split、maxTokenSize 和 token 需要讲解一下。\n\n然而，在讲解之前，需要先讲解 split 字段的类型 SplitFunc。\n\n### 1.4.2.1 SplitFunc 类型和实例 ###\n\n**SplitFunc 类型定义**如下：\n```go\n\ttype SplitFunc func(data []byte, atEOF bool) (advance int, token []byte, err error)\n```\nSplitFunc 定义了 用于对输入进行分词的 split 函数的签名。参数 data 是还未处理的数据，atEOF 标识 Reader 是否还有更多数据（是否到了EOF）。返回值 advance 表示从输入中读取的字节数，token 表示下一个结果数据，err 则代表可能的错误。\n\n举例说明一下这里的 token 代表的意思：\n\n\t有数据 \"studygolang\\tpolaris\\tgolangchina\"，通过\"\\t\"进行分词，那么会得到三个token，它们的内容分别是：studygolang、polaris 和 golangchina。而 SplitFunc 的功能是：进行分词，并返回未处理的数据中第一个 token。对于这个数据，就是返回 studygolang。\n\n如果 data 中没有一个完整的 token，例如，在扫描行（scanning lines）时没有换行符，SplitFunc 会返回(0,nil,nil)通知 Scanner 读取更多数据到 slice 中，然后在这个更大的 slice 中同样的读取点处，从输入中重试读取。如下面要讲解的 split 函数的源码中有这样的代码：\n```go\n\t// Request more data.\n\treturn 0, nil, nil\n```\n如果 `err != nil`，扫描停止，同时该错误会返回。\n\n如果参数 data 为空的 slice，除非 atEOF 为 true，否则该函数永远不会被调用。如果 atEOF 为 true，这时 data 可以非空，这时的数据是没有处理的。\n\n**bufio 包定义的 split 函数，即 SplitFunc 的实例**\n\n在 bufio 包中预定义了一些 split 函数，也就是说，在 Scanner 结构中的 split 字段，可以通过这些预定义的 split 赋值，同时 Scanner 类型的 Split 方法也可以接收这些预定义函数作为参数。所以，我们可以说，这些预定义 split 函数都是 SplitFunc 类型的实例。这些函数包括：ScanBytes、ScanRunes、ScanWords 和 ScanLines。（由于都是 SplitFunc 的实例，自然这些函数的签名都和 SplitFunc 一样）\n\n**ScanBytes** 返回单个字节作为一个 token。\n\n**ScanRunes** 返回单个 UTF-8 编码的 rune 作为一个 token。返回的 rune 序列（token）和 range string类型 返回的序列是等价的，也就是说，对于无效的 UTF-8 编码会解释为 U+FFFD = \"\\xef\\xbf\\xbd\"。\n\n**ScanWords** 返回通过“空格”分词的单词。如：study golang，调用会返回study。注意，这里的“空格”是 `unicode.IsSpace()`，即包括：'\\t', '\\n', '\\v', '\\f', '\\r', ' ', U+0085 (NEL), U+00A0 (NBSP)。\n\n**ScanLines** 返回一行文本，不包括行尾的换行符。这里的换行包括了Windows下的\"\\r\\n\"和Unix下的\"\\n\"。\n\n一般地，我们不会单独使用这些函数，而是提供给 Scanner 实例使用。现在我们回到 Scanner 的 split、maxTokenSize 和 token 字段上来。\n\n**split 字段**（SplitFunc 类型实例），很显然，代表了当前 Scanner 使用的分词策略，可以使用上面介绍的预定义 SplitFunc 实例赋值，也可以自定义 SplitFunc 实例。（当然，要给 split 字段赋值，必须调用 Scanner 的 Split 方法）\n\n**maxTokenSize 字段** 表示通过 split 分词后的一个 token 允许的最大长度。在该包中定义了一个常量 MaxScanTokenSize = 64 * 1024，这是允许的最大 token 长度（64k）。\n\n**token 字段** 上文已经解释了这个是什么意思。\n\n### 1.4.2.2 Scanner 的实例化 ###\n\nScanner 没有导出任何字段，而它需要有外部的 io.Reader 对象，因此，我们不能直接实例化 Scanner 对象，必须通过 bufio 包提供的实例化函数来实例化。实例化函数签名以及内部实现：\n```go\n\tfunc NewScanner(r io.Reader) *Scanner {\n\t\treturn &Scanner{\n\t\t\tr: r,\n\t\t\tsplit: ScanLines,\n\t\t\tmaxTokenSize: MaxScanTokenSize,\n\t\t\tbuf: make([]byte, 4096), // Plausible starting size; needn't be large.\n\t\t}\n\t}\n```\n可见，返回的 Scanner 实例默认的 split 函数是 ScanLines。\n\n### 1.4.2.2 Scanner 的方法 ###\n\n**Split 方法** 前面我们提到过可以通过 Split 方法为 Scanner 实例设置分词行为。由于 Scanner 实例的默认 split 总是 ScanLines，如果我们想要用其他的 split，可以通过 Split 方法做到。\n\n比如，我们想要统计一段英文有多少个单词（不排除重复），我们可以这么做：\n```go\n\tconst input = \"This is The Golang Standard Library.\\nWelcome you!\"\n\tscanner := bufio.NewScanner(strings.NewReader(input))\n\tscanner.Split(bufio.ScanWords)\n\tcount := 0\n\tfor scanner.Scan() {\n\t\tcount++\n\t}\n\tif err := scanner.Err(); err != nil {\n\t\tfmt.Fprintln(os.Stderr, \"reading input:\", err)\n\t}\n\tfmt.Println(count)\n```\n输出：\n```bash\n\t8\n```\n我们实例化 Scanner 后，通过调用 scanner.Split(bufio.ScanWords) 来更改 split 函数。注意，我们应该在调用 Scan 方法之前调用 Split 方法。\n\n**Scan 方法** 该方法好比 iterator 中的 Next 方法，它用于将 Scanner 获取下一个 token，以便 Bytes 和 Text 方法可用。当扫描停止时，它返回false，这时候，要么是到了输入的末尾要么是遇到了一个错误。注意，当 Scan 返回 false 时，通过 Err 方法可以获取第一个遇到的错误（但如果错误是 io.EOF，Err 方法会返回 nil）。\n\n**Bytes 和 Text 方法** 这两个方法的行为一致，都是返回最近的 token，无非 Bytes 返回的是 []byte，Text 返回的是 string。该方法应该在 Scan 调用后调用，而且，下次调用 Scan 会覆盖这次的 token。比如：\n```go\n\tscanner := bufio.NewScanner(strings.NewReader(\"http://studygolang.com. \\nIt is the home of gophers\"))\n\tif scanner.Scan() {\n\t\tscanner.Scan()\n\t\tfmt.Printf(\"%s\", scanner.Text())\n\t}\n```\n返回的是：`It is the home of gophers` 而不是 `http://studygolang.com.`\n\n**Err 方法** 前面已经提到，通过 Err 方法可以获取第一个遇到的错误（但如果错误是 io.EOF，Err 方法会返回 nil）。\n\n下面，我们通过一个完整的示例来演示 Scanner 类型的使用。\n\n### 1.4.2.3 Scanner 使用示例 ###\n\n我们经常会有这样的需求：读取文件中的数据，一次读取一行。在学习了 Reader 类型，我们可以使用它的 ReadBytes 或 ReadString来实现，甚至使用 ReadLine 来实现。然而，在 Go1.1 中，我们可以使用 Scanner 来做这件事，而且更简单好用。\n```go\n\tfile, err := os.Create(\"scanner.txt\")\n\tif err != nil {\n\t panic(err)\n\t}\n\tdefer file.Close()\n\tfile.WriteString(\"http://studygolang.com.\\nIt is the home of gophers.\\nIf you are studying golang, welcome you!\")\n\t// 将文件 offset 设置到文件开头\n\tfile.Seek(0, os.SEEK_SET)\n\tscanner := bufio.NewScanner(file)\n\tfor scanner.Scan() {\n\t\tfmt.Println(scanner.Text())\n\t}\n```\n输出结果：\n```bash\n\thttp://studygolang.com.\n\tIt is the home of gophers.\n\tIf you are studying golang, welcome you!\n```\n## 1.4.3 Writer 类型和方法 ##\n\nbufio.Writer 结构包装了一个 io.Writer 对象，提供缓存功能，同时实现了 io.Writer 接口。\n\nWriter 结构没有任何导出的字段，结构定义如下：\n```go\n\ttype Writer struct {\n\t\terr error\t\t// 写过程中遇到的错误\n\t\tbuf []byte\t\t// 缓存\n\t\tn int\t\t\t// 当前缓存中的字节数\n\t\twr io.Writer\t// 底层的 io.Writer 对象\n\t}\n```\n相比 bufio.Reader, bufio.Writer 结构定义简单很多。\n\n注意：如果在写数据到 Writer 的时候出现了一个错误，不会再允许有数据被写进来了，并且所有随后的写操作都会返回该错误。\n\n### 1.4.3.1 实例化 ###\n\n和 Reader 类型一样，bufio 包提供了两个实例化 bufio.Writer 对象的函数：NewWriter 和 NewWriterSize。其中，NewWriter 函数是调用 NewWriterSize 函数实现的：\n```go\n\tfunc NewWriter(wr io.Writer) *Writer {\n\t\t// 默认缓存大小：defaultBufSize=4096\n\t\treturn NewWriterSize(wr, defaultBufSize)\n\t}\n```\n我们看一下 NewWriterSize 的源码：\n```go\n\tfunc NewWriterSize(wr io.Writer, size int) *Writer {\n\t\t// 已经是 bufio.Writer 类型，且缓存大小不小于 size，则直接返回\n\t\tb, ok := wr.(*Writer)\n\t\tif ok && len(b.buf) >= size {\n\t\t\treturn b\n\t\t}\n\t\tif size <= 0 {\n\t\t\tsize = defaultBufSize\n\t\t}\n\t\treturn &Writer{\n\t\t\tbuf: make([]byte, size),\n\t\t\twr: w,\n\t\t}\n\t}\n```\n### 1.4.3.2 Available 和 Buffered 方法 ###\n\nAvailable 方法获取缓存中还未使用的字节数（缓存大小 - 字段 n 的值）；Buffered 方法获取写入当前缓存中的字节数（字段 n 的值）\n\n### 1.4.3.3 Flush 方法 ###\n\n该方法将缓存中的所有数据写入底层的 io.Writer 对象中。使用 bufio.Writer 时，在所有的 Write 操作完成之后，应该调用 Flush 方法使得缓存都写入 io.Writer 对象中。\n\n### 1.4.3.4 其他方法 ###\n\nWriter 类型其他方法是一些实际的写方法：\n```go\n\t// 实现了 io.ReaderFrom 接口\n\tfunc (b *Writer) ReadFrom(r io.Reader) (n int64, err error)\n\t\n\t// 实现了 io.Writer 接口\n\tfunc (b *Writer) Write(p []byte) (nn int, err error)\n\t\n\t// 实现了 io.ByteWriter 接口\n\tfunc (b *Writer) WriteByte(c byte) error\n\t\n\t// io 中没有该方法的接口，它用于写入单个 Unicode 码点，返回写入的字节数（码点占用的字节），内部实现会根据当前 rune 的范围调用 WriteByte 或 WriteString\n\tfunc (b *Writer) WriteRune(r rune) (size int, err error)\n\t\n\t// 写入字符串，如果返回写入的字节数比 len(s) 小，返回的error会解释原因\n\tfunc (b *Writer) WriteString(s string) (int, error)\n```\n这些写方法在缓存满了时会调用 Flush 方法。另外，这些写方法源码开始处，有这样的代码：\n```go\n\tif b.err != nil {\n\t\treturn b.err\n\t}\n```\n也就是说，只要写的过程中遇到了错误，再次调用写操作会直接返回该错误。\n\n## 1.4.4 ReadWriter 类型和实例化 ##\n\nReadWriter 结构存储了 bufio.Reader 和 bufio.Writer 类型的指针（内嵌），它实现了 io.ReadWriter 结构。\n```\n\ttype ReadWriter struct {\n\t\t*Reader\n\t\t*Writer\n\t}\n```\nReadWriter 的实例化可以跟普通结构类型一样，也可以通过调用 bufio.NewReadWriter 函数来实现：只是简单的实例化 ReadWriter\n```\n\tfunc NewReadWriter(r *Reader, w *Writer) *ReadWriter {\n\t\treturn &ReadWriter{r, w}\n\t}\n```\n# 导航 #\n\n- [目录](/preface.md)\n- 上一节：[fmt — 格式化IO](01.3.md)\n- 下一节：[I/O 总结](01.5.md)\n" }, { "path": "chapter02/02.0.md", "content": "# 第二章 文本 #\n\n几乎任何程序都离不开文本（字符串）。Go 中 string 是内置类型，同时它与普通的 slice 类型有着相似的性质，例如，可以进行切片（slice）操作，这使得 Go 中少了一些处理 string 类型的函数，比如没有 substring 这样的函数，然而却能够很方便的进行这样的操作。除此之外，Go 标准库中有几个包专门用于处理文本。\n\n*strings* 包提供了很多操作字符串的简单函数，通常一般的字符串操作需求都可以在这个包中找到。\n\n*strconv* 包提供了基本数据类型和字符串之间的转换。在 Go 中，没有隐式类型转换，一般的类型转换可以这么做：int32(i)，将 i （比如为 int 类型）转换为 int32，然而，字符串类型和 int、float、bool 等类型之间的转换却没有这么简单。\n\n进行复杂的文本处理必然离不开正则表达式。*regexp* 包提供了正则表达式功能，它的语法基于 [RE2](http://code.google.com/p/re2/wiki/Syntax) ，*regexp/syntax* 子包进行正则表达式解析。\n\nGo 代码使用 UTF-8 编码（且不能带 BOM），同时标识符支持 Unicode 字符。在标准库 *unicode* 包及其子包 utf8、utf16 中，提供了对 Unicode 相关编码、解码的支持，同时提供了测试 Unicode 码点（Unicode code points）属性的功能。\n\n在开发过程中，可能涉及到字符集的转换，作为补充，本章最后会讲解一个第三方库：mahonia — 纯 Go 语言实现的字符集转换库，以方便需要进行字符集转换的读者。\n\n# 导航 #\n\n- [第一章](/chapter01/01.0.md)\n- 下一节：[strings — 字符串操作](02.1.md)\n" }, { "path": "chapter02/02.1.md", "content": "# 2.1 strings — 字符串操作 #\n\n 字符串常见操作有：\n\n - 字符串长度；\n - 求子串；\n - 是否存在某个字符或子串；\n - 子串出现的次数（字符串匹配）；\n - 字符串分割（切分）为[]string；\n - 字符串是否有某个前缀或后缀；\n - 字符或子串在字符串中首次出现的位置或最后一次出现的位置；\n - 通过某个字符串将[]string 连接起来；\n - 字符串重复几次；\n - 字符串中子串替换；\n - 大小写转换；\n - Trim 操作；\n - ...\n\n 前面已经说过，由于 string 类型可以看成是一种特殊的 slice 类型，因此获取长度可以用内置的函数 len；同时支持 切片 操作，因此，子串获取很容易。\n\n 其他的字符串常见操作就是我们这小节要介绍的，由于这些操作函数的使用比较简单，只会对某些函数举例说明；但会深入这些函数的内部实现，更好的掌握它们。\n\n 说明：这里说的字符，指得是 rune 类型，即一个 UTF-8 字符（Unicode 代码点）。\n\n\n## 2.1.1 字符串比较 ##\n \n```go\n // Compare 函数，用于比较两个字符串的大小，如果两个字符串相等，返回为 0。如果 a 小于 b ，返回 -1 ，反之返回 1 。不推荐使用这个函数，直接使用 == != > < >= <= 等一系列运算符更加直观。\n func Compare(a, b string) int \n // EqualFold 函数，计算 s 与 t 忽略字母大小写后是否相等。\n func EqualFold(s, t string) bool\n```\n \n示例：\n \n```go\na := \"gopher\"\nb := \"hello world\"\nfmt.Println(strings.Compare(a, b))\nfmt.Println(strings.Compare(a, a))\nfmt.Println(strings.Compare(b, a))\n\nfmt.Println(strings.EqualFold(\"GO\", \"go\"))\nfmt.Println(strings.EqualFold(\"壹\", \"一\"))\n```\n \n输出结果：\n```bash\n-1\n0\n1\ntrue\nfalse\n```\n \n \n## 2.1.2 是否存在某个字符或子串 ##\n\n有三个函数做这件事：\n```go\n// 子串 substr 在 s 中，返回 true\nfunc Contains(s, substr string) bool\n// chars 中任何一个 Unicode 代码点在 s 中，返回 true\nfunc ContainsAny(s, chars string) bool\n// Unicode 代码点 r 在 s 中，返回 true\nfunc ContainsRune(s string, r rune) bool\n```\n这里对 ContainsAny 函数进行一下说明，看如下例子：\n```go\nfmt.Println(strings.ContainsAny(\"team\", \"i\"))\nfmt.Println(strings.ContainsAny(\"failure\", \"u & i\"))\nfmt.Println(strings.ContainsAny(\"in failure\", \"s g\"))\nfmt.Println(strings.ContainsAny(\"foo\", \"\"))\nfmt.Println(strings.ContainsAny(\"\", \"\"))\n```\n输出：\n```bash\nfalse\ntrue\ntrue\nfalse\nfalse\n```\n也就是说，第二个参数 chars 中任意一个字符（Unicode Code Point）如果在第一个参数 s 中存在，则返回 true。\n\n查看这三个函数的源码，发现它们只是调用了相应的 Index 函数（子串出现的位置），然后和 0 作比较返回 true 或 fale。如，Contains：\n```go\nfunc Contains(s, substr string) bool {\n return Index(s, substr) >= 0\n}\n```\n关于 Index 相关函数的实现，我们后面介绍。\n\n\n## 2.1.3 子串出现次数 ( 字符串匹配 ) ##\n\n在数据结构与算法中，可能会讲解以下字符串匹配算法：\n\n- 朴素匹配算法\n- KMP 算法\n- Rabin-Karp 算法\n- Boyer-Moore 算法\n\n还有其他的算法，这里不一一列举，感兴趣的可以网上搜一下。\n\n在 Go 中，查找子串出现次数即字符串模式匹配，实现的是 Rabin-Karp 算法。Count 函数的签名如下：\n```go\nfunc Count(s, sep string) int\n```\n\n在 Count 的实现中，处理了几种特殊情况，属于字符匹配预处理的一部分。这里要特别说明一下的是当 sep 为空时，Count 的返回值是：utf8.RuneCountInString(s) + 1\n```go\nfmt.Println(strings.Count(\"cheese\", \"e\"))\nfmt.Println(len(\"谷歌中国\"))\nfmt.Println(strings.Count(\"谷歌中国\", \"\"))\n```\n\n 输出：\n```bash\n3\n12 \n5 \n```\n\n关于 Rabin-Karp 算法的实现，有兴趣的可以看看 Count 的源码。\n\n另外，Count 是计算子串在字符串中出现的无重叠的次数，比如：\n```go\nfmt.Println(strings.Count(\"fivevev\", \"vev\"))\n```\n\n输出：\n```bash\n1\n```\n\n\n## 2.1.4 字符串分割为[]string ##\n\n这个需求很常见，倒不一定是为了得到[]string。\n\n该包提供了六个三组分割函数：Fields 和 FieldsFunc、Split 和 SplitAfter、SplitN 和 SplitAfterN。\n\n### 2.1.3.1 Fields 和 FieldsFunc ###\n\n这两个函数的签名如下：\n```go\nfunc Fields(s string) []string\nfunc FieldsFunc(s string, f func(rune) bool) []string\n```\n\nFields 用一个或多个连续的空格分隔字符串 s，返回子字符串的数组（slice）。如果字符串 s 只包含空格，则返回空列表 ([]string 的长度为 0）。其中，空格的定义是 unicode.IsSpace，之前已经介绍过。\n\n常见间隔符包括：'\\t', '\\n', '\\v', '\\f', '\\r', ' ', U+0085 (NEL), U+00A0 (NBSP)\n\n由于是用空格分隔，因此结果中不会含有空格或空子字符串，例如：\n```go\nfmt.Printf(\"Fields are: %q\", strings.Fields(\" foo bar baz \"))\n```\n\n输出结果：\n```bash\nFields are: [\"foo\" \"bar\" \"baz\"]\n```\n\nFieldsFunc 用这样的 Unicode 代码点 c 进行分隔：满足 f(c) 返回 true。该函数返回[]string。如果字符串 s 中所有的代码点 (unicode code points) 都满足 f(c) 或者 s 是空，则 FieldsFunc 返回空 slice。\n\n也就是说，我们可以通过实现一个回调函数来指定分隔字符串 s 的字符。比如上面的例子，我们通过 FieldsFunc 来实现：\n```go\nfmt.Println(strings.FieldsFunc(\" foo bar baz \", unicode.IsSpace))\n```\n\n实际上，Fields 函数就是调用 FieldsFunc 实现的：\n```go\nfunc Fields(s string) []string {\n return FieldsFunc(s, unicode.IsSpace)\n}\n```\n\n\n### 2.1.3.2 Split 和 SplitAfter、 SplitN 和 SplitAfterN ###\n\n之所以将这四个函数放在一起讲，是因为它们都是通过一个同一个内部函数来实现的。它们的函数签名及其实现：\n```go\nfunc Split(s, sep string) []string { return genSplit(s, sep, 0, -1) }\nfunc SplitAfter(s, sep string) []string { return genSplit(s, sep, len(sep), -1) }\nfunc SplitN(s, sep string, n int) []string { return genSplit(s, sep, 0, n) }\nfunc SplitAfterN(s, sep string, n int) []string { return genSplit(s, sep, len(sep), n) }\n```\n\n它们都调用了 genSplit 函数。\n\n这四个函数都是通过 sep 进行分割，返回[]string。如果 sep 为空，相当于分成一个个的 UTF-8 字符，如 `Split(\"abc\",\"\")`，得到的是[a b c]。\n\nSplit(s, sep) 和 SplitN(s, sep, -1) 等价；SplitAfter(s, sep) 和 SplitAfterN(s, sep, -1) 等价。\n\n那么，Split 和 SplitAfter 有啥区别呢？通过这两句代码的结果就知道它们的区别了：\n```go\nfmt.Printf(\"%q\\n\", strings.Split(\"foo,bar,baz\", \",\"))\nfmt.Printf(\"%q\\n\", strings.SplitAfter(\"foo,bar,baz\", \",\"))\n```\n\n输出：\n```bash\n[\"foo\" \"bar\" \"baz\"]\n[\"foo,\" \"bar,\" \"baz\"]\n```\n也就是说，Split 会将 s 中的 sep 去掉，而 SplitAfter 会保留 sep。\n\n带 N 的方法可以通过最后一个参数 n 控制返回的结果中的 slice 中的元素个数，当 n < 0 时，返回所有的子字符串；当 n == 0 时，返回的结果是 nil；当 n > 0 时，表示返回的 slice 中最多只有 n 个元素，其中，最后一个元素不会分割，比如：\n```go\nfmt.Printf(\"%q\\n\", strings.SplitN(\"foo,bar,baz\", \",\", 2))\n```\n\n输出：\n```bash\n[\"foo\" \"bar,baz\"]\n```\n\n另外看一下官方文档提供的例子，注意一下输出结果：\n```go\nfmt.Printf(\"%q\\n\", strings.Split(\"a,b,c\", \",\"))\nfmt.Printf(\"%q\\n\", strings.Split(\"a man a plan a canal panama\", \"a \"))\nfmt.Printf(\"%q\\n\", strings.Split(\" xyz \", \"\"))\nfmt.Printf(\"%q\\n\", strings.Split(\"\", \"Bernardo O'Higgins\"))\n```\n\n输出：\n```go\n[\"a\" \"b\" \"c\"]\n[\"\" \"man \" \"plan \" \"canal panama\"]\n[\" \" \"x\" \"y\" \"z\" \" \"]\n[\"\"]\n```\n\n\n## 2.1.4 字符串是否有某个前缀或后缀 ##\n\n这两个函数比较简单，源码如下：\n```go\n// s 中是否以 prefix 开始\nfunc HasPrefix(s, prefix string) bool {\n return len(s) >= len(prefix) && s[0:len(prefix)] == prefix\n}\n// s 中是否以 suffix 结尾\nfunc HasSuffix(s, suffix string) bool {\n return len(s) >= len(suffix) && s[len(s)-len(suffix):] == suffix\n}\n```\n如果 prefix 或 suffix 为 \"\" , 返回值总是 true。\n\n示例：\n```go\nfmt.Println(strings.HasPrefix(\"Gopher\", \"Go\"))\nfmt.Println(strings.HasPrefix(\"Gopher\", \"C\"))\nfmt.Println(strings.HasPrefix(\"Gopher\", \"\"))\nfmt.Println(strings.HasSuffix(\"Amigo\", \"go\"))\nfmt.Println(strings.HasSuffix(\"Amigo\", \"Ami\"))\nfmt.Println(strings.HasSuffix(\"Amigo\", \"\"))\n```\n \n输出结果：\n```bash\ntrue\nfalse\ntrue\ntrue\nfalse\ntrue\n```\n\n\n## 2.1.5 字符或子串在字符串中出现的位置 ##\n\n有一序列函数与该功能有关：\n```go\n// 在 s 中查找 sep 的第一次出现，返回第一次出现的索引\nfunc Index(s, sep string) int\n// 在 s 中查找字节 c 的第一次出现，返回第一次出现的索引\nfunc IndexByte(s string, c byte) int\n// chars 中任何一个 Unicode 代码点在 s 中首次出现的位置\nfunc IndexAny(s, chars string) int\n// 查找字符 c 在 s 中第一次出现的位置，其中 c 满足 f(c) 返回 true\nfunc IndexFunc(s string, f func(rune) bool) int\n// Unicode 代码点 r 在 s 中第一次出现的位置\nfunc IndexRune(s string, r rune) int\n\n// 有三个对应的查找最后一次出现的位置\nfunc LastIndex(s, sep string) int\nfunc LastIndexByte(s string, c byte) int\nfunc LastIndexAny(s, chars string) int\nfunc LastIndexFunc(s string, f func(rune) bool) int\n```\n\n在 2.1.1 小节提到过，Contain 相关的函数内部调用的是响应的 Index 函数。\n\n这一序列函数，只举 IndexFunc 的例子：\n\n```go\nhan := func(c rune) bool {\n\treturn unicode.Is(unicode.Han, c) // 汉字\n}\nfmt.Println(strings.IndexFunc(\"Hello, world\", han))\nfmt.Println(strings.IndexFunc(\"Hello, 世界\", han))\n```\n\n 输出：\n```bash\n-1\n7\n```\n\n\n## 2.1.6 字符串 JOIN 操作 ##\n\n将字符串数组（或 slice）连接起来可以通过 Join 实现，函数签名如下：\n```go\nfunc Join(a []string, sep string) string\n```\n\n假如没有这个库函数，我们自己实现一个，我们会这么实现：\n```go\nfunc Join(str []string, sep string) string {\n // 特殊情况应该做处理\n if len(str) == 0 {\n \treturn \"\"\n }\n if len(str) == 1 {\n \treturn str[0]\n }\n buffer := bytes.NewBufferString(str[0])\n for _, s := range str[1:] {\n buffer.WriteString(sep)\n buffer.WriteString(s)\n }\n return buffer.String()\n}\n```\n这里，我们使用了 bytes 包的 Buffer 类型，避免大量的字符串连接操作（因为 Go 中字符串是不可变的）。我们再看一下标准库的实现：\n```go\nfunc Join(a []string, sep string) string {\n if len(a) == 0 {\n \treturn \"\"\n }\n if len(a) == 1 {\n \treturn a[0]\n }\n n := len(sep) * (len(a) - 1)\n for i := 0; i < len(a); i++ {\n \tn += len(a[i])\n }\n\n b := make([]byte, n)\n bp := copy(b, a[0])\n for _, s := range a[1:] {\n \tbp += copy(b[bp:], sep)\n \tbp += copy(b[bp:], s)\n }\n return string(b)\n}\n```\n\n标准库的实现没有用 bytes 包，当然也不会简单的通过 + 号连接字符串。Go 中是不允许循环依赖的，标准库中很多时候会出现代码拷贝，而不是引入某个包。这里 Join 的实现方式挺好，我个人猜测，不直接使用 bytes 包，也是不想依赖 bytes 包（其实 bytes 中的实现也是 copy 方式）。\n\n简单使用示例：\n```go\nfmt.Println(Join([]string{\"name=xxx\", \"age=xx\"}, \"&\"))\n```\n输出结果:\n```bash\nname=xxx&age=xx\n```\n\n\n## 2.1.7 字符串重复几次 ##\n\n函数签名如下：\n```go\nfunc Repeat(s string, count int) string\n```\n将 s 重复 count 次，如果 count 为负数或返回值长度 len(s)*count 超出 string 上限会导致 panic，这个函数使用很简单：\n```go\nfmt.Println(\"ba\" + strings.Repeat(\"na\", 2))\n```\n\n输出结果：\n```bash\nbanana\n```\n\n\n## 2.1.8 字符替换 ##\n \n```go\nfunc Map(mapping func(rune) rune, s string) string\n```\n\nMap 函数，将 s 的每一个字符按照 mapping 的规则做映射替换，如果 mapping 返回值 <0 ，则舍弃该字符。该方法只能对每一个字符做处理，但处理方式很灵活，可以方便的过滤，筛选汉字等。\n \n示例：\n```go\nmapping := func(r rune) rune {\n\tswitch {\n\tcase r >= 'A' && r <= 'Z': // 大写字母转小写\n\t\treturn r + 32\n\tcase r >= 'a' && r <= 'z': // 小写字母不处理\n\t\treturn r\n\tcase unicode.Is(unicode.Han, r): // 汉字换行\n\t\treturn '\\n'\n\t}\n\treturn -1 // 过滤所有非字母、汉字的字符\n}\nfmt.Println(strings.Map(mapping, \"Hello你#￥%……\\n（'World\\n,好Hello^(&(*界gopher...\"))\n```\n\n输出结果：\n```bash\nhello\nworld\nhello\ngopher\n```\n\n\n## 2.1.9 字符串子串替换 ##\n\n进行字符串替换时，考虑到性能问题，能不用正则尽量别用，应该用这里的函数。\n\n字符串替换的函数签名如下：\n```go\n// 用 new 替换 s 中的 old，一共替换 n 个。\n// 如果 n < 0，则不限制替换次数，即全部替换\nfunc Replace(s, old, new string, n int) string\n// 该函数内部直接调用了函数 Replace(s, old, new , -1)\nfunc ReplaceAll(s, old, new string) string\n```\n\n使用示例：\n```go\nfmt.Println(strings.Replace(\"oink oink oink\", \"k\", \"ky\", 2))\nfmt.Println(strings.Replace(\"oink oink oink\", \"oink\", \"moo\", -1))\nfmt.Println(strings.ReplaceAll(\"oink oink oink\", \"oink\", \"moo\"))\n```\n\n输出：\n```go\noinky oinky oink\nmoo moo moo\nmoo moo moo\n```\n\n如果我们希望一次替换多个，比如我们希望替换 `This is HTML` 中的 `<` 和 `>` 为 `<` 和 `>`，可以调用上面的函数两次。但标准库提供了另外的方法进行这种替换。\n\n\n## 2.1.10 大小写转换\n \n```go\nfunc ToLower(s string) string\nfunc ToLowerSpecial(c unicode.SpecialCase, s string) string\nfunc ToUpper(s string) string\nfunc ToUpperSpecial(c unicode.SpecialCase, s string) string\n```\n 大小写转换包含了 4 个相关函数，ToLower,ToUpper 用于大小写转换。ToLowerSpecial,ToUpperSpecial 可以转换特殊字符的大小写。\n 举个例子：\n```go\nfmt.Println(strings.ToLower(\"HELLO WORLD\"))\nfmt.Println(strings.ToLower(\"Ā Á Ǎ À\"))\nfmt.Println(strings.ToLowerSpecial(unicode.TurkishCase, \"壹\"))\nfmt.Println(strings.ToLowerSpecial(unicode.TurkishCase, \"HELLO WORLD\"))\nfmt.Println(strings.ToLower(\"Önnek İş\"))\nfmt.Println(strings.ToLowerSpecial(unicode.TurkishCase, \"Önnek İş\"))\n\nfmt.Println(strings.ToUpper(\"hello world\"))\nfmt.Println(strings.ToUpper(\"ā á ǎ à\"))\nfmt.Println(strings.ToUpperSpecial(unicode.TurkishCase, \"一\"))\nfmt.Println(strings.ToUpperSpecial(unicode.TurkishCase, \"hello world\"))\nfmt.Println(strings.ToUpper(\"örnek iş\"))\nfmt.Println(strings.ToUpperSpecial(unicode.TurkishCase, \"örnek iş\"))\n```\n \n输出结果:\n```bash\nhello world\nā á ǎ à\n壹\nhello world\nönnek iş\nönnek iş\nHELLO WORLD\nĀ Á Ǎ À // 汉字拼音有效\n一 // 汉字无效\nHELLO WORLD\nÖRNEK IŞ\nÖRNEK İŞ // 有细微差别\n```\n \n \n## 2.1.10 标题处理\n \n```go\nfunc Title(s string) string\nfunc ToTitle(s string) string\nfunc ToTitleSpecial(c unicode.SpecialCase, s string) string\n```\n标题处理包含 3 个相关函数，其中 Title 会将 s 每个单词的首字母大写，不处理该单词的后续字符。ToTitle 将 s 的每个字母大写。ToTitleSpecial 将 s 的每个字母大写，并且会将一些特殊字母转换为其对应的特殊大写字母。\n \n举个例子：\n```go\nfmt.Println(strings.Title(\"hElLo wOrLd\"))\nfmt.Println(strings.ToTitle(\"hElLo wOrLd\"))\nfmt.Println(strings.ToTitleSpecial(unicode.TurkishCase, \"hElLo wOrLd\"))\nfmt.Println(strings.Title(\"āáǎà ōóǒò êēéěè\"))\nfmt.Println(strings.ToTitle(\"āáǎà ōóǒò êēéěè\"))\nfmt.Println(strings.ToTitleSpecial(unicode.TurkishCase, \"āáǎà ōóǒò êēéěè\"))\nfmt.Println(strings.Title(\"dünyanın ilk borsa yapısı Aizonai kabul edilir\"))\nfmt.Println(strings.ToTitle(\"dünyanın ilk borsa yapısı Aizonai kabul edilir\"))\nfmt.Println(strings.ToTitleSpecial(unicode.TurkishCase, \"dünyanın ilk borsa yapısı Aizonai kabul edilir\"))\n```\n \n输出结果：\n```bash\nHElLo WOrLd\nHELLO WORLD\nHELLO WORLD\nĀáǎà Ōóǒò Êēéěè\nĀÁǍÀ ŌÓǑÒ ÊĒÉĚÈ\nĀÁǍÀ ŌÓǑÒ ÊĒÉĚÈ\nDünyanın Ilk Borsa Yapısı Aizonai Kabul Edilir\nDÜNYANIN ILK BORSA YAPISI AIZONAI KABUL EDILIR\nDÜNYANIN İLK BORSA YAPISI AİZONAİ KABUL EDİLİR\n```\n\n## 2.1.11 修剪 ##\n\n```go\n// 将 s 左侧和右侧中匹配 cutset 中的任一字符的字符去掉\nfunc Trim(s string, cutset string) string\n// 将 s 左侧的匹配 cutset 中的任一字符的字符去掉\nfunc TrimLeft(s string, cutset string) string\n// 将 s 右侧的匹配 cutset 中的任一字符的字符去掉\nfunc TrimRight(s string, cutset string) string\n// 如果 s 的前缀为 prefix 则返回去掉前缀后的 string , 否则 s 没有变化。\nfunc TrimPrefix(s, prefix string) string\n// 如果 s 的后缀为 suffix 则返回去掉后缀后的 string , 否则 s 没有变化。\nfunc TrimSuffix(s, suffix string) string\n// 将 s 左侧和右侧的间隔符去掉。常见间隔符包括：'\\t', '\\n', '\\v', '\\f', '\\r', ' ', U+0085 (NEL)\nfunc TrimSpace(s string) string\n// 将 s 左侧和右侧的匹配 f 的字符去掉\nfunc TrimFunc(s string, f func(rune) bool) string\n// 将 s 左侧的匹配 f 的字符去掉\nfunc TrimLeftFunc(s string, f func(rune) bool) string\n// 将 s 右侧的匹配 f 的字符去掉\nfunc TrimRightFunc(s string, f func(rune) bool) string\n```\n\n包含了 9 个相关函数用于修剪字符串。\n\n举个例子：\n```go\nx := \"!!!@@@你好,!@#$ Gophers###$$$\"\nfmt.Println(strings.Trim(x, \"@#$!%^&*()_+=-\"))\nfmt.Println(strings.TrimLeft(x, \"@#$!%^&*()_+=-\"))\nfmt.Println(strings.TrimRight(x, \"@#$!%^&*()_+=-\"))\nfmt.Println(strings.TrimSpace(\" \\t\\n Hello, Gophers \\n\\t\\r\\n\"))\nfmt.Println(strings.TrimPrefix(x, \"!\"))\nfmt.Println(strings.TrimSuffix(x, \"$\"))\n\nf := func(r rune) bool {\n\treturn !unicode.Is(unicode.Han, r) // 非汉字返回 true\n}\nfmt.Println(strings.TrimFunc(x, f))\nfmt.Println(strings.TrimLeftFunc(x, f))\nfmt.Println(strings.TrimRightFunc(x, f))\n```\n\n输出结果：\n```bash\n你好,!@#$ Gophers\n你好,!@#$ Gophers###$$$\n!!!@@@你好,!@#$ Gophers\nHello, Gophers\n!!@@@你好,!@#$ Gophers###$$$\n!!!@@@你好,!@#$ Gophers###$$\n你好\n你好,!@#$ Gophers###$$$\n!!!@@@你好\n```\n \n## 2.1.12 Replacer 类型 ##\n\n这是一个结构，没有导出任何字段，实例化通过 `func NewReplacer(oldnew ...string) *Replacer` 函数进行，其中不定参数 oldnew 是 old-new 对，即进行多个替换。如果 oldnew 长度与奇数，会导致 panic.\n\n示例：\n```go\nr := strings.NewReplacer(\"<\", \"<\", \">\", \">\")\nfmt.Println(r.Replace(\"This is HTML!\"))\n```\n\n输出结果：\n```go\nThis is <b>HTML</b>!\n```\n另外，Replacer 还提供了另外一个方法，它在替换之后将结果写入 io.Writer 中。\n```go\nfunc (r *Replacer) WriteString(w io.Writer, s string) (n int, err error)\n```\n\n \n## 2.1.13 Reader 类型 ##\n\n看到名字就能猜到，这是实现了 `io` 包中的接口。它实现了 io.Reader（Read 方法），io.ReaderAt（ReadAt 方法），io.Seeker（Seek 方法），io.WriterTo（WriteTo 方法），io.ByteReader（ReadByte 方法），io.ByteScanner（ReadByte 和 UnreadByte 方法），io.RuneReader（ReadRune 方法） 和 io.RuneScanner（ReadRune 和 UnreadRune 方法）。\n\nReader 结构如下：\n```go\ntype Reader struct {\n s string\t// Reader 读取的数据来源\n i int // current reading index（当前读的索引位置）\n prevRune int // index of previous rune; or < 0（前一个读取的 rune 索引位置）\n}\n```\n可见 Reader 结构没有导出任何字段，而是提供一个实例化方法：\n```go\nfunc NewReader(s string) *Reader\n```\n\n该方法接收一个字符串，返回的 Reader 实例就是从该参数字符串读数据。在后面学习了 bytes 包之后，可以知道 bytes.NewBufferString 有类似的功能，不过，如果只是为了读取，NewReader 会更高效。\n\n其他方法不介绍了，都是之前接口的实现，有兴趣的可以看看源码实现，大部分都是根据 i、prevRune 两个属性来控制。\n\n## 2.1.14 Builder 类型 ##\n \n```go\ntype Builder struct {\n\taddr *Builder // of receiver, to detect copies by value\n\tbuf []byte\n}\n```\n该类型实现了 io 包下的 Writer, ByteWriter, StringWriter 等接口，可以向该对象内写入数据，Builder 没有实现 Reader 等接口，所以该类型不可读，但提供了 String 方法可以获取对象内的数据。\n \n```go\n// 该方法向 b 写入一个字节\nfunc (b *Builder) WriteByte(c byte) error\n// WriteRune 方法向 b 写入一个字符\nfunc (b *Builder) WriteRune(r rune) (int, error)\n// WriteRune 方法向 b 写入字节数组 p\nfunc (b *Builder) Write(p []byte) (int, error)\n// WriteRune 方法向 b 写入字符串 s\nfunc (b *Builder) WriteString(s string) (int, error)\n// Len 方法返回 b 的数据长度。\nfunc (b *Builder) Len() int\n// Cap 方法返回 b 的 cap。\nfunc (b *Builder) Cap() int\n// Grow 方法将 b 的 cap 至少增加 n (可能会更多)。如果 n 为负数，会导致 panic。\nfunc (b *Builder) Grow(n int)\n// Reset 方法将 b 清空 b 的所有内容。\nfunc (b *Builder) Reset()\n// String 方法将 b 的数据以 string 类型返回。\nfunc (b *Builder) String() string\n```\nBuilder 有 4 个与写入相关的方法，这 4 个方法的 error 都总是为 nil.\n\nBuilder 的 cap 会自动增长，一般不需要手动调用 Grow 方法。\n \nString 方法可以方便的获取 Builder 的内容。\n \n 举个例子：\n```go\nb := strings.Builder{}\n_ = b.WriteByte('7')\nn, _ := b.WriteRune('夕')\nfmt.Println(n)\nn, _ = b.Write([]byte(\"Hello, World\"))\nfmt.Println(n)\nn, _ = b.WriteString(\"你好，世界\")\nfmt.Println(n)\nfmt.Println(b.Len())\nfmt.Println(b.Cap())\nb.Grow(100)\nfmt.Println(b.Len())\nfmt.Println(b.Cap())\nfmt.Println(b.String())\nb.Reset()\nfmt.Println(b.String())\n```\n \n 输出结果：\n```bash\n3\n12\n15\n31\n32\n31\n164\n7夕Hello, World你好，世界\n```\n \n# 导航 #\n\n- [第二章 文本](/chapter02/02.0.md)\n- 下一节：[bytes — byte slice 便利操作](02.2.md)" }, { "path": "chapter02/02.2.md", "content": "# 2.2 bytes — byte slice 便利操作 #\n\n该包定义了一些操作 byte slice 的便利操作。因为字符串可以表示为 []byte，因此，bytes 包定义的函数、方法等和 strings 包很类似，所以讲解时会和 strings 包类似甚至可以直接参考。\n\n说明：为了方便，会称呼 []byte 为 字节数组\n## Buffer 类型 ##\n\n### 逻辑 ###\n\n![](https://ws2.sinaimg.cn/large/006tKfTcly1g1kncpzk5zj30u021ltda.jpg)\n\n## 2.2.1 是否存在某个子 slice\n```go\n// 子 slice subslice 在 b 中，返回 true\nfunc Contains(b, subslice []byte) bool\n```\n\n该函数的内部调用了 bytes.Index 函数（在后面会讲解）:\n```go\n\tfunc Contains(b, subslice []byte) bool {\n \treturn Index(b, subslice) != -1\n }\n```\n\n题外：对比 `strings.Contains` 你会发现，一个判断 `>=0`，一个判断 `!= -1`，可见库不是一个人写的，没有做到一致性。\n\n## 2.2.2 []byte 出现次数 ##\n```go\n// slice sep 在 s 中出现的次数（无重叠）\nfunc Count(s, sep []byte) int\n```\n和 strings 实现不同，此包中的 Count 核心代码如下：\n```go\ncount := 0\nc := sep[0]\ni := 0\nt := s[:len(s)-n+1]\nfor i < len(t) {\n\t// 判断 sep 第一个字节是否在 t[i:] 中\n\t// 如果在，则比较之后相应的字节\n\tif t[i] != c {\n\t\to := IndexByte(t[i:], c)\n\t\tif o < 0 {\n\t\t\tbreak\n\t\t}\n\t\ti += o\n\t}\n\t// 执行到这里表示 sep[0] == t[i]\n\tif n == 1 || Equal(s[i:i+n], sep) {\n\t\tcount++\n\t\ti += n\n\t\tcontinue\n\t}\n\ti++\n}\n```\n\n\n## 2.2.3 Runes 类型转换\n\n```go\n// 将 []byte 转换为 []rune\nfunc Runes(s []byte) []rune\n```\n该函数将 []byte 转换为 []rune ，适用于汉字等多字节字符，示例：\n```go\nb:=[]byte(\"你好，世界\")\nfor k,v:=range b{\n\tfmt.Printf(\"%d:%s |\",k,string(v))\n}\nr:=bytes.Runes(b)\nfor k,v:=range r{\n\tfmt.Printf(\"%d:%s|\",k,string(v))\n}\n```\n\n运行结果：\n```bash\n0:ä |1:½ |2:  |3:å |4:¥ |5:½ |6:ï |7:¼ |8: |9:ä |10:¸ |11: |12:ç |13: |14: |\n0:你|1:好|2:，|3:世|4:界|\n```\n\n## 2.2.4 Reader 类型\n\n\n```go\ntype Reader struct {\n\ts []byte\n\ti int64 // 当前读取下标\n\tprevRune int // 前一个字符的下标，也可能 < 0\n}\n```\nbytes 包下的 Reader 类型实现了 io 包下的 Reader, ReaderAt, RuneReader, RuneScanner, ByteReader, ByteScanner, ReadSeeker, Seeker, WriterTo 等多个接口。主要用于 Read 数据。\n\n我们需要在通过 bytes.NewReader 方法来初始化 bytes.Reader 类型的对象。初始化时传入 []byte 类型的数据。NewReader 函数签名如下：\n```go\nfunc NewReader(b []byte) *Reader\n```\n\n如果直接声明该对象了，可以通过 Reset 方法重新写入数据，示例：\n```go\nx:=[]byte(\"你好，世界\")\n\nr1:=bytes.NewReader(x)\nd1:=make([]byte,len(x))\nn,_:=r1.Read(d1)\nfmt.Println(n,string(d1))\n\nr2:=bytes.Reader{}\nr2.Reset(x)\nd2:=make([]byte,len(x))\nn,_=r2.Read(d2)\nfmt.Println(n,string(d2))\n```\n\n输出结果：\n```bash\n15 你好，世界\n15 你好，世界\n```\n\nReader 包含了 8 个读取相关的方法，实现了前面提到的 io 包下的 9 个接口（ReadSeeker 接口内嵌 Reader 和 Seeker 两个接口）：\n```go\n// 读取数据至 b \nfunc (r *Reader) Read(b []byte) (n int, err error) \n// 读取一个字节\nfunc (r *Reader) ReadByte() (byte, error)\n// 读取一个字符\nfunc (r *Reader) ReadRune() (ch rune, size int, err error)\n// 读取数据至 w\nfunc (r *Reader) WriteTo(w io.Writer) (n int64, err error)\n// 进度下标指向前一个字节，如果 r.i <= 0 返回错误。\nfunc (r *Reader) UnreadByte() \n// 进度下标指向前一个字符，如果 r.i <= 0 返回错误，且只能在每次 ReadRune 方法后使用一次，否则返回错误。\nfunc (r *Reader) UnreadRune() \n// 读取 r.s[off:] 的数据至b，该方法忽略进度下标 i，不使用也不修改。\nfunc (r *Reader) ReadAt(b []byte, off int64) (n int, err error) \n// 根据 whence 的值，修改并返回进度下标 i ，当 whence == 0 ，进度下标修改为 off，当 whence == 1 ，进度下标修改为 i+off，当 whence == 2 ，进度下标修改为 len[s]+off.\n// off 可以为负数，whence 的只能为 0，1，2，当 whence 为其他值或计算后的进度下标越界，则返回错误。\nfunc (r *Reader) Seek(offset int64, whence int) (int64, error)\n```\n\n示例：\n```go\nx := []byte(\"你好，世界\")\nr1 := bytes.NewReader(x)\n\nch, size, _ := r1.ReadRune()\nfmt.Println(size, string(ch))\n_ = r1.UnreadRune()\nch, size, _ = r1.ReadRune()\nfmt.Println(size, string(ch))\n_ = r1.UnreadRune()\n\nby, _ := r1.ReadByte()\nfmt.Println(by)\n_ = r1.UnreadByte()\nby, _ = r1.ReadByte()\nfmt.Println(by)\n_ = r1.UnreadByte()\n\nd1 := make([]byte, 6)\nn, _ := r1.Read(d1)\nfmt.Println(n, string(d1))\n\nd2 := make([]byte, 6)\nn, _ = r1.ReadAt(d2, 0)\nfmt.Println(n, string(d2))\n\nw1 := &bytes.Buffer{}\n_, _ = r1.Seek(0, 0)\n_, _ = r1.WriteTo(w1)\nfmt.Println(w1.String())\n```\n\n运行结果：\n```go\n3 你\n3 你\n228\n228\n6 你好\n6 你好\n你好，世界\n```\n\n\n## 2.2.5 Buffer 类型\n\n```go\ntype Buffer struct {\n\tbuf []byte\n\toff int \n\tlastRead readOp \n}\n```\n在上一个示例的最后，我们使用了 bytes.Buffer 类型，该类型实现了 io 包下的 ByteScanner, ByteWriter, ReadWriter, Reader, ReaderFrom, RuneReader, RuneScanner, StringWriter, Writer, WriterTo 等接口，可以方便的进行读写操作。\n\n对象可读取数据为 buf[off : len(buf)], off 表示进度下标，lastRead 表示最后读取的一个字符所占字节数，方便 Unread* 相关操作。\n\nBuffer 可以通过 3 中方法初始化对象：\n```go\na := bytes.NewBufferString(\"Hello World\")\nb := bytes.NewBuffer([]byte(\"Hello World\"))\nc := bytes.Buffer{}\n\nfmt.Println(a)\nfmt.Println(b)\nfmt.Println(c)\n}\n```\n\n输出结果：\n```go\nHello World\nHello World\n{[] 0 0}\n```\n\nBuffer 包含了 21 个读写相关的方法，大部分同名方法的用法与前面讲的类似，这里只讲演示其中的 3 个方法：\n```go\n// 读取到字节 delim 后，以字节数组的形式返回该字节及前面读取到的字节。如果遍历 b.buf 也找不到匹配的字节，则返回错误(一般是 EOF)\nfunc (b *Buffer) ReadBytes(delim byte) (line []byte, err error)\n// 读取到字节 delim 后，以字符串的形式返回该字节及前面读取到的字节。如果遍历 b.buf 也找不到匹配的字节，则返回错误(一般是 EOF)\nfunc (b *Buffer) ReadString(delim byte) (line string, err error)\n// 截断 b.buf , 舍弃 b.off+n 之后的数据。n == 0 时，调用 Reset 方法重置该对象，当 n 越界时（n < 0 || n > b.Len() ）方法会触发 panic.\nfunc (b *Buffer) Truncate(n int)\n```\n\n示例：\n```go\na := bytes.NewBufferString(\"Good Night\")\n\nx, err := a.ReadBytes('t')\nif err != nil {\n fmt.Println(\"delim:t err:\", err)\n} else {\n fmt.Println(string(x))\n}\n\na.Truncate(0)\na.WriteString(\"Good Night\")\nfmt.Println(a.Len())\na.Truncate(5)\nfmt.Println(a.Len())\ny, err := a.ReadString('N')\nif err != nil {\n fmt.Println(\"delim:N err:\", err)\n} else {\n fmt.Println(y)\n}\n```\n\n输出结果：\n```bash\nGood Night\n10\n5\ndelim:N err: EOF\n```\n\n\n\n## 2.2.6 其它函数\n\n其它大部分函数、方法与 strings 包下的函数、方法类似，只是数据源从 string 变为了 []byte ，请参考 strings 包的用法。\n\n\n# 导航 #\n\n- 上一节：[strings — 字符串操作](02.1.md)\n- 下一节：[strconv — 字符串和基本数据类型之间转换](02.3.md)" }, { "path": "chapter02/02.3.md", "content": "# 2.3 strconv — 字符串和基本数据类型之间转换 #\n\n这里的基本数据类型包括：布尔、整型（包括有 / 无符号、二进制、八进制、十进制和十六进制）和浮点型等。\n\n## 2.3.1 strconv 包转换错误处理 ##\n\n介绍具体的转换之前，先看看 *strconv* 中的错误处理。\n\n由于将字符串转为其他数据类型可能会出错，*strconv* 包定义了两个 *error* 类型的变量：*ErrRange* 和 *ErrSyntax*。其中，*ErrRange* 表示值超过了类型能表示的最大范围，比如将 \"128\" 转为 int8 就会返回这个错误；*ErrSyntax* 表示语法错误，比如将 \"\" 转为 int 类型会返回这个错误。\n\n然而，在返回错误的时候，不是直接将上面的变量值返回，而是通过构造一个 *NumError* 类型的 *error* 对象返回。*NumError* 结构的定义如下：\n\n\t// A NumError records a failed conversion.\n\ttype NumError struct {\n\t\tFunc string // the failing function (ParseBool, ParseInt, ParseUint, ParseFloat)\n\t\tNum string // the input\n\t\tErr error // the reason the conversion failed (ErrRange, ErrSyntax)\n\t}\n\n可见，该结构记录了转换过程中发生的错误信息。该结构不仅包含了一个 *error* 类型的成员，记录具体的错误信息，而且它自己也实现了 *error* 接口：\n\n\tfunc (e *NumError) Error() string {\n\t\treturn \"strconv.\" + e.Func + \": \" + \"parsing \" + Quote(e.Num) + \": \" + e.Err.Error()\n\t}\n\n包的实现中，定义了两个便捷函数，用于构造 *NumError* 对象：\n\n\tfunc syntaxError(fn, str string) *NumError {\n\t\treturn &NumError{fn, str, ErrSyntax}\n\t}\n\n\tfunc rangeError(fn, str string) *NumError {\n\t\treturn &NumError{fn, str, ErrRange}\n\t}\n\n在遇到 *ErrSyntax* 或 *ErrRange* 错误时，通过上面的函数构造 *NumError* 对象。\n\n## 2.3.2 字符串和整型之间的转换 ##\n\n### 2.3.2.1 字符串转为整型 ###\n\n包括三个函数：ParseInt、ParseUint 和 Atoi，函数原型如下：\n\n\tfunc ParseInt(s string, base int, bitSize int) (i int64, err error)\n\tfunc ParseUint(s string, base int, bitSize int) (n uint64, err error)\n\tfunc Atoi(s string) (i int, err error)\n\n其中，Atoi 是 ParseInt 的便捷版，内部通过调用 *ParseInt(s, 10, 0)* 来实现的；ParseInt 转为有符号整型；ParseUint 转为无符号整型，着重介绍 ParseInt。\n\n参数 *base* 代表字符串按照给定的进制进行解释。一般的，base 的取值为 2~36，如果 base 的值为 0，则会根据字符串的前缀来确定 base 的值：\"0x\" 表示 16 进制； \"0\" 表示 8 进制；否则就是 10 进制。\n\n参数 *bitSize* 表示的是整数取值范围，或者说整数的具体类型。取值 0、8、16、32 和 64 分别代表 int、int8、int16、int32 和 int64。\n\n这里有必要说一下，当 bitSize==0 时的情况。\n\nGo 中，int/uint 类型，不同系统能表示的范围是不一样的，目前的实现是，32 位系统占 4 个字节；64 位系统占 8 个字节。当 bitSize==0 时，应该表示 32 位还是 64 位呢？这里没有利用 *runtime.GOARCH* 之类的方式，而是巧妙的通过如下表达式确定 intSize：\n\n\tconst intSize = 32 << uint(^uint(0)>>63)\n\tconst IntSize = intSize // number of bits in int, uint (32 or 64)\n\n主要是 *^uint(0)>>63* 这个表达式。操作符 *^* 在这里是一元操作符 按位取反，而不是 按位异或。更多解释可以参考：[Go 位运算：取反和异或](http://studygolang.com/topics/303)。\n\n问题：下面的代码 n 和 err 的值分别是什么？\n\n\tn, err := strconv.ParseInt(\"128\", 10, 8)\n\n在 *ParseInt/ParseUint* 的实现中，如果字符串表示的整数超过了 bitSize 参数能够表示的范围，则会返回 ErrRange，同时会返回 bitSize 能够表示的最大或最小值。因此，这里的 n 是 127。\n\n另外，*ParseInt* 返回的是 int64，这是为了能够容纳所有的整型，在实际使用中，可以根据传递的 bitSize，然后将结果转为实际需要的类型。\n\n转换的基本原理（以 \"128\" 转 为 10 进制 int 为例）：\n\n\ts := \"128\"\n\tn := 0\n\tfor i := 0; i < len(s); i++ {\n\t\tn *= 10\t+ s[i] \t// base\n\t}\n\n在循环处理的过程中，会检查数据的有效性和是否越界等。\n\n### 2.3.2.2 整型转为字符串 ###\n\n实际应用中，我们经常会遇到需要将字符串和整型连接起来，在 Java 中，可以通过操作符 \"+\" 做到。不过，在 Go 语言中，你需要将整型转为字符串类型，然后才能进行连接。这个时候，*strconv* 包中的整型转字符串的相关函数就派上用场了。这些函数签名如下：\n\n\tfunc FormatUint(i uint64, base int) string\t// 无符号整型转字符串\n\tfunc FormatInt(i int64, base int) string\t// 有符号整型转字符串\n\tfunc Itoa(i int) string\n\n其中，*Itoa* 内部直接调用 *FormatInt(i, 10)* 实现的。base 参数可以取 2~36（0-9，a-z）。\n\n转换的基本原理（以 10 进制的 127 转 string 为例） ：\n\n\tconst digits = \"0123456789abcdefghijklmnopqrstuvwxyz\"\n\tu := uint64(127)\n\tvar a [65]byte\n\ti := len(a)\n\tb := uint64(base)\n\tfor u >= b {\n\t\ti--\n\t\ta[i] = digits[uintptr(u%b)]\n\t\tu /= b\n\t}\n\ti--\n\ta[i] = digits[uintptr(u)]\n\treturn string(a[1:])\n\n即将整数每一位数字对应到相应的字符，存入字符数组中，最后字符数组转为字符串即为结果。\n\n具体实现时，当 base 是 2 的幂次方时，有优化处理（移位和掩码）；十进制也做了优化。\n\n标准库还提供了另外两个函数：*AppendInt* 和 *AppendUint*，这两个函数不是将整数转为字符串，而是将整数转为字符数组 append 到目标字符数组中。（最终，我们也可以通过返回的 []byte 得到字符串）\n\n除了使用上述方法将整数转为字符串外，经常见到有人使用 *fmt* 包来做这件事。如：\n\n\tfmt.Sprintf(\"%d\", 127)\n\n那么，这两种方式我们该怎么选择呢？我们主要来考察一下性能。\n\n\tstartTime := time.Now()\n for i := 0; i < 10000; i++ {\n fmt.Sprintf(\"%d\", i)\n } \n fmt.Println(time.Now().Sub(startTime))\n\n startTime := time.Now()\n for i := 0; i < 10000; i++ {\n strconv.Itoa(i)\n } \n fmt.Println(time.Now().Sub(startTime))\n\n我们分别循环转换了 10000 次。*Sprintf* 的时间是 3.549761ms，而 *Itoa* 的时间是 848.208us，相差 4 倍多。\n\n*Sprintf* 性能差些可以预见，因为它接收的是 interface，需要进行反射等操作。个人建议使用 *strconv* 包中的方法进行转换。\n\n注意：别想着通过 string(65) 这种方式将整数转为字符串，这样实际上得到的会是 ASCCII 值为 65 的字符，即 'A'。\n\n思考：\n\n\t给定一个 40 以内的正整数，如何快速判断其是否是 2 的幂次方？\n\n*提示：在 strconv 包源码 itoa.go 文件中找答案*\n\n## 2.3.3 字符串和布尔值之间的转换 ##\n\nGo 中字符串和布尔值之间的转换比较简单，主要有三个函数：\n\n\t// 接受 1, t, T, TRUE, true, True, 0, f, F, FALSE, false, False 等字符串；\n\t// 其他形式的字符串会返回错误\n\tfunc ParseBool(str string) (value bool, err error)\n\t// 直接返回 \"true\" 或 \"false\"\n\tfunc FormatBool(b bool) string\n\t// 将 \"true\" 或 \"false\" append 到 dst 中\n\t// 这里用了一个 append 函数对于字符串的特殊形式：append(dst, \"true\"...)\n\tfunc AppendBool(dst []byte, b bool)\n\n## 2.3.4 字符串和浮点数之间的转换 ##\n\n类似的，包含三个函数：\n\n\tfunc ParseFloat(s string, bitSize int) (f float64, err error)\n\tfunc FormatFloat(f float64, fmt byte, prec, bitSize int) string\n\tfunc AppendFloat(dst []byte, f float64, fmt byte, prec int, bitSize int)\n\n函数的命名和作用跟上面讲解的其他类型一致。\n\n关于 *FormatFloat* 的 *fmt* 参数， 在第一章第三节[格式化 IO](/chapter01/01.3.md) 中有详细介绍。而 *prec* 表示有效数字（对 *fmt='b'* 无效），对于 'e', 'E' 和 'f'，有效数字用于小数点之后的位数；对于 'g' 和 'G'，则是所有的有效数字。例如：\n\n\tstrconv.FormatFloat(1223.13252, 'e', 3, 32)\t// 结果：1.223e+03\n\tstrconv.FormatFloat(1223.13252, 'g', 3, 32)\t// 结果：1.22e+03\n\n由于浮点数有精度的问题，精度不一样，ParseFloat 和 FormatFloat 可能达不到互逆的效果。如：\n\n\ts := strconv.FormatFloat(1234.5678, 'g', 6, 64)\n\tstrconv.ParseFloat(s, 64)\n\n另外，fmt='b' 时，得到的字符串是无法通过 *ParseFloat* 还原的。\n\n特别地（不区分大小写），+inf/inf，+infinity/infinity，-inf/-infinity 和 nan 通过 ParseFloat 转换分别返回对应的值（在 math 包中定义）。\n\n同样的，基于性能的考虑，应该使用 *FormatFloat* 而不是 *fmt.Sprintf*。\n\n## 2.3.5 其他导出的函数 ##\n\n如果要输出这样一句话：*This is \"studygolang.com\" website*. 该如何做？\n\nSo easy:\n\n\tfmt.Println(`This is \"studygolang.com\" website`)\n\n如果没有 *``* 符号，该怎么做？转义：\n\n\tfmt.Println(\"This is \\\"studygolang.com\\\" website\")\n\n除了这两种方法，*strconv* 包还提供了函数这做件事（Quote 函数）。我们称 \"studygolang.com\" 这种用双引号引起来的字符串为 Go 语言字面值字符串（Go string literal）。\n\n上面的一句话可以这么做：\n\n\tfmt.Println(\"This is\", strconv.Quote(\"studygolang.com\"), \"website\")\n\n\n# 导航 #\n\n- 上一节：[bytes — byte slice 便利操作](02.2.md)\n- 下一节：[regexp — 正则表达式](02.4.md)\n" }, { "path": "chapter02/02.4.md", "content": "# 2.4 regexp — 正则表达式\n\n正则表达式使用单个字符串来描述、匹配一系列符合某个句法规则的字符串。正则表达式为文本处理提供了强大的功能。Go 作为一门通用语言，自然提供了对正则表达式的支持。\n\n`regexp` 包实现了正则表达式搜索。\n\n正则表达式采用 RE2 语法（除了 \\c、\\C），和 Perl、Python 等语言的正则基本一致。确切地说是兼容 `RE2` 语法。相关资料：[http://code.google.com/p/re2/wiki/Syntax](http://code.google.com/p/re2/wiki/Syntax)，[包：regexp/syntax](http://docs.studygolang.com/pkg/regexp/syntax/)\n\n注意：`regexp` 包的正则表达式实现保证运行时间随着输入大小线性增长的（即复杂度为 O\\(n\\)，其中 n 为输入的长度），这一点，很多正则表达式的开源实现无法保证，参见：RSC 的 [《Regular Expression Matching Can Be Simple And Fast \n\\(but is slow in Java, Perl, PHP, Python, Ruby, ...\\)》](http://swtch.com/~rsc/regexp/regexp1.html)\n\n另外，所有的字符都被视为 utf-8 编码的码值 \\(Code Point\\)。\n\nRegexp 类型提供了多达 16 个方法，用于匹配正则表达式并获取匹配的结果。它们的名字满足如下正则表达式：\n\n```\nFind(All)?(String)?(Submatch)?(Index)?\n```\n\n未完待续。。。\n\n[https://github.com/StefanSchroeder/Golang-Regex-Tutorial](https://github.com/StefanSchroeder/Golang-Regex-Tutorial)\n\n# 导航\n\n* 上一节：[strconv — 字符串和基本数据类型之间转换](02.3.md)\n* 下一节：[unicode — Unicode 码点、UTF-8/16 编码](02.5.md)\n\n\n\n" }, { "path": "chapter02/02.5.md", "content": "# 2.5 unicode — Unicode 码点、UTF-8/16 编码 #\n\n世界中的字符有许许多多，有英文，中文，韩文等。随着全球化进程不断深入，我们强烈需要一个能够容纳世界上所有字符的字符集，方便编码为计算机能处理的二进制数。每个字符都给予一个独一无二的编号，就不会出现写文字的人和阅读文字的人使用不同的编码而出现乱码现象。\n\n于是 Unicode 就出现了，它将所有的字符用一个唯一的数字表示。最开始的时候，unicode 认为使用两个字节，也就是 16 位就能包含所有的字符了。但是非常可惜，两个字节最多只能覆盖 65536 个字符，这显然是不够的，于是出现了 unicode4.0，附加的字符用 4 个字节表示。现在为止，大概 Unicode 可以覆盖 100 多万个字符了。\n\nUnicode 就只是代表字符集，也就是只定义了字符到码点（Code Point）的映射（可以理解为 Unicode 定义了一个表，表中每一行记录是一个字符到一个唯一 ID 的映射，而这个 ID 就是码点），并没有定义码点具体如何编码。对应的字符编码有多种，比如 UTF-8、UTF-16 等。所以需要理解字符集和字符编码是不一样的。更详细的说明可以参考该文：。\n\nUTF-8 表示最少用一个字节就能表示一个字符的编码实现。它采取的方式是对不同的语言使用不同的方法，将 unicode 编码按照这个方法进行转换。\n\n我们只要记住最后的结果是英文占一个字节，中文占三个字节。这种编码实现方式也是现在应用最为广泛的方式了。\n\nUTF-16 表示最少用两个字节能表示一个字符的编码实现。同样是对 unicode 编码进行转换，它的结果是英文占用两个字节，中文占用两个或者四个字节。\n\n实际上，UTF-16 就是最严格实现了 unicode4.0 的编码方式。但由于英文是最通用的语言，所以推广程度没有 UTF-8 那么普及。\n\n回到 Go 对 unicode 包的支持，由于 UTF-8 的作者 Ken Thompson 同时也是 Go 语言的创始人，所以说，在字符支持方面，几乎没有语言的理解会高于 Go 了。\n\nGo 对 unicode 的支持包含三个包 :\n\n* unicode\n* unicode/utf8\n* unicode/utf16\n\nunicode 包包含基本的字符判断函数。utf8 包主要负责 rune 和 byte 之间的转换。utf16 包负责 rune 和 uint16 数组之间的转换。\n\n由于字符的概念有的时候比较模糊，比如字符（小写 a）普通显示为 a，在重音字符中（grave-accented）中显示为 à。\n这时候字符（character）的概念就有点不准确了，因为 a 和 à 显然是两个不同的 unicode 编码，但是却代表同一个字符，所以引入了 rune。\n\n一个 rune 就代表一个 unicode 码点，所以上面的 a 和 à 是两个不同的 rune。\n\n这里有个要注意的事情，Go 语言的所有代码都是 UTF-8 的，所以我们在程序中的字符串都是 UTF-8 编码的，但是我们的单个字符（单引号扩起来的）却是 unicode 的（码点）。\n\n## 2.5.1 unicode 包 ##\n\nunicode 提供数据和函数来测试 Unicode 代码点（Code Point，用 rune 存储）的某些属性。\n\n> 注意，在 Go1.16 之前，unicode 包实现的 unicode 版本是 12.0，Go1.16 实现了 13.0\n\n这个包把所有 unicode 涉及到的码点进行了分类，使用结构 RengeTable 来表示不同类别的字符集合。这些类别都列在 table.go 这个源文件里。\n\n```go\n// RangeTable 通过列出一组 Unicode 码点的范围来定义它。为了节省空间，在两个切片中列出了范围：切片的 16 位范围（R16）和切片的 32 位（R32）范围。这两个切片必须按排序顺序且不重叠。同样，R32 应该仅包含 > = 0x10000（1 << 16）的值（即附加半部分字符）。\ntype RangeTable struct {\n\tR16 []Range16\n\tR32 []Range32\n\tLatinOffset int\t// Hi <= MaxLatin1 的 R16 中的条目数；在 Go 1.1 中添加\n}\n\ntype Range16 struct {\n Lo uint16\n Hi uint16\n Stride uint16\n}\n```\n\n比如控制字符集合：\n\n```go\nvar _Pc = &RangeTable{\n\tR16: []Range16{\n\t\t{0x005f, 0x203f, 8160},\n\t\t{0x2040, 0x2054, 20},\n\t\t{0xfe33, 0xfe34, 1},\n\t\t{0xfe4d, 0xfe4f, 1},\n\t\t{0xff3f, 0xff3f, 1},\n\t},\n}\n```\n\n比如对国内开发者很实用的汉字字符集：\n\n```go\nvar _Han = &RangeTable{\n\tR16: []Range16{\n\t\t{0x2e80, 0x2e99, 1},\n\t\t{0x2e9b, 0x2ef3, 1},\n\t\t{0x2f00, 0x2fd5, 1},\n\t\t{0x3005, 0x3005, 1},\n\t\t{0x3007, 0x3007, 1},\n\t\t{0x3021, 0x3029, 1},\n\t\t{0x3038, 0x303b, 1},\n\t\t{0x3400, 0x4db5, 1},\n\t\t{0x4e00, 0x9fea, 1},\n\t\t{0xf900, 0xfa6d, 1},\n\t\t{0xfa70, 0xfad9, 1},\n\t},\n\tR32: []Range32{\n\t\t{0x20000, 0x2a6d6, 1},\n\t\t{0x2a700, 0x2b734, 1},\n\t\t{0x2b740, 0x2b81d, 1},\n\t\t{0x2b820, 0x2cea1, 1},\n\t\t{0x2ceb0, 0x2ebe0, 1},\n\t\t{0x2f800, 0x2fa1d, 1},\n\t},\n}\n```\n\n回到包的函数，我们看到有下面这些判断函数：\n\n```go\nfunc IsControl(r rune) bool // 是否控制字符\nfunc IsDigit(r rune) bool // 是否阿拉伯数字字符，即 0-9\nfunc IsGraphic(r rune) bool // 是否图形字符\nfunc IsLetter(r rune) bool // 是否字母\nfunc IsLower(r rune) bool // 是否小写字符\nfunc IsMark(r rune) bool // 是否符号字符\nfunc IsNumber(r rune) bool // 是否数字字符，比如罗马数字 Ⅷ 也是数字字符\nfunc IsOneOf(ranges []*RangeTable, r rune) bool // 是否是 RangeTable 中的一个\nfunc IsPrint(r rune) bool // 是否可打印字符\nfunc IsPunct(r rune) bool // 是否标点符号\nfunc IsSpace(r rune) bool // 是否空格\nfunc IsSymbol(r rune) bool // 是否符号字符\nfunc IsTitle(r rune) bool // 是否 title case\nfunc IsUpper(r rune) bool // 是否大写字符\nfunc Is(rangeTab *RangeTable, r rune) bool // r 是否为 rangeTab 类型的字符\nfunc In(r rune, ranges ...*RangeTable) bool // r 是否为 ranges 中任意一个类型的字符\n```\n\n看下面这个例子：\n\n```go\nfunc main() {\n\tsingle := '\\u0015'\n\tfmt.Println(unicode.IsControl(single))\n\tsingle = '\\ufe35'\n\tfmt.Println(unicode.IsControl(single))\n\n\tdigit := '1'\n\tfmt.Println(unicode.IsDigit(digit))\n\tfmt.Println(unicode.IsNumber(digit))\n\n\tletter := 'Ⅷ'\n\tfmt.Println(unicode.IsDigit(letter))\n\tfmt.Println(unicode.IsNumber(letter))\n\n\than:='你'\n\tfmt.Println(unicode.IsDigit(han))\n\tfmt.Println(unicode.Is(unicode.Han,han))\n\tfmt.Println(unicode.In(han,unicode.Gujarati,unicode.White_Space))\n }\n```\n\n输出结果：\n\n```bash\ntrue\nfalse\ntrue\ntrue\nfalse\ntrue\nfalse\ntrue\nfalse\n```\n\n## 2.5.2 utf8 包 ##\n\nutf8 包用于处理 UTF-8 编码的文本，提供一些常量和函数，包括在 rune（码点） 和 UTF-8 字节序列之间的转换。\n\n1）判断是否是有效 utf8 编码的函数：\n\n* func Valid(p []byte) bool\n* func ValidRune(r rune) bool\n* func ValidString(s string) bool\n\n2）得到 rune 所占字节数：\n\n* func RuneLen(r rune) int\n\n3）判断字节数组或者字符串的 rune 数：\n\n* func RuneCount(p []byte) int\n* func RuneCountInString(s string) (n int)\n\n4）编码、解码 rune：\n\n* func EncodeRune(p []byte, r rune) int\n* func DecodeRune(p []byte) (r rune, size int)\n* func DecodeRuneInString(s string) (r rune, size int)\n* func DecodeLastRune(p []byte) (r rune, size int)\n* func DecodeLastRuneInString(s string) (r rune, size int)\n\n5）是否为完整 rune：\n\n* func FullRune(p []byte) bool\n* func FullRuneInString(s string) bool\n\n6）判断一个字节是否为 rune 的第一个字节：\n\n* func RuneStart(b byte) bool\n\n示例：\n\n```go\nword:=[]byte(\"界\")\n\nfmt.Println(utf8.Valid(word[:2]))\nfmt.Println(utf8.ValidRune('界'))\nfmt.Println(utf8.ValidString(\"世界\"))\n\nfmt.Println(utf8.RuneLen('界'))\n\nfmt.Println(utf8.RuneCount(word))\nfmt.Println(utf8.RuneCountInString(\"世界\"))\n\np:=make([]byte,3)\nutf8.EncodeRune(p,'好')\nfmt.Println(p)\nfmt.Println(utf8.DecodeRune(p))\nfmt.Println(utf8.DecodeRuneInString(\"你好\"))\nfmt.Println(utf8.DecodeLastRune([]byte(\"你好\")))\nfmt.Println(utf8.DecodeLastRuneInString(\"你好\"))\n\nfmt.Println(utf8.FullRune(word[:2]))\nfmt.Println(utf8.FullRuneInString(\"你好\"))\n\nfmt.Println(utf8.RuneStart(word[1]))\nfmt.Println(utf8.RuneStart(word[0]))\n```\n\n运行结果：\n\n```bash\nfalse\ntrue\ntrue\n3\n1\n2\n[229 165 189]\n22909 3\n20320 3\n22909 3\n22909 3\nfalse\ntrue\nfalse\ntrue\n```\n\n## 2.5.3 utf16 包 ##\n\nutf16 包的函数就比较少了，主要是 UTF-16 序列的编码和解码。\n\n将 uint16 和 rune 进行转换：\n\n```go\nfunc Encode(s []rune) []uint16\nfunc EncodeRune(r rune) (r1, r2 rune)\nfunc Decode(s []uint16) []rune\nfunc DecodeRune(r1, r2 rune) rune\nfunc IsSurrogate(r rune) bool // 是否为有效代理对\n```\n\nunicode 有个基本字符平面和增补平面的概念，基本字符平面只有 65535 个字符，增补平面（有 16 个）加上去就能表示 1114112 个字符。\n\nutf16 严格地实现了 unicode 的这种编码规范。\n\n而基本字符和增补平面字符就是一个代理对（Surrogate Pair）。一个代理对可以和一个 rune 进行转换。\n\n示例：\n\n```go\nwords := []rune{'𝓐','𝓑'}\n\nu16 := utf16.Encode(words)\nfmt.Println(u16)\nfmt.Println(utf16.Decode(u16))\n\nr1, r2 := utf16.EncodeRune('𝓐')\nfmt.Println(r1,r2)\nfmt.Println(utf16.DecodeRune(r1, r2))\nfmt.Println(utf16.IsSurrogate(r1))\nfmt.Println(utf16.IsSurrogate(r2))\nfmt.Println(utf16.IsSurrogate(1234))\n```\n\n输出结果：\n\n```bash\n[55349 56528 55349 56529]\n[120016 120017]\n55349 56528\n120016\ntrue\ntrue\nfalse\n```\n\n# 导航 #\n\n- 上一节：[regexp — 正则表达式](02.4.md)\n- 第三章：[数据结构和算法](/chapter03/03.0.md)\n\n" }, { "path": "chapter03/03.0.md", "content": "# 第三章 数据结构与算法 #\n\n程序设计离不开数据结构和算法。数据结构是数据组织和存储的逻辑形式，以达到方便访问和修改数据的目的。而算法是根据实际输入输出的需求设计的一系列计算过程，被认为是程序的灵魂。设计良好的算法的重要意义正如*Thomas*在《算法导论》中提到“计算机可以做得很快，但不是无限快；存储器可以做到很便宜，但不是免费的。因此，计算时间是一种有限的资源，存储空间也是一种有限的资源。这些有限的资源必须有效地使用，那些时间上和空间上有效的算法可以帮助做到这一点。“\n\n本章内容涵盖了 Go 标准库中的 3 个包：\n\n*sort* 包包含基本的排序方法，支持切片数据排序以及用户自定义数据集合排序\n\n*index/suffixary* 包实现了后缀数组相关算法以支持许多常见的字符串操作\n\n*container* 包提供了对 heap、list 和 ring 这 3 种数据结构的底层支持。任何实现了相应接口的数据结构都可以调用该结构的方法。\n\n# 导航 #\n\n- [第二章](/chapter02/02.0.md)\n- 下一节：[sort - 排序算法](03.1.md)\n" }, { "path": "chapter03/03.1.md", "content": "# 3.1 sort —— 排序算法 #\n\n该包实现了四种基本排序算法：插入排序、归并排序、堆排序和快速排序。\n但是这四种排序方法是不公开的，它们只被用于 sort 包内部使用。所以在对数据集合排序时不必考虑应当选择哪一种排序方法，只要实现了 sort.Interface 定义的三个方法：获取数据集合长度的 Len() 方法、比较两个元素大小的 Less() 方法和交换两个元素位置的 Swap() 方法，就可以顺利对数据集合进行排序。sort 包会根据实际数据自动选择高效的排序算法。\n除此之外，为了方便对常用数据类型的操作，sort 包提供了对[]int 切片、[]float64 切片和[]string 切片完整支持，主要包括：\n- 对基本数据类型切片的排序支持\n- 基本数据元素查找\n- 判断基本数据类型切片是否已经排好序\n- 对排好序的数据集合逆序\n\n## 3.1.1 数据集合排序 ##\n\n前面已经提到过，对数据集合（包括自定义数据类型的集合）排序需要实现 sort.Interface 接口的三个方法，我们看以下该接口的定义：\n```go\ntype Interface interface {\n\t\t// 获取数据集合元素个数\n\t\tLen() int\n\t\t// 如果 i 索引的数据小于 j 索引的数据，返回 true，且不会调用下面的 Swap()，即数据升序排序。\n\t\tLess(i, j int) bool\n\t\t// 交换 i 和 j 索引的两个元素的位置\n Swap(i, j int)\n}\n```\n\n数据集合实现了这三个方法后，即可调用该包的 Sort() 方法进行排序。\nSort() 方法定义如下：\n```go\nfunc Sort(data Interface)\n```\nSort() 方法惟一的参数就是待排序的数据集合。\n\n该包还提供了一个方法可以判断数据集合是否已经排好顺序，该方法的内部实现依赖于我们自己实现的 Len() 和 Less() 方法：\n```go\nfunc IsSorted(data Interface) bool {\n n := data.Len()\n for i := n - 1; i > 0; i-- {\n if data.Less(i, i-1) {\n return false\n }\n }\n return true\n}\n```\n\n下面是一个使用 sort 包对学生成绩排序的示例：\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"sort\"\n)\n\n// 学生成绩结构体\ntype StuScore struct {\n name string // 姓名\n score int // 成绩\n}\n\ntype StuScores []StuScore\n\n//Len()\nfunc (s StuScores) Len() int {\n\treturn len(s)\n}\n\n//Less(): 成绩将有低到高排序\nfunc (s StuScores) Less(i, j int) bool {\n\treturn s[i].score < s[j].score\n}\n\n//Swap()\nfunc (s StuScores) Swap(i, j int) {\n\ts[i], s[j] = s[j], s[i]\n}\n\nfunc main() {\n stus := StuScores{\n {\"alan\", 95},\n {\"hikerell\", 91},\n {\"acmfly\", 96},\n {\"leao\", 90},\n\t\t\t\t}\n\t\t\t\t\n\t// 打印未排序的 stus 数据\n fmt.Println(\"Default:\\n\\t\",stus)\n //StuScores 已经实现了 sort.Interface 接口 , 所以可以调用 Sort 函数进行排序\n\tsort.Sort(stus)\n\t// 判断是否已经排好顺序，将会打印 true\n\tfmt.Println(\"IS Sorted?\\n\\t\", sort.IsSorted(stus))\n\t// 打印排序后的 stus 数据\n fmt.Println(\"Sorted:\\n\\t\",stus)\n}\n```\n\n该示例程序的自定义类型 StuScores 实现了 sort.Interface 接口，所以可以将其对象作为 sort.Sort() 和 sort.IsSorted() 的参数传入。运行结果： \n```bash\nDefault:\n [{alan 95} {hikerell 91} {acmfly 96} {leao 90}]\nIS Sorted?\n true\nSorted:\n [{leao 90} {hikerell 91} {alan 95} {acmfly 96}]\n```\n\n该示例实现的是升序排序，如果要得到降序排序结果，其实只要修改 Less() 函数：\n```go\n//Less(): 成绩降序排序 , 只将小于号修改为大于号\nfunc (s StuScores) Less(i, j int) bool {\n\treturn s[i].score > s[j].score\n}\n```\n\n此外，*sort*包提供了 Reverse() 方法，可以允许将数据按 Less() 定义的排序方式逆序排序，而不必修改 Less() 代码。方法定义如下：\n```go\nfunc Reverse(data Interface) Interface\n```\n\n我们可以看到 Reverse() 返回的一个 sort.Interface 接口类型，整个 Reverse() 的内部实现比较有趣：\n```go\n// 定义了一个 reverse 结构类型，嵌入 Interface 接口\ntype reverse struct {\n Interface\n}\n\n//reverse 结构类型的 Less() 方法拥有嵌入的 Less() 方法相反的行为\n//Len() 和 Swap() 方法则会保持嵌入类型的方法行为\nfunc (r reverse) Less(i, j int) bool {\n return r.Interface.Less(j, i)\n}\n\n// 返回新的实现 Interface 接口的数据类型\nfunc Reverse(data Interface) Interface {\n return &reverse{data}\n}\n```\n了解内部原理后，可以在学生成绩排序示例中使用 Reverse() 来实现成绩升序排序：\n```go\nsort.Sort(sort.Reverse(stus))\nfmt.Println(stus)\n```\n\n最后一个方法：Search()\n```go\nfunc Search(n int, f func(int) bool) int\n```\n> 该方法会使用“二分查找”算法来找出能使 f(x)(0<=x 前提条件 : f(x)(0<=x 如果不存在 i 可以使 f(i) 返回 ture, 则返回 n。\n\nSearch() 函数一个常用的使用方式是搜索元素 x 是否在已经升序排好的切片 s 中：\n```go\nx := 11\ns := []int{3, 6, 8, 11, 45} // 注意已经升序排序\npos := sort.Search(len(s), func(i int) bool { return s[i] >= x })\nif pos < len(s) && s[pos] == x {\n fmt.Println(x, \" 在 s 中的位置为：\", pos)\n} else {\n fmt.Println(\"s 不包含元素 \", x)\n}\n```\n\n官方文档还给出了一个猜数字的小程序：\n```go\nfunc GuessingGame() {\n\tvar s string\n\tfmt.Printf(\"Pick an integer from 0 to 100.\\n\")\n\tanswer := sort.Search(100, func(i int) bool {\n\t\tfmt.Printf(\"Is your number <= %d? \", i)\n\t\tfmt.Scanf(\"%s\", &s)\n\t\treturn s != \"\" && s[0] == 'y'\n\t})\n\tfmt.Printf(\"Your number is %d.\\n\", answer)\n}\n``` \n\n\n## 3.1.2 *sort*包已经支持的内部数据类型排序\n\n前面已经提到，*sort*包原生支持[]int、[]float64 和[]string 三种内建数据类型切片的排序操作，即不必我们自己实现相关的 Len()、Less() 和 Swap() 方法。\n\n**1. IntSlice 类型及[]int 排序** \n\n由于[]int 切片排序内部实现及使用方法与[]float64 和[]string 类似，所以只详细描述该部分。\n\n*sort*包定义了一个 IntSlice 类型，并且实现了 sort.Interface 接口：\n```go\ntype IntSlice []int\nfunc (p IntSlice) Len() int { return len(p) }\nfunc (p IntSlice) Less(i, j int) bool { return p[i] < p[j] }\nfunc (p IntSlice) Swap(i, j int) { p[i], p[j] = p[j], p[i] }\n//IntSlice 类型定义了 Sort() 方法，包装了 sort.Sort() 函数\nfunc (p IntSlice) Sort() { Sort(p) }\n//IntSlice 类型定义了 SearchInts() 方法，包装了 SearchInts() 函数\nfunc (p IntSlice) Search(x int) int { return SearchInts(p, x) }\n```\n\n并且提供的 sort.Ints() 方法使用了该 IntSlice 类型：\n```go\nfunc Ints(a []int) { Sort(IntSlice(a)) }\n```\n\n所以，对[]int 切片排序更常使用 sort.Ints()，而不是直接使用 IntSlice 类型：\n```go\ns := []int{5, 2, 6, 3, 1, 4} // 未排序的切片数据\nsort.Ints(s)\nfmt.Println(s) // 将会输出[1 2 3 4 5 6]\n```\n\n如果要使用降序排序，显然要用前面提到的 Reverse() 方法：\n```go\ns := []int{5, 2, 6, 3, 1, 4} // 未排序的切片数据\nsort.Sort(sort.Reverse(sort.IntSlice(s)))\nfmt.Println(s) // 将会输出[6 5 4 3 2 1]\n```\n\n如果要查找整数 x 在切片 a 中的位置，相对于前面提到的 Search() 方法，*sort*包提供了 SearchInts():\n```go\nfunc SearchInts(a []int, x int) int\n```\n\n注意，SearchInts() 的使用条件为：**切片 a 已经升序排序** 以下是一个错误使用的例子：\n```go\ns := []int{5, 2, 6, 3, 1, 4} // 未排序的切片数据\nfmt.Println(sort.SearchInts(s, 2)) // 将会输出 0 而不是 1\n```\n\n**2. Float64Slice 类型及[]float64 排序** \n\n实现与 Ints 类似，只看一下其内部实现：\n```go\ntype Float64Slice []float64\n\nfunc (p Float64Slice) Len() int { return len(p) }\nfunc (p Float64Slice) Less(i, j int) bool { return p[i] < p[j] || isNaN(p[i]) && !isNaN(p[j]) }\nfunc (p Float64Slice) Swap(i, j int) { p[i], p[j] = p[j], p[i] }\nfunc (p Float64Slice) Sort() { Sort(p) }\nfunc (p Float64Slice) Search(x float64) int { return SearchFloat64s(p, x) }\n```\n\n与 Sort()、IsSorted()、Search() 相对应的三个方法： \n```go\nfunc Float64s(a []float64) \nfunc Float64sAreSorted(a []float64) bool\nfunc SearchFloat64s(a []float64, x float64) int\n```\n \n要说明一下的是，在上面 Float64Slice 类型定义的 Less 方法中，有一个内部函数 isNaN()。 \nisNaN() 与*math*包中 IsNaN() 实现完全相同，*sort*包之所以不使用 math.IsNaN()，完全是基于包依赖性的考虑，应当看到，*sort*包的实现不依赖与其他任何包。\n\n**3. StringSlice 类型及[]string 排序**\n\n两个 string 对象之间的大小比较是基于“字典序”的。\n\n实现与 Ints 类似，只看一下其内部实现：\n\n```go\ntype StringSlice []string\n\nfunc (p StringSlice) Len() int { return len(p) }\nfunc (p StringSlice) Less(i, j int) bool { return p[i] < p[j] }\nfunc (p StringSlice) Swap(i, j int) { p[i], p[j] = p[j], p[i] }\nfunc (p StringSlice) Sort() { Sort(p) }\nfunc (p StringSlice) Search(x string) int { return SearchStrings(p, x) }\n```\n\n与 Sort()、IsSorted()、Search() 相对应的三个方法： \n```go\nfunc Strings(a []string)\nfunc StringsAreSorted(a []string) bool\nfunc SearchStrings(a []string, x string) int\n```\n\n## 3.1.3 []interface 排序与查找\n\n通过前面的内容我们可以知道，只要实现了 `sort.Interface` 接口，即可通过 sort 包内的函数完成排序，查找等操作。并且 sort 包已经帮我们把`[]int`,`[]float64`,`[]string` 三种类型都实现了该接口，我们可以方便的调用。但是这种用法对于其它数据类型的 slice 不友好，可能我们需要为大量的 struct 定义一个单独的 []struct 类型，再为其实现 `sort.Interface` 接口，类似这样：\n```go\ntype Person struct {\n Name string\n Age int\n}\ntype Persons []Person\n\nfunc (p Persons) Len() int {\n panic(\"implement me\")\n}\n\nfunc (p Persons) Less(i, j int) bool {\n panic(\"implement me\")\n}\n\nfunc (p Persons) Swap(i, j int) {\n panic(\"implement me\")\n}\n```\n\n> 思考一个问题：为什么 sort 包可以完成 `[]int` 的排序，而不能完成 `[]struct` 的排序？\n\n因为排序涉及到比较两个变量的值，而 struct 可能包含多个属性，程序并不知道你想以哪一个属性或哪几个属性作为衡量大小的标准。如果你能帮助程序完成比较，并将结果返回， sort 包内的方法就可以完成排序，判断，查找等。sort 包提供了以下函数：\n\n```go\nfunc Slice(slice interface{}, less func(i, j int) bool) \nfunc SliceStable(slice interface{}, less func(i, j int) bool) \nfunc SliceIsSorted(slice interface{}, less func(i, j int) bool) bool \nfunc Search(n int, f func(int) bool) int\n```\n\n通过函数签名可以看到，排序相关的三个函数都接收 `[]interface`，并且需要传入一个比较函数，用于为程序比较两个变量的大小，因为函数签名和作用域的原因，这个函数只能是 `匿名函数`。\n\n**1. sort.Slice**\n\n该函数完成 []interface 的排序，举个栗子：\n```go\npeople := []struct {\n\tName string\n\tAge int\n}{\n\t{\"Gopher\", 7},\n\t{\"Alice\", 55},\n\t{\"Vera\", 24},\n\t{\"Bob\", 75},\n}\n\nsort.Slice(people, func(i, j int) bool { return people[i].Age < people[j].Age }) // 按年龄升序排序\nfmt.Println(\"Sort by age:\", people)\n```\n\n输出结果：\n```bash\nBy age: [{Gopher 7} {Vera 24} {Alice 55} {Bob 75}]\n```\n\n**2. sort.SliceStable**\n\n该函数完成 []interface 的稳定排序，举个栗子：\n```go\npeople := []struct {\n\tName string\n\tAge int\n}{\n\t{\"Gopher\", 7},\n\t{\"Alice\", 55},\n\t{\"Vera\", 24},\n\t{\"Bob\", 75},\n}\n\nsort.SliceStable(people, func(i, j int) bool { return people[i].Age > people[j].Age }) // 按年龄降序排序\nfmt.Println(\"Sort by age:\", people)\n```\n\n输出结果：\n```bash\nBy age: [{Bob 75} {Alice 55} {Vera 24} {Gopher 7}]\n```\n\n**3. sort.SliceIsSorted**\n\n该函数判断 []interface 是否为有序，举个栗子：\n```go\npeople := []struct {\n Name string\n Age int\n}{\n {\"Gopher\", 7},\n {\"Alice\", 55},\n {\"Vera\", 24},\n {\"Bob\", 75},\n}\n\nsort.Slice(people, func(i, j int) bool { return people[i].Age > people[j].Age }) // 按年龄降序排序\nfmt.Println(\"Sort by age:\", people)\nfmt.Println(\"Sorted:\",sort.SliceIsSorted(people,func(i, j int) bool { return people[i].Age < people[j].Age }))\n```\n\n输出结果：\n```bash\nSort by age: [{Bob 75} {Alice 55} {Vera 24} {Gopher 7}]\nSorted: false\n```\n\nsort 包没有为 []interface 提供反序函数，但是从 1 和 2 可以看出，我们传入的比较函数已经决定了排序结果是升序还是降序。\n\n判断 slice 是否为有序，同样取决于我们传入的比较函数，从 3 可以看出，虽然 slice 已经按年龄降序排序，但我们在判断 slice 是否为有序时给的比较函数是判断其是否为升序有序，所以最终得到的结果为 false。\n\n\n**4. sort.Search**\n\n该函数判断 []interface 是否存在指定元素，举个栗子：\n\n- 升序 slice\n\nsort 包为 `[]int`,`[]float64`,`[]string` 提供的 Search 函数其实也是调用的该函数，因为该函数是使用的二分查找法，所以要求 slice 为升序排序状态。并且判断条件必须为 `>=`，这也是官方库提供的三个查找相关函数的的写法。\n\n举个栗子：\n```go\na := []int{2, 3, 4, 200, 100, 21, 234, 56}\nx := 21\n\nsort.Slice(a, func(i, j int) bool { return a[i] < a[j] }) // 升序排序\nindex := sort.Search(len(a), func(i int) bool { return a[i] >= x }) // 查找元素\n\nif index < len(a) && a[index] == x {\n\tfmt.Printf(\"found %d at index %d in %v\\n\", x, index, a)\n} else {\n\tfmt.Printf(\"%d not found in %v,index:%d\\n\", x, a, index)\n}\n```\n\n输出结果：\n```bash\nfound 21 at index 3 in [2 3 4 21 56 100 200 234]\n```\n\n- 降序 slice\n\n如果 slice 是降序状态，而我们又不想将其变为升序，只需将判断条件由 `>=` 变更为 `<=` 即可。此处就不给代码了，有兴趣的同学可以自己去尝试一下。推荐采用升序排列及相应的判断条件，与官方函数保持风格一致。\n\n# 导航 #\n\n- [第三章 数据结构与算法](/chapter03/03.0.md)\n- 下一节：index/suffixarray — 后缀数组实现子字符串查询" }, { "path": "chapter03/03.3.md", "content": "# 3.3 container — 容器数据类型：heap、list 和 ring #\n\n该包实现了三个复杂的数据结构：堆，链表，环。\n这个包就意味着你使用这三个数据结构的时候不需要再费心从头开始写算法了。\n\n## 3.3.1 堆 ##\n\n这里的堆使用的数据结构是最小二叉树，即根节点比左边子树和右边子树的所有值都小。\ngo 的堆包只是实现了一个接口，我们看下它的定义：\n\n```golang\ntype Interface interface {\n\tsort.Interface\n\tPush(x interface{}) // add x as element Len()\n\tPop() interface{} // remove and return element Len() - 1.\n}\n```\n\n可以看出，这个堆结构继承自 sort.Interface, 回顾下 sort.Interface，它需要实现三个方法\n\n* Len() int\n* Less(i, j int) bool\n* Swap(i, j int)\n\n加上堆接口定义的两个方法\n\n* Push(x interface{})\n* Pop() interface{}\n\n就是说你定义了一个堆，就要实现五个方法，直接拿 package doc 中的 example 做例子：\n\n```golang\ntype IntHeap []int\n\nfunc (h IntHeap) Len() int { return len(h) }\nfunc (h IntHeap) Less(i, j int) bool { return h[i] < h[j] }\nfunc (h IntHeap) Swap(i, j int) { h[i], h[j] = h[j], h[i] }\n\nfunc (h *IntHeap) Push(x interface{}) {\n\t*h = append(*h, x.(int))\n}\n\nfunc (h *IntHeap) Pop() interface{} {\n\told := *h\n\tn := len(old)\n\tx := old[n-1]\n\t*h = old[0 : n-1]\n\treturn x\n}\n```\n那么 IntHeap 就实现了这个堆结构，我们就可以使用堆的方法来对它进行操作：\n\n```golang\nh := &IntHeap{2, 1, 5}\nheap.Init(h)\nheap.Push(h, 3)\nheap.Pop(h)\n```\n\n具体说下内部实现，是使用最小堆，索引排序从根节点开始，然后左子树，右子树的顺序方式。索引布局如下：\n> 0\n> 1 2\n> 3 4 5 6\n> 7 8 9 10 11 \n假设 (heap[1]== 小明 ) 它的左子树 (heap[3]== 小黑 ) 和右子树 (heap[4]== 大黄 ) 且 小明 > 小黑 > 大黄 ; \n\n堆内部实现了 down 和 up 函数 :\n down 函数用于将索引 i 处存储的值 ( 设 i=1, 即小明 ) 与它的左子树 ( 小黑 ) 和右子树 ( 大黄 ) 相比 , 将三者最小的值大黄与小明的位置交换，交换后小明继续与交换后的子树 (heap[9]和 heap[10]) 相比，重复以上步骤，直到小明位置不变。\n\n up 函数用于将索引 i 处的值 ( 设 i=3, 即小黑 ) 与他的父节点 ( 小明 ) 比较，将两者较小的值放到父节点上，本例中即交换小黑和小明的位置，之后小黑继续与其父节点比较，重复以上步骤，直到小黑位置不变。\n\n假设 heap[11]== 阿花\n当从堆中 Pop 一个元素的时候，先把元素和最后一个节点的值 ( 阿花 ) 交换，然后弹出，然后对阿花调用 down，向下保证最小堆。\n\n当往堆中 Push 一个元素的时候，这个元素插入到最后一个节点，本例中为 heap[12]，即作为 heap[5]的右子树，然后调用 up 函数向上比较。\n\n## 3.3.2 链表 ##\n\n链表就是一个有 prev 和 next 指针的数组了。它维护两个 type，( 注意，这里不是 interface)\n\n```golang\ntype Element struct {\n\tnext, prev *Element // 上一个元素和下一个元素\n\tlist *List // 元素所在链表\n\tValue interface{} // 元素\n}\n\ntype List struct {\n\troot Element // 链表的根元素\n\tlen int // 链表的长度\n}\n```\n\n基本使用是先创建 list，然后往 list 中插入值，list 就内部创建一个 Element，并内部设置好 Element 的 next,prev 等。具体可以看下例子：\n\n```golang\n// This example demonstrates an integer heap built using the heap interface.\npackage main\n\nimport (\n\t\"container/list\"\n\t\"fmt\"\n)\n\nfunc main() {\n list := list.New()\n list.PushBack(1)\n list.PushBack(2)\n\n fmt.Printf(\"len: %v\\n\", list.Len())\n fmt.Printf(\"first: %#v\\n\", list.Front())\n fmt.Printf(\"second: %#v\\n\", list.Front().Next())\n}\n\noutput:\nlen: 2\nfirst: &list.Element{next:(*list.Element)(0x2081be1b0), prev:(*list.Element)(0x2081be150), list:(*list.List)(0x2081be150), Value:1}\nsecond: &list.Element{next:(*list.Element)(0x2081be150), prev:(*list.Element)(0x2081be180), list:(*list.List)(0x2081be150), Value:2}\n```\n\nlist 对应的方法有：\n```go\ntype Element\n func (e *Element) Next() *Element\n func (e *Element) Prev() *Element\ntype List\n func New() *List\n func (l *List) Back() *Element // 最后一个元素\n func (l *List) Front() *Element // 第一个元素\n func (l *List) Init() *List // 链表初始化\n    func (l *List) InsertAfter(v interface{}, mark *Element) *Element // 在某个元素后插入\n    func (l *List) InsertBefore(v interface{}, mark *Element) *Element // 在某个元素前插入\n func (l *List) Len() int // 在链表长度\n func (l *List) MoveAfter(e, mark *Element) // 把 e 元素移动到 mark 之后\n func (l *List) MoveBefore(e, mark *Element) // 把 e 元素移动到 mark 之前\n func (l *List) MoveToBack(e *Element) // 把 e 元素移动到队列最后\n func (l *List) MoveToFront(e *Element) // 把 e 元素移动到队列最头部\n func (l *List) PushBack(v interface{}) *Element // 在队列最后插入元素\n func (l *List) PushBackList(other *List) // 在队列最后插入接上新队列\n func (l *List) PushFront(v interface{}) *Element // 在队列头部插入元素\n func (l *List) PushFrontList(other *List) // 在队列头部插入接上新队列\n func (l *List) Remove(e *Element) interface{} // 删除某个元素\n```\n\n## 3.3.3 环 ##\n\n环的结构有点特殊，环的尾部就是头部，所以每个元素实际上就可以代表自身的这个环。\n它不需要像 list 一样保持 list 和 element 两个结构，只需要保持一个结构就行。\n\n```golang\ntype Ring struct {\n\tnext, prev *Ring\n\tValue interface{}\n}\n```\n\n我们初始化环的时候，需要定义好环的大小，然后对环的每个元素进行赋值。环还提供一个 Do 方法，能遍历一遍环，对每个元素执行一个 function。\n看下面的例子：\n\n```golang\n// This example demonstrates an integer heap built using the heap interface.\npackage main\n\nimport (\n\t\"container/ring\"\n\t\"fmt\"\n)\n\nfunc main() {\n ring := ring.New(3)\n\n for i := 1; i <= 3; i++ {\n ring.Value = i\n ring = ring.Next()\n }\n\n // 计算 1+2+3\n s := 0\n ring.Do(func(p interface{}){\n s += p.(int)\n })\n fmt.Println(\"sum is\", s)\n}\n\noutput:\nsum is 6\n```\n\nring 提供的方法有\n\n```go\ntype Ring\n func New(n int) *Ring // 初始化环\n func (r *Ring) Do(f func(interface{})) // 循环环进行操作\n func (r *Ring) Len() int // 环长度\n func (r *Ring) Link(s *Ring) *Ring // 连接两个环\n func (r *Ring) Move(n int) *Ring // 指针从当前元素开始向后移动或者向前（n 可以为负数）\n func (r *Ring) Next() *Ring // 当前元素的下个元素\n func (r *Ring) Prev() *Ring // 当前元素的上个元素\n func (r *Ring) Unlink(n int) *Ring // 从当前元素开始，删除 n 个元素\n```\n\n# 导航 #\n\n- [第三章 数据结构与算法](/chapter03/03.0.md)\n- 上一节：index/suffixarray — 后缀数组实现子字符串查询\n- 下一节：container 总结\n" }, { "path": "chapter04/04.0.md", "content": "# 第四章 日期与时间 #\n\n实际开发中，经常会遇到日期和时间相关的操作，比如：格式化日期和时间，解析一个日期时间字符串等。Go 语言通过标准库 `time` 包处理日期和时间相关的问题。\n\n本章只有 `time` 这一个包，为了便于阅读，将拆为如下小结进行讲解：\n\n- [主要类型概述](04.1.md)\n- [时区](04.2.md)\n- [Time 类型详解](04.3.md)\n- [定时器](04.4.md)\n\n# 导航 #\n\n- [第三章](/chapter03/03.0.md)\n- 下一节：[主要类型概述](04.1.md)\n" }, { "path": "chapter04/04.1.md", "content": "# 4.1 主要类型概述 #\n\ntime 包提供了时间的显示和计量用的功能。日历的计算采用的是公历。提供的主要类型如下：\n\n## Location\n\n代表一个地区，并表示该地区所在的时区（可能多个）。`Location` 通常代表地理位置的偏移，比如 CEST 和 CET 表示中欧。下一节将详细讲解 Location。\n\n## Time\n\n代表一个纳秒精度的时间点，是公历时间。后面会详细介绍。\n\n## Duration\n\n代表两个时间点之间经过的时间，以纳秒为单位。可表示的最长时间段大约 290 年，也就是说如果两个时间点相差超过 290 年，会返回 290 年，也就是 minDuration(-1 << 63) 或 maxDuration(1 << 63 - 1)。\n\n类型定义：`type Duration int64`。\n\n将 `Duration` 类型直接输出时，因为实现了 `fmt.Stringer` 接口，会输出人类友好的可读形式，如：72h3m0.5s。\n\n## Timer 和 Ticker\n\n这是定时器相关类型。本章最后会讨论定时器。\n\n## Weekday 和 Month\n\n这两个类型的原始类型都是 int，定义它们，语义更明确，同时，实现 `fmt.Stringer` 接口，方便输出。\n\n# 导航 #\n\n- [第四章 日期与时间](04.0.md)\n- 下一节：[时区](04.2.md)\n" }, { "path": "chapter04/04.2.md", "content": "# 4.2 时区 #\n\n不同国家（有时甚至是同一个国家内的不同地区）使用不同的时区。对于要输入和输出时间的程序来说，必须对系统所处的时区加以考虑。Go 语言使用 `Location` 来表示地区相关的时区，一个 Location 可能表示多个时区。\n\n`time` 包提供了 Location 的两个实例：`Local` 和 `UTC`。`Local` 代表当前系统本地时区；`UTC` 代表通用协调时间，也就是零时区。`time` 包默认（为显示提供时区）使用 `UTC` 时区。\n\n## Local 是如何做到表示本地时区的？\n\n时区信息既浩繁又多变，Unix 系统以标准格式存于文件中，这些文件位于 /usr/share/zoneinfo，而本地时区可以通过 /etc/localtime 获取，这是一个符号链接，指向 /usr/share/zoneinfo 中某一个时区。比如我本地电脑指向的是：/usr/share/zoneinfo/Asia/Shanghai。\n\n因此，在初始化 Local 时，通过读取 /etc/localtime 可以获取到系统本地时区。\n\n当然，如果设置了环境变量 `TZ`，则会优先使用它。\n\n相关代码：\n\n```go\ntz, ok := syscall.Getenv(\"TZ\")\nswitch {\ncase !ok:\n\tz, err := loadZoneFile(\"\", \"/etc/localtime\")\n\tif err == nil {\n\t\tlocalLoc = *z\n\t\tlocalLoc.name = \"Local\"\n\t\treturn\n\t}\ncase tz != \"\" && tz != \"UTC\":\n\tif z, err := loadLocation(tz); err == nil {\n\t\tlocalLoc = *z\n\t\treturn\n\t}\n}\n```\n## 获得特定时区的实例\n\n函数 `LoadLocation` 可以根据名称获取特定时区的实例。函数声明如下：\n\n`func LoadLocation(name string) (*Location, error)`\n\n如果 name 是 \"\" 或 \"UTC\"，返回 UTC；如果 name 是 \"Local\"，返回 Local；否则 name 应该是 IANA 时区数据库里有记录的地点名（该数据库记录了地点和对应的时区），如 \"America/New_York\"。\n\nLoadLocation 函数需要的时区数据库可能不是所有系统都提供，特别是非 Unix 系统。此时 `LoadLocation` 会查找环境变量 ZONEINFO 指定目录或解压该变量指定的 zip 文件（如果有该环境变量）；然后查找 Unix 系统的惯例时区数据安装位置，最后查找 `$GOROOT/lib/time/zoneinfo.zip`。\n\n可以在 Unix 系统下的 /usr/share/zoneinfo 中找到所有的名称。\n\n## 总结\n\n通常，我们使用 `time.Local` 即可，偶尔可能会需要使用 `UTC`。在解析时间时，心中一定记得有时区这么回事。当你发现时间出现莫名的情况时，很可能是因为时区的问题，特别是当时间相差 8 小时时。\n\n# 导航 #\n\n- 上一节：[主要类型概述](04.1.md)\n- 下一节：[Time 类型详解](04.3.md)\n" }, { "path": "chapter04/04.3.md", "content": "# 4.3 Time 类型详解 #\n\n`Time` 代表一个纳秒精度的时间点。\n\n程序中应使用 Time 类型值来保存和传递时间，而不是指针。就是说，表示时间的变量和字段，应为 time.Time 类型，而不是 *time.Time. 类型。一个 Time 类型值可以被多个 go 协程同时使用。时间点可以使用 Before、After 和 Equal 方法进行比较。Sub 方法让两个时间点相减，生成一个 Duration 类型值（代表时间段）。Add 方法给一个时间点加上一个时间段，生成一个新的 Time 类型时间点。\n\nTime 零值代表时间点 January 1, year 1, 00:00:00.000000000 UTC。因为本时间点一般不会出现在使用中，IsZero 方法提供了检验时间是否是显式初始化的一个简单途径。\n\n每一个 Time 都具有一个地点信息（即对应地点的时区信息），当计算时间的表示格式时，如 Format、Hour 和 Year 等方法，都会考虑该信息。Local、UTC 和 In 方法返回一个指定时区（但指向同一时间点）的 Time。修改地点 / 时区信息只是会改变其表示；不会修改被表示的时间点，因此也不会影响其计算。\n\n通过 `==` 比较 Time 时，Location 信息也会参与比较，因此 Time 不应该作为 map 的 key。\n\n## Time 的内部结构\n```go\ntype Time struct {\n\t// sec gives the number of seconds elapsed since\n\t// January 1, year 1 00:00:00 UTC.\n\tsec int64\n\n\t// nsec specifies a non-negative nanosecond\n\t// offset within the second named by Seconds.\n\t// It must be in the range [0, 999999999].\n\tnsec int32\n\n\t// loc specifies the Location that should be used to\n\t// determine the minute, hour, month, day, and year\n\t// that correspond to this Time.\n\t// Only the zero Time has a nil Location.\n\t// In that case it is interpreted to mean UTC.\n\tloc *Location\n}\n```\n\n要讲解 `time.Time` 的内部结构，得先看 `time.Now()` 函数。\n\n```go\n// Now returns the current local time.\nfunc Now() Time {\n\tsec, nsec := now()\n\treturn Time{sec + unixToInternal, nsec, Local}\n}\n```\nnow() 的具体实现在 `runtime` 包中，以 linux/amd64 为例，在 sys_linux_amd64.s 中的 `time · now`，这是汇编实现的：\n\n* 调用系统调用 `clock_gettime` 获取时钟值（这是 POSIX 时钟）。其中 clockid_t 时钟类型是 CLOCK_REALTIME，也就是可设定的系统级实时时钟。得到的是 struct timespec 类型。（可以到纳秒）\n* 如果 `clock_gettime` 不存在，则使用精度差些的系统调用 `gettimeofday`。得到的是 struct timeval 类型。（最多到微秒）\n\n*注意：* 这里使用了 Linux 的 vdso 特性，不了解的，可以查阅相关知识。\n\n虽然 `timespec` 和 `timeval` 不一样，但结构类似。因为 `now()` 函数返回两个值：sec( 秒 ) 和 nsec( 纳秒 )，所以，`time · now` 的实现将这两个结构转为需要的返回值。需要注意的是，Linux 系统调用返回的 sec( 秒 ) 是 Unix 时间戳，也就是从 1970-1-1 算起的。\n\n回到 `time.Now()` 的实现，现在我们得到了 sec 和 nsec，从 `Time{sec + unixToInternal, nsec, Local}` 这句可以看出，Time 结构的 sec 并非 Unix 时间戳，实际上，加上的 `unixToInternal` 是 1-1-1 到 1970-1-1 经历的秒数。也就是 `Time` 中的 sec 是从 1-1-1 算起的秒数，而不是 Unix 时间戳。\n\n`Time` 的最后一个字段表示地点时区信息。本章后面会专门介绍。\n\n## 常用函数或方法\n\n`Time` 相关的函数和方法较多，有些很容易理解，不赘述，查文档即可。\n\n### 零值的判断\n\n因为 `Time` 的零值是 sec 和 nsec 都是 0，表示 1 年 1 月 1 日。\n\nTime.IsZero() 函数用于判断 Time 表示的时间是否是 0 值。\n\n### 与 Unix 时间戳的转换\n\n相关函数或方法：\n\n* time.Unix(sec, nsec int64) 通过 Unix 时间戳生成 `time.Time` 实例；\n* time.Time.Unix() 得到 Unix 时间戳；\n* time.Time.UnixNano() 得到 Unix 时间戳的纳秒表示；\n\n### 格式化和解析\n\n这是实际开发中常用到的。\n\n* time.Parse 和 time.ParseInLocation\n* time.Time.Format\n\n#### 解析\n\n对于解析，要特别注意时区问题，否则很容易出 bug。比如：\n\n```go\nt, _ := time.Parse(\"2006-01-02 15:04:05\", \"2016-06-13 09:14:00\")\nfmt.Println(time.Now().Sub(t).Hours())\n```\n`2016-06-13 09:14:00` 这个时间可能是参数传递过来的。这段代码的结果跟预期的不一样。\n\n原因是 `time.Now()` 的时区是 `time.Local`，而 `time.Parse` 解析出来的时区却是 time.UTC（可以通过 `Time.Location()` 函数知道是哪个时区）。在中国，它们相差 8 小时。\n\n所以，一般的，我们应该总是使用 `time.ParseInLocation` 来解析时间，并给第三个参数传递 `time.Local`。\n\n#### 为什么是 2006-01-02 15:04:05\n\n可能你已经注意到：`2006-01-02 15:04:05` 这个字符串了。没错，这是固定写法，类似于其他语言中 `Y-m-d H:i:s` 等。为什么采用这种形式？又为什么是这个时间点而不是其他时间点？\n\n* 官方说，使用具体的时间，比使用 `Y-m-d H:i:s` 更容易理解和记忆；这么一说还真是 ~\n* 而选择这个时间点，也是出于好记的考虑，官方的例子：`Mon Jan 2 15:04:05 MST 2006`，另一种形式 `01/02 03:04:05PM '06 -0700`，对应是 1、2、3、4、5、6、7；常见的格式：`2006-01-02 15:04:05`，很好记：2006 年 1 月 2 日 3 点 4 分 5 秒 ~\n\n*如果你是 PHPer，喜欢 PHP 的格式，可以试试 [times](https://github.com/polaris1119/times) 这个包。*\n\n#### 格式化\n\n时间格式化输出，使用 `Format` 方法，`layout` 参数和 `Parse` 的一样。`Time.String()` 方法使用了 `2006-01-02 15:04:05.999999999 -0700 MST` 这种 `layout`。\n\n### 实现 序列化 / 反序列化 相关接口\n\n`Time` 实现了 `encoding` 包中的 `BinaryMarshaler`、`BinaryUnmarshaler`、`TextMarshaler` 和 `TextUnmarshaler` 接口；`encoding/json` 包中的 `Marshaler` 和 `Unmarshaler` 接口。\n\n它还实现了 `gob` 包中的 `GobEncoder` 和 `GobDecoder` 接口。\n\n对于文本序列化 / 反序列化，通过 `Parse` 和 `Format` 实现；对于二进制序列化，需要单独实现。\n\n对于 json，使用的是 `time.RFC3339Nano` 这种格式。通常程序中不使用这种格式。解决办法是定义自己的类型。如：\n\n```go\ntype OftenTime time.Time\n\nfunc (self OftenTime) MarshalJSON() ([]byte, error) {\n\tt := time.Time(self)\n\tif y := t.Year(); y < 0 || y >= 10000 {\n\t\treturn nil, errors.New(\"Time.MarshalJSON: year outside of range [0,9999]\")\n\t}\n\t// 注意 `\"2006-01-02 15:04:05\"`。因为是 JSON，双引号不能少\n\treturn []byte(t.Format(`\"2006-01-02 15:04:05\"`)), nil\n}\n```\n\n### Round 和 Truncate 方法\n\n比如，有这么个需求：获取当前时间整点的 `Time` 实例。例如，当前时间是 15:54:23，需要的是 15:00:00。我们可以这么做：\n\n```\nt, _ := time.ParseInLocation(\"2006-01-02 15:04:05\", time.Now().Format(\"2006-01-02 15:00:00\"), time.Local)\nfmt.Println(t)\n```\n实际上，`time` 包给我们提供了专门的方法，功能更强大，性能也更好，这就是 `Round` 和 `Trunate`，它们区别，一个是取最接近的，一个是向下取整。\n\n使用示例：\n\n```go\nt, _ := time.ParseInLocation(\"2006-01-02 15:04:05\", \"2016-06-13 15:34:39\", time.Local)\n// 整点（向下取整）\nfmt.Println(t.Truncate(1 * time.Hour))\n// 整点（最接近）\nfmt.Println(t.Round(1 * time.Hour))\n\n// 整分（向下取整）\nfmt.Println(t.Truncate(1 * time.Minute))\n// 整分（最接近）\nfmt.Println(t.Round(1 * time.Minute))\n\nt2, _ := time.ParseInLocation(\"2006-01-02 15:04:05\", t.Format(\"2006-01-02 15:00:00\"), time.Local)\nfmt.Println(t2)\n```\n\n# 导航 #\n\n- 上一节：[时区](04.2.md)\n- 下一节：[定时器](04.4.md)\n" }, { "path": "chapter04/04.4.md", "content": "# 4.4 定时器 #\n\n定时器是进程规划自己在未来某一时刻接获通知的一种机制。本节介绍两种定时器：`Timer`（到达指定时间触发且只触发一次）和 `Ticker`（间隔特定时间触发）。\n\n## Timer\n\n### 内部实现源码分析\n\n`Timer` 类型代表单次时间事件。当 `Timer` 到期时，当时的时间会被发送给 C (channel)，除非 `Timer` 是被 `AfterFunc` 函数创建的。\n\n注意：`Timer` 的实例必须通过 `NewTimer` 或 `AfterFunc` 获得。\n\n类型定义如下：\n\n```go\ntype Timer struct {\n\tC <-chan Time\t // The channel on which the time is delivered.\n\tr runtimeTimer\n}\n```\nC 已经解释了，我们看看 `runtimeTimer`。它定义在 sleep.go 文件中，必须和 `runtime` 包中 `time.go` 文件中的 `timer` 必须保持一致：\n\n```go\ntype timer struct {\n\ti int // heap index\n\n\t// Timer wakes up at when, and then at when+period, ... (period > 0 only)\n\t// each time calling f(now, arg) in the timer goroutine, so f must be\n\t// a well-behaved function and not block.\n\twhen int64\n\tperiod int64\n\tf func(interface{}, uintptr)\n\targ interface{}\n\tseq uintptr\n}\n```\n我们通过 `NewTimer()` 来看这些字段都怎么赋值，是什么用途。\n\n```go\n// NewTimer creates a new Timer that will send\n// the current time on its channel after at least duration d.\nfunc NewTimer(d Duration) *Timer {\n\tc := make(chan Time, 1)\n\tt := &Timer{\n\t\tC: c,\n\t\tr: runtimeTimer{\n\t\t\twhen: when(d),\n\t\t\tf: sendTime,\n\t\t\targ: c,\n\t\t},\n\t}\n\tstartTimer(&t.r)\n\treturn t\n}\n```\n在 `when` 表示的时间到时，会往 Timer.C 中发送当前时间。`when` 表示的时间是纳秒时间，正常通过 `runtimeNano() + int64(d)` 赋值。跟上一节中讲到的 `now()` 类似，`runtimeNano()` 也在 `runtime` 中实现（`runtime · nanotime`）：\n\n* 调用系统调用 `clock_gettime` 获取时钟值（这是 POSIX 时钟）。其中 clockid_t 时钟类型是 CLOCK_MONOTONIC，也就是不可设定的恒定态时钟。具体的是什么时间，SUSv3 规定始于未予规范的过去某一点，Linux 上，始于系统启动。\n* 如果 `clock_gettime` 不存在，则使用精度差些的系统调用 `gettimeofday`。\n\n`f` 参数的值是 `sendTime`，定时器时间到时，会调用 f，并将 `arg` 和 `seq` 传给 `f`。\n\n因为 `Timer` 是一次性的，所以 `period` 保留默认值 0。\n\n定时器的具体实现逻辑，都在 `runtime` 中的 `time.go` 中，它的实现，没有采用经典 Unix 间隔定时器 `setitimer` 系统调用，也没有 采用 POSIX 间隔式定时器（相关系统调用：`timer_create`、`timer_settime` 和 `timer_delete`），而是通过四叉树堆 (heep) 实现的（`runtimeTimer` 结构中的 `i` 字段，表示在堆中的索引）。通过构建一个最小堆，保证最快拿到到期了的定时器执行。定时器的执行，在专门的 `goroutine` 中进行的：`go timerproc()`。有兴趣的同学，可以阅读 `runtime/time.go` 的源码。\n\n### Timer 相关函数或方法的使用\n\n**通过 `time.After` 模拟超时：**\n\n```go\nc := make(chan int)\n\ngo func() {\n\t// time.Sleep(1 * time.Second)\n\ttime.Sleep(3 * time.Second)\n\t<-c\n}()\n\nselect {\ncase c <- 1:\n\tfmt.Println(\"channel...\")\ncase <-time.After(2 * time.Second):\n\tclose(c)\n\tfmt.Println(\"timeout...\")\n}\n```\n\n**`time.Stop` 停止定时器 或 `time.Reset` 重置定时器**\n\n```go\nstart := time.Now()\ntimer := time.AfterFunc(2*time.Second, func() {\n\tfmt.Println(\"after func callback, elaspe:\", time.Now().Sub(start))\n})\n\ntime.Sleep(1 * time.Second)\n// time.Sleep(3*time.Second)\n// Reset 在 Timer 还未触发时返回 true；触发了或 Stop 了，返回 false\nif timer.Reset(3 * time.Second) {\n\tfmt.Println(\"timer has not trigger!\")\n} else {\n\tfmt.Println(\"timer had expired or stop!\")\n}\n\ntime.Sleep(10 * time.Second)\n\n// output:\n// timer has not trigger!\n// after func callback, elaspe: 4.00026461s\n```\n如果定时器还未触发，`Stop` 会将其移除，并返回 true；否则返回 false；后续再对该 `Timer` 调用 `Stop`，直接返回 false。\n\n`Reset` 会先调用 `stopTimer` 再调用 `startTimer`，类似于废弃之前的定时器，重新启动一个定时器。返回值和 `Stop` 一样。\n\n### Sleep 的内部实现\n\n查看 `runtime/time.go` 文件中的 `timeSleep` 可知，`Sleep` 的是通过 `Timer` 实现的，把当前 goroutine 作为 `arg` 参数（`getg()`)。\n\n## Ticker 相关函数或方法的使用\n\n`Ticker` 和 `Timer` 类似，区别是：`Ticker` 中的 `runtimeTimer` 字段的 `period` 字段会赋值为 `NewTicker(d Duration)` 中的 `d`，表示每间隔 `d` 纳秒，定时器就会触发一次。\n\n除非程序终止前定时器一直需要触发，否则，不需要时应该调用 `Ticker.Stop` 来释放相关资源。\n\n如果程序终止前需要定时器一直触发，可以使用更简单方便的 `time.Tick` 函数，因为 `Ticker` 实例隐藏起来了，因此，该函数启动的定时器无法停止。\n\n## 定时器的实际应用\n\n在实际开发中，定时器用的较多的会是 `Timer`，如模拟超时，而需要类似 `Tiker` 的功能时，可以使用实现了 `cron spec` 的库 [cron](https://github.com/robfig/cron)，感兴趣的可以参考文章：[《Go 语言版 crontab》](http://blog.studygolang.com/2014/02/go_crontab/)。\n\n# 导航 #\n\n- 上一节：[Time 类型详解](04.3.md)\n- 下一节：[Unix 时间相关系统调用](04.5.md)\n" }, { "path": "chapter05/05.1.md", "content": "# 5.1 math — 基本数学函数 #\n\nmath 包实现的就是数学函数计算。\n\n## 5.1.1 三角函数 ##\n\n正弦函数，反正弦函数，双曲正弦，反双曲正弦\n\n - func Sin(x float64) float64\n - func Asin(x float64) float64\n - func Sinh(x float64) float64\n - func Asinh(x float64) float64\n\n一次性返回 sin,cos\n\n- func Sincos(x float64) (sin, cos float64)\n\n余弦函数，反余弦函数，双曲余弦，反双曲余弦\n\n - func Cos(x float64) float64\n - func Acos(x float64) float64\n - func Cosh(x float64) float64\n - func Acosh(x float64) float64\n\n正切函数，反正切函数，双曲正切，反双曲正切\n\n - func Tan(x float64) float64\n - func Atan(x float64) float64 和 func Atan2(y, x float64) float64\n - func Tanh(x float64) float64\n - func Atanh(x float64) float64\n\n## 5.1.2 幂次函数 ##\n \n - func Cbrt(x float64) float64 // 立方根函数\n - func Pow(x, y float64) float64 // x 的幂函数\n - func Pow10(e int) float64 // 10 根的幂函数\n - func Sqrt(x float64) float64 // 平方根\n - func Log(x float64) float64 // 对数函数\n - func Log10(x float64) float64 // 10 为底的对数函数\n - func Log2(x float64) float64 // 2 为底的对数函数\n - func Log1p(x float64) float64 // log(1 + x)\n - func Logb(x float64) float64 // 相当于 log2(x) 的绝对值\n - func Ilogb(x float64) int // 相当于 log2(x) 的绝对值的整数部分\n - func Exp(x float64) float64 // 指数函数\n - func Exp2(x float64) float64 // 2 为底的指数函数\n - func Expm1(x float64) float64 // Exp(x) - 1\n\n## 5.1.3 特殊函数 ##\n\n - func Inf(sign int) float64 // 正无穷\n - func IsInf(f float64, sign int) bool // 是否正无穷\n - func NaN() float64 // 无穷值\n - func IsNaN(f float64) (is bool) // 是否是无穷值\n - func Hypot(p, q float64) float64 // 计算直角三角形的斜边长\n\n## 5.1.4 类型转化函数 ##\n\n - func Float32bits(f float32) uint32 // float32 和 unit32 的转换\n - func Float32frombits(b uint32) float32 // uint32 和 float32 的转换\n - func Float64bits(f float64) uint64 // float64 和 uint64 的转换\n - func Float64frombits(b uint64) float64 // uint64 和 float64 的转换\n\n## 5.1.5 其他函数 ##\n\n - func Abs(x float64) float64 // 绝对值函数\n - func Ceil(x float64) float64 // 向上取整\n - func Floor(x float64) float64 // 向下取整\n - func Mod(x, y float64) float64 // 取模\n - func Modf(f float64) (int float64, frac float64) // 分解 f，以得到 f 的整数和小数部分\n - func Frexp(f float64) (frac float64, exp int) // 分解 f，得到 f 的位数和指数\n - func Max(x, y float64) float64 // 取大值\n - func Min(x, y float64) float64 // 取小值\n - func Dim(x, y float64) float64 // 复数的维数\n - func J0(x float64) float64 // 0 阶贝塞尔函数\n - func J1(x float64) float64 // 1 阶贝塞尔函数\n - func Jn(n int, x float64) float64 // n 阶贝塞尔函数\n - func Y0(x float64) float64 // 第二类贝塞尔函数 0 阶\n - func Y1(x float64) float64 // 第二类贝塞尔函数 1 阶\n - func Yn(n int, x float64) float64 // 第二类贝塞尔函数 n 阶\n - func Erf(x float64) float64 // 误差函数\n - func Erfc(x float64) float64 // 余补误差函数\n - func Copysign(x, y float64) float64 // 以 y 的符号返回 x 值\n - func Signbit(x float64) bool // 获取 x 的符号\n - func Gamma(x float64) float64 // 伽玛函数\n - func Lgamma(x float64) (lgamma float64, sign int) // 伽玛函数的自然对数\n - func Ldexp(frac float64, exp int) float64 // value 乘以 2 的 exp 次幂\n - func Nextafter(x, y float64) (r float64) // 返回参数 x 在参数 y 方向上可以表示的最接近的数值，若 x 等于 y，则返回 x\n - func Nextafter32(x, y float32) (r float32) // 返回参数 x 在参数 y 方向上可以表示的最接近的数值，若 x 等于 y，则返回 x\n - func Remainder(x, y float64) float64 // 取余运算\n - func Trunc(x float64) float64 // 截取函数\n\n# 导航 #\n" }, { "path": "chapter06/06.0.md", "content": "# 第六章 文件系统 #\n\nGo 的标准库提供了很多工具，可以处理文件系统中的文件、构造和解析文件名等。\n\n处理文件的第一步是确定要处理的文件的名字。Go 将文件名表示为简单的字符串，提供了 `path`、`filepath` 等库来操作文件名或路径。用 `os` 中 `File` 结构的 `Readdir` 可以列出一个目录中的内容。\n\n可以用 `os.Stat` 或 `os.Lstat` 来检查文件的一些特性，如权限、大小等。\n\n有时需要创建草稿文件来保存临时数据，或将数据移动到一个永久位置之前需要临时文件存储，`os.TempDir` 可以返回默认的临时目录，用于存放临时文件。关于临时文件，在 `ioutil` 中已经讲解了。\n\n`os` 包还包含了很多其他文件系统相关的操作，比如创建目录、重命名、移动文件等等。\n\n由于本章探讨文件系统相关知识，`os` 包中关于进程相关的知识会在后续章节讲解。\n\n# 导航 #\n\n- [第五章](/chapter05/05.0.md)\n- 下一节：[os — 平台无关的操作系统功能实现](06.1.md)\n" }, { "path": "chapter06/06.1.md", "content": "# 6.1 os — 平台无关的操作系统功能实现 #\n\n`os` 包提供了平台无关的操作系统功能接口。尽管错误处理是 go 风格的，但设计是 Unix 风格的；所以，失败的调用会返回 `error` 而非错误码。通常 `error` 里会包含更多信息。例如，如果使用一个文件名的调用（如 Open、Stat）失败了，打印错误时会包含该文件名，错误类型将为 `*PathError`，其内部可以解包获得更多信息。\n\nos 包规定为所有操作系统实现的接口都是一致的。有一些某个系统特定的功能，需要使用 `syscall` 获取。实际上，`os` 依赖于 `syscall`。在实际编程中，我们应该总是优先使用 `os` 中提供的功能，而不是 `syscall`。\n\n下面是一个简单的例子，打开一个文件并从中读取一些数据：\n\n```go\nfile, err := os.Open(\"file.go\") // For read access.\nif err != nil {\n\tlog.Fatal(err)\n}\n```\n如果打开失败，错误字符串是自解释的，例如：\n\n`open file.go: no such file or directory`\n\n而不像 C 语言，需要额外的函数（或宏）来解释错误码。\n\n## 文件 I/O\n\n在第一章，我们较全面的介绍了 Go 中的 I/O。本节，我们着重介绍文件相关的 I/O。因为 I/O 操作涉及到系统调用，在讲解时会涉及到 Unix 在这方面的系统调用。\n\n在 Unix 系统调用中，所有 I/O 操作以文件描述符 ( 一个非负整数 , 通常是小整数 ) 来指代打开的文件。文件描述符用以表示所有类型的已打开文件，包括管道（pipe）、FIFO、socket、终端、设备和普通文件。这里，我们主要介绍普通文件的 I/O。\n\n在 Go 中，文件描述符封装在 `os.File` 结构中，通过 `File.Fd()` 可以获得底层的文件描述符：fd。\n\n按照惯例，大多数程序都期望能够使用 3 种标准的文件描述符：0- 标准输入；1- 标准输出；2- 标准错误。`os` 包提供了 3 个 `File` 对象，分别代表这 3 种标准描述符：`Stdin`、`Stdout` 和 `Stderr`，它们对应的文件名分别是：/dev/stdin、/dev/stdout 和 /dev/stderr。注意，这里说的文件名，并不一定存在，比如 Windows 下就没有。\n\n### 打开一个文件：OpenFile\n\n`OpenFile` 既能打开一个已经存在的文件，也能创建并打开一个新文件。\n\n`func OpenFile(name string, flag int, perm FileMode) (*File, error)`\n\n`OpenFile` 是一个更一般性的文件打开函数，大多数调用者都应用 `Open` 或 `Create` 代替本函数。它会使用指定的选项（如 O_RDONLY 等）、指定的模式（如 0666 等）打开指定名称的文件。如果操作成功，返回的文件对象可用于 I/O。如果出错，错误底层类型是 `*PathError`。\n\n要打开的文件由参数 `name` 指定，它可以是绝对路径或相对路径（相对于进程当前工作目录），也可以是一个符号链接（会对其进行解引用）。\n\n位掩码参数 `flag` 用于指定文件的访问模式，可用的值在 `os` 中定义为常量（以下值并非所有操作系统都可用）：\n\n```\nconst (\n O_RDONLY int = syscall.O_RDONLY // 只读模式打开文件\n O_WRONLY int = syscall.O_WRONLY // 只写模式打开文件\n O_RDWR int = syscall.O_RDWR // 读写模式打开文件\n O_APPEND int = syscall.O_APPEND // 写操作时将数据附加到文件尾部\n O_CREATE int = syscall.O_CREAT // 如果不存在将创建一个新文件\n O_EXCL int = syscall.O_EXCL // 和 O_CREATE 配合使用，文件必须不存在\n O_SYNC int = syscall.O_SYNC // 打开文件用于同步 I/O\n O_TRUNC int = syscall.O_TRUNC // 如果可能，打开时清空文件\n)\n```\n其中，`O_RDONLY`、`O_WRONLY`、`O_RDWR` 应该只指定一个，剩下的通过 `|` 操作符来指定。该函数内部会给 `flags` 加上 `syscall.O_CLOEXEC`，在 fork 子进程时会关闭通过 `OpenFile` 打开的文件，即子进程不会重用该文件描述符。\n\n*注意：由于历史原因，`O_RDONLY | O_WRONLY` 并非等于 `O_RDWR`，它们的值一般是 0、1、2。*\n\n位掩码参数 `perm` 指定了文件的模式和权限位，类型是 `os.FileMode`，文件模式位常量定义在 `os` 中：\n\n```go\nconst (\n // 单字符是被 String 方法用于格式化的属性缩写。\n ModeDir FileMode = 1 << (32 - 1 - iota) // d: 目录\n ModeAppend // a: 只能写入，且只能写入到末尾\n ModeExclusive // l: 用于执行\n ModeTemporary // T: 临时文件（非备份文件）\n ModeSymlink // L: 符号链接（不是快捷方式文件）\n ModeDevice // D: 设备\n ModeNamedPipe // p: 命名管道（FIFO）\n ModeSocket // S: Unix 域 socket\n ModeSetuid // u: 表示文件具有其创建者用户 id 权限\n ModeSetgid // g: 表示文件具有其创建者组 id 的权限\n ModeCharDevice // c: 字符设备，需已设置 ModeDevice\n ModeSticky // t: 只有 root/ 创建者能删除 / 移动文件\n \n // 覆盖所有类型位（用于通过 & 获取类型位），对普通文件，所有这些位都不应被设置\n ModeType = ModeDir | ModeSymlink | ModeNamedPipe | ModeSocket | ModeDevice\n ModePerm FileMode = 0777 // 覆盖所有 Unix 权限位（用于通过 & 获取类型位）\n)\n```\n以上常量在所有操作系统都有相同的含义（可用时），因此文件的信息可以在不同的操作系统之间安全的移植。不是所有的位都能用于所有的系统，唯一共有的是用于表示目录的 `ModeDir` 位。\n\n以上这些被定义的位是 `FileMode` 最重要的位。另外 9 个位（权限位）为标准 Unix rwxrwxrwx 权限（所有人都可读、写、运行）。\n\n`FileMode` 还定义了几个方法，用于判断文件类型的 `IsDir()` 和 `IsRegular()`，用于获取权限的 `Perm()`。\n\n返回的 `error`，具体实现是 `*os.PathError`，它会记录具体操作、文件路径和错误原因。\n\n另外，在 `OpenFile` 内部会调用 `NewFile`，来得到 `File` 对象。\n\n**使用方法**\n\n打开一个文件，一般通过 `Open` 或 `Create`，我们看这两个函数的实现。\n\n```go\nfunc Open(name string) (*File, error) {\n\treturn OpenFile(name, O_RDONLY, 0)\n}\n\nfunc Create(name string) (*File, error) {\n\treturn OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0666)\n}\n```\n\n### 读取文件内容：Read\n\n`func (f *File) Read(b []byte) (n int, err error)`\n\n`Read` 方法从 `f` 中读取最多 `len(b)` 字节数据并写入 `b`。它返回读取的字节数和可能遇到的任何错误。文件终止标志是读取 0 个字节且返回值 err 为 `io.EOF`。\n\n从方法声明可以知道，`File` 实现了 `io.Reader` 接口。\n\n`Read` 对应的系统调用是 `read`。\n\n对比下 `ReadAt` 方法：\n\n`func (f *File) ReadAt(b []byte, off int64) (n int, err error)`\n\n`ReadAt` 从指定的位置（相对于文件开始位置）读取长度为 `len(b)` 个字节数据并写入 `b`。它返回读取的字节数和可能遇到的任何错误。当 n0，`Readdirnames` 函数会返回一个最多 n 个成员的切片。这时，如果 `Readdirnames` 返回一个空切片，它会返回一个非 nil 的错误说明原因。如果到达了目录 `f` 的结尾，返回值 err 会是 `io.EOF`。\n\n如果 n<=0，`Readdirnames` 函数返回目录中剩余所有文件对象的名字构成的切片。此时，如果 `Readdirnames` 调用成功（读取所有内容直到结尾），它会返回该切片和 nil 的错误值。如果在到达结尾前遇到错误，会返回之前成功读取的名字构成的切片和该错误。\n\n`func (f *File) Readdir(n int) (fi []FileInfo, err error)`\n\n`Readdir` 内部会调用 `Readdirnames`，将得到的 `names` 构造路径，通过 `Lstat` 构造出 `[]FileInfo`。\n\n列出某个目录的文件列表示例程序见 [dirtree](/code/src/chapter06/os/dirtree/main.go)。\n\n# 导航 #\n\n- [第六章](/chapter06/06.0.md)\n- 下一节：[path/filepath — 兼容操作系统的文件路径操作](06.2.md)\n" }, { "path": "chapter06/06.2.md", "content": "# 6.2 path/filepath — 兼容操作系统的文件路径操作 #\n\n`path/filepath` 包涉及到路径操作时，路径分隔符使用 `os.PathSeparator`。不同系统，路径表示方式有所不同，比如 Unix 和 Windows 差别很大。本包能够处理所有的文件路径，不管是什么系统。\n\n注意，路径操作函数并不会校验路径是否真实存在。\n\n## 解析路径名字符串\n\n`Dir()` 和 `Base()` 函数将一个路径名字符串分解成目录和文件名两部分。（注意一般情况，这些函数与 Unix 中 dirname 和 basename 命令类似，但如果路径以 `/` 结尾，`Dir` 的行为和 `dirname` 不太一致。）\n\n```go\nfunc Dir(path string) string\nfunc Base(path string) string\n```\n`Dir` 返回路径中除去最后一个路径元素的部分，即该路径最后一个元素所在的目录。在使用 `Split` 去掉最后一个元素后，会简化路径并去掉末尾的斜杠。如果路径是空字符串，会返回 \".\"；如果路径由 1 到多个斜杠后跟 0 到多个非斜杠字符组成，会返回 \"/\"；其他任何情况下都不会返回以斜杠结尾的路径。\n\n`Base` 函数返回路径的最后一个元素。在提取元素前会去掉末尾的斜杠。如果路径是 \"\"，会返回 \".\"；如果路径是只有一个斜杆构成的，会返回 \"/\"。\n\n比如，给定路径名 `/home/polaris/studygolang.go`，`Dir` 返回 `/home/polaris`，而 `Base` 返回 `studygolang.go`。\n\n如果给定路径名 `/home/polaris/studygolang/`，`Dir` 返回 `/home/polaris/studygolang`（这与 Unix 中的 dirname 不一致，dirname 会返回 /home/polaris），而 `Base` 返回 `studygolang`。\n\n有人提出此问题，见[issue13199](https://github.com/golang/go/issues/13199)，不过官方认为这不是问题，如果需要和 `dirname` 一样的功能，应该自己处理，比如在调用 `Dir` 之前，先将末尾的 `/` 去掉。\n\n此外，`Ext` 可以获得路径中文件名的扩展名。\n\n`func Ext(path string) string`\n\n`Ext` 函数返回 `path` 文件扩展名。扩展名是路径中最后一个从 `.` 开始的部分，包括 `.`。如果该元素没有 `.` 会返回空字符串。\n\n## 相对路径和绝对路径\n\n某个进程都会有当前工作目录（进程相关章节会详细介绍），一般的相对路径，就是针对进程当前工作目录而言的。当然，可以针对某个目录指定相对路径。\n\n绝对路径，在 Unix 中，以 `/` 开始；在 Windows 下以某个盘符开始，比如 `C:\\Program Files`。\n\n`func IsAbs(path string) bool`\n\n`IsAbs` 返回路径是否是一个绝对路径。而\n\n`func Abs(path string) (string, error)`\n\n`Abs` 函数返回 `path` 代表的绝对路径，如果 `path` 不是绝对路径，会加入当前工作目录以使之成为绝对路径。因为硬链接的存在，不能保证返回的绝对路径是唯一指向该地址的绝对路径。在 `os.Getwd` 出错时，`Abs` 会返回该错误，一般不会出错，如果路径名长度超过系统限制，则会报错。\n\n`func Rel(basepath, targpath string) (string, error)`\n\n`Rel` 函数返回一个相对路径，将 `basepath` 和该路径用路径分隔符连起来的新路径在词法上等价于 `targpath`。也就是说，`Join(basepath, Rel(basepath, targpath))` 等价于 `targpath`。如果成功执行，返回值总是相对于 `basepath` 的，即使 `basepath` 和 `targpath` 没有共享的路径元素。如果两个参数一个是相对路径而另一个是绝对路径，或者 `targpath` 无法表示为相对于 `basepath` 的路径，将返回错误。\n\n```go\nfmt.Println(filepath.Rel(\"/home/polaris/studygolang\", \"/home/polaris/studygolang/src/logic/topic.go\"))\nfmt.Println(filepath.Rel(\"/home/polaris/studygolang\", \"/data/studygolang\"))\n\n// Output:\n// src/logic/topic.go \n// ../../../data/studygolang \n```\n\n## 路径的切分和拼接\n\n对于一个常规文件路径，我们可以通过 `Split` 函数得到它的目录路径和文件名：\n\n`func Split(path string) (dir, file string)`\n\n`Split` 函数根据最后一个路径分隔符将路径 `path` 分隔为目录和文件名两部分（`dir` 和 `file`）。如果路径中没有路径分隔符，函数返回值 `dir` 为空字符串，`file` 等于 `path`；反之，如果路径中最后一个字符是 `/`，则 `dir` 等于 `path`，`file` 为空字符串。返回值满足 `path == dir+file`。`dir` 非空时，最后一个字符总是 `/`。\n\n```go\n// dir == /home/polaris/，file == studygolang\nfilepath.Split(\"/home/polaris/studygolang\")\n\n// dir == /home/polaris/studygolang/，file == \"\"\nfilepath.Split(\"/home/polaris/studygolang/\")\n\n// dir == \"\"，file == studygolang\nfilepath.Split(\"studygolang\")\n```\n相对路径到绝对路径的转变，需要经过路径的拼接。`Join` 用于将多个路径拼接起来，会根据情况添加路径分隔符。\n\n`func Join(elem ...string) string`\n\n`Join` 函数可以将任意数量的路径元素放入一个单一路径里，会根据需要添加路径分隔符。结果是经过 `Clean` 的，所有的空字符串元素会被忽略。对于拼接路径的需求，我们应该总是使用 `Join` 函数来处理。\n\n有时，我们需要分割 `PATH` 或 `GOPATH` 之类的环境变量（这些路径被特定于 `OS` 的列表分隔符连接起来），`filepath.SplitList` 就是这个用途：\n\n`func SplitList(path string) []string`\n\n注意，与 `strings.Split` 函数的不同之处是：对 \"\"，SplitList 返回[]string{}，而 `strings.Split` 返回 []string{\"\"}。`SplitList` 内部调用的是 `strings.Split`。\n\n## 规整化路径\n\n`func Clean(path string) string`\n\n`Clean` 函数通过单纯的词法操作返回和 `path` 代表同一地址的最短路径。\n\n它会不断的依次应用如下的规则，直到不能再进行任何处理：\n\n1. 将连续的多个路径分隔符替换为单个路径分隔符\n2. 剔除每一个 `.` 路径名元素（代表当前目录）\n3. 剔除每一个路径内的 `..` 路径名元素（代表父目录）和它前面的非 `..` 路径名元素\n4. 剔除开始于根路径的 `..` 路径名元素，即将路径开始处的 `/..` 替换为 `/`（假设路径分隔符是 `/`）\n\n返回的路径只有其代表一个根地址时才以路径分隔符结尾，如 Unix 的 `/` 或 Windows 的 `C:\\`。\n\n如果处理的结果是空字符串，Clean 会返回 `.`，代表当前路径。\n\n## 符号链接指向的路径名\n\n在上一节 `os` 包中介绍了 `Readlink`，可以读取符号链接指向的路径名。不过，如果原路径中又包含符号链接，`Readlink` 却不会解析出来。`filepath.EvalSymlinks` 会将所有路径的符号链接都解析出来。除此之外，它返回的路径，是直接可访问的。\n\n`func EvalSymlinks(path string) (string, error)`\n\n如果 `path` 或返回值是相对路径，则是相对于进程当前工作目录。\n\n`os.Readlink` 和 `filepath.EvalSymlinks` 区别示例程序：\n\n```go\n// 在当前目录下创建一个 studygolang.txt 文件和一个 symlink 目录，在 symlink 目录下对 studygolang.txt 建一个符号链接 studygolang.txt.2\nfmt.Println(filepath.EvalSymlinks(\"symlink/studygolang.txt.2\"))\nfmt.Println(os.Readlink(\"symlink/studygolang.txt.2\"))\n\n// Ouput:\n// studygolang.txt \n// ../studygolang.txt \n```\n\n## 文件路径匹配\n\n`func Match(pattern, name string) (matched bool, err error)`\n\n`Match` 指示 `name` 是否和 shell 的文件模式匹配。模式语法如下：\n\n```go\npattern:\n\t{ term }\nterm:\n\t'*' 匹配 0 或多个非路径分隔符的字符\n\t'?' 匹配 1 个非路径分隔符的字符\n\t'[' [ '^' ] { character-range } ']' \n\t\t\t\t 字符组（必须非空）\n\tc 匹配字符 c（c != '*', '?', '\\\\', '['）\n\t'\\\\' c 匹配字符 c\ncharacter-range:\n\tc 匹配字符 c（c != '\\\\', '-', ']'）\n\t'\\\\' c 匹配字符 c\n\tlo '-' hi 匹配区间[lo, hi]内的字符\n```\n匹配要求 `pattern` 必须和 `name` 全匹配上，不只是子串。在 Windows 下转义字符被禁用。\n\n`Match` 函数很少使用，搜索了一遍，标准库没有用到这个函数。而 `Glob` 函数在模板标准库中被用到了。\n\n`func Glob(pattern string) (matches []string, err error)`\n\n`Glob` 函数返回所有匹配了 模式字符串 `pattern` 的文件列表或者 nil（如果没有匹配的文件）。`pattern` 的语法和 `Match` 函数相同。`pattern` 可以描述多层的名字，如 `/usr/*/bin/ed`（假设路径分隔符是 `/`）。\n\n注意，`Glob` 会忽略任何文件系统相关的错误，如读目录引发的 I/O 错误。唯一的错误和 `Match` 一样，在 `pattern` 不合法时，返回 `filepath.ErrBadPattern`。返回的结果是根据文件名字典顺序进行了排序的。\n\n`Glob` 的常见用法，是读取某个目录下所有的文件，比如写单元测试时，读取 `testdata` 目录下所有测试数据：\n\n`filepath.Glob(\"testdata/*.input\")`\n\n## 遍历目录\n\n在介绍 `os` 时，讲解了读取目录的方法，并给出了一个遍历目录的示例。在 `filepath` 中，提供了 `Walk` 函数，用于遍历目录树。\n\n`func Walk(root string, walkFn WalkFunc) error`\n\n`Walk` 函数会遍历 `root` 指定的目录下的文件树，对每一个该文件树中的目录和文件都会调用 `walkFn`，包括 `root` 自身。所有访问文件 / 目录时遇到的错误都会传递给 `walkFn` 过滤。文件是按字典顺序遍历的，这让输出更漂亮，但也导致处理非常大的目录时效率会降低。`Walk` 函数不会遍历文件树中的符号链接（快捷方式）文件包含的路径。\n\n`walkFn` 的类型 `WalkFunc` 的定义如下：\n\n`type WalkFunc func(path string, info os.FileInfo, err error) error`\n\n`Walk` 函数对每一个文件 / 目录都会调用 `WalkFunc` 函数类型值。调用时 `path` 参数会包含 `Walk` 的 `root` 参数作为前缀；就是说，如果 `Walk` 函数的 `root` 为 \"dir\"，该目录下有文件 \"a\"，将会使用 \"dir/a\" 作为调用 `walkFn` 的参数。`walkFn` 参数被调用时的 `info` 参数是 `path` 指定的地址（文件 / 目录）的文件信息，类型为 `os.FileInfo`。\n\n如果遍历 `path` 指定的文件或目录时出现了问题，传入的参数 `err` 会描述该问题，`WalkFunc` 类型函数可以决定如何去处理该错误（`Walk` 函数将不会深入该目录）；如果该函数返回一个错误，`Walk` 函数的执行会中止；只有一个例外，如果 `Walk` 的 `walkFn` 返回值是 `SkipDir`，将会跳过该目录的内容而 `Walk` 函数照常执行处理下一个文件。\n\n和 `os` 遍历目录树的示例对应，使用 `Walk` 遍历目录树的示例程序在 [walk](/code/src/chapter06/filepath/walk/main.go)，程序简单很多。\n\n## Windows 起作用的函数\n\n`filepath` 中有三个函数：`VolumeName`、`FromSlash` 和 `ToSlash`，针对非 Unix 平台的。\n\n## 关于 path 包\n\n`path` 包提供了对 `/` 分隔的路径的实用操作函数。\n\n在 Unix 中，路径的分隔符是 `/`，但 Windows 是 `\\`。在使用 `path` 包时，应该总是使用 `/`，不论什么系统。\n\n`path` 包中提供的函数，`filepath` 都有提供，功能类似，但实现不同。\n\n一般应该总是使用 `filepath` 包，而不是 `path` 包。\n\n# 导航 #\n\n- 上一节：[os — 平台无关的操作系统功能实现](06.1.md)\n- 下一节：[io/fs — 抽象文件系统](06.3.md)\n" }, { "path": "chapter06/06.3.md", "content": "# 6.3 io/fs — 抽象文件系统 #\n\nGo 语言从 1.16 开始增加了 io/fs 包，该包定义了一个文件系统需要的相关基础接口，因此我们称之为抽象文件系统。该文件系统是层级文件系统或叫树形文件系统，Unix 文件系统就是这种类型。\n\n本节除了讲解标准库的相关内容，还会实现一个文件系统作为例子。\n\n> 注意，因为抽象了一个文件系统，之前 os 包中和文件系统相关的功能都移到 io/fs 包了，os 中的原类型只是 io/fs 对应类型的别名。如果你的系统要求 Go1.16，应该优先使用 io/fs 包。\n\n## 三个核心接口 ##\n\n一个文件系统有些必要的元素，io/fs 包提供两个最小的接口来表示，即 fs.FS 和 fs.File。但因为 fs.File 依赖 fs.FileInfo 接口，因此实际上是三个接口。\n\n### fs.FS ###\n\n该接口提供了对层级文件系统的访问。一个文件系统的最低要求是必须实现 fs.FS 接口，但一般还会实现额外的接口，比如 ReadFileFS，该接口在后文讲解。\n\n```go\ntype FS interface {\n // Open opens the named file.\n //\n // When Open returns an error, it should be of type *PathError\n // with the Op field set to \"open\", the Path field set to name,\n // and the Err field describing the problem.\n //\n // Open should reject attempts to open names that do not satisfy\n // ValidPath(name), returning a *PathError with Err set to\n // ErrInvalid or ErrNotExist.\n Open(name string) (File, error)\n}\n```\n\n该接口只有一个方法，即打开一个命名文件，该方法的实现要求如下：\n\n- 如果 Open 方法出错，应该返回 `*PathError` 类型的错误，该类型定义如下：\n\n```go\ntype PathError struct {\n Op string\n Path string\n Err error\n}\n```\n\n返回该类型错误时，Op 字段设置为 \"open\"，Path 字段设置为文件名，而 Err 字段描述错误原因。\n\n注：在 os 那小节提到过该类型，Go 1.16 后，`os.PathError` 只是 `fs.PathError` 的别名。\n\n```go\ntype PathError = fs.PathError\n```\n\n- 对于指定的文件名，需要满足 `ValidPath(name)` 函数，如果不满足，则返回 `*PathError` 的 Err 为 fs.ErrInvalid 或 fs.ErrNotExist 的错误。\n\n```go\nfunc ValidPath(name string) bool\n```\n\n传递给该函数的 name 应该是一个非根，且是 `/` 分隔的，例如 `x/y/z`。除了只包含 `.`，其他情况不能有 `.` 和 `..`。\n\n因为 Open 方法返回一个 fs.File 接口类型，因此一个文件系统只实现 fs.FS 还不够，需要同时实现 fs.File 接口。\n\n### fs.File ###\n\n该接口提供对单个文件的访问。File 接口是文件的最低实现要求。一个文件可以实现其他接口，例如fs.ReadDirFile，fs.ReaderAt 或 fs.Seeker，以提供额外或优化的功能。\n\n```go\ntype File interface {\n Stat() (FileInfo, error)\n Read([]byte) (int, error)\n Close() error\n}\n```\n\n通过 fs.FS 接口的 Open 打开文件后，通过 fs.File 接口的 Read 方法进行读操作，这个方法和 io.Reader 接口的 Read 方法签名一样。\n\n对操作系统有所了解的读者应该知晓（特别是 Unix 系统），目录也是文件，只是特殊的文件。因此，在遍历文件目录树时，我们通常需要判断文件是什么类型，也可能需要获取文件的一些元数据信息，比如文件名、大小、修改时间等，而这就是 Stat 方法的功能。该方法会返回一个 FileInfo 类型，它也是一个接口。这就是文件系统需要实现的第三接口，稍后讲解。\n\n在 Go 中，你应该始终记住，打开文件，进行操作后，记得关闭文件，否则会泄露文件描述符。所以，fs.File 的第是三个方法就是 Close 方法，它的签名和 io.Closer 是一致的。\n\n### fs.FileInfo ###\n\n该接口描述一个文件的元数据信息，它由 Stat 返回。为了方便，在 io/fs 包有一个 Stat 函数：\n\n```go\nfunc Stat(fsys FS, name string) (FileInfo, error)\n```\n\n该函数接受任意的 FS 文件系统和该系统下的任意一个文件。如果 fsys 实现了 StatFS，则直接通过 StatFS 的 Stat 方法获取 FileInfo，否则需要 Open 文件，然后调用 File 的 Stat 方法来获取 FileInfo。关于 fs.StatFS 接口后文讲解。\n\n本节开头提到了，Go1.16 开始，os 包中和文件系统相关的类型移到 io/fs 包中了，fs.FileInfo 就是其中之一。因为在 os 中已经讲过该接口了，此处不再赘述。\n\n## 实现一个文件系统 ##\n\n介绍完这三个核心接口，我们尝试实现一个文件系统。这是一个基于内存的文件系统，这个实现相对比较简陋。\n\n### 实现 fs.File 和 fs.FileInfo ###\n\n实现文件系统先实现这两个接口。我们通过一个类型来实现：\n\n```go\ntype file struct {\n\tname string\n\tcontent *bytes.Buffer\n\tmodTime time.Time\n\tclosed bool\n}\n\nfunc (f *file) Read(p []byte) (int, error) {\n\tif f.closed {\n\t\treturn 0, errors.New(\"file closed\")\n\t}\n\n\treturn f.content.Read(p)\n}\n\nfunc (f *file) Stat() (fs.FileInfo, error) {\n\tif f.closed {\n\t\treturn nil, errors.New(\"file closed\")\n\t}\n\n\treturn f, nil\n}\n\n// Close 关闭文件，可以调用多次。\nfunc (f *file) Close() error {\n\tf.closed = true\n\treturn nil\n}\n\n// 实现 fs.FileInfo\n\nfunc (f *file) Name() string {\n\treturn f.name\n}\n\nfunc (f *file) Size() int64 {\n\treturn int64(f.content.Len())\n}\n\nfunc (f *file) Mode() fs.FileMode {\n\t// 固定为 0444\n\treturn 0444\n}\n\nfunc (f *file) ModTime() time.Time {\n\treturn f.modTime\n}\n\n// IsDir 目前未实现目录功能\nfunc (f *file) IsDir() bool {\n\treturn false\n}\n\nfunc (f *file) Sys() interface{} {\n\treturn nil\n}\n```\n\n- file 同时实现 fs.File 和 fs.FileInfo；\n- 文件内容放在 file 的 bytes.Buffer 类型中，它实现了 io.Reader，因此 file 的 Read 可以直接通过它实现；\n- 目前是一个简化实现，因此 IsDir 未实现目录功能，只返回 false；\n\n### 实现 fs.FS ###\n\n实现了 fs.File，通过它可以实现 fs.FS：\n\n```go\ntype FS struct {\n\tfiles map[string]*file\n}\n\nfunc NewFS() *FS {\n\treturn &FS{\n\t\tfiles: make(map[string]*file),\n\t}\n}\n\nfunc (fsys *FS) Open(name string) (fs.File, error) {\n\tif !fs.ValidPath(name) {\n\t\treturn nil, &fs.PathError{\n\t\t\tOp: \"open\",\n\t\t\tPath: name,\n\t\t\tErr: fs.ErrInvalid,\n\t\t}\n\t}\n\n\tif f, ok := fsys.files[name]; !ok {\n\t\treturn nil, &fs.PathError{\n\t\t\tOp: \"open\",\n\t\t\tPath: name,\n\t\t\tErr: fs.ErrNotExist,\n\t\t}\n\t} else {\n\t\treturn f, nil\n\t}\n}\n```\n\n- FS 类型中的 files 存放所有的文件；\n- 按照前面 Open 方法的实现要求，先通过 ValidPath 函数进行校验，接着通过 name 查找 file；\n\n细心的读者应该会发现，io/fs 并没有提供 Write 相关的功能，那我们读什么呢？为此，我们实现一个 Write 的功能。\n\n```go\nfunc (fsys *FS) WriteFile(name, content string) error {\n\tif !fs.ValidPath(name) {\n\t\treturn &fs.PathError{\n\t\t\tOp: \"write\",\n\t\t\tPath: name,\n\t\t\tErr: fs.ErrInvalid,\n\t\t}\n\t}\n\n\tf := &file{\n\t\tname: name,\n\t\tcontent: bytes.NewBufferString(content),\n\t\tmodTime: time.Now(),\n\t}\n\n\tfsys.files[name] = f\n\n\treturn nil\n}\n```\n\nWriteFile 方法就是生成一个 file 然后存入 files 中。\n\n### 验证 ###\n\n一个基于内存的文件系统已经实现完成，接下来需要验证下。\n\n```go\nfunc TestMemFS(t *testing.T) {\n\tname := \"x/y/name.txt\"\n\tcontent := \"This is polarisxu, welcome.\"\n\tmemFS := memfs.NewFS()\n\terr := memFS.WriteFile(name, content)\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\n\tf, err := memFS.Open(name)\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\tdefer f.Close()\n\n\tfi, err := f.Stat()\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\n\tt.Log(fi.Name(), fi.Size(), fi.ModTime())\n\n\tvar result = make([]byte, int(fi.Size()))\n\tn, err := f.Read(result)\n\tif err != nil {\n\t\tt.Fatal(err)\n\t}\n\n\tif string(result[:n]) != content {\n\t\tt.Errorf(\"expect: %s, actual: %s\", content, result[:n])\n\t}\n}\n```\n\n如果测试通过，说明基于内存的简单文件系统已经完成。至于缺失的功能，本节后面再完善。\n\n## 增强型接口 ##\n\n上面实现的内存文件系统中，目录功能是有问题的，比如我们没法遍历整个文件系统。要实现一个更完整的文件系统，需要实现 io/fs 包中的其他接口。\n\n### fs.DirEntry 和相关接口 ###\n\n在文件系统中，一个目录下可能会有子目录或文件，这称为 entry，在 io/fs 包中用 DirEntry 接口表示：\n\n```go\ntype DirEntry interface {\n\t// Name returns the name of the file (or subdirectory) described by the entry.\n\t// This name is only the final element of the path (the base name), not the entire path.\n\t// For example, Name would return \"hello.go\" not \"/home/gopher/hello.go\".\n\tName() string\n\n\t// IsDir reports whether the entry describes a directory.\n\tIsDir() bool\n\n\t// Type returns the type bits for the entry.\n\t// The type bits are a subset of the usual FileMode bits, those returned by the FileMode.Type method.\n\tType() FileMode\n\n\t// Info returns the FileInfo for the file or subdirectory described by the entry.\n\t// The returned FileInfo may be from the time of the original directory read\n\t// or from the time of the call to Info. If the file has been removed or renamed\n\t// since the directory read, Info may return an error satisfying errors.Is(err, ErrNotExist).\n\t// If the entry denotes a symbolic link, Info reports the information about the link itself,\n\t// not the link's target.\n\tInfo() (FileInfo, error)\n}\n```\n\n- `Name()` 方法和 FileInfo 接口的 `Name()` 方法类似，代表的是 base name，而我们上面实现的文件系统没有处理这一点；\n- `Type()` 方法返回一个 fs.FileMode，表示 entry 的位类型，关于 FileMode 的详细信息在 os 包中有讲解；\n- `Info()` 方法和 Stat 有点类似，获取元数据信息；如果 entry 是软链接，Info() 返回的 FileInfo 是链接本身的信息，而不是目标文件；\n\n为了方便遍历文件系统（目录），io/fs 包提供了 ReadDir 函数，用来获取某个目录下的所有目录项：\n\n```go\nfunc ReadDir(fsys FS, name string) ([]DirEntry, error)\n```\n\n对于这个函数的实现，如果第一个参数实现了 fs.ReadDirFS 接口，直接调用该接口的 ReadDir 方法：\n\n```go\ntype ReadDirFS interface {\n\tFS\n\n\t// ReadDir reads the named directory\n\t// and returns a list of directory entries sorted by filename.\n\tReadDir(name string) ([]DirEntry, error)\n}\n```\n\n否则看是否实现了 fs.ReadDirFile 接口，没实现则报错；否则调用该接口的 ReadDir 方法：\n\n```go\ntype ReadDirFile interface {\n\tFile\n\n\t// ReadDir reads the contents of the directory and returns\n\t// a slice of up to n DirEntry values in directory order.\n\t// Subsequent calls on the same file will yield further DirEntry values.\n\t//\n\t// If n > 0, ReadDir returns at most n DirEntry structures.\n\t// In this case, if ReadDir returns an empty slice, it will return\n\t// a non-nil error explaining why.\n\t// At the end of a directory, the error is io.EOF.\n\t//\n\t// If n <= 0, ReadDir returns all the DirEntry values from the directory\n\t// in a single slice. In this case, if ReadDir succeeds (reads all the way\n\t// to the end of the directory), it returns the slice and a nil error.\n\t// If it encounters an error before the end of the directory,\n\t// ReadDir returns the DirEntry list read until that point and a non-nil error.\n\tReadDir(n int) ([]DirEntry, error)\n}\n```\n\n这个接口的 ReadDir 比 ReadDirFS 复杂多了，但 ReadDirFS 的 ReadDir 必须自己对 entry 进行排序。此外，如果目录下内容特别多，ReadDirFile 接口会更适合，它可以分段读取。而且目录应该实现 ReadDirFile 接口。\n\n## 其他 fs.FS 相关的接口 ##\n\n在讲解 fs.FS 接口时提到还有其他接口，用于增强 fs.FS，即嵌入了 fs.FS 接口，除了已经介绍的 ReadDirFS 接口，还有如下接口。\n\n### fs.ReadFileFS ###\n\n该接口的定义如下：\n\n```go\ntype ReadFileFS interface {\n\tFS\n\n\t// ReadFile reads the named file and returns its contents.\n\t// A successful call returns a nil error, not io.EOF.\n\t// (Because ReadFile reads the whole file, the expected EOF\n\t// from the final Read is not treated as an error to be reported.)\n\tReadFile(name string) ([]byte, error)\n}\n```\n\n也就是说这是一个支持 ReadFile 的文件系统，如果一个文件系统实现了该接口，则 fs.ReadFile 函数会先直接使用该接口的 ReadFile 方法来实现：\n\n```go\nfunc ReadFile(fsys FS, name string) ([]byte, error)\n```\n\n如果没实现该接口，则通过 fs.FS 的 Open 方法获取 fs.File 类型，然后调用 fs.File 的 Read 方法来实现。有兴趣可以查看 fs.ReadFile 函数的实现。\n\n### fs.StatFS ###\n\n该接口的定义如下：\n\n```go\ntype StatFS interface {\n\tFS\n\n\t// Stat returns a FileInfo describing the file.\n\t// If there is an error, it should be of type *PathError.\n\tStat(name string) (FileInfo, error)\n}\n```\n\n如果一个文件系统支持 Stat 功能，则 fs.Stat 函数会优先使用该文件系统的 Stat 方法，否则通过 fs.FS 的 Open 方法获取 fs.File 类型，然后调用 fs.File 的 Stat 方法来实现。\n\n### fs.GlobFS ###\n\n该接口的定义如下：\n\n```go\ntype GlobFS interface {\n\tFS\n\n\t// Glob returns the names of all files matching pattern,\n\t// providing an implementation of the top-level\n\t// Glob function.\n\tGlob(pattern string) ([]string, error)\n}\n```\n\n类似的，实现了该接口，表示文件系统支持 Glob 方法。对应的，io/fs 提供了 Glob 函数：\n\n```go\nfunc Glob(fsys FS, pattern string) (matches []string, err error)\n```\n\n- 这是用于文件模式匹配的；\n- 语法和 path.Match 相同；\n- 模式（pattern）可以描述层级，比如：/usr/*/bin/ed；\n- 该函数会忽略文件系统错误，比如 IO 错误；唯一的错误是模式语法错误；\n\n和其他 fs.FS 相关接口对应的函数一样，Glob 函数内部实现优先调用 fs.GlobFS 接口，如果没实现该接口，则使用 ReadDir 遍历目录树来查找匹配的目标。\n\n### fs.SubFS ###\n\n该接口的定义如下：\n\n```go\ntype SubFS interface {\n\tFS\n\n\t// Sub returns an FS corresponding to the subtree rooted at dir.\n\tSub(dir string) (FS, error)\n}\n```\n\n这个接口的作用主要是让一个文件系统支持定义子文件系统。io/fs 包也提供了一个相应的函数 Sub：\n\n```go\nfunc Sub(fsys FS, dir string) (FS, error)\n```\n\n通过该函数可以获得一个子文件系统，该子文件系统的根由第二个参数 `dir` 指定。\n\n类似的，该函数的实现会优先判断 fsys 是否实现了 fs.SubFS 接口，以便调用其 Sub 方法。如果未实现，同时 dir 是 `.`，则原样返回 fsys，否则返回一个新实现的 fs.FS。\n\n不过有一点需要注意，对于 os 实现的 fs.FS 文件系统（磁盘文件系统），Sub 并不能提到 chroot 的进制，它不会限制子文件系统根之外的操作，典型的，子文件系统内部的文件软连到根之外，Sub 得到的子文件系统不会阻止这种行为。\n\n查看 fs.Sub 函数的源码可以发现，如果 fsys 没有实现 fs.SubFS，Sub 函数返回的 FS 实现了不少 FS 相关接口。\n\n### 设计思想 ###\n\n上面啰啰嗦嗦讲了好几个 fs.FS 相关接口，其中目的之一是希望理解其设计思想。\n\nio/fs 包中和 fs.FS 相关的接口如下：\n\n- fs.ReadDirFS\n- fs.ReadFileFS\n- fs.StatFS\n- fs.SubFS\n- fs.GlobFS\n\nGo 以简单著称，大道至简。Go 强调定义小接口。fs.FS 接口只有一个方法：Open，其他 fs.FS 相关接口都内嵌了 fs.FS 接口，以此来扩展文件系统的功能。同时 io/fs 包辅以相关便捷函数（比如 Stat、Sub、Glob 等），达到操作 fs.FS 的目的。\n\n## 完善内存文件系统 ##\n\n是时候完善我们上面实现的内存文件系统了。\n\n前面只是实现了文件的写入、读取，并没有实现文件系统该有的目录树。现在补充完善这部分内容，实现一个较完整的内存文件系统。具体看代码前，看看如何设计。\n\n### 如何设计 ###\n\n先通过一个类图表示 io/fs 包相关接口的关系。\n\n![](imgs/fs-class-diagram.png)\n\n要基于这些接口实现一个文件系统，我们需要先了解一些文件系统相关的知识（前面有提到，这里总结下）。\n\n- 文件系统是一个树形结构，有一个根目录；\n- 一个目录下的目录项，可以是文件或子目录；\n- 一切皆文件，所以目录也是文件；（虽然如此，但两者还是有不小区别，因此实现时不一定适合使用嵌入）\n\n所以，我们在实现 fs.FS 接口时，定义的类型 FS 有一个根目录字段：\n\n```go\ntype FS struct {\n\trootDir *dir\n}\n```\n\n#### 文件的实现 ####\n\n从上面类图可以看出，一个文件需要实现 fs.File 接口，同时因为该接口依赖 fs.FileInfo 接口，我们可以选择用一个单独的类型实现 fs.FileInfo 接口，也可以直接用这个文件类型（file）实现该接口，内存文件系统直接使用文件类型实现了 fs.FileInfo 接口。此外，一个文件还是其所在目录的目录项，因此还需要实现 fs.DirEntry 接口。因此内存文件系统的 file 类型实现了以下接口：\n\n- fs.File\n- fs.FileInfo\n- fs.DirEntry\n\n具体如何实现这些接口，需要先思考一个问题：文件内容用什么表示？因为是内存文件系统，因此一切都在内存中。文件内容本质上是字节数组，但因为要实现 fs.File 接口，这其中关键的是 Read 方法，它的签名和 io.Reader 接口的 Read 方法是一样的，因此在 file 类型中，我们用一个 bytes.Buffer 字段来存放文件内容。\n\n至于其他接口的实现相对较简单，这里不赘述。值得一提的是，因为 file 类型实现了 fs.FileInfo 接口，所以在实现 Stat 方法时，直接返回 file 的实例即可。\n\n#### 目录的实现 ####\n\n对于目录，我们用类型 dir 表示，它首先是其所在目录的目录项，因此需要实现 fs.DirEntry 接口；其次目录也是文件，因此它需要实现 fs.File 接口。同时，读取目录的内容，即读取其目录项，不应该通过 Read 读取，而 fs.ReadDirFile 接口是用来读目录的，因此 dir 应该实现它。同样的，因为 fs.DirEntry 和 fs.File 都依赖 fs.FileInfo 接口，跟 file 一样，我们不单独实现，而是让 dir 直接实现它。因此内存文件系统的 dir 类型实现了以下接口：\n\n- fs.DirEntry\n- fs.File\n- fs.ReadDirFile\n- fs.FileInfo\n\n因为目录涉及到有目录项，构成了一个树形结构。这里使用一个 map 来存放所有的目录项，key 是目录项的名称，value 是目录项的实例。\n\n```go\n// dir 代表一个目录\ntype dir struct {\n\tname string\n\tmodTime time.Time\n\n\t// 存放该目录下的子项，value 可能是 *dir 或 *file\n\tchildren map[string]fs.DirEntry\n}\n```\n\n因为 Read 对于目录来说没有实际价值，因此它的实现返回错误即可。dir 的难点在于实现 fs.ReadDirFile 接口中的 ReadDir 方法：给定一个目录，该方法需要返回该目录下的所有目录项。而且，根据 fs.ReadDirFile 中 ReadDir 方法的实现要求，它应该支持分步读取目录项。所以，在 dir 类型中增加一个字段：idx，用来表示当前读取到什么位置的目录项了。具体实现代码见后文。\n\n#### fs.FS 接口的实现 ####\n\n对于内存文件系统，如何实现 Open 方法呢？我们需要根据参数 name 在文件系统的目录树中找到该文件所在位置。因此，我们将该文件用 `/` 分隔，从左到右，一部分一部分，从文件系统的根开始，在目录树中查找，直到找到对应的文件，然后返回该文件。如果没找到，返回错误。\n\n具体来说，在遍历文件系统目录树时，如果某个目录项是文件，且是 name 的最后一部分，表示找到了该文件；如果某个目录项是目录，则递归遍历它的目录项。\n\n#### 创建目录和文件的实现 ####\n\nio/fs 没有定义创建目录和文件的接口，从这个维度看，io/fs 定义的文件系统是一个只读文件系统。但实际的文件系统，必然要有写入的接口。因此我们还需要实现创建目录和创建文件（写入内容）的功能。\n\n先看创建目录的实现。\n\n创建目录，实际上是构建一个层级关系。方法签名如下：\n\n```go\nfunc (fsys *FS) MkdirAll(path string) error\n```\n\n根据传入的 path，比如 `x/y/z`，能够创建对应的目录结构。因此我们将 path 通过 `/` 分隔，从左到右，一步步从文件系统的根开始在对应的层级创建目录。创建时，需要判断是否已经存在对应的目录。关键代码如下：\n\n```go\ncur := fsys.rootDir\nparts := strings.Split(path, \"/\")\nfor _, part := range parts {\n child := cur.children[part]\n if child == nil {\n childDir := &dir{\n name: part,\n modTime: time.Now(),\n children: make(map[string]fs.DirEntry),\n }\n cur.children[part] = childDir\n cur = childDir\n } else {\n childDir, ok := child.(*dir)\n if !ok {\n return fmt.Errorf(\"%s is not directory\", part)\n }\n\n cur = childDir\n }\n}\n```\n\n文件的创键和内容写入通过 WriteFile 方法实现。签名如下：\n\n```go\nfunc (fsys *FS) WriteFile(name, content string) error\n```\n\n在非完善版本中，粗暴的直接将传递的文件名（包括路径）和 file 实例关联，没有处理目录层级关系。因此，这里的实现的关键是要找到该文件（name 对应）的目录 dir 实例。和上面创建目录的思路类似，一步步处理。\n\n```go\n// getDir 通过一个路径获取其 dir 类型实例\nfunc (fsys *FS) getDir(path string) (*dir, error) {\n\tparts := strings.Split(path, \"/\")\n\n\tcur := fsys.rootDir\n\tfor _, part := range parts {\n\t\tchild := cur.children[part]\n\t\tif child == nil {\n\t\t\treturn nil, fmt.Errorf(\"%s is not exists\", path)\n\t\t}\n\n\t\tchildDir, ok := child.(*dir)\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"%s is not directory\", path)\n\t\t}\n\n\t\tcur = childDir\n\t}\n\n\treturn cur, nil\n}\n```\n\n得到了文件应该放置的目录（dir）后，就可以构建一个 file 实例，并将该实例放置到其目录的目录项中。\n\n```go\nfilename := filepath.Base(name)\n\ndir.children[filename] = &file{\n name: filename,\n content: bytes.NewBufferString(content),\n modTime: time.Now(),\n}\n```\n\n### 完整的实现代码 ###\n\n以下是 dir 类型的实现，代表一个目录，注意注释。\n\n```go\n// dir 代表一个目录\ntype dir struct {\n\tname string\n\tmodTime time.Time\n\n\t// 存放该目录下的子项，value 可能是 *dir 或 *file\n\tchildren map[string]fs.DirEntry\n\n\t// ReadDir 遍历用\n\tidx int\n}\n\n// dir 虽然是一个目录，但根据一切皆文件的思想，目录也是文件，因此需要实现 fs.File 接口\n// 这样，fs.FS 的 Open 方法可以对目录起作用。\n\nfunc (d *dir) Read(p []byte) (int, error) {\n\treturn 0, &fs.PathError{\n\t\tOp: \"read\",\n\t\tPath: d.name,\n\t\tErr: errors.New(\"is directory\"),\n\t}\n}\n\nfunc (d *dir) Stat() (fs.FileInfo, error) {\n\treturn d, nil\n}\n\nfunc (d *dir) Close() error {\n\treturn nil\n}\n\n// ReadDir 实现 fs.ReadDirFile 接口，方便遍历目录\nfunc (d *dir) ReadDir(n int) ([]fs.DirEntry, error) {\n\tnames := make([]string, 0, len(d.children))\n\tfor name := range d.children {\n\t\tnames = append(names, name)\n\t}\n\n\ttotalEntry := len(names)\n\tif n <= 0 {\n\t\tn = totalEntry\n\t}\n\n\tdirEntries := make([]fs.DirEntry, 0, n)\n\tfor i := d.idx; i < n && i < totalEntry; i++ {\n\t\tname := names[i]\n\t\tchild := d.children[name]\n\n\t\tf, isFile := child.(*file)\n\t\tif isFile {\n\t\t\tdirEntries = append(dirEntries, f)\n\t\t} else {\n\t\t\tdirEntry := child.(*dir)\n\t\t\tdirEntries = append(dirEntries, dirEntry)\n\t\t}\n\n\t\td.idx = i\n\t}\n\n\treturn dirEntries, nil\n}\n\n// 因为 fs.Stat 对目录也是有效的，因此 dir 需要实现 fs.FileInfo 接口\n\nfunc (d *dir) Name() string {\n\treturn d.name\n}\n\nfunc (d *dir) Size() int64 {\n\treturn 0\n}\n\nfunc (d *dir) Mode() fs.FileMode {\n\treturn fs.ModeDir | 0444\n}\n\nfunc (d *dir) ModTime() time.Time {\n\treturn d.modTime\n}\n\nfunc (d *dir) IsDir() bool {\n\treturn true\n}\n\nfunc (d *dir) Sys() interface{} {\n\treturn nil\n}\n\n// 因为 dir 是一个目录项，因此需要实现 fs.DirEntry 接口\n\nfunc (d *dir) Type() fs.FileMode {\n\treturn d.Mode()\n}\n\nfunc (d *dir) Info() (fs.FileInfo, error) {\n\treturn d, nil\n}\n```\n\n接着是 file 的实现，代表一个文件，注意注释。\n\n```go\n// file 代表一个文件\ntype file struct {\n\tname string\n\t// 存放文件内容\n\tcontent *bytes.Buffer\n\tmodTime time.Time\n\tclosed bool\n}\n\n// 实现 fs.File 接口\n\nfunc (f *file) Read(p []byte) (int, error) {\n\tif f.closed {\n\t\treturn 0, errors.New(\"file closed\")\n\t}\n\n\treturn f.content.Read(p)\n}\n\nfunc (f *file) Stat() (fs.FileInfo, error) {\n\tif f.closed {\n\t\treturn nil, errors.New(\"file closed\")\n\t}\n\n\treturn f, nil\n}\n\n// Close 关闭文件，可以调用多次。\nfunc (f *file) Close() error {\n\tf.closed = true\n\treturn nil\n}\n\n// 实现 fs.FileInfo 接口\n\nfunc (f *file) Name() string {\n\treturn f.name\n}\n\nfunc (f *file) Size() int64 {\n\treturn int64(f.content.Len())\n}\n\nfunc (f *file) Mode() fs.FileMode {\n\t// 固定为 0444\n\treturn 0444\n}\n\nfunc (f *file) ModTime() time.Time {\n\treturn f.modTime\n}\n\nfunc (f *file) IsDir() bool {\n\treturn false\n}\n\nfunc (f *file) Sys() interface{} {\n\treturn nil\n}\n\n// 文件也是某个目录下的目录项，因此需要实现 fs.DirEntry 接口\n\nfunc (f *file) Type() fs.FileMode {\n\treturn f.Mode()\n}\n\nfunc (f *file) Info() (fs.FileInfo, error) {\n\treturn f, nil\n}\n```\n\n有了目录（dir）和文件（file），看 fs.FS 的实现。\n\n```go\n// FS 是 fs.FS 的内存文件系统实现\ntype FS struct {\n\trootDir *dir\n}\n\n// NewFS 创建一个内存文件系统的实例\nfunc NewFS() *FS {\n\treturn &FS{\n\t\trootDir: &dir{\n\t\t\tchildren: make(map[string]fs.DirEntry),\n\t\t},\n\t}\n}\n\n// Open 实现 fs.FS 的 Open 方法\nfunc (fsys *FS) Open(name string) (fs.File, error) {\n\t// 1、校验 name\n\tif !fs.ValidPath(name) {\n\t\treturn nil, &fs.PathError{\n\t\t\tOp: \"open\",\n\t\t\tPath: name,\n\t\t\tErr: fs.ErrInvalid,\n\t\t}\n\t}\n\n\t// 2、根目录处理\n\tif name == \".\" || name == \"\" {\n\t\t// 重置目录的遍历\n\t\tfsys.rootDir.idx = 0\n\t\treturn fsys.rootDir, nil\n\t}\n\n\t// 3、根据 name 在目录树中进行查找\n\tcur := fsys.rootDir\n\tparts := strings.Split(name, \"/\")\n\tfor i, part := range parts {\n\t\t// 不存在返回错误\n\t\tchild := cur.children[part]\n\t\tif child == nil {\n\t\t\treturn nil, &fs.PathError{\n\t\t\t\tOp: \"open\",\n\t\t\t\tPath: name,\n\t\t\t\tErr: fs.ErrNotExist,\n\t\t\t}\n\t\t}\n\n\t\t// 是否是文件\n\t\tf, ok := child.(*file)\n\t\tif ok {\n\t\t\t// 文件名是最后一项\n\t\t\tif i == len(parts)-1 {\n\t\t\t\treturn f, nil\n\t\t\t}\n\n\t\t\treturn nil, &fs.PathError{\n\t\t\t\tOp: \"open\",\n\t\t\t\tPath: name,\n\t\t\t\tErr: fs.ErrNotExist,\n\t\t\t}\n\t\t}\n\n\t\t// 是否是目录\n\t\td, ok := child.(*dir)\n\t\tif !ok {\n\t\t\treturn nil, &fs.PathError{\n\t\t\t\tOp: \"open\",\n\t\t\t\tPath: name,\n\t\t\t\tErr: errors.New(\"not a directory\"),\n\t\t\t}\n\t\t}\n\t\t// 重置，避免遍历问题\n\t\td.idx = 0\n\n\t\tcur = d\n\t}\n\n\treturn cur, nil\n}\n\n// MkdirAll 这不是 io/fs 的要求，但一个文件系统目录树需要可以构建\n// 这个方法就是用来创建目录\nfunc (fsys *FS) MkdirAll(path string) error {\n\tif !fs.ValidPath(path) {\n\t\treturn errors.New(\"Invalid path\")\n\t}\n\n\tif path == \".\" {\n\t\treturn nil\n\t}\n\n\tcur := fsys.rootDir\n\tparts := strings.Split(path, \"/\")\n\tfor _, part := range parts {\n\t\tchild := cur.children[part]\n\t\tif child == nil {\n\t\t\tchildDir := &dir{\n\t\t\t\tname: part,\n\t\t\t\tmodTime: time.Now(),\n\t\t\t\tchildren: make(map[string]fs.DirEntry),\n\t\t\t}\n\t\t\tcur.children[part] = childDir\n\t\t\tcur = childDir\n\t\t} else {\n\t\t\tchildDir, ok := child.(*dir)\n\t\t\tif !ok {\n\t\t\t\treturn fmt.Errorf(\"%s is not directory\", part)\n\t\t\t}\n\n\t\t\tcur = childDir\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// WriteFile 也不是 io/fs 的要求，和 MkdirAll 类似，文件内容也需要有接口写入\nfunc (fsys *FS) WriteFile(name, content string) error {\n\tif !fs.ValidPath(name) {\n\t\treturn &fs.PathError{\n\t\t\tOp: \"write\",\n\t\t\tPath: name,\n\t\t\tErr: fs.ErrInvalid,\n\t\t}\n\t}\n\n\tvar err error\n\tdir := fsys.rootDir\n\n\tpath := filepath.Dir(name)\n\tif path != \".\" {\n\t\tdir, err = fsys.getDir(path)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\tfilename := filepath.Base(name)\n\n\tdir.children[filename] = &file{\n\t\tname: filename,\n\t\tcontent: bytes.NewBufferString(content),\n\t\tmodTime: time.Now(),\n\t}\n\n\treturn nil\n}\n\n// getDir 通过一个路径获取其 dir 类型实例\nfunc (fsys *FS) getDir(path string) (*dir, error) {\n\tparts := strings.Split(path, \"/\")\n\n\tcur := fsys.rootDir\n\tfor _, part := range parts {\n\t\tchild := cur.children[part]\n\t\tif child == nil {\n\t\t\treturn nil, fmt.Errorf(\"%s is not exists\", path)\n\t\t}\n\n\t\tchildDir, ok := child.(*dir)\n\t\tif !ok {\n\t\t\treturn nil, fmt.Errorf(\"%s is not directory\", path)\n\t\t}\n\n\t\tcur = childDir\n\t}\n\n\treturn cur, nil\n}\n```\n\n为了完整性，我把所有代码列出来了，关键的地方加上了注释。\n\n## 验证正确性并学习 fs.WalkDir ##\n\n用心的读者可能会发现，io/fs 包还有一个类型和函数没有介绍，那就是 fs.WalkDir 函数和 WalkDirFunc 类型。它们是遍历目录用的。这里通过验证上面内存文件系统的正确性来学习它们。\n\n首先，我们使用 MkdirAll 和 WriteFile 创建如下的目录树：\n\n```bash\n├── a\n│   ├── b\n│   │   └── z\n├── x\n│   └── y\n│   │   └── z\n│   └── name.txt\n```\n\n即执行如下代码：\n\n```go\nmemFS := memfs.NewFS()\nmemFS.MkdirAll(\"a/b/z\")\nmemFS.MkdirAll(\"x/y/z\")\nmemFS.WriteFile(\"x/name.txt\", \"This is polarisxu, welcome.\")\n```\n\n基于这个目录树，我们该怎么遍历它？\n\n### 自己实现遍历方法 ###\n\n遍历目录树也是一个面试常考的基础题目。熟悉的朋友应该知道，这需要用到递归。基于上面的内存文件系统 API，我们实现遍历目录树。\n\n通过 io/fs 包的 ReadDir 函数读取目录下所有目录项，然后遍历这些目录项，如果某个目录项是目录，递归处理它。\n\n```go\nfunc walk(fsys fs.FS, parent, base string) error {\n\tdirEntries, err := fs.ReadDir(fsys, filepath.Join(parent, base))\n\tif err != nil {\n\t\treturn err\n\t}\n\tfor _, dirEntry := range dirEntries {\n\t\tname := dirEntry.Name()\n fmt.Println(name)\n\n\t\tif dirEntry.IsDir() {\n\t\t\terr = walk(fsys, filepath.Join(parent, base), name)\n\t\t}\n\t}\n\treturn err\n}\n```\n\n然后用根目录调用它：\n\n```go\nwalk(memFS, \"\", \".\")\n```\n\n### 使用 fs.WalkDir 实现 ###\n\n其实标准库为我们实现了这样的功能，通过它提供的方法可以很容易的实现遍历。\n\n```go\nfs.WalkDir(memFS, \".\", func(path string, d fs.DirEntry, err error) error {\n\tfmt.Pritnln(path)\n\treturn nil\n})\n```\n\n是不是不要太简单？\n\n关于 fs.WalkDir 和 fs.WalkDirFunc 有一大段文字说明，介绍其中的一些细节。比如在回调函数中，如果返回 fs.SkipDir，则会停止该目录的遍历。这里细说了。\n\n## 小结\n\nio/fs 包基本上是在 os 包的基础上抽象出来的。之所以抽象，是因为 Go1.16 的 embed 功能，它需要文件系统，但又不同于 os 的文件系统。所以做了这个抽象。\n\n基于 io/fs 包的接口，标准库不少地方做了改动，以支持 fs.FS 接口。此外还有第三方实现了它的文件系统：\n\n- ：用于读取 GitHub gists 的文件；\n- ：hash 文件，以便 HTTP Cache；\n- ：内存文件系统的实现；本小节文件系统的实现参考了它。\n\n# 导航 #\n\n- 上一节：[path/filepath — 兼容操作系统的文件路径操作](06.2.md)\n- 第七章：[数据持久存储与交换](/chapter07/07.0.md)\n" }, { "path": "chapter07/07.0.md", "content": "# 第七章 数据持久存储与交换 #\n\n现代程序离不开数据存储，现阶段很热的所谓大数据处理、云盘等，更是以存储为依托。有数据存储，自然需要进行数据交换，已达到数据共享等目的。\n\n关系型数据库发展了很长一段时间，SQL/SQL-like 已经很成熟，使用也很广泛，Go 语言标准库提供了对 SQL/SQL-like 数据库的操作的标准接口，即 [database/sql](http://docs.studygolang.com/pkg/database/sql) 包。\n\n在数据交换方面，有很多成熟的协议可以使用，常用的有：JSON、XML 等，似乎 Java 社区更喜欢 XML，而目前似乎使用更多的是 JSON。在交换协议选择方面，考虑的主要这几个方面因素：性能、跨语言（通用性）、传输量等。因此，对于性能要求高的场景，会使用 protobuf、msgpack 之类的协议。由于 JSON 和 XML 使用很广泛，Go 语言提供了解析它们的标准库；同时，为了方便 Go 程序直接数据交换，Go 专门提供了 [gob](http://docs.studygolang.com/pkg/) 这种交换协议。\n\n# 导航 #\n\n- [目录](/preface.md)\n- 下一节：[database/sql — SQL/SQL-Like 数据库操作接口](07.1.md)\n" }, { "path": "chapter07/07.1.md", "content": "# 7.1 database/sql — SQL/SQL-Like 数据库操作接口 #\n\n这是 Go 提供的操作 SQL/SQL-Like 数据库的通用接口，但 Go 标准库并没有提供具体数据库的实现，需要结合第三方的驱动来使用该接口。本书使用的是 mysql 的驱动：[github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)。\n\n*注：该包有一个子包：driver，它定义了一些接口供数据库驱动实现，一般业务代码中使用 database/sql 包即可，尽量避免使用 driver 这个子包。*\n\n## 7.1.1 database/sql 是什么？ ##\n\n很明显，[database/sql](http://docs.studygolang.com/pkg/database/sql) 首先是 Go 标准库提供的一个包，用于和 SQL/SQL-Like 数据库 ( 关系或类似关系数据库）通讯。它提供了和 ODBC、Perl 的 DBI、Java 的 JDBC 和 PHP 的 PDO 类似的功能。然而，它的设计却不太一样，掌握了它有利于构建健壮、高性能的基于 database 的应用。\n\n另一方面，database/sql 提供的是抽象概念，和具体数据库无关，具体的数据库实现，有驱动来做，这样可以很方便的更换数据库。\n\n该包提供了一些类型（概括性的），每个类型可能包括一个或多个概念。\n\n- DB \nsql.DB 类型代表了一个数据库。这点和很多其他语言不同，它并不代表一个到数据库的具体连接，而是一个能操作的数据库对象，具体的连接在内部通过连接池来管理，对外不暴露。这点是很多人容易误解的：每一次数据库操作，都产生一个 sql.DB 实例，操作完 Close。\n- Results \n定义了三种结果类型：sql.Rows、sql.Row 和 sql.Result，分别用于获取多个多行结果、一行结果和修改数据库影响的行数（或其返回 last insert id）。\n- Statements \nsql.Stmt 代表一个语句，如：DDL、DML 等。\n- Transactions \nsql.Tx 代表带有特定属性的一个事务。\n\n## 7.1.2 sql.DB 的使用 ##\n\n官方文档关于 DB 的描述：\n\n> 是一个数据库句柄，代表一个具有零到多个底层连接的连接池，它可以安全的被多个 goroutine 同时使用。 \n> sql 包会自动创建和释放连接；它也会维护一个闲置连接的连接池。如果数据库具有单连接状态的概念，该状态只有在事务中被观察时才可信。一旦调用了 BD.Begin，返回的 Tx 会绑定到单个连接。当调用事务 Tx 的 Commit 或 Rollback 后，该事务使用的连接会归还到 DB 的闲置连接池中。连接池的大小可以用 SetMaxIdleConns 方法控制。\n\n由于 DB 并非一个实际的到数据库的连接，而且可以被多个 goroutine 并发使用，因此，程序中只需要拥有一个全局的实例即可。所以，经常见到的示例代码：\n```go\n\tdb, err := sql.Open(\"mysql\", \"root:@tcp(localhost:3306)/test?charset=utf8\")\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer db.Close()\n```\n实际中，`defer db.Close()` 可以不调用，官方文档关于 DB.Close 的说明也提到了：Close 用于关闭数据库，释放任何打开的资源。一般不会关闭 DB，因为 DB 句柄通常被多个 goroutine 共享，并长期活跃。当然，如果你确定 DB 只会被使用一次，之后不会使用了，应该调用 Close。\n\n所以，实际的 Go 程序，应该在一个 go 文件中的 init 函数中调用 `sql.Open` 初始化全局的 sql.DB 对象，供程序中所有需要进行数据库操作的地方使用。\n\n前面说过，sql.DB 并不是实际的数据库连接，因此，sql.Open 函数并没有进行数据库连接，只有在驱动未注册时才会返回 `err != nil`。\n\n例如：`db, err := sql.Open(\"mysql\", \"root:@tcp23(localhost233:3306)/test?charset=utf8\")`。虽然这里的 dsn 是错误的，但依然 `err == nil`，只有在实际操作数据库（查询、更新等）或调用 `Ping` 时才会报错。\n\n关于 Open 函数的参数，第一个是驱动名，为了避免混淆，一般和驱动包名一致，在驱动实现中，会有类似这样的代码：\n```go\n\tfunc init() {\n\t\tsql.Register(\"mysql\", &MySQLDriver{})\n\t}\n```\n其中 mysql 即是注册的驱动名。由于注册驱动是在 init 函数中进行的，这也就是为什么采用 `_ \"github.com/go-sql-driver/mysql\"` 这种方式引入驱动包。第二个参数是 DSN（数据源名称），这个是和具体驱动相关的，database/sql 包并没有规定，具体书写方式参见驱动文档。\n\n### 7.1.2.1 连接池的工作原理 ###\n\n获取 DB 对象后，连接池是空的，第一个连接在需要的时候才会创建。可以通过下面的代码验证这一点：\n```go\n\tdb, _ := sql.Open(\"mysql\", \"root:@tcp(localhost:3306)/test?charset=utf8\")\n\tfmt.Println(\"please exec show processlist\")\n\ttime.Sleep(10 * time.Second)\n\tfmt.Println(\"please exec show processlist again\")\n\tdb.Ping()\n\ttime.Sleep(10 * time.Second)\n```\n在 Ping 执行之前和之后，show processlist 多了一条记录，即多了一个连接，Command 列是 Sleep。\n\n连接池的工作方式：当调用一个函数，需要访问数据库时，该函数会请求从连接池中获取一个连接，如果连接池中存在一个空闲连接，它会将该空闲连接给该函数；否则，会打开一个新的连接。当该函数结束时，该连接要么返回给连接池，要么传递给某个需要该连接的对象，知道该对象完成时，连接才会返回给连接池。相关方法的处理说明（假设 sql.DB 的对象是 db）：\n\n- **db.Ping()** 会将连接立马返回给连接池。\n- **db.Exec()** 会将连接立马返回给连接池，但是它返回的 Result 对象会引用该连接，所以，之后可能会再次被使用。\n- **db.Query()** 会传递连接给 sql.Rows 对象，直到完全遍历了所有的行或 Rows 的 Close 方法被调用了，连接才会返回给连接池。\n- **db.QueryRow()** 会传递连接给 sql.Row 对象，当该对象的 Scan 方法被调用时，连接会返回给连接池。\n- **db.Begin()** 会传递连接给 sql.Tx 对象，当该对象的 Commit 或 Rollback 方法被调用时，该链接会返回给连接池。\n\n从上面的解释可以知道，大部分时候，我们不需要关心连接不释放问题，它们会自动返回给连接池，只有 Query 方法有点特殊，后面讲解如何处理。\n\n注意：如果某个连接有问题（broken connection)，database/sql 内部会进行[最多 2 次](https://github.com/golang/go/blob/release-branch.go1.13/src/database/sql/sql.go#L1390) 的重试，从连接池中获取或新开一个连接来服务，因此，你的代码中不需要重试的逻辑。\n\n### 7.1.2.2 控制连接池 ###\n\nGo1.2.1 之前，没法控制连接池，Go1.2.1 之后，提供了两个方法来控制连接池（Go1.2 提供了控制，不过有 bug）。\n\n- **db.SetMaxOpenConns(n int)** 设置连接池中最多保存打开多少个数据库连接。注意，它包括在使用的和空闲的。如果某个方法调用需要一个连接，但连接池中没有空闲的可用，且打开的连接数达到了该方法设置的最大值，该方法调用将堵塞。默认限制是 0，表示最大打开数没有限制。\n- **db.SetMaxIdleConns(n int)** 设置连接池中能够保持的最大空闲连接的数量。[默认值是 2](http://docs.studygolang.com/src/database/sql/sql.go?s=13724:13743#L501) \n\n上面的两个设置，可以用程序实际测试。比如通过下面的代码，可以验证 MaxIdleConns 是 2：\n```go\n\tdb, _ := sql.Open(\"mysql\", \"root:@tcp(localhost:3306)/test?charset=utf8\")\n\t\n\t// 去掉注释，可以看看相应的空闲连接是不是变化了\n\t// db.SetMaxIdleConns(3)\n\t\n\tfor i := 0; i < 10; i++ {\n\t\tgo func() {\n\t\t\tdb.Ping()\n\t\t}()\n\t}\n\n\ttime.Sleep(20 * time.Second)\n```\n通过 show processlist 命令，可以看到有两个是 Sleep 的连接。\n\n\n# 导航 #\n\n- [第七章 数据持久存储与交换](/chapter07/07.0.md)\n- 下一节：encoding/json — json 解析\n" }, { "path": "chapter07/07.5.md", "content": "# 7.5 encoding/csv — 逗号分隔值文件\n\n对 CSV 大家应该不陌生。因为它可以通过 Excel 打开（虽然 CSV 是纯文本格式），而且解析简单方便，因此，很多时候，我们做导出功能时，都会选择导出 CSV 格式。当然，导入我们也会期望使用 CSV 格式，这时往往会提供模板下载，让用户通过修改这个模板数据，然后导入。而这个模板往往也会采用 CSV 格式。通常，数据库数据导出也支持 CSV 格式。\n\n关于 CSV 的解释：\n\n> CSV，即逗号分隔值（Comma-Separated Values，CSV），其文件以纯文本形式存储表格数据（数字和文本）。纯文本意味着该文件是一个字符序列，不含必须像二进制数字那样被解读的数据。CSV 文件由任意数目的记录组成，记录间以某种换行符分隔；每条记录由字段组成，字段间的分隔符是其它字符或字符串，最常见的是逗号或制表符。通常，所有记录都有完全相同的字段序列。\n\nGo 语言标准库支持对 CSV 格式的读写。\n\n## 7.5.1 简述\n\ncsv 包用于读取和写入逗号分隔值（CSV）文件。CSV 文件类型有很多种，该包支持 RFC 4180 中描述的格式。\n\n一个 csv 文件包含每个记录一到多个字段的零到多个记录。每条记录由换行符分隔。最后一条记录可以选择是否由换行符结束。\n\n```bash\nfield1,field2,field3\n```\n\n空白视为字段的一部分。\n\n" }, { "path": "chapter08/08.0.md", "content": "# 第八章 数据压缩与归档 #\n\n在计算机算法中，经常会有以空间换时间的做法；而无损压缩算法以压缩或解压缩数据花费的时间来换取存储空间。除此之外，压缩还有另外一个重要用途，那就是减少网络传输的数据量，进而减少网络传输的时间。\n\nGo 标准库实现了一些最流行的压缩标准。zlib 和 gzip 提供了 GNU zip 库，bzip2 用于读写 bzip2 格式。这些格式都可以处理数据流而不考虑输入格式，并且提供了接口可以透明地读写压缩文件。除此之外，标准库还提供了 DEFLATE 压缩算法的实现，gzip 和 zlib 可以读取基于 DEFLATE 的文件格式。\n\n标准库提供了 LZW 压缩算法（串表压缩算法）的实现，该算法常用的文件格式：GIF 和 PDF。另外，TIFF 文件格式使用和该算法类似，但和目前 LZW 算法版本不兼容。\n\n标准库还提供一些包管理归档 (archive) 格式，将多个文件合并到一个文件，从而将其作为一个单元管理。`archive/tar` 读写 UNIX 磁带归档格式，这是一种老标准，但由于其灵活性，当前仍得到广泛使用。`archive/zip` 根据 zip 格式来处理归档，这种格式因 PC 程序 PKZIP 得以普及，原先在 MS-DOS 和 Windows 下使用，不过由于其 API 的简单性以及这种格式的可移植性，现在也用于其他平台。\n\n# 导航 #\n\n- [第七章](/chapter07/07.0.md)\n- 下一节：[flate - DEFLATE 压缩算法](08.1.md)\n" }, { "path": "chapter08/08.1.md", "content": "# flate - DEFLATE 压缩算法 #\n\nDEFLATE 是同时使用了哈夫曼编码（Huffman Coding）与 LZ77 算法的一个无损数据压缩算法，是一种压缩数据流的算法。任何需要流式压缩的地方都可以用。目前 zip 压缩文件默认使用的就是该算法。\n\n关于算法的原理，以及 哈夫曼编码（Huffman Coding）与 LZ77 算法，感兴趣的读者可以查询相关资料，这里推荐 [GZIP 压缩原理分析——第五章 Deflate 算法详解](http://blog.csdn.net/jison_r_wang/article/details/52071317) 序列文章。\n\n\n## 使用预设字典提升压缩率\n\n\n\n# 导航 #\n\n- [第八章](/chapter08/08.0.md)\n- 下一节：[zlib - GNU zlib 压缩](08.2.md)" }, { "path": "chapter08/08.5.md", "content": "# 8.1 archive/tar — tar 档案读写\n\n熟悉 Linux 的朋友，对于 tar 格式的文件应该不会陌生。\n\n\n\n" }, { "path": "chapter09/09.0.md", "content": "# 第九章 测试 #\n\nGo 语言从开发初期就注意了测试用例的编写。特别是静态语言，由于调试没有动态语言那么方便，所以能最快最方便地编写一个测试用例就显得非常重要了。\n\n本章内容涵盖了 Go 标准库中的 2 个包：\n\n* *testing* 方便进行 Go 包的自动化单元测试、基准测试\n* *net/http/httptest* 提供测试 `HTTP` 的工具\n\n# 导航 #\n\n- [第八章](/chapter08/08.0.md)\n- 下一节：[testing - 单元测试](09.1.md)\n" }, { "path": "chapter09/09.1.md", "content": "# testing - 单元测试 #\n\n`testing` 为 Go 语言 package 提供自动化测试的支持。通过 `go test` 命令，能够自动执行如下形式的任何函数：\n\n\tfunc TestXxx(*testing.T)\n\n注意：Xxx 可以是任何字母数字字符串，但是第一个字母不能是小写字母。\n\n在这些函数中，使用 `Error`、`Fail` 或相关方法来发出失败信号。\n\n要编写一个新的测试套件，需要创建一个名称以 _test.go 结尾的文件，该文件包含 `TestXxx` 函数，如上所述。 将该文件放在与被测试文件相同的包中。该文件将被排除在正常的程序包之外，但在运行 `go test` 命令时将被包含。 有关详细信息，请运行 `go help test` 和 `go help testflag` 了解。\n\n如果有需要，可以调用 `*T` 和 `*B` 的 `Skip` 方法，跳过该测试或基准测试：\n\n```go\nfunc TestTimeConsuming(t *testing.T) {\n if testing.Short() {\n t.Skip(\"skipping test in short mode.\")\n }\n ...\n}\n```\n\n## 第一个单元测试 ##\n\n要测试的代码：\n\n```go\nfunc Fib(n int) int {\n if n < 2 {\n return n\n }\n return Fib(n-1) + Fib(n-2)\n}\n```\n\n测试代码：\n\n```go\nfunc TestFib(t *testing.T) {\n\tvar (\n\t\tin = 7\n\t\texpected = 13\n\t)\n\tactual := Fib(in)\n\tif actual != expected {\n\t\tt.Errorf(\"Fib(%d) = %d; expected %d\", in, actual, expected)\n\t}\n}\n```\n执行 `go test .`，输出：\n\n```\n$ go test .\nok \tchapter09/testing\t0.007s\n```\n\n表示测试通过。\n\n我们将 `Sum` 函数改为：\n\n```go\nfunc Fib(n int) int {\n if n < 2 {\n return n\n }\n return Fib(n-1) + Fib(n-1)\n}\n```\n\n再执行 `go test .`，输出：\n\n```\n$ go test .\n--- FAIL: TestSum (0.00s)\n\tt_test.go:16: Fib(10) = 64; expected 13\nFAIL\nFAIL\tchapter09/testing\t0.009s\n```\n\n## Table-Driven Test ##\n\n测试讲究 case 覆盖，按上面的方式，当我们要覆盖更多 case 时，显然通过修改代码的方式很笨拙。这时我们可以采用 Table-Driven 的方式写测试，标准库中有很多测试是使用这种方式写的。\n\n```go\nfunc TestFib(t *testing.T) {\n\tvar fibTests = []struct {\n\t\tin int // input\n\t\texpected int // expected result\n\t}{\n\t\t{1, 1},\n\t\t{2, 1},\n\t\t{3, 2},\n\t\t{4, 3},\n\t\t{5, 5},\n\t\t{6, 8},\n\t\t{7, 13},\n\t}\n\n\tfor _, tt := range fibTests {\n\t\tactual := Fib(tt.in)\n\t\tif actual != tt.expected {\n\t\t\tt.Errorf(\"Fib(%d) = %d; expected %d\", tt.in, actual, tt.expected)\n\t\t}\n\t}\n}\n```\n由于我们使用的是 `t.Errorf`，即使其中某个 case 失败，也不会终止测试执行。\n\n## T 类型 ##\n\n单元测试中，传递给测试函数的参数是 `*testing.T` 类型。它用于管理测试状态并支持格式化测试日志。测试日志会在执行测试的过程中不断累积，并在测试完成时转储至标准输出。\n\n当测试函数返回时，或者当测试函数调用 `FailNow`、 `Fatal`、`Fatalf`、`SkipNow`、`Skip`、`Skipf` 中的任意一个时，则宣告该测试函数结束。跟 `Parallel` 方法一样，以上提到的这些方法只能在运行测试函数的 goroutine 中调用。\n\n至于其他报告方法，比如 `Log` 以及 `Error` 的变种， 则可以在多个 goroutine 中同时进行调用。\n\n### 报告方法 ###\n\n上面提到的系列包括方法，带 `f` 的是格式化的，格式化语法参考 `fmt` 包。\n\nT 类型内嵌了 common 类型，common 提供这一系列方法，我们经常会用到的（注意，这里说的测试中断，都是指当前测试函数）：\n\n1）当我们遇到一个断言错误的时候，标识这个测试失败，会使用到：\n\n Fail : 测试失败，测试继续，也就是之后的代码依然会执行\n FailNow : 测试失败，测试中断\n\n在 `FailNow ` 方法实现的内部，是通过调用 `runtime.Goexit()` 来中断测试的。\n\n2）当我们遇到一个断言错误，只希望跳过这个错误，但是不希望标识测试失败，会使用到：\n\n SkipNow : 跳过测试，测试中断\n\n在 `SkipNow` 方法实现的内部，是通过调用 `runtime.Goexit()` 来中断测试的。\n\n3）当我们只希望打印信息，会用到 :\n\n Log : 输出信息\n Logf : 输出格式化的信息\n\n注意：默认情况下，单元测试成功时，它们打印的信息不会输出，可以通过加上 `-v` 选项，输出这些信息。但对于基准测试，它们总是会被输出。\n\n4）当我们希望跳过这个测试，并且打印出信息，会用到：\n\n Skip : 相当于 Log + SkipNow\n Skipf : 相当于 Logf + SkipNow\n\n5）当我们希望断言失败的时候，标识测试失败，并打印出必要的信息，但是测试继续，会用到：\n\n Error : 相当于 Log + Fail\n Errorf : 相当于 Logf + Fail\n\n6）当我们希望断言失败的时候，标识测试失败，打印出必要的信息，但中断测试，会用到：\n\n Fatal : 相当于 Log + FailNow\n Fatalf : 相当于 Logf + FailNow\n\n### Parallel 测试 ###\n\n包中的 Parallel 方法表示当前测试只会与其他带有 Parallel 方法的测试并行进行测试。\n\n下面例子将演示 Parallel 的使用方法：\n\n```go\nvar (\n\tdata = make(map[string]string)\n\tlocker sync.RWMutex\n)\n\nfunc WriteToMap(k, v string) {\n\tlocker.Lock()\n\tdefer locker.Unlock()\n\tdata[k] = v\n}\n\nfunc ReadFromMap(k string) string {\n\tlocker.RLock()\n\tdefer locker.RUnlock()\n\treturn data[k]\n}\n```\n\n测试代码：\n\n```go\nvar pairs = []struct {\n\tk string\n\tv string\n}{\n\t{\"polaris\", \" 徐新华 \"},\n\t{\"studygolang\", \"Go 语言中文网 \"},\n\t{\"stdlib\", \"Go 语言标准库 \"},\n\t{\"polaris1\", \" 徐新华 1\"},\n\t{\"studygolang1\", \"Go 语言中文网 1\"},\n\t{\"stdlib1\", \"Go 语言标准库 1\"},\n\t{\"polaris2\", \" 徐新华 2\"},\n\t{\"studygolang2\", \"Go 语言中文网 2\"},\n\t{\"stdlib2\", \"Go 语言标准库 2\"},\n\t{\"polaris3\", \" 徐新华 3\"},\n\t{\"studygolang3\", \"Go 语言中文网 3\"},\n\t{\"stdlib3\", \"Go 语言标准库 3\"},\n\t{\"polaris4\", \" 徐新华 4\"},\n\t{\"studygolang4\", \"Go 语言中文网 4\"},\n\t{\"stdlib4\", \"Go 语言标准库 4\"},\n}\n\n// 注意 TestWriteToMap 需要在 TestReadFromMap 之前\nfunc TestWriteToMap(t *testing.T) {\n\tt.Parallel()\n\tfor _, tt := range pairs {\n\t\tWriteToMap(tt.k, tt.v)\n\t}\n}\n\nfunc TestReadFromMap(t *testing.T) {\n\tt.Parallel()\n\tfor _, tt := range pairs {\n\t\tactual := ReadFromMap(tt.k)\n\t\tif actual != tt.v {\n\t\t\tt.Errorf(\"the value of key(%s) is %s, expected: %s\", tt.k, actual, tt.v)\n\t\t}\n\t}\n}\n```\n试验步骤：\n\n1. 注释掉 WriteToMap 和 ReadFromMap 中 locker 保护的代码，同时注释掉测试代码中的 t.Parallel，执行测试，测试通过，即使加上 `-race`，测试依然通过；\n2. 只注释掉 WriteToMap 和 ReadFromMap 中 locker 保护的代码，执行测试，测试失败（如果未失败，加上 `-race` 一定会失败）；\n\n如果代码能够进行并行测试，在写测试时，尽量加上 Parallel，这样可以测试出一些可能的问题。\n\n关于 Parallel 的更多内容，会在 [子测试](09.3.md) 中介绍。\n\n当你写完一个函数，结构体，main 之后，你下一步需要的就是测试了。testing 包提供了很简单易用的测试包。\n\n# 写一个基本的测试用例 #\n\n测试文件的文件名需要以_test.go 为结尾，测试用例需要以 TestXxxx 的形式存在。\n\n比如我要测试 utils 包的 sql.go 中的函数：\n\n func GetOne(db *sql.DB, query string, args ...interface{}) (map[string][]byte, error) {\n\n就需要创建一个 sql_test.go\n```go\n package utils\n\n import (\n \"database/sql\"\n _ \"fmt\"\n _ \"github.com/go-sql-driver/mysql\"\n \"strconv\"\n \"testing\"\n )\n\n func Test_GetOne(t *testing.T) {\n db, err := sql.Open(\"mysql\", \"root:123.abc@tcp(192.168.33.10:3306)/test\")\n defer func() {\n db.Close()\n }()\n if err != nil {\n t.Fatal(err)\n }\n\n // 测试 empty\n car_brand, err := GetOne(db, \"select * from user where id = 999999\")\n if (car_brand != nil) || (err != nil) {\n t.Fatal(\"emtpy 测试错误 \")\n }\n }\n```\n# testing 的测试用例形式 #\n\n测试用例有四种形式：\n\n\tTestXxxx(t *testing.T) // 基本测试用例\n\tBenchmarkXxxx(b *testing.B) // 压力测试的测试用例\n\tExample_Xxx() // 测试控制台输出的例子\n\tTestMain(m *testing.M) // 测试 Main 函数\n\n给个 Example 的例子 :（Example 需要在最后用注释的方式确认控制台输出和预期是不是一致的）\n```go\n func Example_GetScore() {\n score := getScore(100, 100, 100, 2.1)\n fmt.Println(score)\n // Output:\n // 31.1\n }\n```\n# testing 的变量 #\n\ngotest 的变量有这些：\n\n* test.short : 一个快速测试的标记，在测试用例中可以使用 testing.Short() 来绕开一些测试\n* test.outputdir : 输出目录\n* test.coverprofile : 测试覆盖率参数，指定输出文件\n* test.run : 指定正则来运行某个 / 某些测试用例\n* test.memprofile : 内存分析参数，指定输出文件\n* test.memprofilerate : 内存分析参数，内存分析的抽样率\n* test.cpuprofile : cpu 分析输出参数，为空则不做 cpu 分析\n* test.blockprofile : 阻塞事件的分析参数，指定输出文件\n* test.blockprofilerate : 阻塞事件的分析参数，指定抽样频率\n* test.timeout : 超时时间\n* test.cpu : 指定 cpu 数量\n* test.parallel : 指定运行测试用例的并行数\n\n# testing 的结构体 #\n\n* B : 压力测试\n* BenchmarkResult : 压力测试结果\n* Cover : 代码覆盖率相关结构体\n* CoverBlock : 代码覆盖率相关结构体\n* InternalBenchmark : 内部使用的结构体\n* InternalExample : 内部使用的结构体\n* InternalTest : 内部使用的结构体\n* M : main 测试使用的结构体\n* PB : Parallel benchmarks 并行测试使用的结构体\n* T : 普通测试用例\n* TB : 测试用例的接口\n\n# testing 的通用方法 #\n\nT 结构内部是继承自 common 结构，common 结构提供集中方法，是我们经常会用到的：\n\n1）当我们遇到一个断言错误的时候，我们就会判断这个测试用例失败，就会使用到：\n\n Fail : case 失败，测试用例继续\n FailedNow : case 失败，测试用例中断\n\n2）当我们遇到一个断言错误，只希望跳过这个错误，但是不希望标示测试用例失败，会使用到：\n\n SkipNow : case 跳过，测试用例不继续\n\n3）当我们只希望在一个地方打印出信息，我们会用到 :\n\n Log : 输出信息\n Logf : 输出有 format 的信息\n\n4）当我们希望跳过这个用例，并且打印出信息 :\n\n Skip : Log + SkipNow\n Skipf : Logf + SkipNow\n\n5）当我们希望断言失败的时候，测试用例失败，打印出必要的信息，但是测试用例继续：\n\n Error : Log + Fail\n Errorf : Logf + Fail\n\n6）当我们希望断言失败的时候，测试用例失败，打印出必要的信息，测试用例中断：\n\n Fatal : Log + FailNow\n Fatalf : Logf + FailNow\n\n# 扩展阅读 #\n\n[GO 中如何进行单元测试](http://blog.studygolang.com/2017/10/how-to-test-with-go/)\n[GoDoc - testing](https://godoc.org/testing)\n[testing/testing.go 源代码](https://golang.org/src/testing/testing.go)\n\n# 导航 #\n\n- [第九章](/chapter09/09.0.md)\n- 下一节：[testing - 基准测试](09.2.md)\n" }, { "path": "chapter09/09.2.md", "content": "# testing - 基准测试 #\n\n在 _test.go 结尾的测试文件中，如下形式的函数：\n\n\tfunc BenchmarkXxx(*testing.B)\n\n被认为是基准测试，通过 `go test` 命令，加上 `-bench` 标志来执行。多个基准测试按照顺序运行。\n\n基准测试函数的形式如下：\n\n```go\nfunc BenchmarkHello(b *testing.B) {\n for i := 0; i < b.N; i++ {\n fmt.Sprintf(\"hello\")\n }\n}\n```\n\n基准函数会运行目标代码 b.N 次。在基准执行期间，程序会自动调整 b.N 直到基准测试函数持续足够长的时间。输出结果形如：\n\n\tBenchmarkHello 10000000 282 ns/op\n\n意味着循环执行了 10000000 次，每次循环花费 282 纳秒 (ns)。\n\n如果基准测试在循环前需要一些耗时的配置，则可以先重置定时器：\n\n```go\nfunc BenchmarkBigLen(b *testing.B) {\n big := NewBig()\n b.ResetTimer()\n for i := 0; i < b.N; i++ {\n big.Len()\n }\n}\n```\n如果基准测试需要在并行设置中测试性能，则可以使用 `RunParallel` 辅助函数 ; 这样的基准测试一般与 `go test -cpu` 标志一起使用：\n\n```go\nfunc BenchmarkTemplateParallel(b *testing.B) {\n\ttempl := template.Must(template.New(\"test\").Parse(\"Hello, {{.}}!\"))\n\tb.RunParallel(func(pb *testing.PB) {\n\t\t// 每个 goroutine 有属于自己的 bytes.Buffer.\n\t\tvar buf bytes.Buffer\n\t\tfor pb.Next() {\n\t\t\t// 循环体在所有 goroutine 中总共执行 b.N 次\n\t\t\tbuf.Reset()\n\t\t\ttempl.Execute(&buf, \"World\")\n\t\t}\n\t})\n}\n```\n\n## 基准测试示例 ##\n\n接着上一节的例子，我们对 `Fib` 进行基准测试：\n\n```go\nfunc BenchmarkFib10(b *testing.B) {\n for n := 0; n < b.N; n++ {\n Fib(10)\n }\n}\n```\n执行 `go test -bench=.`，输出：\n\n```\n$ go test -bench=.\nBenchmarkFib10-4 \t 3000000\t 424 ns/op\nPASS\nok \tchapter09/testing\t1.724s\n```\n这里测试了 `Fib(10)` 的情况，我们可能需要测试更多不同的情况，这时可以改写我们的测试代码：\n\n```go\nfunc BenchmarkFib1(b *testing.B) { benchmarkFib(1, b) }\nfunc BenchmarkFib2(b *testing.B) { benchmarkFib(2, b) }\nfunc BenchmarkFib3(b *testing.B) { benchmarkFib(3, b) }\nfunc BenchmarkFib10(b *testing.B) { benchmarkFib(10, b) }\nfunc BenchmarkFib20(b *testing.B) { benchmarkFib(20, b) }\nfunc BenchmarkFib40(b *testing.B) { benchmarkFib(40, b) }\n\nfunc benchmarkFib(i int, b *testing.B) {\n\tfor n := 0; n < b.N; n++ {\n\t\tFib(i)\n\t}\n}\n```\n再次执行 `go test -bench=.`，输出：\n\n```\n$ go test -bench=.\nBenchmarkFib1-4 \t1000000000\t 2.58 ns/op\nBenchmarkFib2-4 \t200000000\t 7.38 ns/op\nBenchmarkFib3-4 \t100000000\t 13.0 ns/op\nBenchmarkFib10-4 \t 3000000\t 429 ns/op\nBenchmarkFib20-4 \t 30000\t 54335 ns/op\nBenchmarkFib40-4 \t 2\t 805759850 ns/op\nPASS\nok \tchapter09/testing\t15.361s\n```\n默认情况下，每个基准测试最少运行 1 秒。如果基准测试函数返回时，还不到 1 秒钟，`b.N` 的值会按照序列 1,2,5,10,20,50,... 增加，同时再次运行基准测测试函数。\n\n我们注意到 `BenchmarkFib40` 一共才运行 2 次。为了更精确的结果，我们可以通过 `-benchtime` 标志指定运行时间，从而使它运行更多次。\n\n```\n$ go test -bench=Fib40 -benchtime=20s\nBenchmarkFib40-4 \t 30\t 838675800 ns/op\n```\n\n## B 类型 ##\n\nB 是传递给基准测试函数的一种类型，它用于管理基准测试的计时行为，并指示应该迭代地运行测试多少次。\n\n当基准测试函数返回时，或者当基准测试函数调用 `FailNow`、`Fatal`、`Fatalf`、`SkipNow`、`Skip`、`Skipf` 中的任意一个方法时，则宣告测试函数结束。至于其他报告方法，比如 `Log` 和 `Error` 的变种，则可以在其他 goroutine 中同时进行调用。\n\n跟单元测试一样，基准测试会在执行的过程中积累日志，并在测试完毕时将日志转储到标准错误。但跟单元测试不一样的是，为了避免基准测试的结果受到日志打印操作的影响，基准测试总是会把日志打印出来。\n\nB 类型中的报告方法使用方式和 T 类型是一样的，一般来说，基准测试中也不需要使用，毕竟主要是测性能。这里我们对 B 类型中其他的一些方法进行讲解。\n\n### 计时方法 ###\n\n有三个方法用于计时：\n\n1. StartTimer：开始对测试进行计时。该方法会在基准测试开始时自动被调用，我们也可以在调用 StopTimer 之后恢复计时；\n2. StopTimer：停止对测试进行计时。当你需要执行一些复杂的初始化操作，并且你不想对这些操作进行测量时，就可以使用这个方法来暂时地停止计时；\n3. ResetTimer：对已经逝去的基准测试时间以及内存分配计数器进行清零。对于正在运行中的计时器，这个方法不会产生任何效果。本节开头有使用示例。\n\n### 并行执行 ###\n\n通过 `RunParallel` 方法能够并行地执行给定的基准测试。`RunParallel `会创建出多个 goroutine，并将 b.N 分配给这些 goroutine 执行，其中 goroutine 数量的默认值为 GOMAXPROCS。用户如果想要增加非 CPU 受限（non-CPU-bound）基准测试的并行性，那么可以在 `RunParallel` 之前调用 `SetParallelism`（如 `SetParallelism(2)`，则 goroutine 数量为 2*GOMAXPROCS）。`RunParallel` 通常会与 `-cpu` 标志一同使用。\n\n`body` 函数将在每个 goroutine 中执行，这个函数需要设置所有 goroutine 本地的状态，并迭代直到 `pb.Next` 返回 false 值为止。因为 `StartTimer`、`StopTime` 和 `ResetTimer` 这三个方法都带有全局作用，所以 `body` 函数不应该调用这些方法； 除此之外，`body` 函数也不应该调用 `Run` 方法。\n\n具体的使用示例，在本节开头已经提供！\n\n### 内存统计 ###\n\n`ReportAllocs` 方法用于打开当前基准测试的内存统计功能， 与 `go test` 使用 `-benchmem` 标志类似，但 `ReportAllocs` 只影响那些调用了该函数的基准测试。\n\n测试示例：\n\n```go\nfunc BenchmarkTmplExucte(b *testing.B) {\n\tb.ReportAllocs()\n\ttempl := template.Must(template.New(\"test\").Parse(\"Hello, {{.}}!\"))\n\tb.RunParallel(func(pb *testing.PB) {\n\t\t// Each goroutine has its own bytes.Buffer.\n\t\tvar buf bytes.Buffer\n\t\tfor pb.Next() {\n\t\t\t// The loop body is executed b.N times total across all goroutines.\n\t\t\tbuf.Reset()\n\t\t\ttempl.Execute(&buf, \"World\")\n\t\t}\n\t})\n}\n```\n\n测试结果类似这样：\n\n\tBenchmarkTmplExucte-4 \t 2000000\t 898 ns/op\t 368 B/op\t 9 allocs/op\n\n### 基准测试结果 ##\n\n对上述结果中的每一项，你是否都清楚是什么意思呢？\n\n- `2000000` ：基准测试的迭代总次数 b.N\n- `898 ns/op`：平均每次迭代所消耗的纳秒数\n- `368 B/op`：平均每次迭代内存所分配的字节数\n- `9 allocs/op`：平均每次迭代的内存分配次数\n\n`testing` 包中的 `BenchmarkResult` 类型能为你提供帮助，它保存了基准测试的结果，定义如下：\n\n```go\ntype BenchmarkResult struct {\n N int // The number of iterations. 基准测试的迭代总次数，即 b.N\n T time.Duration // The total time taken. 基准测试的总耗时\n Bytes int64 // Bytes processed in one iteration. 一次迭代处理的字节数，通过 b.SetBytes 设置\n MemAllocs uint64 // The total number of memory allocations. 内存分配的总次数\n MemBytes uint64 // The total number of bytes allocated. 内存分配的总字节数\n}\n```\n\n该类型还提供了每次迭代操作所消耗资源的计算方法，示例如下：\n\n```go\npackage main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"testing\"\n\t\"text/template\"\n)\n\nfunc main() {\n\tbenchmarkResult := testing.Benchmark(func(b *testing.B) {\n\t\ttempl := template.Must(template.New(\"test\").Parse(\"Hello, {{.}}!\"))\n\t\t// RunParallel will create GOMAXPROCS goroutines\n\t\t// and distribute work among them.\n\t\tb.RunParallel(func(pb *testing.PB) {\n\t\t\t// Each goroutine has its own bytes.Buffer.\n\t\t\tvar buf bytes.Buffer\n\t\t\tfor pb.Next() {\n\t\t\t\t// The loop body is executed b.N times total across all goroutines.\n\t\t\t\tbuf.Reset()\n\t\t\t\ttempl.Execute(&buf, \"World\")\n\t\t\t}\n\t\t})\n\t})\n\n\t// fmt.Printf(\"%8d\\t%10d ns/op\\t%10d B/op\\t%10d allocs/op\\n\", benchmarkResult.N, benchmarkResult.NsPerOp(), benchmarkResult.AllocedBytesPerOp(), benchmarkResult.AllocsPerOp())\n\tfmt.Printf(\"%s\\t%s\\n\", benchmarkResult.String(), benchmarkResult.MemString())\n}\n```\n\n# 导航 #\n\n- 上一节：[testing - 单元测试](09.1.md)\n- 下一节：[testing - 子测试与子基准测试](09.3.md)\n" }, { "path": "chapter09/09.3.md", "content": "# testing - 子测试与子基准测试 #\n\n从 Go 1.7 开始，引入了一个新特性：子测试（subtests）与子基准测试（sub-benchmarks），它意味着您现在可以拥有嵌套测试，这对于过滤执行特定测试用例非常有用。\n\nT 和 B 的 `Run` 方法允许定义子单元测试和子基准测试，而不必为它们单独定义函数。这便于创建基于 Table-Driven 的基准测试和层级测试。它还提供了一种共享通用 `setup` 和 `tear-down` 代码的方法：\n\n```go\nfunc TestFoo(t *testing.T) {\n // \n t.Run(\"A=1\", func(t *testing.T) { ... })\n t.Run(\"A=2\", func(t *testing.T) { ... })\n t.Run(\"B=1\", func(t *testing.T) { ... })\n // \n}\n```\n每个子测试和子基准测试都有一个唯一的名称：由顶层测试的名称与传递给 `Run` 的名称组成，以斜杠分隔，并具有可选的尾随序列号，用于消除歧义。\n\n命令行标志 `-run` 和 `-bench` 的参数是非固定的正则表达式，用于匹配测试名称。对于由斜杠分隔的测试名称，例如子测试的名称，它名称本身即可作为参数，依次匹配由斜杠分隔的每部分名称。因为参数是非固定的，一个空的表达式匹配任何字符串，所以下述例子中的 “匹配” 意味着 “顶层/子测试名称包含有”：\n\n```\ngo test -run '' # 执行所有测试。\ngo test -run Foo # 执行匹配 \"Foo\" 的顶层测试，例如 \"TestFooBar\"。\ngo test -run Foo/A= # 对于匹配 \"Foo\" 的顶层测试，执行其匹配 \"A=\" 的子测试。\ngo test -run /A=1 # 执行所有匹配 \"A=1\" 的子测试。\n```\n子测试也可用于程序并行控制。只有子测试全部执行完毕后，父测试才会完成。在下述例子中，所有子测试之间并行运行，此处的 “并行” 只限于这些子测试之间，并不影响定义在其他顶层测试中的子测试：\n\n```go\nfunc TestGroupedParallel(t *testing.T) {\n for _, tc := range tests {\n tc := tc // capture range variable\n t.Run(tc.Name, func(t *testing.T) {\n t.Parallel()\n ...\n })\n }\n}\n```\n在所有子测试并行运行完毕之前，`Run` 方法不会返回。下述例子提供了一种方法，用于在子测试并行运行完毕后清理资源：\n\n```go\nfunc TestTeardownParallel(t *testing.T) {\n // This Run will not return until the parallel tests finish.\n t.Run(\"group\", func(t *testing.T) {\n t.Run(\"Test1\", parallelTest1)\n t.Run(\"Test2\", parallelTest2)\n t.Run(\"Test3\", parallelTest3)\n })\n // \n}\n```\n\n# 导航 #\n\n- 上一节：[testing - 基准测试](09.2.md)\n- 下一节：[testing - 运行并验证示例](09.4.md)\n" }, { "path": "chapter09/09.4.md", "content": "# testing - 运行并验证示例 #\n\n`testing` 包除了测试，还提供了运行并验证示例的功能。示例，一方面是文档的效果，是关于某个功能的使用例子；另一方面，可以被当做测试运行。\n\n一个示例的例子如下：\n\n```go\nfunc ExampleHello() {\n\tfmt.Println(\"Hello\")\n\t// Output: Hello\n}\n```\n\n如果 `Output: Hello` 改为：`Output: hello`，运行测试会失败，提示：\n\n```bash\ngot:\nHello\nwant:\nhello\n```\n\n一个示例函数以 Example 开头，如果示例函数包含以 \"Output:\" 开头的行注释，在运行测试时，go 会将示例函数的输出和 \"Output:\" 注释中的值做比较，就如上面的例子。\n\n有时候，输出顺序可能不确定，比如循环输出 map 的值，那么可以使用 \"Unordered output:\" 开头的注释。\n\n如果示例函数没有上述输出注释，该示例函数只会被编译而不会被运行。\n\n## 命名约定\n\nGo 语言通过大量的命名约定来简化工具的复杂度，规范代码的风格。对示例函数的命名有如下约定：\n\n- 包级别的示例函数，直接命名为 `func Example() { ... }`\n- 函数 F 的示例，命名为 `func ExampleF() { ... }`\n- 类型 T 的示例，命名为 `func ExampleT() { ... }`\n- 类型 T 上的 方法 M 的示例，命名为 `func ExampleT_M() { ... }`\n\n有时，我们想要给 包 / 类型 / 函数 / 方法 提供多个示例，可以通过在示例函数名称后附加一个不同的后缀来实现，但这种后缀必须以小写字母开头，如：\n\n```go\nfunc Example_suffix() { ... }\nfunc ExampleF_suffix() { ... }\nfunc ExampleT_suffix() { ... }\nfunc ExampleT_M_suffix() { ... }\n```\n通常，示例代码会放在单独的示例文件中，命名为 `example_test.go`。可以查看 `io` 包中的 `example_test.go` 了解示例的编写。\n\n## 实现原理\n\n本节开头提到了示例的两个作用，它们分别是由 `godoc` 和 `go test` 这两个命令实现的。\n\n在执行 `go test` 时，会运行示例。具体的实现原理，可以通过阅读 `go test` 命令源码和 `testing` 包中 `example.go` 文件了解。\n\n# 导航 #\n\n- 上一节：[testing - 子测试与子基准测试](09.3.md)\n- 下一节：[testing - 其他功能](09.5.md)\n" }, { "path": "chapter09/09.5.md", "content": "# testing - 其他功能 #\n\n## TestMain\n\n在写测试时，有时需要在测试之前或之后进行额外的设置（setup）或拆卸（teardown）；有时，测试还需要控制在主线程上运行的代码。为了支持这些需求，`testing` 包提供了 `TestMain` 函数 :\n\n\tfunc TestMain(m *testing.M)\n\n如果测试文件中包含该函数，那么生成的测试将调用 `TestMain(m)`，而不是直接运行测试。`TestMain` 运行在主 goroutine 中 , 可以在调用 `m.Run` 前后做任何设置和拆卸。注意，在 `TestMain` 函数的最后，应该使用 `m.Run` 的返回值作为参数去调用 `os.Exit`。\n\n另外，在调用 `TestMain` 时 , `flag.Parse` 并没有被调用。所以，如果 `TestMain` 依赖于 command-line 标志（包括 `testing` 包的标志），则应该显式地调用 `flag.Parse`。注意，这里的依赖是指，若 `TestMain` 函数内需要用到 command-line 标志，则必须显式地调用 `flag.Parse`，否则不需要，因为 `m.Run` 中调用 `flag.Parse`。\n\n一个包含 `TestMain` 的例子如下：\n\n```go\npackage mytestmain\n\nimport ( \n\t\"flag\"\n\t\"fmt\"\n\t\"os\"\n\t\"testing\"\n)\n\nvar db struct { \n\tDns string\n}\n\nfunc TestMain(m *testing.M) {\n\tdb.Dns = os.Getenv(\"DATABASE_DNS\")\n\tif db.Dns == \"\" {\n\t\tdb.Dns = \"root:123456@tcp(localhost:3306)/?charset=utf8&parseTime=True&loc=Local\"\n\t}\n\n\tflag.Parse()\n\texitCode := m.Run()\n\n\tdb.Dns = \"\"\n\n\t// 退出\n\tos.Exit(exitCode)\n}\n\nfunc TestDatabase(t *testing.T) {\n\tfmt.Println(db.Dns)\n}\n```\n\n对 `m.Run` 感兴趣的可以阅读源码，了解其原理。\n\n## Test Coverage\n\n测试覆盖率，这里讨论的是基于代码的测试覆盖率。\n\nGo 从 1.2 开始，引入了对测试覆盖率的支持，使用的是与 cover 相关的工具（`go test -cover`、`go tool cover`）。虽然 `testing` 包提供了 cover 相关函数，不过它们是给 cover 的工具使用的。\n\n关于测试覆盖率的更多信息，可以参考官方的博文：[The cover story](https://blog.golang.org/cover)\n\n# 导航 #\n\n- 上一节：[testing - 运行并验证示例](09.4.md)\n- 下一节：[httptest - HTTP 测试辅助工具](09.6.md)\n" }, { "path": "chapter09/09.6.md", "content": "# httptest - HTTP 测试辅助工具 #\n\n由于 Go 标准库的强大支持，Go 可以很容易的进行 Web 开发。为此，Go 标准库专门提供了 `net/http/httptest` 包专门用于进行 http Web 开发测试。\n\n本节我们通过一个社区帖子的增删改查的例子来学习该包。\n\n## 简单的 Web 应用\n\n我们首先构建一个简单的 Web 应用。\n\n为了简单起见，数据保存在内存，并且没有考虑并发问题。\n\n```go\n// 保存 Topic，没有考虑并发问题\nvar TopicCache = make([]*Topic, 0, 16)\n\ntype Topic struct {\n\tId int `json:\"id\"`\n\tTitle string `json:\"title\"`\n\tContent string `json:\"content\"`\n\tCreatedAt time.Time `json:\"created_at\"`\n}\n```\n对于 `Topic` 的增删改查代码很简单，可以查看[完整代码](/code/src/chapter09/httptest/data.go)。\n\n接下来，是通过 `net/http` 包来实现一个 Web 应用。\n\n```go\nfunc main() {\n\thttp.HandleFunc(\"/topic/\", handleRequest)\n\thttp.ListenAndServe(\":2017\", nil)\n}\n...\n```\n`/topic/` 开头的请求都交由 `handleRequest` 处理，它根据不同的 `Method` 执行相应的增删改查，详细代码可以查看 [server.go](/code/src/chapter09/httptest/server.go)。\n\n准备好 Web 应用后，我们启动它。\n\n> go run server.go data.go\n\n通过 `curl` 进行简单的测试：\n\n> 增：curl -i -X POST http://localhost:2017/topic/ -H 'content-type: application/json' -d '{\"title\":\"The Go Standard Library\",\"content\":\"It contains many packages.\"}'\n\n> 查：curl -i -X GET http://localhost:2017/topic/1\n\n> 改：curl -i -X PUT http://localhost:2017/topic/1 -H 'content-type: application/json' -d '{\"title\":\"The Go Standard Library By Example\",\"content\":\"It contains many packages, enjoying it.\"}'\n\n> 删：curl -i -X DELETE http://localhost:2017/topic/1\n\n## 通过 httptest 进行测试\n\n上面，我们通过 `curl` 对我们的 Web 应用的接口进行了测试。现在，我们通过 `net/http/httptest` 包进行测试。\n\n我们先测试创建帖子，也就是测试 `handlePost` 函数。\n\n```go\nfunc TestHandlePost(t *testing.T) {\n\tmux := http.NewServeMux()\n\tmux.HandleFunc(\"/topic/\", handleRequest)\n\n\treader := strings.NewReader(`{\"title\":\"The Go Standard Library\",\"content\":\"It contains many packages.\"}`)\n\tr, _ := http.NewRequest(http.MethodPost, \"/topic/\", reader)\n\n\tw := httptest.NewRecorder()\n\n\tmux.ServeHTTP(w, r)\n\t\n\tresp := w.Result()\n\tif resp.StatusCode != http.StatusOK {\n\t\tt.Errorf(\"Response code is %v\", resp.StatusCode)\n\t}\n}\n```\n首先跟待测试代码一样，配置上路由，对 `/topic/` 的请求都交由 `handleRequest ` 处理。\n\n```go\nmux := http.NewServeMux()\nmux.HandleFunc(\"/topic/\", handleRequest)\n```\n\n因为 `handlePost` 的函数签名是 `func handlePost(w http.ResponseWriter, r *http.Request) error`，为了测试它，我们必须创建 `http.ResponseWriter` 和 `http.Request` 的实例。\n\n接下来的代码就是创建一个 `http.Request` 实例 和一个 `http.ResponseWriter` 的实例。这里的关键是，通过 `httptest.NewRecorder()` 可以获得 `httptest.ResponseRecorder` 结构，而此结构实现了`http.ResponseWriter` 接口。\n\n```go\nreader := strings.NewReader(`{\"title\":\"The Go Standard Library\",\"content\":\"It contains many packages.\"}`)\nr, _ := http.NewRequest(http.MethodPost, \"/topic/\", reader)\n\nw := httptest.NewRecorder()\n```\n\n准备好之后，可以测试目标函数了。这里，我们没有直接调用 `handlePost(w, r)`，而是调用 `mux.ServeHTTP(w, r)`，实际上这里直接调用 `handlePost(w, r)` 也是可以的，但调用 `mux.ServeHTTP(w, r)` 会更完整地测试整个流程。`mux.ServeHTTP(w, r)` 最终也会调用到 `handlePost(w, r)`。\n\n最后，通过 `go test -v` 运行测试。\n\n查、改和删帖子的接口测试代码类似，比如，`handleGet` 的测试代码如下：\n\n```go\nfunc TestHandleGet(t *testing.T) {\n\tmux := http.NewServeMux()\n\tmux.HandleFunc(\"/topic/\", handleRequest)\n\n\tr, _ := http.NewRequest(http.MethodGet, \"/topic/1\", nil)\n\n\tw := httptest.NewRecorder()\n\n\tmux.ServeHTTP(w, r)\n\t\n\tresp := w.Result()\n\tif resp.StatusCode != http.StatusOK {\n\t\tt.Errorf(\"Response code is %v\", resp.StatusCode)\n\t}\n\n\ttopic := new(Topic)\n\tjson.Unmarshal(w.Body.Bytes(), topic)\n\tif topic.Id != 1 {\n\t\tt.Errorf(\"Cannot get topic\")\n\t}\n}\n```\n\n*注意：因为数据没有落地存储，为了保证后面的测试正常，请将 `TestHandlePost` 放在最前面。*\n\n## 测试代码改进\n\n细心的朋友应该会发现，上面的测试代码有重复，比如：\n\n```go\nmux := http.NewServeMux()\nmux.HandleFunc(\"/topic/\", handleRequest)\n```\n\n以及：\n\n```go\nw := httptest.NewRecorder()\n```\n\n这正好是前面学习的 `setup` 可以做的事情，因此可以使用 `TestMain` 来做重构。\n\n```go\nvar w *httptest.ResponseRecorder\n\nfunc TestMain(m *testing.M) {\n\thttp.DefaultServeMux.HandleFunc(\"/topic/\", handleRequest)\n\n\tw = httptest.NewRecorder()\n\n\tos.Exit(m.Run())\n}\n```\n\n# 导航 #\n\n- 上一节：[testing - 其他功能](09.5.md)\n- 下一节：[总结](09.7.md)\n" }, { "path": "chapter09/09.7.md", "content": "# 总结 #\n\n除了标准库提供的测试包，还有很多优秀的第三方测试包，比如 [testify](https://github.com/stretchr/testify) 可有助于 testing 进行单元测试，进行 mock 等，有机会会写文章介绍它的使用；再比如，[ginkgo](https://github.com/onsi/ginkgo) 有助于集成测试等等。\n\n参考阅读：[Testing Go at Stream](https://getstream.io/blog/how-we-test-go-at-stream/)\n\n# 导航 #\n\n- 上一节：[httptest - HTTP 测试辅助工具](09.6.md)\n- [第十章 进程、线程与 goroutine](/chapter10/10.0.md)" }, { "path": "chapter10/10.0.md", "content": "# 第十章 进程、线程和 goroutine #\n\n本章将研究 Go 语言进程、线程和 goroutine，会涉及到操作系统关于进程、线程的知识，同时研究 Go 语言提供的相关标准库 API；goroutine 作为 Go 的一个核心特性，本章会重点介绍。\n\n虽然标准库中能操作进程、线程和 goroutine 的 API 不多，但它们是深入学习、理解 Go 语言必须掌握的知识。本章从操作系统和 Go 源码层面深入探讨它们。\n\n# 导航 #\n\n- [第九章](/chapter09/09.0.md)\n- 下一节：[创建进程](10.1.md)\n" }, { "path": "chapter10/10.1.md", "content": "# 10.1 创建进程 #\n\n`os` 包及其子包 `os/exec` 提供了创建进程的方法。\n\n一般的，应该优先使用 `os/exec` 包。因为 `os/exec` 包依赖 `os` 包中关键创建进程的 API，为了便于理解，我们先探讨 `os` 包中和进程相关的部分。\n\n## 进程的创建\n\n在 Unix 中，创建一个进程，通过系统调用 `fork` 实现（及其一些变种，如 vfork、clone）。在 Go 语言中，Linux 下创建进程使用的系统调用是 `clone`。\n\n很多时候，系统调用 `fork`、`execve`、`wait` 和 `exit` 会在一起出现。此处先简要介绍这 4 个系统调用及其典型用法。\n\n- fork：允许一进程（父进程）创建一新进程（子进程）。具体做法是，新的子进程几近于对父进程的翻版：子进程获得父进程的栈、数据段、堆和执行文本段的拷贝。可将此视为把父进程一分为二。\n- exit(status)：终止一进程，将进程占用的所有资源（内存、文件描述符等）归还内核，交其进行再次分配。参数 `status` 为一整型变量，表示进程的退出状态。父进程可使用系统调用 `wait()` 来获取该状态。\n- wait(&status) 目的有二：其一，如果子进程尚未调用 `exit()` 终止，那么 `wait` 会挂起父进程直至子进程终止；其二，子进程的终止状态通过 `wait` 的 `status` 参数返回。\n- execve(pathname, argv, envp) 加载一个新程序（路径名为 pathname，参数列表为 argv，环境变量列表为 envp）到当前进程的内存。这将丢弃现存的程序文本段，并为新程序重新创建栈、数据段以及堆。通常将这一动作称为执行一个新程序。\n\n在 Go 语言中，没有直接提供 `fork` 系统调用的封装，而是将 `fork` 和 `execve` 合二为一，提供了 `syscall.ForkExec`。如果想只调用 `fork`，得自己通过 `syscall.Syscall(syscall.SYS_FORK, 0, 0, 0)` 实现。\n\n### Process 及其相关方法\n\n`os.Process` 存储了通过 `StartProcess` 创建的进程的相关信息。\n\n```go\ntype Process struct {\n\tPid int\n\thandle uintptr // handle is accessed atomically on Windows\n\tisdone uint32 // process has been successfully waited on, non zero if true\n}\n```\n一般通过 `StartProcess` 创建 `Process` 的实例，函数声明如下：\n\n`func StartProcess(name string, argv []string, attr *ProcAttr) (*Process, error)`\n\n它使用提供的程序名、命令行参数、属性开始一个新进程。`StartProcess` 是一个低级别的接口。`os/exec` 包提供了高级别的接口，一般应该尽量使用 `os/exec` 包。如果出错，错误的类型会是 `*PathError`。\n\n其中的参数 `attr`，类型是 `ProcAttr` 的指针，用于为 `StartProcess` 创建新进程提供一些属性。定义如下：\n\n```go\ntype ProcAttr struct {\n // 如果 Dir 非空，子进程会在创建 Process 实例前先进入该目录。（即设为子进程的当前工作目录）\n Dir string\n // 如果 Env 非空，它会作为新进程的环境变量。必须采用 Environ 返回值的格式。\n // 如果 Env 为 nil，将使用 Environ 函数的返回值。\n Env []string\n // Files 指定被新进程继承的打开文件对象。\n // 前三个绑定为标准输入、标准输出、标准错误输出。\n // 依赖底层操作系统的实现可能会支持额外的文件对象。\n // nil 相当于在进程开始时关闭的文件对象。\n Files []*File\n // 操作系统特定的创建属性。\n // 注意设置本字段意味着你的程序可能会执行异常甚至在某些操作系统中无法通过编译。这时候可以通过为特定系统设置。\n // 看 syscall.SysProcAttr 的定义，可以知道用于控制进程的相关属性。\n Sys *syscall.SysProcAttr\n}\n```\n\n`FindProcess` 可以通过 `pid` 查找一个运行中的进程。该函数返回的 `Process` 对象可以用于获取关于底层操作系统进程的信息。在 Unix 系统中，此函数总是成功，即使 `pid` 对应的进程不存在。\n\n`func FindProcess(pid int) (*Process, error)`\n\n`Process` 提供了四个方法：`Kill`、`Signal`、`Wait` 和 `Release`。其中 `Kill` 和 `Signal` 跟信号相关，而 `Kill` 实际上就是调用 `Signal`，发送了 `SIGKILL` 信号，强制进程退出，关于信号，后续章节会专门讲解。\n\n`Release` 方法用于释放 `Process` 对象相关的资源，以便将来可以被再使用。该方法只有在确定没有调用 `Wait` 时才需要调用。Unix 中，该方法的内部实现只是将 `Process` 的 `pid` 置为 -1。\n\n我们重点看看 `Wait` 方法。\n\n`func (p *Process) Wait() (*ProcessState, error)`\n\n在多进程应用程序的设计中，父进程需要知道某个子进程何时改变了状态 —— 子进程终止或因收到信号而停止。`Wait` 方法就是一种用于监控子进程的技术。\n\n`Wait` 方法阻塞直到进程退出，然后返回一个 `ProcessState` 描述进程的状态和可能的错误。`Wait` 方法会释放绑定到 `Process` 的所有资源。在大多数操作系统中，`Process` 必须是当前进程的子进程，否则会返回错误。\n\n看看 `ProcessState` 的内部结构：\n\n```go\ntype ProcessState struct {\n\tpid int // The process's id.\n status syscall.WaitStatus // System-dependent status info.\n rusage *syscall.Rusage\n}\n```\n\n`ProcessState` 保存了 `Wait` 函数报告的某个进程的信息。`status` 记录了状态原因，通过 `syscal.WaitStatus` 类型定义的方法可以判断：\n\n- Exited()：是否正常退出，如调用 `os.Exit`；\n- Signaled()：是否收到未处理信号而终止；\n- CoreDump()：是否收到未处理信号而终止，同时生成 coredump 文件，如 SIGABRT；\n- Stopped()：是否因信号而停止（SIGSTOP）；\n- Continued()：是否因收到信号 SIGCONT 而恢复；\n\n`syscal.WaitStatus` 还提供了其他一些方法，比如获取退出状态、信号、停止信号和中断（Trap）原因。\n\n因为 Linux 下 `Wait` 的内部实现使用的是 `wait4` 系统调用，因此，`ProcessState` 中包含了 `rusage`，用于统计进程的各类资源信息。一般情况下，`syscall.Rusage` 中定义的信息都用不到，如果实际中需要使用，可以查阅 Linux 系统调用 `getrusage` 获得相关说明 (`getrusage(2)`)。\n\n`ProcessState` 结构内部字段是私有的，我们可以通过它提供的方法来获得一些基本信息，比如：进程是否退出、Pid、进程是否是正常退出、进程 CPU 时间、用户时间等等。\n\n实现类似 Linux 中 `time` 命令的功能：\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"os/exec\"\n\t\"path/filepath\"\n\t\"time\"\n)\n\nfunc main() {\n\tif len(os.Args) < 2 {\n\t\tfmt.Printf(\"Usage: %s [command]\\n\", os.Args[0])\n\t\tos.Exit(1)\n\t}\n\n\tcmdName := os.Args[1]\n\tif filepath.Base(os.Args[1]) == os.Args[1] {\n\t\tif lp, err := exec.LookPath(os.Args[1]); err != nil {\n\t\t\tfmt.Println(\"look path error:\", err)\n\t\t\tos.Exit(1)\n\t\t} else {\n\t\t\tcmdName = lp\n\t\t}\n\t}\n\n\tprocAttr := &os.ProcAttr{\n\t\tFiles: []*os.File{os.Stdin, os.Stdout, os.Stderr},\n\t}\n\n\tcwd, err := os.Getwd()\n\tif err != nil {\n\t\tfmt.Println(\"look path error:\", err)\n\t\tos.Exit(1)\n\t}\n\n\tstart := time.Now()\n\tprocess, err := os.StartProcess(cmdName, []string{cwd}, procAttr)\n\tif err != nil {\n\t\tfmt.Println(\"start process error:\", err)\n\t\tos.Exit(2)\n\t}\n\n\tprocessState, err := process.Wait()\n\tif err != nil {\n\t\tfmt.Println(\"wait error:\", err)\n\t\tos.Exit(3)\n\t}\n\n\tfmt.Println()\n\tfmt.Println(\"real\", time.Now().Sub(start))\n\tfmt.Println(\"user\", processState.UserTime())\n\tfmt.Println(\"system\", processState.SystemTime())\n}\n\n// go build main.go && ./main ls\n// Output:\n//\n// real 4.994739ms\n// user 1.177ms\n// system 2.279ms\n```\n\n## 运行外部命令\n\n通过 `os` 包可以做到运行外部命令，如前面的例子。不过，Go 标准库为我们封装了更好用的包： `os/exec`，运行外部命令，应该优先使用它，它包装了 `os.StartProcess` 函数以便更容易的重定向标准输入和输出，使用管道连接 I/O，以及作其它的一些调整。\n\n### 查找可执行程序\n\n`exec.LookPath` 函数在 `PATH` 指定目录中搜索可执行程序，如 `file` 中有 `/`，则只在当前目录搜索。该函数返回完整路径或相对于当前路径的一个相对路径。\n\n`func LookPath(file string) (string, error)`\n\n如果在 `PATH` 中没有找到可执行文件，则返回 `exec.ErrNotFound`。\n\n### Cmd 及其相关方法\n\n`Cmd` 结构代表一个正在准备或者在执行中的外部命令，调用了 `Run`、`Output` 或 `CombinedOutput` 后，`Cmd` 实例不能被重用。\n\n```go\ntype Cmd struct {\n // Path 是将要执行的命令路径。\n // 该字段不能为空（也是唯一一个不能为空的字段），如为相对路径会相对于 Dir 字段。\n // 通过 Command 初始化时，会在需要时调用 LookPath 获得完整的路径。\n Path string\n \n // Args 存放着命令的参数，第一个值是要执行的命令（Args[0])；如果为空切片或者 nil，使用 {Path} 运行。\n // 一般情况下，Path 和 Args 都应被 Command 函数设定。\n Args []string\n \n // Env 指定进程的环境变量，如为 nil，则使用当前进程的环境变量，即 os.Environ()，一般就是当前系统的环境变量。\n Env []string\n \n // Dir 指定命令的工作目录。如为空字符串，会在调用者的进程当前工作目录下执行。\n Dir string\n \n // Stdin 指定进程的标准输入，如为 nil，进程会从空设备读取（os.DevNull）\n // 如果 Stdin 是 *os.File 的实例，进程的标准输入会直接指向这个文件\n // 否则，会在一个单独的 goroutine 中从 Stdin 中读数据，然后将数据通过管道传递到该命令中（也就是从 Stdin 读到数据后，写入管道，该命令可以从管道读到这个数据）。在 goroutine 停止数据拷贝之前（停止的原因如遇到 EOF 或其他错误，或管道的 write 端错误），Wait 方法会一直堵塞。\n Stdin io.Reader\n \n // Stdout 和 Stderr 指定进程的标准输出和标准错误输出。\n // 如果任一个为 nil，Run 方法会将对应的文件描述符关联到空设备（os.DevNull）\n // 如果两个字段相同，同一时间最多有一个线程可以写入。\n Stdout io.Writer\n Stderr io.Writer\n \n // ExtraFiles 指定额外被新进程继承的已打开文件，不包括标准输入、标准输出、标准错误输出。\n // 如果本字段非 nil，其中的元素 i 会变成文件描述符 3+i。\n //\n // BUG: 在 OS X 10.6 系统中，子进程可能会继承不期望的文件描述符。\n // http://golang.org/issue/2603\n ExtraFiles []*os.File\n \n // SysProcAttr 提供可选的、各操作系统特定的 sys 属性。\n // Run 方法会将它作为 os.ProcAttr 的 Sys 字段传递给 os.StartProcess 函数。\n SysProcAttr *syscall.SysProcAttr\n \n // Process 是底层的，只执行一次的进程。\n Process *os.Process\n \n // ProcessState 包含一个已经存在的进程的信息，只有在调用 Wait 或 Run 后才可用。\n ProcessState *os.ProcessState\n}\n```\n**Command**\n\n一般的，应该通过 `exec.Command` 函数产生 `Cmd` 实例：\n\n`func Command(name string, arg ...string) *Cmd`\n\n该函数返回一个 `*Cmd`，用于使用给出的参数执行 `name` 指定的程序。返回的 `*Cmd` 只设定了 `Path` 和 `Args` 两个字段。\n\n如果 `name` 不含路径分隔符，将使用 `LookPath` 获取完整路径；否则直接使用 `name`。参数 `arg` 不应包含命令名。\n\n得到 `*Cmd` 实例后，接下来一般有两种写法：\n\n1. 调用 `Start()`，接着调用 `Wait()`，然后会阻塞直到命令执行完成；\n2. 调用 `Run()`，它内部会先调用 `Start()`，接着调用 `Wait()`；\n\n**Start**\n\n`func (c *Cmd) Start() error`\n\n开始执行 `c` 包含的命令，但并不会等待该命令完成即返回。`Wait` 方法会返回命令的退出状态码并在命令执行完后释放相关的资源。内部调用 `os.StartProcess`，执行 `forkExec`。\n\n**Wait**\n\n`func (c *Cmd) Wait() error`\n\n`Wait` 会阻塞直到该命令执行完成，该命令必须是先通过 `Start` 执行。\n\n如果命令成功执行，stdin、stdout、stderr 数据传递没有问题，并且返回状态码为 0，方法的返回值为 nil；如果命令没有执行或者执行失败，会返回 `*ExitError` 类型的错误；否则返回的 error 可能是表示 I/O 问题。\n\n如果 `c.Stdin` 不是 `*os.File` 类型，`Wait` 会等待，直到数据从 `c.Stdin` 拷贝到进程的标准输入。\n\n`Wait` 方法会在命令返回后释放相关的资源。\n\n**Output**\n\n除了 `Run()` 是 `Start`+`Wait` 的简便写法，`Output()` 更是 `Run()` 的简便写法，外加获取外部命令的输出。\n\n`func (c *Cmd) Output() ([]byte, error)`\n\n它要求 `c.Stdout` 必须是 `nil`，内部会将 `bytes.Buffer` 赋值给 `c.Stdout`，在 `Run()` 成功返回后，会将 `Buffer` 的结果返回（`stdout.Bytes()`)。 \n\n**CombinedOutput**\n\n`Output()` 只返回 `Stdout` 的结果，而 `CombinedOutput` 组合 `Stdout` 和 `Stderr` 的输出，即 `Stdout` 和 `Stderr` 都赋值为同一个 `bytes.Buffer`。 \n\n\n**StdoutPipe、StderrPipe 和 StdinPipe**\n\n除了上面介绍的 `Output` 和 `CombinedOutput` 直接获取命令输出结果外，还可以通过 `StdoutPipe` 返回 `io.ReadCloser` 来获取输出；相应的 `StderrPipe` 得到错误信息；而 `StdinPipe` 则可以往命令写入数据。\n\n`func (c *Cmd) StdoutPipe() (io.ReadCloser, error)`\n\n`StdoutPipe` 方法返回一个在命令 `Start` 执行后与命令标准输出关联的管道。`Wait` 方法会在命令结束后会关闭这个管道，所以一般不需要手动关闭该管道。但是在从管道读取完全部数据之前调用 `Wait` 出错了，则必须手动关闭。\n\n`func (c *Cmd) StderrPipe() (io.ReadCloser, error)`\n\n`StderrPipe` 方法返回一个在命令 `Start` 执行后与命令标准错误输出关联的管道。`Wait` 方法会在命令结束后会关闭这个管道，一般不需要手动关闭该管道。但是在从管道读取完全部数据之前调用 `Wait` 出错了，则必须手动关闭。\n\n`func (c *Cmd) StdinPipe() (io.WriteCloser, error)`\n\n`StdinPipe` 方法返回一个在命令 `Start` 执行后与命令标准输入关联的管道。`Wait` 方法会在命令结束后会关闭这个管道。必要时调用者可以调用 `Close` 方法来强行关闭管道。例如，标准输入已经关闭了，命令执行才完成，这时调用者需要显示关闭管道。\n\n因为 `Wait` 之后，会将管道关闭，所以，要使用这些方法，只能使用 `Start`+`Wait` 组合，不能使用 `Run`。\n\n### 执行外部命令示例\n\n前面讲到，通过 `Cmd` 实例后，有两种方式运行命令。有时候，我们不只是简单的运行命令，还希望能控制命令的输入和输出。通过上面的 API 介绍，控制输入输出有几种方法：\n\n- 得到 `Cmd ` 实例后，直接给它的字段 `Stdin`、`Stdout` 和 `Stderr` 赋值；\n- 通过 `Output` 或 `CombinedOutput` 获得输出；\n- 通过带 `Pipe` 后缀的方法获得管道，用于输入或输出；\n\n#### 直接赋值 `Stdin`、`Stdout` 和 `Stderr`\n\n```go\nfunc FillStd(name string, arg ...string) ([]byte, error) {\n\tcmd := exec.Command(name, arg...)\n\tvar out = new(bytes.Buffer)\n\n\tcmd.Stdout = out\n\tcmd.Stderr = out\n\n\terr := cmd.Run()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn out.Bytes(), nil\n}\n```\n\n#### 使用 `Output`\n\n```go\nfunc UseOutput(name string, arg ...string) ([]byte, error) {\n\treturn exec.Command(name, arg...).Output()\n}\n```\n\n#### 使用 Pipe\n\n```go\nfunc UsePipe(name string, arg ...string) ([]byte, error) {\n\tcmd := exec.Command(name, arg...)\n\tstdout, err := cmd.StdoutPipe()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif err = cmd.Start(); err != nil {\n\t\treturn nil, err\n\t}\n\n\tvar out = make([]byte, 0, 1024)\n\tfor {\n\t\ttmp := make([]byte, 128)\n\t\tn, err := stdout.Read(tmp)\n\t\tout = append(out, tmp[:n]...)\n\t\tif err != nil {\n\t\t\tbreak\n\t\t}\n\t}\n\n\tif err = cmd.Wait(); err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn out, nil\n}\n```\n\n完整代码见 [os_exec](/code/src/chapter10/os_exec.go)。\n\n## 进程终止\n\n`os.Exit()` 函数会终止当前进程，对应的系统调用不是 `_exit`，而是 `exit_group`。\n\n`func Exit(code int)`\n\n`Exit` 让当前进程以给出的状态码 `code` 退出。一般来说，状态码 0 表示成功，非 0 表示出错。进程会立刻终止，defer 的函数不会被执行。\n\n# 导航 #\n\n- [第十章](/chapter10/10.0.md)\n- 下一节：[进程属性和控制](10.2.md)\n \n" }, { "path": "chapter10/10.2.md", "content": "# 10.2 进程属性和控制 #\n\n每个进程都有一些属性，`os` 包提供了一些函数可以获取进程属性。\n\n## 进程 ID\n\n每个进程都会有一个进程 ID，可以通过 `os.Getpid` 获得。同时，每个进程都有创建自己的父进程，通过 `os.Getppid` 获得。\n\n## 进程凭证\n\nUnix 中进程都有一套数字表示的用户 ID(UID) 和组 ID(GID)，有时也将这些 ID 称之为进程凭证。Windows 下总是 -1。\n\n### 实际用户 ID 和实际组 ID\n\n实际用户 ID（real user ID）和实际组 ID（real group ID）确定了进程所属的用户和组。登录 shell 从 `/etc/passwd` 文件读取用户 ID 和组 ID。当创建新进程时（如 shell 执行程序），将从其父进程中继承这些 ID。\n\n可通过 `os.Getuid()` 和 `os.Getgid()` 获取当前进程的实际用户 ID 和实际组 ID；\n\n### 有效用户 ID 和有效组 ID\n\n大多数 Unix 实现中，当进程尝试执行各种操作（即系统调用）时，将结合有效用户 ID、有效组 ID，连同辅助组 ID 一起来确定授予进程的权限。内核还会使用有效用户 ID 来决定一个进程是否能向另一个进程发送信号。\n\n有效用户 ID 为 0（root 的用户 ID）的进程拥有超级用户的所有权限。这样的进程又称为特权级进程（privileged process）。某些系统调用只能由特权级进程执行。\n\n可通过 `os.Geteuid()` 和 `os.Getegid()` 获取当前进程的有效用户 ID（effective user ID）和有效组 ID（effectvie group ID）。\n\n通常，有效用户 ID 及组 ID 与其相应的实际 ID 相等，但有两种方法能够致使二者不同。一是使用相关系统调用；二是执行 set-user-ID 和 set-group-ID 程序。\n\n### Set-User-ID 和 Set-Group-ID 程序\n\n`set-user-ID` 程序会将进程的有效用户 ID 置为可执行文件的用户 ID（属主），从而获得常规情况下并不具有的权限。`set-group-ID` 程序对进程有效组 ID 实现类似任务。（有时也将这程序简称为 set-UID 程序和 set-GID 程序。）\n\n与其他文件一样，可执行文件的用户 ID 和组 ID 决定了该文件的所有权。在 [6.1 os — 平台无关的操作系统功能实现](chapter06/06.1.md) 中提到过，文件还拥有两个特别的权限位 set-user-ID 位和 set-group-ID 位，可以使用 `os.Chmod` 修改这些权限位（非特权用户进程只能修改其自身文件，而特权用户进程能修改任何文件）。\n\n文件设置了 set-user-ID 位后，`ls -l` 显示文件后，会在属主用户执行权限字段上看到字母 s（有执行权限时） 或 S（无执行权限时）；相应的 set-group-ID 则是在组用户执行位上看到 s 或 S。\n\n当运行 set-user-ID 程序时，内核会将进程的有效用户 ID 设置为可执行文件的用户 ID。set-group-ID 程序对进程有效组 ID 的操作与之类似。通过这种方法修改进程的有效用户 ID 或组 ID，能够使进程（换言之，执行该程序的用户）获得常规情况下所不具有的权限。例如，如果一个可执行文件的属主为 root，且为此程序设置了 set-user-ID 权限位，那么当运行该程序时，进程会取得超级用户权限。\n\n也可以利用程序的 set-user-ID 和 set-group-ID 机制，将进程的有效 ID 修改为 root 之外的其他用户。例如，为提供一个受保护文件的访问，可采用如下方案：创建一个具有对该文件访问权限的专有用户（组）ID，然后再创建一个 set-user-ID（set-group-ID）程序，将进程有效用户（组）ID 变更为这个专用 ID。这样，无需拥有超级用户的所有权限，程序就能访问该文件。\n\nLinux 系统中经常使用的 set-user-ID 程序，如 passwd。\n\n#### 测试 set-user-ID 程序\n\n在 Linux 的某个目录下，用 root 账号创建一个文件：\n\n`echo \"This is my shadow, studygolang.\" > my_shadow.txt`\n\n然后将所有权限都去掉：`chmod 0 my_shadow.txt`。 ls -l 结果类似如下：\n\n`---------- 1 root root 32 6 月 24 17:31 my_shadow.txt`\n\n这时，如果非 root 用户是无法查看文件内容的。\n\n接着，用 root 账号创建一个 `main.go` 文件，内容如下：\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"io/ioutil\"\n\t\"log\"\n\t\"os\"\n)\n\nfunc main() {\n\tfile, err := os.Open(\"my_shadow.txt\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer file.Close()\n\n\tdata, err := ioutil.ReadAll(file)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tfmt.Printf(\"my_shadow:%s\\n\", data)\n}\n```\n就是简单地读取 `my_shadow` 文件内容。`go build main.go` 后，生成的 `main` 可执行文件，权限是：`-rwxrwxr-x`。\n\n这时，切换到非 root 用户，执行 `./main`，会输出：\n\n`open my_shadow.txt: permission denied`\n\n因为这时的 `main` 程序生成的进程有效用户 ID 是当前用户的（非 root）。\n\n接着，给 `main` 设置 `set-user-ID` 位：`chmod u+s main`，权限变为 `-rwsrwxr-x`，非 root 下再次执行 `./main`，输出：\n\n`my_shadow:This is my shadow, studygolang.`\n\n因为设置了 `set-user-ID` 位，这时 `main` 程序生成的进程有效用户是 `main` 文件的属主，即 root 的 ID，因此有权限读 `my_shadow.txt`。\n\n### 修改进程的凭证\n\n`os` 包没有提供相应的功能修改进程的凭证，在 `syscall` 包对这些系统调用进行了封装。因为 [https://golang.org/s/go1.4-syscall](https://golang.org/s/go1.4-syscall)，用户程序不建议直接使用该包，应该使用 `golang.org/x/sys` 包代替。\n\n该包提供了修改进程各种 ID 的系统调用封装，这里不一一介绍。\n\n此外，`os` 还提供了获取辅助组 ID 的函数：`os.Getgroups()`。\n\n### 操作系统用户\n\n包 `os/user` 允许通过名称或 ID 查询用户账号。用户结构定义如下：\n\n```go\ntype User struct {\n Uid string // user id\n Gid string // primary group id\n Username string\n Name string\n HomeDir string\n}\n```\n`User` 代表一个用户帐户。\n\n在 POSIX 系统中 Uid 和 Gid 字段分别包含代表 uid 和 gid 的十进制数字。在 Windows 系统中 Uid 和 Gid 包含字符串格式的安全标识符（SID）。在 Plan 9 系统中，Uid、Gid、Username 和 Name 字段是 /dev/user 的内容。\n\n`Current` 函数可以获取当前用户账号。而 `Lookup` 和 `LookupId` 则分别根据用户名和用户 ID 查询用户。如果对应的用户不存在，则返回 `user.UnknownUserError\t` 或 `user.UnknownUserIdError`。\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os/user\"\n)\n\nfunc main() {\n\tfmt.Println(user.Current())\n\tfmt.Println(user.Lookup(\"xuxinhua\"))\n\tfmt.Println(user.LookupId(\"0\"))\n}\n\n// Output:\n// &{502 502 xuxinhua /home/xuxinhua} \n// &{502 502 xuxinhua /home/xuxinhua} \n// &{0 0 root root /root} \n```\n\n## 进程的当前工作目录\n\n一个进程的当前工作目录（current working directory）定义了该进程解析相对路径名的起点。新进程的当前工作目录继承自其父进程。\n\n`func Getwd() (dir string, err error)`\n\n`Getwd` 返回一个对应当前工作目录的根路径。如果当前目录可以经过多条路径抵达（比如符号链接），`Getwd` 会返回其中一个。对应系统调用：`getcwd`。\n\n`func Chdir(dir string) error`\n\n相应的，`Chdir` 将当前工作目录修改为 `dir` 指定的目录。如果出错，会返回 `*PathError` 类型的错误。对应系统调用 `chdir`。\n\n另外，`os.File` 有一个方法：`Chdir`，对应系统调用 `fchidr`（以文件描述符为参数），也可以改变当前工作目录。\n\n## 改变进程的根目录\n\n每个进程都有一个根目录，该目录是解释绝对路径（即那些以 / 开始的目录）时的起点。默认情况下，这是文件系统的真是根目录。新进程从其父进程处继承根目录。有时可能需要改变一个进程的根目录（比如 ftp 服务就是一个典型的例子）。系统调用 `chroot` 能改变一个进程的根目录，Go 中对应的封装在 `syscall.Chroot`。\n\n除此之外，在 `fork` 子进程时，可以通过给 `syscall.SysProcAttr` 结构的 `Chroot` 字段指定一个路径，来初始化子进程的根目录。\n\n## 进程环境列表\n\n每个进程都有与其相关的称之为环境列表（environment list）的字符串数组，或简称环境（environment）。其中每个字符串都以 名称 = 值（name=value）形式定义。因此，环境是“名称 - 值”的成对集合，可存储任何信息。常将列表中的名称称为环境变量（environment variables）。\n\n新进程在创建之时，会继承其父进程的环境副本。这是一种原始的进程间通信方式，却颇为常用。环境（environment）提供了将信息和父进程传递给子进程的方法。创建后，父子进程的环境相互独立，互不影响。\n\n环境变量的常见用途之一是在 shell 中，通过在自身环境中放置变量值，shell 就可确保把这些值传递给其所创建的进程，并以此来执行用户命令。\n\n在程序中，可以通过 `os.Environ` 获取环境列表：\n\n`func Environ() []string`\n\n返回的 `[]string` 中每个元素是 `key=value` 的形式。\n\n`func Getenv(key string) string`\n\n`Getenv` 检索并返回名为 `key` 的环境变量的值。如果不存在该环境变量会返回空字符串。有时候，可能环境变量存在，只是值刚好是空。为了区分这种情况，提供了另外一个函数 `LookupEnv()`：\n\n`func LookupEnv(key string) (string, bool)`\n\n如果变量名存在，第二个参数返回 `true`，否则返回 `false`。\n\n`func Setenv(key, value string) error`\n\n`Setenv` 设置名为 `key` 的环境变量，值为 `value`。如果出错会返回该错误。（如果值之前存在，会覆盖）\n\n`func Unsetenv(key string) error`\n\n`Unsetenv` 删除名为 `key` 的环境变量。\n\n`func Clearenv()`\n\n`Clearenv` 删除所有环境变量。\n\n```go\npackage main\n\nimport (\n \"fmt\"\n \"os\"\n)\n\nfunc main() {\n fmt.Println(\"The num of environ:\", len(os.Environ()))\n godebug, ok := os.LookupEnv(\"GODEBUG\")\n if ok {\n fmt.Println(\"GODEBUG==\", godebug)\n } else {\n fmt.Println(\"GODEBUG not exists!\")\n os.Setenv(\"GODEBUG\", \"gctrace=1\")\n fmt.Println(\"after setenv:\", os.Getenv(\"GODEBUG\"))\n }\n\n os.Clearenv()\n fmt.Println(\"clearenv, the num:\", len(os.Environ()))\n}\n\n// Output:\n// The num of environ: 25\n// GODEBUG not exists!\n// after setenv: gctrace=1\n// clearenv, the num: 0\n```\n\n另外，`ExpandEnv` 和 `Getenv` 功能类似，不过，前者使用变量方式，如：\n\nos.ExpandEnv(\"$GODEBUG\") 和 os.Getenv(\"GODEBUG\") 是一样的。\n\n实际上，`os.ExpandEnv` 调用的是 `os.Expand(s, os.Getenv)`。\n\n`func Expand(s string, mapping func(string) string) string`\n\n`Expand` 能够将 ${var} 或 $var 形式的变量，经过 mapping 处理，得到结果。 \n\n# 导航 #\n\n- 上一节：[创建进程](10.1.md)\n- 下一节：[线程](10.3.md)\n \n" }, { "path": "chapter10/10.3.md", "content": "# 10.3 线程 #\n\n与进程类似，线程是允许应用程序并发执行多个任务的一种机制。一个进程可以包含多个线程。同一个程序中的所有线程均会独立执行相同程序，且共享同一份全局内存区域。\n\n同一进程中的多个线程可以并发执行。在多处理器环境下，多个线程可以同时并行。如果一个线程因等待 I/O 操作而遭阻塞，那么其他线程依然可以继续运行。\n\n在 Linux 中，通过系统调用 `clone()` 来实现线程的。从前面的介绍，我们知道，该系统调用也可以用来创建进程。实际上，从内核的角度来说，它并没有线程这个概念。Linux 把所有的线程都当作进程来实现。内核并没有准备特别的调度算法或是定义特别的数据结构来表征线程。相反，线程仅仅被视为一个使用某些共享资源的进程。所以，在内核中，它看起来就是一个普通的进程（只是该进程和其他一些进程共享某些资源，如地址空间）。 \n\n在 Go 中，通过 `clone()` 系统调用来创建线程，其中的 `clone_flags` 为：\n\n```go\ncloneFlags = _CLONE_VM | /* share memory */\n\t\t_CLONE_FS | /* share cwd, etc */\n\t\t_CLONE_FILES | /* share fd table */\n\t\t_CLONE_SIGHAND | /* share sig handler table */\n\t\t_CLONE_THREAD /* revisit - okay for now */\n```\n\n也就是说，父子俩共享了地址空间 (_CLONE_VM)、文件系统资源 (_CLONE_FS)、文件描述符 (_CLONE_FILES) 和信号处理程序 (_CLONE_SIGHAND)。而 `_CLONE_THREAD` 则会将父子进程放入相同的线程组。这样一来，新建的进程和父进程都叫做线程。\n\n\n\n\n# 导航 #\n\n- 上一节：[进程属性和控制](10.2.md)\n- 下一节：[进程间通信](10.4.md)\n \n" }, { "path": "chapter10/10.4.md", "content": "# 10.3 进程间通信 #\n\n进程之间用来相互通讯和同步\n\n# 导航 #\n\n- 上一节：[创建进程](10.1.md)\n- 下一节：[进程间通信](10.3.md)\n \n" }, { "path": "chapter13/13.0.md", "content": "# 第十三章 应用构建 与 debug #\n\n本章我们来研究应用程序构建相关的标准库，包括用于命令行参数解析的 flag 包，简单的日志记录包 log（以及 syslog)，公共变量标准接口 expvar 包，以及运行时的调试工具 runtime/debug 包。\n\n# 导航 #\n\n- [第十二章](/chapter12/12.0.md)\n- 下一节：[flag - 命令行参数解析](13.1.md)\n" }, { "path": "chapter13/13.1.md", "content": "# 13.1 flag - 命令行参数解析 #\n\n在写命令行程序（工具、server）时，对命令参数进行解析是常见的需求。各种语言一般都会提供解析命令行参数的方法或库，以方便程序员使用。如果命令行参数纯粹自己写代码解析，对于比较复杂的，还是挺费劲的。在 go 标准库中提供了一个包：`flag`，方便进行命令行解析。\n\n**注：区分几个概念**\n\n1. 命令行参数（或参数）：是指运行程序提供的参数\n2. 已定义命令行参数：是指程序中通过 flag.Xxx 等这种形式定义了的参数\n3. 非 flag（non-flag）命令行参数（或保留的命令行参数）：后文解释\n\n## 使用示例\n\n我们以 nginx 为例，执行 nginx -h，输出如下：\n\n```go\nnginx version: nginx/1.10.0\nUsage: nginx [-?hvVtTq] [-s signal] [-c filename] [-p prefix] [-g directives]\n\nOptions:\n -?,-h : this help\n -v : show version and exit\n -V : show version and configure options then exit\n -t : test configuration and exit\n -T : test configuration, dump it and exit\n -q : suppress non-error messages during configuration testing\n -s signal : send signal to a master process: stop, quit, reopen, reload\n -p prefix : set prefix path (default: /usr/local/nginx/)\n -c filename : set configuration file (default: conf/nginx.conf)\n -g directives : set global directives out of configuration file\n\n```\n\n我们通过 `flag` 实现类似 nginx 的这个输出，创建文件 nginx.go，内容如下：\n\n```go\npackage main\n\nimport (\n\t\"flag\"\n\t\"fmt\"\n\t\"os\"\n)\n\n// 实际中应该用更好的变量名\nvar (\n\th bool\n\n\tv, V bool\n\tt, T bool\n\tq *bool\n\n\ts string\n\tp string\n\tc string\n\tg string\n)\n\nfunc init() {\n\tflag.BoolVar(&h, \"h\", false, \"this help\")\n\n\tflag.BoolVar(&v, \"v\", false, \"show version and exit\")\n\tflag.BoolVar(&V, \"V\", false, \"show version and configure options then exit\")\n\n\tflag.BoolVar(&t, \"t\", false, \"test configuration and exit\")\n\tflag.BoolVar(&T, \"T\", false, \"test configuration, dump it and exit\")\n\n\t// 另一种绑定方式\n\tq = flag.Bool(\"q\", false, \"suppress non-error messages during configuration testing\")\n\n\t// 注意 `signal`。默认是 -s string，有了 `signal` 之后，变为 -s signal\n\tflag.StringVar(&s, \"s\", \"\", \"send `signal` to a master process: stop, quit, reopen, reload\")\n\tflag.StringVar(&p, \"p\", \"/usr/local/nginx/\", \"set `prefix` path\")\n\tflag.StringVar(&c, \"c\", \"conf/nginx.conf\", \"set configuration `file`\")\n\tflag.StringVar(&g, \"g\", \"conf/nginx.conf\", \"set global `directives` out of configuration file\")\n\n\t// 改变默认的 Usage\n\tflag.Usage = usage\n}\n\nfunc main() {\n\tflag.Parse()\n\n\tif h {\n\t\tflag.Usage()\n\t}\n}\n\nfunc usage() {\n\tfmt.Fprintf(os.Stderr, `nginx version: nginx/1.10.0\nUsage: nginx [-hvVtTq] [-s signal] [-c filename] [-p prefix] [-g directives]\n\nOptions:\n`)\n\tflag.PrintDefaults()\n}\n```\n执行：go run nginx.go -h，（或 go build -o nginx && ./nginx -h）输出如下：\n\n```\nnginx version: nginx/1.10.0\nUsage: nginx [-hvVtTq] [-s signal] [-c filename] [-p prefix] [-g directives]\n\nOptions:\n -T\ttest configuration, dump it and exit\n -V\tshow version and configure options then exit\n -c file\n \tset configuration file (default \"conf/nginx.conf\")\n -g directives\n \tset global directives out of configuration file (default \"conf/nginx.conf\")\n -h\tthis help\n -p prefix\n \tset prefix path (default \"/usr/local/nginx/\")\n -q\tsuppress non-error messages during configuration testing\n -s signal\n \tsend signal to a master process: stop, quit, reopen, reload\n -t\ttest configuration and exit\n -v\tshow version and exit\n```\n\n仔细理解以上例子，如果有不理解的，看完下文的讲解再回过头来看。\n\n## flag 包概述\n\n`flag` 包实现了命令行参数的解析。\n\n### 定义 flags 有两种方式\n\n1）flag.Xxx()，其中 `Xxx` 可以是 Int、String 等；返回一个相应类型的指针，如：\n\n\tvar ip = flag.Int(\"flagname\", 1234, \"help message for flagname\")\n\n2）flag.XxxVar()，将 flag 绑定到一个变量上，如：\n\n```go\nvar flagvar int\nflag.IntVar(&flagvar, \"flagname\", 1234, \"help message for flagname\")\n```\n\n### 自定义 Value\n\n另外，还可以创建自定义 flag，只要实现 flag.Value 接口即可（要求 `receiver` 是指针），这时候可以通过如下方式定义该 flag：\n\n\tflag.Var(&flagVal, \"name\", \"help message for flagname\")\n\n\n例如，解析我喜欢的编程语言，我们希望直接解析到 slice 中，我们可以定义如下 Value：\n\n```go\ntype sliceValue []string\n\nfunc newSliceValue(vals []string, p *[]string) *sliceValue {\n\t*p = vals\n\treturn (*sliceValue)(p)\n}\n\nfunc (s *sliceValue) Set(val string) error {\n\t*s = sliceValue(strings.Split(val, \",\"))\n\treturn nil\n}\n\nfunc (s *sliceValue) Get() interface{} { return []string(*s) }\n\nfunc (s *sliceValue) String() string { return strings.Join([]string(*s), \",\") }\n```\n之后可以这么使用：\n\n```go\nvar languages []string\nflag.Var(newSliceValue([]string{}, &languages), \"slice\", \"I like programming `languages`\")\n```\n\n这样通过 `-slice \"go,php\"` 这样的形式传递参数，`languages` 得到的就是 `[go, php]`。\n\nflag 中对 Duration 这种非基本类型的支持，使用的就是类似这样的方式。\n\n### 解析 flag\n\n在所有的 flag 定义完成之后，可以通过调用 `flag.Parse()` 进行解析。\n\n命令行 flag 的语法有如下三种形式：\n\n\t-flag // 只支持 bool 类型\n\t-flag=x\n\t-flag x // 只支持非 bool 类型\n\n其中第三种形式只能用于非 bool 类型的 flag，原因是：如果支持，那么对于这样的命令 cmd -x *，如果有一个文件名字是：0 或 false 等，则命令的原意会改变（之所以这样，是因为 bool 类型支持 `-flag` 这种形式，如果 bool 类型不支持 `-flag` 这种形式，则 bool 类型可以和其他类型一样处理。也正因为这样，Parse() 中，对 bool 类型进行了特殊处理）。默认的，提供了 `-flag`，则对应的值为 true，否则为 `flag.Bool/BoolVar` 中指定的默认值；如果希望显示设置为 false 则使用 `-flag=false`。\n\nint 类型可以是十进制、十六进制、八进制甚至是负数；bool 类型可以是 1, 0, t, f, true, false, TRUE, FALSE, True, False。Duration 可以接受任何 time.ParseDuration 能解析的类型。\n\n## 类型和函数\n\n在看类型和函数之前，先看一下变量。\n\nErrHelp：该错误类型用于当命令行指定了 · -help` 参数但没有定义时。\n\nUsage：这是一个函数，用于输出所有定义了的命令行参数和帮助信息（usage message）。一般，当命令行参数解析出错时，该函数会被调用。我们可以指定自己的 Usage 函数，即：`flag.Usage = func(){}`\n\n### 函数\n\ngo 标准库中，经常这么做：\n\n> 定义了一个类型，提供了很多方法；为了方便使用，会实例化一个该类型的实例（通用），这样便可以直接使用该实例调用方法。比如：encoding/base64 中提供了 StdEncoding 和 URLEncoding 实例，使用时：base64.StdEncoding.Encode()\n\n在 flag 包使用了有类似的方法，比如 CommandLine 实例，只不过 flag 进行了进一步封装：将 FlagSet 的方法都重新定义了一遍，也就是提供了一序列函数，而函数中只是简单的调用已经实例化好了的 FlagSet 实例：CommandLine 的方法。这样，使用者是这么调用：flag.Parse() 而不是 flag. CommandLine.Parse()。（Go 1.2 起，将 CommandLine 导出，之前是非导出的）\n\n这里不详细介绍各个函数，在类型方法中介绍。\n\n### 类型（数据结构）\n\n1）ErrorHandling\n\n\ttype ErrorHandling int\n\n该类型定义了在参数解析出错时错误处理方式。定义了三个该类型的常量：\n\n```go\nconst (\n\tContinueOnError ErrorHandling = iota\n\tExitOnError\n\tPanicOnError\n)\n```\n三个常量在源码的 FlagSet 的方法 parseOne() 中使用了。\n\n2）Flag\n\n```go\n// A Flag represents the state of a flag.\ntype Flag struct {\n\tName string // name as it appears on command line\n\tUsage string // help message\n\tValue Value // value as set\n\tDefValue string // default value (as text); for usage message\n}\n```\nFlag 类型代表一个 flag 的状态。\n\n比如，对于命令：`./nginx -c /etc/nginx.conf`，相应代码是：\n\n\tflag.StringVar(&c, \"c\", \"conf/nginx.conf\", \"set configuration `file`\")\n\n则该 Flag 实例（可以通过 `flag.Lookup(\"c\")` 获得）相应各个字段的值为：\n\n```go\n&Flag{\n\tName: c,\n\tUsage: set configuration file,\n\tValue: /etc/nginx.conf,\n\tDefValue: conf/nginx.conf,\n}\n```\n\n3）FlagSet\n\n```go\n// A FlagSet represents a set of defined flags.\ntype FlagSet struct {\n\t// Usage is the function called when an error occurs while parsing flags.\n\t// The field is a function (not a method) that may be changed to point to\n\t// a custom error handler.\n\tUsage func()\n\n\tname string // FlagSet 的名字。CommandLine 给的是 os.Args[0]\n\tparsed bool // 是否执行过 Parse()\n\tactual map[string]*Flag // 存放实际传递了的参数（即命令行参数）\n\tformal map[string]*Flag // 存放所有已定义命令行参数\n\targs []string // arguments after flags // 开始存放所有参数，最后保留 非 flag（non-flag）参数\n\texitOnError bool // does the program exit if there's an error?\n\terrorHandling ErrorHandling // 当解析出错时，处理错误的方式\n\toutput io.Writer // nil means stderr; use out() accessor\n}\n```\n4）Value 接口\n\n```go\n// Value is the interface to the dynamic value stored in a flag.\n// (The default value is represented as a string.)\ntype Value interface {\n\tString() string\n\tSet(string) error\n}\n```\n所有参数类型需要实现 Value 接口，flag 包中，为 int、float、bool 等实现了该接口。借助该接口，我们可以自定义 flag。（上文已经给了具体的例子）\n\n## 主要类型的方法（包括类型实例化）\n\nflag 包中主要是 FlagSet 类型。\n\n### 实例化方式\n\n`NewFlagSet()` 用于实例化 FlagSet。预定义的 FlagSet 实例 `CommandLine` 的定义方式：\n\n```go\n// The default set of command-line flags, parsed from os.Args.\nvar CommandLine = NewFlagSet(os.Args[0], ExitOnError)\n```\n可见，默认的 FlagSet 实例在解析出错时会退出程序。\n\n由于 FlagSet 中的字段没有 export，其他方式获得 FlagSet 实例后，比如：FlagSet{} 或 new(FlagSet)，应该调用 Init() 方法，以初始化 name 和 errorHandling，否则 name 为空，errorHandling 为 ContinueOnError。\n\n### 定义 flag 参数的方法\n\n这一序列的方法都有两种形式，在一开始已经说了两种方式的区别。这些方法用于定义某一类型的 flag 参数。\n\n### 解析参数（Parse）\n\n\tfunc (f *FlagSet) Parse(arguments []string) error\n\n从参数列表中解析定义的 flag。方法参数 arguments 不包括命令名，即应该是 os.Args[1:]。事实上，`flag.Parse()` 函数就是这么做的：\n\n```go\n// Parse parses the command-line flags from os.Args[1:]. Must be called\n// after all flags are defined and before flags are accessed by the program.\nfunc Parse() {\n\t// Ignore errors; CommandLine is set for ExitOnError.\n\tCommandLine.Parse(os.Args[1:])\n}\n```\n\n该方法应该在 flag 参数定义后而具体参数值被访问前调用。\n\n如果提供了 `-help` 参数（命令中给了）但没有定义（代码中没有），该方法返回 `ErrHelp` 错误。默认的 CommandLine，在 Parse 出错时会退出程序（ExitOnError）。\n\n为了更深入的理解，我们看一下 `Parse(arguments []string)` 的源码：\n\n```go\nfunc (f *FlagSet) Parse(arguments []string) error {\n\tf.parsed = true\n\tf.args = arguments\n\tfor {\n\t\tseen, err := f.parseOne()\n\t\tif seen {\n\t\t\tcontinue\n\t\t}\n\t\tif err == nil {\n\t\t\tbreak\n\t\t}\n\t\tswitch f.errorHandling {\n\t\tcase ContinueOnError:\n\t\t\treturn err\n\t\tcase ExitOnError:\n\t\t\tos.Exit(2)\n\t\tcase PanicOnError:\n\t\t\tpanic(err)\n\t\t}\n\t}\n\treturn nil\n}\n```\n真正解析参数的方法是非导出方法 `parseOne`。\n\n结合 `parseOne` 方法，我们来解释 `non-flag` 以及包文档中的这句话：\n\n> Flag parsing stops just before the first non-flag argument (\"-\" is a non-flag argument) or after the terminator \"--\".\n\n我们需要了解解析什么时候停止。\n\n根据 Parse() 中 for 循环终止的条件（不考虑解析出错），我们知道，当 parseOne 返回 `false, nil` 时，Parse 解析终止。正常解析完成我们不考虑。看一下 parseOne 的源码发现，有两处会返回 `false, nil`。\n\n1）第一个 non-flag 参数\n\n```go\ns := f.args[0]\nif len(s) == 0 || s[0] != '-' || len(s) == 1 {\n\treturn false, nil\n}\n```\n也就是，当遇到单独的一个 \"-\" 或不是 \"-\" 开始时，会停止解析。比如：\n\n> ./nginx - -c 或 ./nginx build -c\n\n这两种情况，`-c` 都不会被正确解析。像该例子中的 \"-\" 或 build（以及之后的参数），我们称之为 `non-flag` 参数。\n\n2）两个连续的 \"--\"\n\n```go\nif s[1] == '-' {\n\tnum_minuses++\n\tif len(s) == 2 { // \"--\" terminates the flags\n\t\tf.args = f.args[1:]\n\t\treturn false, nil\n\t}\n}\n```\n也就是，当遇到连续的两个 \"-\" 时，解析停止。\n\n*说明：这里说的 \"-\" 和 \"--\"，位置和 \"-c\" 这种的一样。*也就是说，下面这种情况并不是这里说的：\n\n> ./nginx -c --\n\n这里的 \"--\" 会被当成是 `c` 的值\n\nparseOne 方法中接下来是处理 `-flag=x` 这种形式，然后是 `-flag` 这种形式（bool 类型）（这里对 bool 进行了特殊处理），接着是 `-flag x` 这种形式，最后，将解析成功的 Flag 实例存入 FlagSet 的 actual map 中。\n\n另外，在 parseOne 中有这么一句：\n\n\tf.args = f.args[1:]\n\n也就是说，每执行成功一次 parseOne，f.args 会少一个。所以，FlagSet 中的 args 最后留下来的就是所有 `non-flag` 参数。\n\n### Arg(i int) 和 Args()、NArg()、NFlag()\n\nArg(i int) 和 Args() 这两个方法就是获取 `non-flag` 参数的；NArg() 获得 `non-flag` 的个数；NFlag() 获得 FlagSet 中 actual 长度（即被设置了的参数个数）。\n\n### Visit/VisitAll\n\n这两个函数分别用于访问 FlatSet 的 actual 和 formal 中的 Flag，而具体的访问方式由调用者决定。\n\n### PrintDefaults()\n\n打印所有已定义参数的默认值（调用 VisitAll 实现），默认输出到标准错误，除非指定了 FlagSet 的 output（通过 SetOutput() 设置）\n\n### Set(name, value string)\n\n设置某个 flag 的值（通过 name 查找到对应的 Flag）\n\n## 总结\n\n使用建议：虽然上面讲了那么多，一般来说，我们只简单的定义 flag，然后 parse，就如同开始的例子一样。\n\n如果项目需要复杂或更高级的命令行解析方式，可以使用 https://github.com/urfave/cli 或者 https://github.com/spf13/cobra 这两个强大的库。\n\n# 导航 #\n\n- [第十三章](13.0.md)\n- 下一节：[log - 日志记录](13.2.md)\n" }, { "path": "chapter13/13.3.md", "content": "# 13.3 expvar - 公共变量的标准化接口 #\n\nexpvar 挺简单的，然而，它也是很有用的。但不幸的是，貌似了解它的人不多。来自 godoc.org 的数据表明，没有多少人知道这个包。截止目前（2017-6-18），该包被公开的项目 import 2207 次，相比较而言，连 image 包都被 import 3491 次之多。\n\n如果你看到了这里，希望以后你的项目中能使用上 expvar 这个包。\n\n## 包简介 ##\n\n包 expvar 为公共变量提供了一个标准化的接口，如服务器中的操作计数器。它以 JSON 格式通过 `/debug/vars` 接口以 HTTP 的方式公开这些公共变量。\n\n设置或修改这些公共变量的操作是原子的。\n\n除了为程序增加 HTTP handler，此包还注册以下变量：\n\n cmdline os.Args\n memstats runtime.Memstats\n\n导入该包有时只是为注册其 HTTP handler 和上述变量。 要以这种方式使用，请将此包通过如下形式引入到程序中：\n\n import _ \"expvar\"\n\n## 例子 ##\n\n在继续介绍此包的详细信息之前，我们演示使用 expvar 包可以做什么。以下代码创建一个在监听 8080 端口的 HTTP 服务器。每个请求到达 hander() 后，在向访问者发送响应消息之前增加计数器。\n```go\n package main\n \n import (\n \"expvar\"\n \"fmt\"\n \"net/http\"\n )\n \n var visits = expvar.NewInt(\"visits\")\n \n func handler(w http.ResponseWriter, r *http.Request) {\n visits.Add(1)\n fmt.Fprintf(w, \"Hi there, I love %s!\", r.URL.Path[1:])\n }\n \n func main() {\n http.HandleFunc(\"/\", handler)\n http.ListenAndServe(\":8080\", nil)\n }\n```\n导入 expvar 包后，它将为 `http.DefaultServeMux` 上的 PATH `/debug/vars` 注册一个处理函数。此处理程序返回已在 expvar 包中注册的所有公共变量。运行代码并访问 `http://localhost:8080/debug/vars`，您将看到如下所示的内容（输出被截断以增加可读性）：\n\n {\n \"cmdline\": [\n \"/var/folders/qv/2jztyc09357ddtxn_bvgh8j00000gn/T/go-build146580631/command-line-arguments/_obj/exe/test\"\n ],\n \"memstats\": {\n \"Alloc\": 414432,\n \"TotalAlloc\": 414432,\n \"Sys\": 3084288,\n \"Lookups\": 13,\n \"Mallocs\": 5111,\n \"Frees\": 147,\n \"HeapAlloc\": 414432,\n \"HeapSys\": 1703936,\n \"HeapIdle\": 835584,\n \"HeapInuse\": 868352,\n \"HeapReleased\": 0,\n \"HeapObjects\": 4964,\n \"StackInuse\": 393216,\n \"StackSys\": 393216,\n \"MSpanInuse\": 15504,\n \"MSpanSys\": 16384,\n \"MCacheInuse\": 4800,\n \"MCacheSys\": 16384,\n \"BuckHashSys\": 2426,\n \"GCSys\": 137216,\n \"OtherSys\": 814726,\n \"NextGC\": 4473924,\n \"LastGC\": 0,\n \"PauseTotalNs\": 0,\n \"PauseNs\": [\n 0,\n 0,\n ],\n \"PauseEnd\": [\n 0,\n 0\n ],\n \"GCCPUFraction\": 0,\n \"EnableGC\": true,\n \"DebugGC\": false,\n \"BySize\": [\n {\n \"Size\": 16640,\n \"Mallocs\": 0,\n \"Frees\": 0\n },\n {\n \"Size\": 17664,\n \"Mallocs\": 0,\n \"Frees\": 0\n }\n ]\n },\n \"visits\": 0\n }\n\n信息真不少。这是因为默认情况下该包注册了 `os.Args` 和 `runtime.Memstats` 两个指标。因为我们还没有访问到增加 visits 的路径，所以它的值仍然为 0。现在通过访问 `http:// localhost:8080/golang` 来增加计数器，然后返回。计数器不再为 0。\n\n## expvar.Publish 函数 ##\n\nexpvar 包相当小且容易理解。它主要由两个部分组成。第一个是函数 `expvar.Publish(name string，v expvar.Var)`。该函数可用于在未导出的全局注册表中注册具有特定名称（name）的 v。以下代码段显示了具体实现。接下来的 3 个代码段是从 expvar 包的源代码中截取的。\n\n先看下全局注册表：\n```go\n\tvar (\n\t\tmutex sync.RWMutex\n\t\tvars = make(map[string]Var)\n\t\tvarKeys []string // sorted\n\t)\n```\n全局注册表实际就是一个 map：vars。\n\nPublish 函数的实现：\n```go\n // Publish declares a named exported variable. This should be called from a\n // package's init function when it creates its Vars. If the name is already\n // registered then this will log.Panic.\n func Publish(name string, v Var) {\n mutex.Lock()\n defer mutex.Unlock()\n \n // Check if name has been taken already. If so, panic.\n if _, existing := vars[name]; existing {\n log.Panicln(\"Reuse of exported var name:\", name)\n }\n \n // vars is the global registry. It is defined somewhere else in the\n // expvar package like this:\n //\n // vars = make(map[string]Var)\n vars[name] = v\n // 一方面，该包中所有公共变量，放在 vars 中，同时，通过 varKeys 保存了所有变量名，并且按字母序排序，即实现了一个有序的、线程安全的 map\n varKeys = append(varKeys, name)\n sort.Strings(varKeys)\n }\n```\nexpvar 包内置的两个公共变量就是通过 Publish 注册的：\n\n\tPublish(\"cmdline\", Func(cmdline))\n\tPublish(\"memstats\", Func(memstats))\n\n## expvar.Var 接口 ##\n\n另一个重要的组成部分是 `expvar.Var` 接口。 这个接口只有一个方法：\n```go\n // Var is an abstract type for all exported variables.\n type Var interface {\n // String returns a valid JSON value for the variable.\n // Types with String methods that do not return valid JSON\n // (such as time.Time) must not be used as a Var.\n String() string\n }\n```\n所以你可以在有 String() string 方法的所有类型上调用 Publish() 函数，但需要注意的是，这里的 String() 要求返回的是一个有效的 JSON 字符串。\n\n## expvar.Int 类型 ##\n\nexpvar 包提供了其他几个类型，它们实现了 expvar.Var 接口。其中一个是 expvar.Int，我们已经在演示代码中通过 expvar.NewInt(\"visits\") 方式使用它了，它会创建一个新的 expvar.Int，并使用 expvar.Publish 注册它，然后返回一个指向新创建的 expvar.Int 的指针。\n```go\n func NewInt(name string) *Int {\n v := new(Int)\n Publish(name, v)\n return v\n }\n```\nexpvar.Int 包装一个 int64，并有两个函数 Add(delta int64) 和 Set(value int64)，它们以线程安全的方式（通过 `atomic` 包实现）修改包装的 int64。另外通过 `Value() int64` 函数获得包装的 int64。\n```go\n\ttype Int struct {\n\t\ti int64\n\t}\n```\n## 其他类型 ##\n\n除了 expvar.Int，该包还提供了一些实现 expvar.Var 接口的其他类型：\n\n* [expvar.Float](http://docs.studygolang.com/pkg/expvar/#Float)\n* [expvar.String](http://docs.studygolang.com/pkg/expvar/#String)\n* [expvar.Map](http://docs.studygolang.com/pkg/expvar/#Map)\n* [expvar.Func](http://docs.studygolang.com/pkg/expvar/#Func)\n\n前两个类型包装了 float64 和 string。后两种类型需要稍微解释下。\n\n`expvar.Map` 类型可用于使公共变量出现在某个名称空间下。可以这样用：\n```go\n var stats = expvar.NewMap(\"http\")\n var requests, requestsFailed expvar.Int\n \n func init() {\n stats.Set(\"req_succ\", &requests)\n stats.Set(\"req_failed\", &requestsFailed)\n }\n```\n这段代码使用名称空间 http 注册了两个指标 req_succ 和 req_failed。它将显示在 JSON 响应中，如下所示：\n\n {\n \"http\": {\n \"req_succ\": 18,\n \"req_failed\": 21\n }\n }\n\n当要注册某个函数的执行结果到某个公共变量时，您可以使用 `expvar.Func`。假设您希望计算应用程序的正常运行时间，每次有人访问 `http://localhost:8080/debug/vars` 时，都必须重新计算此值。\n```go\n var start = time.Now()\n \n func calculateUptime() interface {\n return time.Since(start).String()\n }\n \n expvar.Publish(\"uptime\", expvar.Func(calculateUptime))\n```\n实际上，内置的两个指标 `cmdline` 和 `memstats` 就是通过这种方式注册的。注意，函数签名有如下要求：没有参数，返回 interface{}\n\n\ttype Func func() interface{}\n\n## 关于 Handler 函数 ##\n\n本文开始时提到，可以简单的导入 expvar 包，然后使用其副作用，导出路径 `/debug/vars`。然而，如果我们使用了一些框架，并非使用 `http.DefaultServeMux`，而是框架自己定义的 `Mux`，这时直接导入使用副作用可能不会生效。我们可以按照使用的框架，定义自己的路径，比如也叫 `/debug/vars`，然后，这对应的处理程序中，按如下的两种方式处理：\n\n1）将处理直接交给 `expvar.Handler`，比如：\n\n handler := expvar.Handler()\n handler.ServeHTTP(w, req)\n\n2）自己遍历 expvar 中的公共变量，构造输出，甚至可以过滤 expvar 默认提供的 cmdline 和 memstats，我们看下 expvarHandler 的源码就明白了：（通过 expvar.Do 函数来遍历的）\n```go\n func expvarHandler(w http.ResponseWriter, r *http.Request) {\n w.Header().Set(\"Content-Type\", \"application/json; charset=utf-8\")\n fmt.Fprintf(w, \"{\\n\")\n first := true\n Do(func(kv KeyValue) {\n if !first {\n fmt.Fprintf(w, \",\\n\")\n }\n first = false\n fmt.Fprintf(w, \"%q: %s\", kv.Key, kv.Value)\n })\n fmt.Fprintf(w, \"\\n}\\n\")\n }\n```\n[Go 语言中文网](https://github.com/studygolang/studygolang/blob/V3.0/src/http/controller/admin/metrics.go#L42) 因为使用了 Echo 框架，使用第 1 种方式来处理的。\n\n## 定义自己的 expvar.Var 类型 ##\n\nexpvar 包提供了 int、float 和 string 这三种基本数据类型的 expvar.Var 实现，以及 Func 和 Map。有时，我们自己有一个复杂的类型，想要实现 expvar.Var 接口，怎么做呢？\n\n从上面的介绍，应该很容易实现吧，如果您遇到了具体的需求，可以试试。\n\n## 总结 ##\n\n综上所述，通过 expvar 包，可以非常容易的展示应用程序指标。建议您在您的每个应用程序中使用它来展示一些指示应用程序运行状况的指标，通过它和其他的一些工具来监控应用程序。\n\n# 导航 #\n\n- 上一节：[log - 日志记录](10.2.md)\n- 下一节：[runtime/debug - 运行时的调试工具](10.4.md)\n \n" }, { "path": "chapter14/14.0.md", "content": "# 第十四章 运行时特性 #\n\n运行时（runtime）是 Go 语言最重要的部分，关于它包含的内容，比如内存分配、调度、高级数据结构的实现等，都是高级进阶内容，超出了本书的范围。\n\n本章主要着重介绍使用方面，在日常开发中可能会用到 runtime 包或子包中的某些功能，它们也是标准库的一部分。\n\n# 导航 #\n\n- [第十三章](/chapter13/01.0.md)\n- 下一节：[runtime 包](14.1.md)" }, { "path": "chapter14/14.2.md", "content": "# 14.2 io — 基本的 IO 接口 #\n\n\n\n# 导航 #\n\n- 上一节：[runtime 包](14.1.md)\n- 下一节：[]()\n\n" }, { "path": "chapter15/15.02.md", "content": "# 15.2 — 非类型安全操作 #\n\n*unsafe*库徘徊在“类型安全”边缘，由于它们绕过了 Golang 的内存安全原则，一般被认为使用该库是不安全的。但是，在许多情况下，*unsafe*库的作用又是不可替代的，灵活地使用它们可以实现对内存的直接读写操作。在*reflect*库、*syscall*库以及其他许多需要操作内存的开源项目中都有对它的引用。\n\n*unsafe*库源码极少，只有两个类型的定义和三个方法的声明。\n\n## Arbitrary 类型 ##\n\n官方导出这个类型只是出于完善文档的考虑，在其他的库和任何项目中都没有使用价值，除非程序员故意使用它。\n\n## Pointer 类型 ##\n\n这个类型比较重要，它是实现定位欲读写的内存的基础。官方文档对该类型有四个重要描述：\n\n- （1）任何类型的指针都可以被转化为 Pointer\n- （2）Pointer 可以被转化为任何类型的指针\n- （3）uintptr 可以被转化为 Pointer\n- （4）Pointer 可以被转化为 uintptr\n\n举例来说，该类型可以这样使用：\n```go\n func main() {\n i := 100\n fmt.Println(i) // 100\n p := (*int)unsafe.Pointer(&i)\n fmt.Println(*p) // 100\n *p = 0\n fmt.Println(i) // 0\n fmt.Println(*p) // 0\n }\n```\n## Sizeof 函数 ##\n\n该函数的定义如下：\n\n func Sizeof(v ArbitraryType) uintptr\n \nSizeof 函数返回变量 v 占用的内存空间的字节数，该字节数不是按照变量 v 实际占用的内存计算，而是按照 v 的“ top level ”内存计算。比如，在 64 位系统中，如果变量 v 是 int 类型，会返回 16，因为 v 的“ top level ”内存就是它的值使用的内存；如果变量 v 是 string 类型，会返回 16，因为 v 的“ top level ”内存不是存放着实际的字符串，而是该字符串的地址；如果变量 v 是 slice 类型，会返回 24，这是因为 slice 的描述符就占了 24 个字节。\n\n## Offsetof 函数 ##\n\n该函数的定义如下：\n\n func Offsetof(v ArbitraryType) uintptr\n \n该函数返回由 v 所指示的某结构体中的字段在该结构体中的位置偏移字节数，注意，v 的表达方式必须是“ struct.filed ”形式。\n举例说明，在 64 为系统中运行以下代码：\n```go\n type Datas struct{\n c0 byte\n c1 int\n c2 string\n c3 int\n }\n func main(){\n var d Datas\n fmt.Println(unsafe.Offset(d.c0)) // 0\n fmt.Println(unsafe.Offset(d.c1)) // 8\n fmt.Println(unsafe.Offset(d.c2)) // 16\n fmt.Println(unsafe.Offset(d.c3)) // 32\n }\n ``` \n如果知道的结构体的起始地址和字段的偏移值，就可以直接读写内存：\n```go\n d.c3 = 13\n p := unsafe.Pointer(&d)\n\toffset := unsafe.Offsetof(d.c3)\n\tq := (*int)(unsafe.Pointer(uintptr(p) + offset))\n fmt.Println(*q) // 13\n *p = 1013\n fmt.Println(d.c3) // 1013\n``` \n\n\n# 导航 #\n\n- [目录](/preface.md)\n- 上一节：buildin\n- 下一节：暂未确定\n" }, { "path": "chapter16/16.01.md", "content": "# sync - 处理同步需求 #\n\ngolang 是一门语言级别支持并发的程序语言。golang 中使用 go 语句来开启一个新的协程。\ngoroutine 是非常轻量的，除了给它分配栈空间，它所占用的内存空间是微乎其微的。\n\n但当多个 goroutine 同时进行处理的时候，就会遇到比如同时抢占一个资源，某个 goroutine 等待另一个 goroutine 处理完某一个步骤之后才能继续的需求。\n在 golang 的官方文档上，作者明确指出，golang 并不希望依靠共享内存的方式进行进程的协同操作。而是希望通过管道 channel 的方式进行。\n当然，golang 也提供了共享内存，锁，等机制进行协同操作的包。sync 包就是为了这个目的而出现的。\n\n## 锁 ##\n\nsync 包中定义了 Locker 结构来代表锁。\n\n```golang\ntype Locker interface {\n Lock()\n Unlock()\n}\n```\n并且创造了两个结构来实现 Locker 接口：Mutex 和 RWMutex。\n\nMutex 就是互斥锁，互斥锁代表着当数据被加锁了之后，除了加锁的程序，其他程序不能对数据进行读操作和写操作。\n这个当然能解决并发程序对资源的操作。但是，效率上是个问题。当加锁后，其他程序要读取操作数据，就只能进行等待了。\n这个时候就需要使用读写锁。\n\n读写锁分为读锁和写锁，读数据的时候上读锁，写数据的时候上写锁。有写锁的时候，数据不可读不可写。有读锁的时候，数据可读，不可写。\n互斥锁就不举例子，读写锁可以看下面的例子：\n\n```golang\npackage main\n\nimport (\n \"sync\"\n \"time\"\n)\n\nvar m *sync.RWMutex\nvar val = 0\n\nfunc main() {\n m = new(sync.RWMutex)\n go read(1)\n go write(2)\n go read(3)\n time.Sleep(5 * time.Second)\n}\n\nfunc read(i int) {\n m.RLock()\n time.Sleep(1 * time.Second)\n println(\"val: \", val)\n time.Sleep(1 * time.Second)\n m.RUnlock()\n}\n\nfunc write(i int) {\n\tm.Lock()\n val = 10\n\ttime.Sleep(1 * time.Second)\n\tm.Unlock()\n}\n\n返回：\nval: 0\nval: 10\n\n```\n但是如果我们把 read 中的 RLock 和 RUnlock 两个函数给注释了，就返回了 :\n```golang\nval: 10\nval: 10\n```\n这个就是由于读的时候没有加读锁，在准备读取 val 的时候，val 被 write 函数进行修改了。\n\n## 临时对象池 ##\n\n当多个 goroutine 都需要创建同一个对象的时候，如果 goroutine 过多，可能导致对象的创建数目剧增。\n而对象又是占用内存的，进而导致的就是内存回收的 GC 压力徒增。造成“并发大－占用内存大－ GC 缓慢－处理并发能力降低－并发更大”这样的恶性循环。\n在这个时候，我们非常迫切需要有一个对象池，每个 goroutine 不再自己单独创建对象，而是从对象池中获取出一个对象（如果池中已经有的话）。\n这就是 sync.Pool 出现的目的了。\n\nsync.Pool 的使用非常简单，提供两个方法 :Get 和 Put 和一个初始化回调函数 New。\n\n看下面这个例子（取自[gomemcache](https://github.com/bradfitz/gomemcache/blob/master/memcache/selector.go)）：\n```golang\n// keyBufPool returns []byte buffers for use by PickServer's call to\n// crc32.ChecksumIEEE to avoid allocations. (but doesn't avoid the\n// copies, which at least are bounded in size and small)\nvar keyBufPool = sync.Pool{\n\tNew: func() interface{} {\n\t\tb := make([]byte, 256)\n\t\treturn &b\n\t},\n}\n\nfunc (ss *ServerList) PickServer(key string) (net.Addr, error) {\n\tss.mu.RLock()\n\tdefer ss.mu.RUnlock()\n\tif len(ss.addrs) == 0 {\n\t\treturn nil, ErrNoServers\n\t}\n\tif len(ss.addrs) == 1 {\n\t\treturn ss.addrs[0], nil\n\t}\n\tbufp := keyBufPool.Get().(*[]byte)\n\tn := copy(*bufp, key)\n\tcs := crc32.ChecksumIEEE((*bufp)[:n])\n\tkeyBufPool.Put(bufp)\n\n\treturn ss.addrs[cs%uint32(len(ss.addrs))], nil\n}\n```\n\n这是实际项目中的一个例子，这里使用 keyBufPool 的目的是为了让 crc32.ChecksumIEEE 所使用的[]bytes 数组可以重复使用，减少 GC 的压力。\n\n但是这里可能会有一个问题，我们没有看到 Pool 的手动回收函数。\n那么是不是就意味着，如果我们的并发量不断增加，这个 Pool 的体积会不断变大，或者一直维持在很大的范围内呢？\n\n答案是不会的，sync.Pool 的回收是有的，它是在系统自动 GC 的时候，触发 pool.go 中的 poolCleanup 函数。\n\n```golang\nfunc poolCleanup() {\n\tfor i, p := range allPools {\n\t\tallPools[i] = nil\n\t\tfor i := 0; i < int(p.localSize); i++ {\n\t\t\tl := indexLocal(p.local, i)\n\t\t\tl.private = nil\n\t\t\tfor j := range l.shared {\n\t\t\t\tl.shared[j] = nil\n\t\t\t}\n\t\t\tl.shared = nil\n\t\t}\n\t\tp.local = nil\n\t\tp.localSize = 0\n\t}\n\tallPools = []*Pool{}\n}\n```\n\n这个函数会把 Pool 中所有 goroutine 创建的对象都进行销毁。\n\n那这里另外一个问题也凸显出来了，很可能我上一步刚往 pool 中 PUT 一个对象之后，下一步 GC 触发，导致 pool 的 GET 函数获取不到 PUT 进去的对象。\n这个时候，GET 函数就会调用 New 函数，临时创建出一个对象，并存放到 pool 中。\n\n根据以上结论，sync.Pool 其实不适合用来做持久保存的对象池（比如连接池）。它更适合用来做临时对象池，目的是为了降低 GC 的压力。\n\n连接池性能测试\n\n```golang\npackage main\n\nimport (\n \"sync\"\n \"testing\"\n)\n\nvar bytePool = sync.Pool{\n New: newPool,\n}\n\nfunc newPool() interface{} {\n b := make([]byte, 1024)\n return &b\n}\nfunc BenchmarkAlloc(b *testing.B) {\n for i := 0; i < b.N; i++ {\n obj := make([]byte, 1024)\n _ = obj\n }\n}\n\nfunc BenchmarkPool(b *testing.B) {\n for i := 0; i < b.N; i++ {\n obj := bytePool.Get().(*[]byte)\n _ = obj\n bytePool.Put(obj)\n }\n}\n```\n\n文件目录下执行 `go test -bench . `\n\n```\nE:\\MyGo\\sync>go test -bench .\ntesting: warning: no tests to run\nPASS\nBenchmarkAlloc-4 50000000 39.3 ns/op\nBenchmarkPool-4 50000000 25.4 ns/op\nok _/E_/MyGo/sync 3.345s\n```\n\n通过性能测试可以清楚地看到，使用连接池消耗的 CPU 时间远远小于每次手动分配内存。\n\n## Once ##\n\n有的时候，我们多个 goroutine 都要过一个操作，但是这个操作我只希望被执行一次，这个时候 Once 就上场了。比如下面的例子 :\n\n```golang\npackage main\n\nimport (\n \"fmt\"\n \"sync\"\n \"time\"\n)\n\nfunc main() {\n var once sync.Once\n onceBody := func() {\n fmt.Println(\"Only once\")\n }\n for i := 0; i < 10; i++ {\n go func() {\n once.Do(onceBody)\n }()\n }\n time.Sleep(3e9)\n}\n\n```\n只会打出一次 \"Only once\"。\n\n## WaitGroup 和 Cond ##\n\n一个 goroutine 需要等待一批 goroutine 执行完毕以后才继续执行，那么这种多线程等待的问题就可以使用 WaitGroup 了。\n\n```golang\npackage main\n\nimport (\n \"fmt\"\n \"sync\"\n)\n\nfunc main() {\n wp := new(sync.WaitGroup)\n wp.Add(10);\n\n for i := 0; i < 10; i++ {\n go func() {\n fmt.Println(\"done \", i)\n wp.Done()\n }()\n }\n\n wp.Wait()\n fmt.Println(\"wait end\")\n}\n```\n\n还有个 sync.Cond 是用来控制某个条件下，goroutine 进入等待时期，等待信号到来，然后重新启动。比如：\n\n```golang\npackage main\n\nimport (\n \"fmt\"\n \"sync\"\n \"time\"\n)\n\nfunc main() {\n locker := new(sync.Mutex)\n cond := sync.NewCond(locker)\n done := false\n\n cond.L.Lock()\n\n go func() {\n time.Sleep(2e9)\n done = true\n cond.Signal()\n }()\n\n if (!done) {\n cond.Wait()\n }\n\n fmt.Println(\"now done is \", done);\n}\n```\n这里当主 goroutine 进入 cond.Wait 的时候，就会进入等待，当从 goroutine 发出信号之后，主 goroutine 才会继续往下面走。\n\nsync.Cond 还有一个 BroadCast 方法，用来通知唤醒所有等待的 gouroutine。\n```golang\n\npackage main\n\nimport (\n \"fmt\"\n \"sync\"\n \"time\"\n)\n\nvar locker = new(sync.Mutex)\nvar cond = sync.NewCond(locker)\n\nfunc test(x int) {\n\n cond.L.Lock() // 获取锁\n cond.Wait() // 等待通知 暂时阻塞\n fmt.Println(x)\n time.Sleep(time.Second * 1)\n cond.L.Unlock() // 释放锁，不释放的话将只会有一次输出\n}\nfunc main() {\n for i := 0; i < 40; i++ {\n go test(i)\n }\n fmt.Println(\"start all\")\n cond.Broadcast() // 下发广播给所有等待的 goroutine\n time.Sleep(time.Second * 60)\n}\n\n```\n主 gouroutine 开启后，可以创建多个从 gouroutine，从 gouroutine 获取锁后，进入 cond.Wait 状态，当主 gouroutine 执行完任务后，通过 BroadCast 广播信号。\n处于 cond.Wait 状态的所有 gouroutine 收到信号后将全部被唤醒并往下执行。需要注意的是，从 gouroutine 执行完任务后，需要通过 cond.L.Unlock 释放锁， 否则其它被唤醒的 gouroutine 将没法继续执行。\n通过查看 cond.Wait 的源码就明白为什么需要需要释放锁了\n```golang\nfunc (c *Cond) Wait() {\n c.checker.check()\n if raceenabled {\n raceDisable()\n }\n atomic.AddUint32(&c.waiters, 1)\n if raceenabled {\n raceEnable()\n }\n c.L.Unlock()\n runtime_Syncsemacquire(&c.sema)\n c.L.Lock()\n}\n```\nCond.Wait 会自动释放锁等待信号的到来，当信号到来后，第一个获取到信号的 Wait 将继续往下执行并从新上锁，如果不释放锁， 其它收到信号的 gouroutine 将阻塞无法继续执行。\n由于各个 Wait 收到信号的时间是不确定的，因此每次的输出顺序也都是随机的。\n# 导航 #\n\n- [目录](/preface.md)\n- 上一节：buildin\n- 下一节：暂未确定\n" }, { "path": "chapter16/16.02.md", "content": "# sync/atomic - 原子操作 #\n\n对于并发操作而言，原子操作是个非常现实的问题。典型的就是 i++ 的问题。\n当两个 CPU 同时对内存中的 i 进行读取，然后把加一之后的值放入内存中，可能两次 i++ 的结果，这个 i 只增加了一次。\n如何保证多 CPU 对同一块内存的操作是原子的。\ngolang 中 sync/atomic 就是做这个使用的。\n\n具体的原子操作在不同的操作系统中实现是不同的。比如在 Intel 的 CPU 架构机器上，主要是使用总线锁的方式实现的。\n大致的意思就是当一个 CPU 需要操作一个内存块的时候，向总线发送一个 LOCK 信号，所有 CPU 收到这个信号后就不对这个内存块进行操作了。\n等待操作的 CPU 执行完操作后，发送 UNLOCK 信号，才结束。\n在 AMD 的 CPU 架构机器上就是使用 MESI 一致性协议的方式来保证原子操作。\n所以我们在看 atomic 源码的时候，我们看到它针对不同的操作系统有不同汇编语言文件。\n\n如果我们善用原子操作，它会比锁更为高效。\n\n## CAS ##\n\n原子操作中最经典的 CAS(compare-and-swap) 在 atomic 包中是 Compare 开头的函数。\n\n- func CompareAndSwapInt32(addr \\*int32, old, new int32) (swapped bool)\n- func CompareAndSwapInt64(addr \\*int64, old, new int64) (swapped bool)\n- func CompareAndSwapPointer(addr \\*unsafe.Pointer, old, new unsafe.Pointer) (swapped bool)\n- func CompareAndSwapUint32(addr \\*uint32, old, new uint32) (swapped bool)\n- func CompareAndSwapUint64(addr \\*uint64, old, new uint64) (swapped bool)\n- func CompareAndSwapUintptr(addr \\*uintptr, old, new uintptr) (swapped bool)\n\nCAS 的意思是判断内存中的某个值是否等于 old 值，如果是的话，则赋 new 值给这块内存。CAS 是一个方法，并不局限在 CPU 原子操作中。\nCAS 比互斥锁乐观，但是也就代表 CAS 是有赋值不成功的时候，调用 CAS 的那一方就需要处理赋值不成功的后续行为了。\n\n这一系列的函数需要比较后再进行交换，也有不需要进行比较就进行交换的原子操作。\n\n- func SwapInt32(addr \\*int32, new int32) (old int32)\n- func SwapInt64(addr \\*int64, new int64) (old int64)\n- func SwapPointer(addr \\*unsafe.Pointer, new unsafe.Pointer) (old unsafe.Pointer)\n- func SwapUint32(addr \\*uint32, new uint32) (old uint32)\n- func SwapUint64(addr \\*uint64, new uint64) (old uint64)\n- func SwapUintptr(addr \\*uintptr, new uintptr) (old uintptr)\n\n## 增加或减少 ##\n\n对一个数值进行增加或者减少的行为也需要保证是原子的，它对应于 atomic 包的函数就是\n\n- func AddInt32(addr \\*int32, delta int32) (new int32)\n- func AddInt64(addr \\*int64, delta int64) (new int64)\n- func AddUint32(addr \\*uint32, delta uint32) (new uint32)\n- func AddUint64(addr \\*uint64, delta uint64) (new uint64)\n- func AddUintptr(addr \\*uintptr, delta uintptr) (new uintptr)\n\n## 读取或写入 ##\n\n当我们要读取一个变量的时候，很有可能这个变量正在被写入，这个时候，我们就很有可能读取到写到一半的数据。\n所以读取操作是需要一个原子行为的。在 atomic 包中就是 Load 开头的函数群。\n\n- func LoadInt32(addr \\*int32) (val int32)\n- func LoadInt64(addr \\*int64) (val int64)\n- func LoadPointer(addr \\*unsafe.Pointer) (val unsafe.Pointer)\n- func LoadUint32(addr \\*uint32) (val uint32)\n- func LoadUint64(addr \\*uint64) (val uint64)\n- func LoadUintptr(addr \\*uintptr) (val uintptr)\n\n好了，读取我们是完成了原子性，那写入呢？也是同样的，如果有多个 CPU 往内存中一个数据块写入数据的时候，可能导致这个写入的数据不完整。\n在 atomic 包对应的是 Store 开头的函数群。\n\n- func StoreInt32(addr \\*int32, val int32)\n- func StoreInt64(addr \\*int64, val int64)\n- func StorePointer(addr \\*unsafe.Pointer, val unsafe.Pointer)\n- func StoreUint32(addr \\*uint32, val uint32)\n- func StoreUint64(addr \\*uint64, val uint64)\n- func StoreUintptr(addr \\*uintptr, val uintptr)\n\n# 导航 #\n\n- [目录](/preface.md)\n- 上一节：[sync - 处理同步需求](chapter16/16.01.md)\n- 下一节：[os/signal - 信号](chapter16/16.03.md)\n" }, { "path": "chapter16/16.03.md", "content": "# os/signal - 信号 #\n\n## 基本概念\n\n信号是事件发生时对进程的通知机制。有时也称之为软件中断。信号与硬件中断的相似之处在于打断了程序执行的正常流程，大多数情况下，无法预测信号到达的精确时间。\n\n因为一个具有合适权限的进程可以向另一个进程发送信号，这可以称为进程间的一种同步技术。当然，进程也可以向自身发送信号。然而，发往进程的诸多信号，通常都是源于内核。引发内核为进程产生信号的各类事件如下。\n\n* 硬件发生异常，即硬件检测到一个错误条件并通知内核，随即再由内核发送相应信号给相关进程。比如执行一条异常的机器语言指令（除 0，引用无法访问的内存区域）。\n* 用户键入了能够产生信号的终端特殊字符。如中断字符（通常是 Control-C）、暂停字符（通常是 Control-Z）。\n* 发生了软件事件。如调整了终端窗口大小，定时器到期等。\n\n针对每个信号，都定义了一个唯一的（小）整数，从 1 开始顺序展开。系统会用相应常量表示。Linux 中，1-31 为标准信号；32-64 为实时信号（通过 `kill -l` 可以查看）。\n\n信号达到后，进程视具体信号执行如下默认操作之一。\n\n* 忽略信号，也就是内核将信号丢弃，信号对进程不产生任何影响。\n* 终止（杀死）进程。\n* 产生 coredump 文件，同时进程终止。\n* 暂停（Stop）进程的执行。\n* 恢复进程执行。\n\n当然，对于有些信号，程序是可以改变默认行为的，这也就是 `os/signal` 包的用途。\n\n兼容性问题：信号的概念来自于 Unix-like 系统。Windows 下只支持 os.SIGINT 信号。\n\n## Go 对信号的处理\n\n程序无法捕获信号 SIGKILL 和 SIGSTOP （终止和暂停进程），因此 `os/signal` 包对这两个信号无效。\n\n### Go 程序对信号的默认行为\n\nGo 语言实现了自己的运行时，因此，对信号的默认处理方式和普通的 C 程序不太一样。\n\n* SIGBUS（总线错误）, SIGFPE（算术错误）和 SIGSEGV（段错误）称为同步信号，它们在程序执行错误时触发，而不是通过 `os.Process.Kill` 之类的触发。通常，Go 程序会将这类信号转为 run-time panic。\n* SIGHUP（挂起）, SIGINT（中断）或 SIGTERM（终止）默认会使得程序退出。\n* SIGQUIT, SIGILL, SIGTRAP, SIGABRT, SIGSTKFLT, SIGEMT 或 SIGSYS 默认会使得程序退出，同时生成 stack dump。\n* SIGTSTP, SIGTTIN 或 SIGTTOU，这是 shell 使用的，作业控制的信号，执行系统默认的行为。\n* SIGPROF（性能分析定时器，记录 CPU 时间，包括用户态和内核态）， Go 运行时使用该信号实现 `runtime.CPUProfile`。\n* 其他信号，Go 捕获了，但没有做任何处理。\n\n信号可以被忽略或通过掩码阻塞（屏蔽字 mask）。忽略信号通过 signal.Ignore，没有导出 API 可以直接修改阻塞掩码，虽然 Go 内部有实现 sigprocmask 等。Go 中的信号被 runtime 控制，在使用时和 C 是不太一样的。\n\n### 改变信号的默认行为\n\n这就是 `os/signal` 包的功能。\n\n`Notify` 改变信号处理，可以改变信号的默认行为；`Ignore` 可以忽略信号；`Reset` 重置信号为默认行为；`Stop` 则停止接收信号，但并没有重置为默认行为。\n\n### SIGPIPE\n\n文档中对这个信号单独进行了说明。如果 Go 程序往一个 broken pipe 写数据，内核会产生一个 SIGPIPE 信号。\n\n如果 Go 程序没有为 SIGPIPE 信号调用 Notify，对于标准输出或标准错误（文件描述符 1 或 2），该信号会使得程序退出；但其他文件描述符对该信号是啥也不做，当然 write 会返回错误 EPIPE。\n\n如果 Go 程序为 SIGPIPE 调用了 Notify，不论什么文件描述符，SIGPIPE 信号都会传递给 Notify channel，当然 write 依然会返回 EPIPE。\n\n也就是说，默认情况下，Go 的命令行程序跟传统的 Unix 命令行程序行为一致；但当往一个关闭的网络连接写数据时，传统 Unix 程序会 crash，但 Go 程序不会。\n\n### cgo 注意事项\n\n如果非 Go 代码使用信号相关功能，需要仔细阅读掌握 `os/signal` 包中相关文档：Go programs that use cgo or SWIG 和 Non-Go programs that call Go code\n\n## signal 中 API 详解\n\n### Ignore 函数\n\n`func Ignore(sig ...os.Signal)`\n\n忽略一个、多个或全部（不提供任何信号）信号。如果程序接收到了被忽略的信号，则什么也不做。对一个信号，如果先调用 `Notify`，再调用 `Ignore`，`Notify` 的效果会被取消；如果先调用 `Ignore`，在调用 `Notify`，接着调用 `Reset/Stop` 的话，会回到 Ingore 的效果。注意，如果 Notify 作用于多个 chan，则 Stop 需要对每个 chan 都调用才能起到该作用。\n\n### Notify 函数\n\n`func Notify(c chan<- os.Signal, sig ...os.Signal)`\n\n类似于绑定信号处理程序。将输入信号转发到 chan c。如果没有列出要传递的信号，会将所有输入信号传递到 c；否则只传递列出的输入信号。\n\nchannel c 缓存如何决定？因为 `signal` 包不会为了向 c 发送信息而阻塞（就是说如果发送时 c 阻塞了，signal 包会直接放弃）：调用者应该保证 c 有足够的缓存空间可以跟上期望的信号频率。对使用单一信号用于通知的 channel，缓存为 1 就足够了。\n\n相关源码：\n\n\t// src/os/signal/signal.go process 函数\n\tfor c, h := range handlers.m {\n\t\tif h.want(n) {\n\t\t\t// send but do not block for it\n\t\t\tselect {\n\t\t\tcase c <- sig:\n\t\t\tdefault:\t// 保证不会阻塞，直接丢弃\n\t\t\t}\n\t\t}\n\t}\n\n可以使用同一 channel 多次调用 `Notify`：每一次都会扩展该 channel 接收的信号集。唯一从信号集去除信号的方法是调用 `Stop`。可以使用同一信号和不同 channel 多次调用 `Notify`：每一个 channel 都会独立接收到该信号的一个拷贝。\n\n### Stop 函数\n\n`func Stop(c chan<- os.Signal)`\n\n让 signal 包停止向 c 转发信号。它会取消之前使用 c 调用的所有 `Notify` 的效果。当 `Stop` 返回后，会保证 c 不再接收到任何信号。\n\n### Reset 函数\n\n`func Reset(sig ...os.Signal)`\n\n取消之前使用 `Notify` 对信号产生的效果；如果没有参数，则所有信号处理都被重置。\n\n### 使用示例\n\n注：syscall 包中定义了所有的信号常量\n\n\tpackage main\n\t\n\timport (\n\t\t\"fmt\"\n\t\t\"os\"\n\t\t\"os/signal\"\n\t\t\"syscall\"\n\t)\n\t\n\tvar firstSigusr1 = true\n\t\n\tfunc main() {\n\t\t// 忽略 Control-C (SIGINT)\n\t\t// os.Interrupt 和 syscall.SIGINT 是同义词\n\t\tsignal.Ignore(os.Interrupt)\n\t\n\t\tc1 := make(chan os.Signal, 2)\n\t\t// Notify SIGHUP\n\t\tsignal.Notify(c1, syscall.SIGHUP)\n\t\t// Notify SIGUSR1\n\t\tsignal.Notify(c1, syscall.SIGUSR1)\n\t\tgo func() {\n\t\t\tfor {\n\t\t\t\tswitch <-c1 {\n\t\t\t\tcase syscall.SIGHUP:\n\t\t\t\t\tfmt.Println(\"sighup, reset sighup\")\n\t\t\t\t\tsignal.Reset(syscall.SIGHUP)\n\t\t\t\tcase syscall.SIGUSR1:\n\t\t\t\t\tif firstSigusr1 {\n\t\t\t\t\t\tfmt.Println(\"first usr1, notify interrupt which had ignore!\")\n\t\t\t\t\t\tc2 := make(chan os.Signal, 1)\n\t\t\t\t\t\t// Notify Interrupt\n\t\t\t\t\t\tsignal.Notify(c2, os.Interrupt)\n\t\t\t\t\t\tgo handlerInterrupt(c2)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}()\n\t\n\t\tselect {}\n\t}\n\t\n\tfunc handlerInterrupt(c <-chan os.Signal) {\n\t\tfor {\n\t\t\tswitch <-c {\n\t\t\tcase os.Interrupt:\n\t\t\t\tfmt.Println(\"signal interrupt\")\n\t\t\t}\n\t\t}\n\t}\n\n编译后运行，先后给该进程发送如下信号：SIGINT、SIGUSR1、SIGINT、SIGHUP、SIGHUP，看输出是不是和你预期的一样。\n\n### 关于信号的额外说明\n\n1. 查看 Go 中 Linux/amd64 信号的实现，发现大量使用的是 rt 相关系统调用，这是支持实时信号处理的 API。\n2. C 语言中信号处理涉及到可重入函数和异步信号安全函数问题；Go 中不存在此问题。\n3. Unix 和信号处理相关的很多系统调用，Go 都隐藏起来了，Go 中对信号的处理，`signal` 包中的函数基本就能搞定。\n\n# 导航 #\n\n- [目录](/preface.md)\n- 上一节：[sync/atomic - 原子操作](chapter16/16.02.md)\n- 下一节：暂未确定\n" }, { "path": "code/chapter08/result/chapter08/tar.go", "content": "package main\n\nimport (\n\t\"archive/tar\"\n\t\"log\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\nfunc main() {\n\tf, err := os.Create(\"result/polarisxu.tar\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer f.Close()\n\n\ttw := tar.NewWriter(f)\n\tdefer tw.Close()\n\n\troot, err := filepath.Abs(\"..\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\terr = ScanDir(tw, root, root)\n\tif err != nil {\n\t\tos.Remove(\"result/polarisxu.tar\")\n\t\tlog.Fatal(err)\n\t}\n}\n\nfunc ScanDir(tw *tar.Writer, root, dirName string) error {\n\tdirEntries, err := os.ReadDir(dirName)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tfor _, dirEntry := range dirEntries {\n\t\tnewPath := dirName + \"/\" + dirEntry.Name()\n\t\tif dirEntry.IsDir() {\n\t\t\tif err = ScanDir(tw, root, newPath); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t} else {\n\t\t\thdr := &tar.Header{\n\t\t\t\tName: dirName[len(root):] + \"/\" + dirEntry.Name(),\n\t\t\t\t// Mode: int64(dirEntry.Type().Perm()),\n\t\t\t}\n\t\t\tfileInfo, err := dirEntry.Info()\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\thdr.Mode = int64(fileInfo.Mode().Perm())\n\t\t\tbody, err := os.ReadFile(newPath)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\thdr.Size = int64(len(body))\n\t\t\tif err = tw.WriteHeader(hdr); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\n\t\t\tif _, err = tw.Write(body); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t}\n\t}\n\n\treturn nil\n}\n" }, { "path": "code/chapter08/result/install.bat", "content": "@echo off\n\nsetlocal\n\nif exist install.bat goto ok\necho install.bat must be run from its folder\ngoto end\n\n:ok\n\nset OLDGOPATH=%GOPATH%\nset GOPATH=%~dp0;%~dp0..\\thirdparty\n\ngofmt -w src\n\ngo install chapter01/io\n\nset GOPATH=%OLDGOPATH%\n\n:end\necho finished" }, { "path": "code/chapter08/result/install.sh", "content": "#!/usr/bin/env bash\n\nset -e\n\nif [ ! -f install.sh ]; then\n\techo 'install must be run within its container folder' 1>&2\n\texit 1\nfi\n\nCURDIR=`pwd`\nOLDGOPATH=\"$GOPATH\"\nexport GOPATH=\"$CURDIR\"\n\ngofmt -w src\n\ngo install ./...\n\nexport GOPATH=\"$OLDGOPATH\"\nexport PATH=\"$OLDPATH\"\n\necho 'finished'\n\n" }, { "path": "code/chapter08/result/src/chapter01/io/01.txt", "content": "from file" }, { "path": "code/chapter08/result/src/chapter01/io/byterwer.go", "content": "package main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"os\"\n)\n\nfunc ByteRWerExample() {\nFOREND:\n\tfor {\n\t\tfmt.Println(\"请输入要通过WriteByte写入的一个ASCII字符（b：返回上级；q：退出）：\")\n\t\tvar ch byte\n\t\tfmt.Scanf(\"%c\\n\", &ch)\n\t\tswitch ch {\n\t\tcase 'b':\n\t\t\tfmt.Println(\"返回上级菜单！\")\n\t\t\tbreak FOREND\n\t\tcase 'q':\n\t\t\tfmt.Println(\"程序退出！\")\n\t\t\tos.Exit(0)\n\t\tdefault:\n\t\t\tbuffer := new(bytes.Buffer)\n\t\t\terr := buffer.WriteByte(ch)\n\t\t\tif err == nil {\n\t\t\t\tfmt.Println(\"写入一个字节成功！准备读取该字节……\")\n\t\t\t\tnewCh, _ := buffer.ReadByte()\n\t\t\t\tfmt.Printf(\"读取的字节：%c\\n\", newCh)\n\t\t\t} else {\n\t\t\t\tfmt.Println(\"写入错误\")\n\t\t\t}\n\t\t}\n\n\t}\n}\n" }, { "path": "code/chapter08/result/src/chapter01/io/main.go", "content": "package main\n\nimport (\n\t\"fmt\"\n\t\"util\"\n)\n\nfunc main() {\n\tutil.Welcome()\n\tMainMenu()\n}\n\nfunc MainMenu() {\nMAINFOR:\n\tfor {\n\t\tfmt.Println(\"\")\n\t\tfmt.Println(\"*******请选择示例：*********\")\n\t\tfmt.Println(\"1 表示 io.Reader 示例\")\n\t\tfmt.Println(\"2 表示 io.ByteReader/ByteWriter 示例\")\n\t\tfmt.Println(\"q 退出\")\n\t\tfmt.Println(\"***********************************\")\n\n\t\tvar ch string\n\t\tfmt.Scanln(&ch)\n\n\t\tswitch ch {\n\t\tcase \"1\":\n\t\t\tReaderExample()\n\t\tcase \"2\":\n\t\t\tByteRWerExample()\n\t\tcase \"q\":\n\t\t\tfmt.Println(\"程序退出！\")\n\t\t\tbreak MAINFOR\n\t\tdefault:\n\t\t\tfmt.Println(\"输入错误！\")\n\t\t\tcontinue\n\t\t}\n\t}\n}\n" }, { "path": "code/chapter08/result/src/chapter01/io/reader.go", "content": "// io.Reader 接口示例\npackage main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"os\"\n\t\"strings\"\n\t\"util\"\n)\n\nfunc ReaderExample() {\nFOREND:\n\tfor {\n\t\treaderMenu()\n\n\t\tvar ch string\n\t\tfmt.Scanln(&ch)\n\t\tvar (\n\t\t\tdata []byte\n\t\t\terr error\n\t\t)\n\t\tswitch strings.ToLower(ch) {\n\t\tcase \"1\":\n\t\t\tfmt.Println(\"请输入不多于9个字符，以回车结束：\")\n\t\t\tdata, err = ReadFrom(os.Stdin, 11)\n\t\tcase \"2\":\n\t\t\tfile, err := os.Open(util.GetProjectRoot() + \"/src/chapter01/io/01.txt\")\n\t\t\tif err != nil {\n\t\t\t\tfmt.Println(\"打开文件 01.txt 错误:\", err)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tdata, err = ReadFrom(file, 9)\n\t\t\tfile.Close()\n\t\tcase \"3\":\n\t\t\tdata, err = ReadFrom(strings.NewReader(\"from string\"), 12)\n\t\tcase \"4\":\n\t\t\tfmt.Println(\"暂未实现！\")\n\t\tcase \"b\":\n\t\t\tfmt.Println(\"返回上级菜单！\")\n\t\t\tbreak FOREND\n\t\tcase \"q\":\n\t\t\tfmt.Println(\"程序退出！\")\n\t\t\tos.Exit(0)\n\t\tdefault:\n\t\t\tfmt.Println(\"输入错误！\")\n\t\t\tcontinue\n\t\t}\n\n\t\tif err != nil {\n\t\t\tfmt.Println(\"数据读取失败，可以试试从其他输入源读取！\")\n\t\t} else {\n\t\t\tfmt.Printf(\"读取到的数据是：%s\\n\", data)\n\t\t}\n\t}\n}\n\nfunc ReadFrom(reader io.Reader, num int) ([]byte, error) {\n\tp := make([]byte, num)\n\tn, err := reader.Read(p)\n\tif n > 0 {\n\t\treturn p[:n], nil\n\t}\n\treturn p, err\n}\n\nfunc readerMenu() {\n\tfmt.Println(\"\")\n\tfmt.Println(\"*******从不同来源读取数据*********\")\n\tfmt.Println(\"*******请选择数据源，请输入：*********\")\n\tfmt.Println(\"1 表示 标准输入\")\n\tfmt.Println(\"2 表示 普通文件\")\n\tfmt.Println(\"3 表示 从字符串\")\n\tfmt.Println(\"4 表示 从网络\")\n\tfmt.Println(\"b 返回上级菜单\")\n\tfmt.Println(\"q 退出\")\n\tfmt.Println(\"***********************************\")\n}\n" }, { "path": "code/chapter08/result/src/chapter06/filepath/walk/main.go", "content": "package main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\nfunc main() {\n\tfilepath.Walk(\"../../..\", func(path string, info os.FileInfo, err error) error {\n\t\tif info.IsDir() {\n\t\t\treturn nil\n\t\t}\n\n\t\tfmt.Println(\"file:\", info.Name(), \"in directory:\", path)\n\n\t\treturn nil\n\t})\n}\n" }, { "path": "code/chapter08/result/src/chapter06/os/dirtree/main.go", "content": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\nfunc main() {\n\tReadAndOutputDir(\"../../..\", 3)\n}\n\nfunc ReadAndOutputDir(rootPath string, deep int) {\n\tfile, err := os.Open(rootPath)\n\tif err != nil {\n\t\tfmt.Println(\"error:\", err)\n\t\treturn\n\t}\n\tdefer file.Close()\n\n\tfor {\n\t\tfileInfos, err := file.Readdir(100)\n\t\tif err != nil {\n\t\t\tif err == io.EOF {\n\t\t\t\tbreak\n\t\t\t}\n\t\t\tfmt.Println(\"readdir error:\", err)\n\t\t\treturn\n\t\t}\n\n\t\tif len(fileInfos) == 0 {\n\t\t\tbreak\n\t\t}\n\n\t\tfor _, fileInfo := range fileInfos {\n\t\t\tif fileInfo.IsDir() {\n\t\t\t\tif deep > 0 {\n\t\t\t\t\tReadAndOutputDir(filepath.Join(rootPath, string(os.PathSeparator), fileInfo.Name()), deep-1)\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tfmt.Println(\"file:\", fileInfo.Name(), \"in directory:\", rootPath)\n\t\t\t}\n\t\t}\n\t}\n}\n" }, { "path": "code/chapter08/result/src/chapter09/benchmark_result.go", "content": "package main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"testing\"\n\t\"text/template\"\n)\n\nfunc main() {\n\tbenchmarkResult := testing.Benchmark(func(b *testing.B) {\n\t\ttempl := template.Must(template.New(\"test\").Parse(\"Hello, {{.}}!\"))\n\t\t// RunParallel will create GOMAXPROCS goroutines\n\t\t// and distribute work among them.\n\t\tb.RunParallel(func(pb *testing.PB) {\n\t\t\t// Each goroutine has its own bytes.Buffer.\n\t\t\tvar buf bytes.Buffer\n\t\t\tfor pb.Next() {\n\t\t\t\t// The loop body is executed b.N times total across all goroutines.\n\t\t\t\tbuf.Reset()\n\t\t\t\ttempl.Execute(&buf, \"World\")\n\t\t\t}\n\t\t})\n\t})\n\n\t// fmt.Printf(\"%8d\\t%10d ns/op\\t%10d B/op\\t%10d allocs/op\\n\", benchmarkResult.N, benchmarkResult.NsPerOp(), benchmarkResult.AllocedBytesPerOp(), benchmarkResult.AllocsPerOp())\n\tfmt.Printf(\"%s\\t%s\\n\", benchmarkResult.String(), benchmarkResult.MemString())\n}\n" }, { "path": "code/chapter08/result/src/chapter09/httptest/data.go", "content": "package main\n\nimport (\n\t\"errors\"\n\t\"time\"\n)\n\n// 保存 Topic，没有考虑并发问题\nvar TopicCache = make([]*Topic, 0, 16)\n\ntype Topic struct {\n\tId int `json:\"id\"`\n\tTitle string `json:\"title\"`\n\tContent string `json:\"content\"`\n\tCreatedAt time.Time `json:\"created_at\"`\n}\n\nfunc FindTopic(id int) (*Topic, error) {\n\tif err := checkIndex(id); err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn TopicCache[id-1], nil\n}\n\nfunc (t *Topic) Create() error {\n\tt.Id = len(TopicCache) + 1\n\tt.CreatedAt = time.Now()\n\tTopicCache = append(TopicCache, t)\n\treturn nil\n}\n\nfunc (t *Topic) Update() error {\n\tif err := checkIndex(t.Id); err != nil {\n\t\treturn err\n\t}\n\tTopicCache[t.Id-1] = t\n\treturn nil\n}\n\n// 简单的将对应的 slice 位置置为 nil\nfunc (t *Topic) Delete() error {\n\tif err := checkIndex(t.Id); err != nil {\n\t\treturn err\n\t}\n\tTopicCache[t.Id-1] = nil\n\treturn nil\n}\n\nfunc checkIndex(id int) error {\n\tif id > 0 && len(TopicCache) <= id-1 {\n\t\treturn errors.New(\"The topic is not exists!\")\n\t}\n\n\treturn nil\n}\n" }, { "path": "code/chapter08/result/src/chapter09/httptest/server.go", "content": "package main\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"path\"\n\t\"strconv\"\n)\n\nfunc main() {\n\thttp.HandleFunc(\"/topic/\", handleRequest)\n\n\thttp.ListenAndServe(\":2017\", nil)\n}\n\n// main handler function\nfunc handleRequest(w http.ResponseWriter, r *http.Request) {\n\tvar err error\n\tswitch r.Method {\n\tcase http.MethodGet:\n\t\terr = handleGet(w, r)\n\tcase http.MethodPost:\n\t\terr = handlePost(w, r)\n\tcase http.MethodPut:\n\t\terr = handlePut(w, r)\n\tcase http.MethodDelete:\n\t\terr = handleDelete(w, r)\n\t}\n\tif err != nil {\n\t\thttp.Error(w, err.Error(), http.StatusInternalServerError)\n\t\treturn\n\t}\n}\n\n// 获取一个帖子\n// 如 GET /topic/1\nfunc handleGet(w http.ResponseWriter, r *http.Request) error {\n\tid, err := strconv.Atoi(path.Base(r.URL.Path))\n\tif err != nil {\n\t\treturn err\n\t}\n\ttopic, err := FindTopic(id)\n\tif err != nil {\n\t\treturn err\n\t}\n\toutput, err := json.MarshalIndent(&topic, \"\", \"\\t\\t\")\n\tif err != nil {\n\t\treturn err\n\t}\n\tw.Header().Set(\"Content-Type\", \"application/json\")\n\tw.Write(output)\n\treturn nil\n}\n\n// 增加一个帖子\n// POST /topic/\nfunc handlePost(w http.ResponseWriter, r *http.Request) (err error) {\n\tbody := make([]byte, r.ContentLength)\n\tr.Body.Read(body)\n\tvar topic = new(Topic)\n\terr = json.Unmarshal(body, &topic)\n\tif err != nil {\n\t\treturn\n\t}\n\n\terr = topic.Create()\n\tif err != nil {\n\t\treturn\n\t}\n\tw.WriteHeader(http.StatusOK)\n\treturn\n}\n\n// 更新一个帖子\n// PUT /topic/1\nfunc handlePut(w http.ResponseWriter, r *http.Request) error {\n\tid, err := strconv.Atoi(path.Base(r.URL.Path))\n\tif err != nil {\n\t\treturn err\n\t}\n\ttopic, err := FindTopic(id)\n\tif err != nil {\n\t\treturn err\n\t}\n\tbody := make([]byte, r.ContentLength)\n\tr.Body.Read(body)\n\tjson.Unmarshal(body, topic)\n\terr = topic.Update()\n\tif err != nil {\n\t\treturn err\n\t}\n\tw.WriteHeader(http.StatusOK)\n\treturn nil\n}\n\n// 删除一个帖子\n// DELETE /topic/1\nfunc handleDelete(w http.ResponseWriter, r *http.Request) (err error) {\n\tid, err := strconv.Atoi(path.Base(r.URL.Path))\n\tif err != nil {\n\t\treturn\n\t}\n\ttopic, err := FindTopic(id)\n\tif err != nil {\n\t\treturn\n\t}\n\terr = topic.Delete()\n\tif err != nil {\n\t\treturn\n\t}\n\tw.WriteHeader(http.StatusOK)\n\treturn\n}\n" }, { "path": "code/chapter08/result/src/chapter09/httptest/server_test.go", "content": "package main\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"os\"\n\t\"strings\"\n\t\"testing\"\n)\n\nvar w *httptest.ResponseRecorder\n\nfunc TestMain(m *testing.M) {\n\thttp.DefaultServeMux.HandleFunc(\"/topic/\", handleRequest)\n\n\tw = httptest.NewRecorder()\n\n\tos.Exit(m.Run())\n}\n\nfunc TestHandlePost(t *testing.T) {\n\treader := strings.NewReader(`{\"title\":\"The Go Standard Library\",\"content\":\"It contains many packages.\"}`)\n\tr, _ := http.NewRequest(http.MethodPost, \"/topic/\", reader)\n\n\thttp.DefaultServeMux.ServeHTTP(w, r)\n\n\tresult := w.Result()\n\tif result.StatusCode != http.StatusOK {\n\t\tt.Errorf(\"Response code is %v\", result.StatusCode)\n\t}\n}\n\nfunc TestHandleGet(t *testing.T) {\n\tr, _ := http.NewRequest(http.MethodGet, \"/topic/1\", nil)\n\n\thttp.DefaultServeMux.ServeHTTP(w, r)\n\n\tresult := w.Result()\n\tif result.StatusCode != http.StatusOK {\n\t\tt.Errorf(\"Response code is %v\", result.StatusCode)\n\t}\n\n\ttopic := new(Topic)\n\tjson.Unmarshal(w.Body.Bytes(), topic)\n\tif topic.Id != 1 {\n\t\tt.Errorf(\"Cannot get topic\")\n\t}\n}\n" }, { "path": "code/chapter08/result/src/chapter09/testing/example_test.go", "content": "package testing_test\n\nimport (\n\t. \"chapter09/testing\"\n\t\"fmt\"\n)\n\nfunc ExampleFib() {\n\tfmt.Println(Fib(7))\n\t// Output: 13\n}\n" }, { "path": "code/chapter08/result/src/chapter09/testing/parallel.go", "content": "package testing\n\nimport \"sync\"\n\nvar (\n\tdata = make(map[string]string)\n\tlocker sync.RWMutex\n)\n\nfunc WriteToMap(k, v string) {\n\tlocker.Lock()\n\tdefer locker.Unlock()\n\tdata[k] = v\n}\n\nfunc ReadFromMap(k string) string {\n\tlocker.RLock()\n\tdefer locker.RUnlock()\n\treturn data[k]\n}\n" }, { "path": "code/chapter08/result/src/chapter09/testing/parallel_test.go", "content": "package testing_test\n\nimport (\n\t\"bytes\"\n\t. \"chapter09/testing\"\n\t\"html/template\"\n\t\"testing\"\n)\n\nvar pairs = []struct {\n\tk string\n\tv string\n}{\n\t{\"polaris\", \"徐新华\"},\n\t{\"studygolang\", \"Go语言中文网\"},\n\t{\"stdlib\", \"Go语言标准库\"},\n\t{\"polaris1\", \"徐新华1\"},\n\t{\"studygolang1\", \"Go语言中文网1\"},\n\t{\"stdlib1\", \"Go语言标准库1\"},\n\t{\"polaris2\", \"徐新华2\"},\n\t{\"studygolang2\", \"Go语言中文网2\"},\n\t{\"stdlib2\", \"Go语言标准库2\"},\n\t{\"polaris3\", \"徐新华3\"},\n\t{\"studygolang3\", \"Go语言中文网3\"},\n\t{\"stdlib3\", \"Go语言标准库3\"},\n\t{\"polaris4\", \"徐新华4\"},\n\t{\"studygolang4\", \"Go语言中文网4\"},\n\t{\"stdlib4\", \"Go语言标准库4\"},\n}\n\n// 注意 TestWriteToMap 需要在 TestReadFromMap 之前\nfunc TestWriteToMap(t *testing.T) {\n\tt.Parallel()\n\tfor _, tt := range pairs {\n\t\tWriteToMap(tt.k, tt.v)\n\t}\n}\n\nfunc TestReadFromMap(t *testing.T) {\n\tt.Parallel()\n\tfor _, tt := range pairs {\n\t\tactual := ReadFromMap(tt.k)\n\t\tif actual != tt.v {\n\t\t\tt.Errorf(\"the value of key(%s) is %s, expected: %s\", tt.k, actual, tt.v)\n\t\t}\n\t}\n}\n\nfunc BenchmarkTemplateParallel(b *testing.B) {\n\ttempl := template.Must(template.New(\"test\").Parse(\"Hello, {{.}}!\"))\n\tb.RunParallel(func(pb *testing.PB) {\n\t\tvar buf bytes.Buffer\n\t\tfor pb.Next() {\n\t\t\tbuf.Reset()\n\t\t\ttempl.Execute(&buf, \"World\")\n\t\t}\n\t})\n}\n" }, { "path": "code/chapter08/result/src/chapter09/testing/server_test.go", "content": "package testing\n\nimport (\n\t\"fmt\"\n\t\"testing\"\n\t\"time\"\n)\n\nfunc TestTime(t *testing.T) {\n\ttestCases := []struct {\n\t\tgmt string\n\t\tloc string\n\t\twant string\n\t}{\n\t\t{\"12:31\", \"Europe/Zuri\", \"13:31\"},\n\t\t{\"12:31\", \"America/New_York\", \"7:31\"},\n\t\t{\"08:08\", \"Australia/Sydney\", \"18:08\"},\n\t}\n\tfor _, tc := range testCases {\n\t\tt.Run(fmt.Sprintf(\"%s in %s\", tc.gmt, tc.loc), func(t *testing.T) {\n\t\t\tt.Parallel()\n\t\t\tloc, err := time.LoadLocation(tc.loc)\n\t\t\tif err != nil {\n\t\t\t\tt.Fatal(\"could not load location\")\n\t\t\t}\n\t\t\tgmt, _ := time.Parse(\"15:04\", tc.gmt)\n\t\t\tif got := gmt.In(loc).Format(\"15:04\"); got != tc.want {\n\t\t\t\tt.Errorf(\"got %s; want %s\", got, tc.want)\n\t\t\t}\n\t\t})\n\t}\n}\n" }, { "path": "code/chapter08/result/src/chapter09/testing/t.go", "content": "package testing\n\nfunc Fib(n int) int {\n\tif n < 2 {\n\t\treturn n\n\t}\n\treturn Fib(n-1) + Fib(n-2)\n}\n" }, { "path": "code/chapter08/result/src/chapter09/testing/t_test.go", "content": "package testing_test\n\nimport (\n\t\"bytes\"\n\t\"html/template\"\n\t\"testing\"\n\t\"time\"\n\n\t. \"chapter09/testing\"\n)\n\n// Table-Driven Test\nfunc TestFib_TableDrivenParallel(t *testing.T) {\n\tvar fibTests = []struct {\n\t\tname string\n\t\tin int // input\n\t\texpected int // expected result\n\t}{\n\t\t{\"1的Fib\", 1, 1},\n\t\t{\"2的Fib\", 2, 1},\n\t\t{\"3的Fib\", 3, 2},\n\t\t{\"4的Fib\", 4, 3},\n\t\t{\"5的Fib\", 5, 5},\n\t\t{\"6的Fib\", 6, 8},\n\t\t{\"7的Fib\", 7, 13},\n\t}\n\n\tfor _, tt := range fibTests {\n\t\ttt := tt\n\t\tt.Run(tt.name, func(t *testing.T) {\n\t\t\tt.Log(\"time:\", time.Now())\n\t\t\tt.Parallel()\n\t\t\ttime.Sleep(3 * time.Second)\n\t\t\tactual := Fib(tt.in)\n\t\t\tif actual != tt.expected {\n\t\t\t\tt.Errorf(\"Fib(%d) = %d; expected %d\", tt.in, actual, tt.expected)\n\t\t\t}\n\t\t})\n\t}\n\n\tfor _, tt := range fibTests {\n\t\tt.Log(\"time:\", time.Now())\n\t\tactual := Fib(tt.in)\n\t\tif actual != tt.expected {\n\t\t\tt.Errorf(\"Fib(%d) = %d; expected %d\", tt.in, actual, tt.expected)\n\t\t}\n\t}\n\n\tdefer func() {\n\t\tt.Log(\"time:\", time.Now())\n\t}()\n}\n\nfunc TestFib(t *testing.T) {\n\tvar (\n\t\tin = 7 // input\n\t\texpected = 13 // expected result\n\t)\n\tactual := Fib(in)\n\tif actual != expected {\n\t\tt.Errorf(\"Fib(%d) = %d; expected %d\", in, actual, expected)\n\t}\n}\n\n// Table-Driven Test\nfunc TestFib_TableDriven(t *testing.T) {\n\tvar fibTests = []struct {\n\t\tin int // input\n\t\texpected int // expected result\n\t}{\n\t\t{1, 1},\n\t\t{2, 1},\n\t\t{3, 2},\n\t\t{4, 3},\n\t\t{5, 5},\n\t\t{6, 8},\n\t\t{7, 13},\n\t}\n\n\tfor _, tt := range fibTests {\n\t\tactual := Fib(tt.in)\n\t\tif actual != tt.expected {\n\t\t\tt.Errorf(\"Fib(%d) = %d; expected %d\", tt.in, actual, tt.expected)\n\t\t}\n\t}\n}\n\nfunc BenchmarkFib1(b *testing.B) { benchmarkFib(1, b) }\nfunc BenchmarkFib2(b *testing.B) { benchmarkFib(2, b) }\nfunc BenchmarkFib3(b *testing.B) { benchmarkFib(3, b) }\nfunc BenchmarkFib10(b *testing.B) { benchmarkFib(10, b) }\nfunc BenchmarkFib20(b *testing.B) { benchmarkFib(20, b) }\nfunc BenchmarkFib40(b *testing.B) { benchmarkFib(40, b) }\n\nfunc benchmarkFib(i int, b *testing.B) {\n\tfor n := 0; n < b.N; n++ {\n\t\tFib(i)\n\t}\n}\n\nfunc BenchmarkTmplExucte(b *testing.B) {\n\tb.ReportAllocs()\n\n\ttempl := template.Must(template.New(\"test\").Parse(\"Hello, {{.}}!\"))\n\tb.RunParallel(func(pb *testing.PB) {\n\t\t// Each goroutine has its own bytes.Buffer.\n\t\tvar buf bytes.Buffer\n\t\tfor pb.Next() {\n\t\t\t// The loop body is executed b.N times total across all goroutines.\n\t\t\tbuf.Reset()\n\t\t\ttempl.Execute(&buf, \"World\")\n\t\t}\n\t})\n}\n" }, { "path": "code/chapter08/result/src/chapter10/os_exec.go", "content": "package main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\t\"os/exec\"\n)\n\nfunc main() {\n\targNum := len(os.Args)\n\tif argNum < 2 {\n\t\tlog.Printf(\"Usage:%s command\\n\", os.Args[0])\n\t\tos.Exit(1)\n\t}\n\n\targ := []string{}\n\tif argNum > 2 {\n\t\targ = os.Args[2:]\n\t}\n\n\tmainOutput(UsePipe(os.Args[1], arg...))\n}\n\nfunc mainOutput(out []byte, err error) {\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tfmt.Printf(\"The output of command %q is\\n%s\\n\", os.Args[1], out)\n}\n\n// 直接给 Cmd.Stdout 赋值\nfunc FillStd(name string, arg ...string) ([]byte, error) {\n\tcmd := exec.Command(name, arg...)\n\tvar out = new(bytes.Buffer)\n\n\tcmd.Stdout = out\n\tcmd.Stderr = out\n\n\terr := cmd.Run()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn out.Bytes(), nil\n}\n\nfunc UseOutput(name string, arg ...string) ([]byte, error) {\n\treturn exec.Command(name, arg...).Output()\n}\n\n// 使用 Pipe\nfunc UsePipe(name string, arg ...string) ([]byte, error) {\n\tcmd := exec.Command(name, arg...)\n\tstdout, err := cmd.StdoutPipe()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif err = cmd.Start(); err != nil {\n\t\treturn nil, err\n\t}\n\n\tvar out = make([]byte, 0, 1024)\n\tfor {\n\t\ttmp := make([]byte, 128)\n\t\tn, err := stdout.Read(tmp)\n\t\tout = append(out, tmp[:n]...)\n\t\tif err != nil {\n\t\t\tbreak\n\t\t}\n\t}\n\n\tif err = cmd.Wait(); err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn out, nil\n}\n" }, { "path": "code/chapter08/result/src/chapter13/flag/nginx.go", "content": "package main\n\nimport (\n\t\"flag\"\n\t\"fmt\"\n\t\"os\"\n)\n\n// 实际中应该用更好的变量名\nvar (\n\th bool\n\n\tv, V bool\n\tt, T bool\n\tq *bool\n\n\ts string\n\tp string\n\tc string\n\tg string\n)\n\nfunc init() {\n\tflag.BoolVar(&h, \"h\", false, \"this help\")\n\n\tflag.BoolVar(&v, \"v\", false, \"show version and exit\")\n\tflag.BoolVar(&V, \"V\", false, \"show version and configure options then exit\")\n\n\tflag.BoolVar(&t, \"t\", false, \"test configuration and exit\")\n\tflag.BoolVar(&T, \"T\", false, \"test configuration, dump it and exit\")\n\n\t// 另一种绑定方式\n\tq = flag.Bool(\"q\", false, \"suppress non-error messages during configuration testing\")\n\n\t// 注意 `signal`。默认是 -s string，有了 `signal` 之后，变为 -s signal\n\tflag.StringVar(&s, \"s\", \"\", \"send `signal` to a master process: stop, quit, reopen, reload\")\n\tflag.StringVar(&p, \"p\", \"/usr/local/nginx/\", \"set `prefix` path\")\n\tflag.StringVar(&c, \"c\", \"conf/nginx.conf\", \"set configuration `file`\")\n\tflag.StringVar(&g, \"g\", \"conf/nginx.conf\", \"set global `directives` out of configuration file\")\n\n\t// 改变默认的 Usage\n\tflag.Usage = usage\n}\n\nfunc main() {\n\tflag.Parse()\n\n\tif h {\n\t\tflag.Usage()\n\t}\n}\n\nfunc usage() {\n\tfmt.Fprintf(os.Stderr, `nginx version: nginx/1.10.0\nUsage: nginx [-hvVtTq] [-s signal] [-c filename] [-p prefix] [-g directives]\n\nOptions:\n`)\n\tflag.PrintDefaults()\n}\n" }, { "path": "code/chapter08/result/src/util/util.go", "content": "// Copyright 2013 The StudyGolang Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style\n// license that can be found in the LICENSE file.\n// http://studygolang.com\n// Author：polaris\tstudygolang@gmail.com\n\npackage util\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"path\"\n\t\"path/filepath\"\n\t\"strings\"\n)\n\n// 获得项目根目录\nfunc GetProjectRoot() string {\n\tbinDir, err := executableDir()\n\tif err != nil {\n\t\treturn \"\"\n\t}\n\treturn path.Dir(binDir)\n}\n\n// 获得可执行程序所在目录\nfunc executableDir() (string, error) {\n\tpathAbs, err := filepath.Abs(os.Args[0])\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\treturn filepath.Dir(pathAbs), nil\n}\n\nfunc Welcome() {\n\tfmt.Println(\"***********************************\")\n\tfmt.Println(\"*******欢迎来到Go语言中文网*******\")\n\tfmt.Println(\"***********************************\")\n}\n\n// strings.Index的UTF-8版本\n// 即 Utf8Index(\"Go语言中文网\", \"学习\") 返回 4，而不是strings.Index的 8\nfunc Utf8Index(str, substr string) int {\n\tasciiPos := strings.Index(str, substr)\n\tif asciiPos == -1 || asciiPos == 0 {\n\t\treturn asciiPos\n\t}\n\tpos := 0\n\ttotalSize := 0\n\treader := strings.NewReader(str)\n\tfor _, size, err := reader.ReadRune(); err == nil; _, size, err = reader.ReadRune() {\n\t\ttotalSize += size\n\t\tpos++\n\t\t// 匹配到\n\t\tif totalSize == asciiPos {\n\t\t\treturn pos\n\t\t}\n\t}\n\treturn pos\n}\n" }, { "path": "code/chapter08/tar.go", "content": "package main\n\nimport (\n\t\"archive/tar\"\n\t\"log\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\nfunc main() {\n\tf, err := os.Create(\"result/polarisxu.tar\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer f.Close()\n\n\ttw := tar.NewWriter(f)\n\tdefer tw.Close()\n\n\troot, err := filepath.Abs(\"..\")\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\terr = ScanDir(tw, root, root)\n\tif err != nil {\n\t\tos.Remove(\"result/polarisxu.tar\")\n\t\tlog.Fatal(err)\n\t}\n}\n\nfunc ScanDir(tw *tar.Writer, root, dirName string) error {\n\tdirEntries, err := os.ReadDir(dirName)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tfor _, dirEntry := range dirEntries {\n\t\tnewPath := dirName + \"/\" + dirEntry.Name()\n\t\tif dirEntry.IsDir() {\n\t\t\tif err = ScanDir(tw, root, newPath); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t} else {\n\t\t\thdr := &tar.Header{\n\t\t\t\tName: dirName[len(root):] + \"/\" + dirEntry.Name(),\n\t\t\t}\n\t\t\tfileInfo, err := dirEntry.Info()\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\thdr.Mode = int64(fileInfo.Mode().Perm())\n\t\t\tbody, err := os.ReadFile(newPath)\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\thdr.Size = int64(len(body))\n\t\t\tif err = tw.WriteHeader(hdr); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\n\t\t\tif _, err = tw.Write(body); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t}\n\t}\n\n\treturn nil\n}\n" }, { "path": "code/install.bat", "content": "@echo off\n\nsetlocal\n\nif exist install.bat goto ok\necho install.bat must be run from its folder\ngoto end\n\n:ok\n\nset OLDGOPATH=%GOPATH%\nset GOPATH=%~dp0;%~dp0..\\thirdparty\n\ngofmt -w src\n\ngo install chapter01/io\n\nset GOPATH=%OLDGOPATH%\n\n:end\necho finished" }, { "path": "code/install.sh", "content": "#!/usr/bin/env bash\n\nset -e\n\nif [ ! -f install.sh ]; then\n\techo 'install must be run within its container folder' 1>&2\n\texit 1\nfi\n\nCURDIR=`pwd`\nOLDGOPATH=\"$GOPATH\"\nexport GOPATH=\"$CURDIR\"\n\ngofmt -w src\n\ngo install ./...\n\nexport GOPATH=\"$OLDGOPATH\"\nexport PATH=\"$OLDPATH\"\n\necho 'finished'\n\n" }, { "path": "code/src/chapter01/io/01.txt", "content": "from file" }, { "path": "code/src/chapter01/io/byterwer.go", "content": "package main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"os\"\n)\n\nfunc ByteRWerExample() {\nFOREND:\n\tfor {\n\t\tfmt.Println(\"请输入要通过WriteByte写入的一个ASCII字符（b：返回上级；q：退出）：\")\n\t\tvar ch byte\n\t\tfmt.Scanf(\"%c\\n\", &ch)\n\t\tswitch ch {\n\t\tcase 'b':\n\t\t\tfmt.Println(\"返回上级菜单！\")\n\t\t\tbreak FOREND\n\t\tcase 'q':\n\t\t\tfmt.Println(\"程序退出！\")\n\t\t\tos.Exit(0)\n\t\tdefault:\n\t\t\tbuffer := new(bytes.Buffer)\n\t\t\terr := buffer.WriteByte(ch)\n\t\t\tif err == nil {\n\t\t\t\tfmt.Println(\"写入一个字节成功！准备读取该字节……\")\n\t\t\t\tnewCh, _ := buffer.ReadByte()\n\t\t\t\tfmt.Printf(\"读取的字节：%c\\n\", newCh)\n\t\t\t} else {\n\t\t\t\tfmt.Println(\"写入错误\")\n\t\t\t}\n\t\t}\n\n\t}\n}\n" }, { "path": "code/src/chapter01/io/main.go", "content": "package main\n\nimport (\n\t\"fmt\"\n\t\"util\"\n)\n\nfunc main() {\n\tutil.Welcome()\n\tMainMenu()\n}\n\nfunc MainMenu() {\nMAINFOR:\n\tfor {\n\t\tfmt.Println(\"\")\n\t\tfmt.Println(\"*******请选择示例：*********\")\n\t\tfmt.Println(\"1 表示 io.Reader 示例\")\n\t\tfmt.Println(\"2 表示 io.ByteReader/ByteWriter 示例\")\n\t\tfmt.Println(\"q 退出\")\n\t\tfmt.Println(\"***********************************\")\n\n\t\tvar ch string\n\t\tfmt.Scanln(&ch)\n\n\t\tswitch ch {\n\t\tcase \"1\":\n\t\t\tReaderExample()\n\t\tcase \"2\":\n\t\t\tByteRWerExample()\n\t\tcase \"q\":\n\t\t\tfmt.Println(\"程序退出！\")\n\t\t\tbreak MAINFOR\n\t\tdefault:\n\t\t\tfmt.Println(\"输入错误！\")\n\t\t\tcontinue\n\t\t}\n\t}\n}\n" }, { "path": "code/src/chapter01/io/reader.go", "content": "// io.Reader 接口示例\npackage main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"os\"\n\t\"strings\"\n\t\"util\"\n)\n\nfunc ReaderExample() {\nFOREND:\n\tfor {\n\t\treaderMenu()\n\n\t\tvar ch string\n\t\tfmt.Scanln(&ch)\n\t\tvar (\n\t\t\tdata []byte\n\t\t\terr error\n\t\t)\n\t\tswitch strings.ToLower(ch) {\n\t\tcase \"1\":\n\t\t\tfmt.Println(\"请输入不多于9个字符，以回车结束：\")\n\t\t\tdata, err = ReadFrom(os.Stdin, 11)\n\t\tcase \"2\":\n\t\t\tfile, err := os.Open(util.GetProjectRoot() + \"/src/chapter01/io/01.txt\")\n\t\t\tif err != nil {\n\t\t\t\tfmt.Println(\"打开文件 01.txt 错误:\", err)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tdata, err = ReadFrom(file, 9)\n\t\t\tfile.Close()\n\t\tcase \"3\":\n\t\t\tdata, err = ReadFrom(strings.NewReader(\"from string\"), 12)\n\t\tcase \"4\":\n\t\t\tfmt.Println(\"暂未实现！\")\n\t\tcase \"b\":\n\t\t\tfmt.Println(\"返回上级菜单！\")\n\t\t\tbreak FOREND\n\t\tcase \"q\":\n\t\t\tfmt.Println(\"程序退出！\")\n\t\t\tos.Exit(0)\n\t\tdefault:\n\t\t\tfmt.Println(\"输入错误！\")\n\t\t\tcontinue\n\t\t}\n\n\t\tif err != nil {\n\t\t\tfmt.Println(\"数据读取失败，可以试试从其他输入源读取！\")\n\t\t} else {\n\t\t\tfmt.Printf(\"读取到的数据是：%s\\n\", data)\n\t\t}\n\t}\n}\n\nfunc ReadFrom(reader io.Reader, num int) ([]byte, error) {\n\tp := make([]byte, num)\n\tn, err := reader.Read(p)\n\tif n > 0 {\n\t\treturn p[:n], nil\n\t}\n\treturn p, err\n}\n\nfunc readerMenu() {\n\tfmt.Println(\"\")\n\tfmt.Println(\"*******从不同来源读取数据*********\")\n\tfmt.Println(\"*******请选择数据源，请输入：*********\")\n\tfmt.Println(\"1 表示 标准输入\")\n\tfmt.Println(\"2 表示 普通文件\")\n\tfmt.Println(\"3 表示 从字符串\")\n\tfmt.Println(\"4 表示 从网络\")\n\tfmt.Println(\"b 返回上级菜单\")\n\tfmt.Println(\"q 退出\")\n\tfmt.Println(\"***********************************\")\n}\n" }, { "path": "code/src/chapter06/filepath/walk/main.go", "content": "package main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\nfunc main() {\n\tfilepath.Walk(\"../../..\", func(path string, info os.FileInfo, err error) error {\n\t\tif info.IsDir() {\n\t\t\treturn nil\n\t\t}\n\n\t\tfmt.Println(\"file:\", info.Name(), \"in directory:\", path)\n\n\t\treturn nil\n\t})\n}\n" }, { "path": "code/src/chapter06/os/dirtree/main.go", "content": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"os\"\n\t\"path/filepath\"\n)\n\nfunc main() {\n\tReadAndOutputDir(\"../../..\", 3)\n}\n\nfunc ReadAndOutputDir(rootPath string, deep int) {\n\tfile, err := os.Open(rootPath)\n\tif err != nil {\n\t\tfmt.Println(\"error:\", err)\n\t\treturn\n\t}\n\tdefer file.Close()\n\n\tfor {\n\t\tfileInfos, err := file.Readdir(100)\n\t\tif err != nil {\n\t\t\tif err == io.EOF {\n\t\t\t\tbreak\n\t\t\t}\n\t\t\tfmt.Println(\"readdir error:\", err)\n\t\t\treturn\n\t\t}\n\n\t\tif len(fileInfos) == 0 {\n\t\t\tbreak\n\t\t}\n\n\t\tfor _, fileInfo := range fileInfos {\n\t\t\tif fileInfo.IsDir() {\n\t\t\t\tif deep > 0 {\n\t\t\t\t\tReadAndOutputDir(filepath.Join(rootPath, string(os.PathSeparator), fileInfo.Name()), deep-1)\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tfmt.Println(\"file:\", fileInfo.Name(), \"in directory:\", rootPath)\n\t\t\t}\n\t\t}\n\t}\n}\n" }, { "path": "code/src/chapter09/benchmark_result.go", "content": "package main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"testing\"\n\t\"text/template\"\n)\n\nfunc main() {\n\tbenchmarkResult := testing.Benchmark(func(b *testing.B) {\n\t\ttempl := template.Must(template.New(\"test\").Parse(\"Hello, {{.}}!\"))\n\t\t// RunParallel will create GOMAXPROCS goroutines\n\t\t// and distribute work among them.\n\t\tb.RunParallel(func(pb *testing.PB) {\n\t\t\t// Each goroutine has its own bytes.Buffer.\n\t\t\tvar buf bytes.Buffer\n\t\t\tfor pb.Next() {\n\t\t\t\t// The loop body is executed b.N times total across all goroutines.\n\t\t\t\tbuf.Reset()\n\t\t\t\ttempl.Execute(&buf, \"World\")\n\t\t\t}\n\t\t})\n\t})\n\n\t// fmt.Printf(\"%8d\\t%10d ns/op\\t%10d B/op\\t%10d allocs/op\\n\", benchmarkResult.N, benchmarkResult.NsPerOp(), benchmarkResult.AllocedBytesPerOp(), benchmarkResult.AllocsPerOp())\n\tfmt.Printf(\"%s\\t%s\\n\", benchmarkResult.String(), benchmarkResult.MemString())\n}\n" }, { "path": "code/src/chapter09/httptest/data.go", "content": "package main\n\nimport (\n\t\"errors\"\n\t\"time\"\n)\n\n// 保存 Topic，没有考虑并发问题\nvar TopicCache = make([]*Topic, 0, 16)\n\ntype Topic struct {\n\tId int `json:\"id\"`\n\tTitle string `json:\"title\"`\n\tContent string `json:\"content\"`\n\tCreatedAt time.Time `json:\"created_at\"`\n}\n\nfunc FindTopic(id int) (*Topic, error) {\n\tif err := checkIndex(id); err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn TopicCache[id-1], nil\n}\n\nfunc (t *Topic) Create() error {\n\tt.Id = len(TopicCache) + 1\n\tt.CreatedAt = time.Now()\n\tTopicCache = append(TopicCache, t)\n\treturn nil\n}\n\nfunc (t *Topic) Update() error {\n\tif err := checkIndex(t.Id); err != nil {\n\t\treturn err\n\t}\n\tTopicCache[t.Id-1] = t\n\treturn nil\n}\n\n// 简单的将对应的 slice 位置置为 nil\nfunc (t *Topic) Delete() error {\n\tif err := checkIndex(t.Id); err != nil {\n\t\treturn err\n\t}\n\tTopicCache[t.Id-1] = nil\n\treturn nil\n}\n\nfunc checkIndex(id int) error {\n\tif id > 0 && len(TopicCache) <= id-1 {\n\t\treturn errors.New(\"The topic is not exists!\")\n\t}\n\n\treturn nil\n}\n" }, { "path": "code/src/chapter09/httptest/server.go", "content": "package main\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"path\"\n\t\"strconv\"\n)\n\nfunc main() {\n\thttp.HandleFunc(\"/topic/\", handleRequest)\n\n\thttp.ListenAndServe(\":2017\", nil)\n}\n\n// main handler function\nfunc handleRequest(w http.ResponseWriter, r *http.Request) {\n\tvar err error\n\tswitch r.Method {\n\tcase http.MethodGet:\n\t\terr = handleGet(w, r)\n\tcase http.MethodPost:\n\t\terr = handlePost(w, r)\n\tcase http.MethodPut:\n\t\terr = handlePut(w, r)\n\tcase http.MethodDelete:\n\t\terr = handleDelete(w, r)\n\t}\n\tif err != nil {\n\t\thttp.Error(w, err.Error(), http.StatusInternalServerError)\n\t\treturn\n\t}\n}\n\n// 获取一个帖子\n// 如 GET /topic/1\nfunc handleGet(w http.ResponseWriter, r *http.Request) error {\n\tid, err := strconv.Atoi(path.Base(r.URL.Path))\n\tif err != nil {\n\t\treturn err\n\t}\n\ttopic, err := FindTopic(id)\n\tif err != nil {\n\t\treturn err\n\t}\n\toutput, err := json.MarshalIndent(&topic, \"\", \"\\t\\t\")\n\tif err != nil {\n\t\treturn err\n\t}\n\tw.Header().Set(\"Content-Type\", \"application/json\")\n\tw.Write(output)\n\treturn nil\n}\n\n// 增加一个帖子\n// POST /topic/\nfunc handlePost(w http.ResponseWriter, r *http.Request) (err error) {\n\tbody := make([]byte, r.ContentLength)\n\tr.Body.Read(body)\n\tvar topic = new(Topic)\n\terr = json.Unmarshal(body, &topic)\n\tif err != nil {\n\t\treturn\n\t}\n\n\terr = topic.Create()\n\tif err != nil {\n\t\treturn\n\t}\n\tw.WriteHeader(http.StatusOK)\n\treturn\n}\n\n// 更新一个帖子\n// PUT /topic/1\nfunc handlePut(w http.ResponseWriter, r *http.Request) error {\n\tid, err := strconv.Atoi(path.Base(r.URL.Path))\n\tif err != nil {\n\t\treturn err\n\t}\n\ttopic, err := FindTopic(id)\n\tif err != nil {\n\t\treturn err\n\t}\n\tbody := make([]byte, r.ContentLength)\n\tr.Body.Read(body)\n\tjson.Unmarshal(body, topic)\n\terr = topic.Update()\n\tif err != nil {\n\t\treturn err\n\t}\n\tw.WriteHeader(http.StatusOK)\n\treturn nil\n}\n\n// 删除一个帖子\n// DELETE /topic/1\nfunc handleDelete(w http.ResponseWriter, r *http.Request) (err error) {\n\tid, err := strconv.Atoi(path.Base(r.URL.Path))\n\tif err != nil {\n\t\treturn\n\t}\n\ttopic, err := FindTopic(id)\n\tif err != nil {\n\t\treturn\n\t}\n\terr = topic.Delete()\n\tif err != nil {\n\t\treturn\n\t}\n\tw.WriteHeader(http.StatusOK)\n\treturn\n}\n" }, { "path": "code/src/chapter09/httptest/server_test.go", "content": "package main\n\nimport (\n\t\"encoding/json\"\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"os\"\n\t\"strings\"\n\t\"testing\"\n)\n\nvar w *httptest.ResponseRecorder\n\nfunc TestMain(m *testing.M) {\n\thttp.DefaultServeMux.HandleFunc(\"/topic/\", handleRequest)\n\n\tw = httptest.NewRecorder()\n\n\tos.Exit(m.Run())\n}\n\nfunc TestHandlePost(t *testing.T) {\n\treader := strings.NewReader(`{\"title\":\"The Go Standard Library\",\"content\":\"It contains many packages.\"}`)\n\tr, _ := http.NewRequest(http.MethodPost, \"/topic/\", reader)\n\n\thttp.DefaultServeMux.ServeHTTP(w, r)\n\n\tresult := w.Result()\n\tif result.StatusCode != http.StatusOK {\n\t\tt.Errorf(\"Response code is %v\", result.StatusCode)\n\t}\n}\n\nfunc TestHandleGet(t *testing.T) {\n\tr, _ := http.NewRequest(http.MethodGet, \"/topic/1\", nil)\n\n\thttp.DefaultServeMux.ServeHTTP(w, r)\n\n\tresult := w.Result()\n\tif result.StatusCode != http.StatusOK {\n\t\tt.Errorf(\"Response code is %v\", result.StatusCode)\n\t}\n\n\ttopic := new(Topic)\n\tjson.Unmarshal(w.Body.Bytes(), topic)\n\tif topic.Id != 1 {\n\t\tt.Errorf(\"Cannot get topic\")\n\t}\n}\n" }, { "path": "code/src/chapter09/testing/example_test.go", "content": "package testing_test\n\nimport (\n\t. \"chapter09/testing\"\n\t\"fmt\"\n)\n\nfunc ExampleFib() {\n\tfmt.Println(Fib(7))\n\t// Output: 13\n}\n" }, { "path": "code/src/chapter09/testing/parallel.go", "content": "package testing\n\nimport \"sync\"\n\nvar (\n\tdata = make(map[string]string)\n\tlocker sync.RWMutex\n)\n\nfunc WriteToMap(k, v string) {\n\tlocker.Lock()\n\tdefer locker.Unlock()\n\tdata[k] = v\n}\n\nfunc ReadFromMap(k string) string {\n\tlocker.RLock()\n\tdefer locker.RUnlock()\n\treturn data[k]\n}\n" }, { "path": "code/src/chapter09/testing/parallel_test.go", "content": "package testing_test\n\nimport (\n\t\"bytes\"\n\t. \"chapter09/testing\"\n\t\"html/template\"\n\t\"testing\"\n)\n\nvar pairs = []struct {\n\tk string\n\tv string\n}{\n\t{\"polaris\", \"徐新华\"},\n\t{\"studygolang\", \"Go语言中文网\"},\n\t{\"stdlib\", \"Go语言标准库\"},\n\t{\"polaris1\", \"徐新华1\"},\n\t{\"studygolang1\", \"Go语言中文网1\"},\n\t{\"stdlib1\", \"Go语言标准库1\"},\n\t{\"polaris2\", \"徐新华2\"},\n\t{\"studygolang2\", \"Go语言中文网2\"},\n\t{\"stdlib2\", \"Go语言标准库2\"},\n\t{\"polaris3\", \"徐新华3\"},\n\t{\"studygolang3\", \"Go语言中文网3\"},\n\t{\"stdlib3\", \"Go语言标准库3\"},\n\t{\"polaris4\", \"徐新华4\"},\n\t{\"studygolang4\", \"Go语言中文网4\"},\n\t{\"stdlib4\", \"Go语言标准库4\"},\n}\n\n// 注意 TestWriteToMap 需要在 TestReadFromMap 之前\nfunc TestWriteToMap(t *testing.T) {\n\tt.Parallel()\n\tfor _, tt := range pairs {\n\t\tWriteToMap(tt.k, tt.v)\n\t}\n}\n\nfunc TestReadFromMap(t *testing.T) {\n\tt.Parallel()\n\tfor _, tt := range pairs {\n\t\tactual := ReadFromMap(tt.k)\n\t\tif actual != tt.v {\n\t\t\tt.Errorf(\"the value of key(%s) is %s, expected: %s\", tt.k, actual, tt.v)\n\t\t}\n\t}\n}\n\nfunc BenchmarkTemplateParallel(b *testing.B) {\n\ttempl := template.Must(template.New(\"test\").Parse(\"Hello, {{.}}!\"))\n\tb.RunParallel(func(pb *testing.PB) {\n\t\tvar buf bytes.Buffer\n\t\tfor pb.Next() {\n\t\t\tbuf.Reset()\n\t\t\ttempl.Execute(&buf, \"World\")\n\t\t}\n\t})\n}\n" }, { "path": "code/src/chapter09/testing/server_test.go", "content": "package testing\n\nimport (\n\t\"fmt\"\n\t\"testing\"\n\t\"time\"\n)\n\nfunc TestTime(t *testing.T) {\n\ttestCases := []struct {\n\t\tgmt string\n\t\tloc string\n\t\twant string\n\t}{\n\t\t{\"12:31\", \"Europe/Zuri\", \"13:31\"},\n\t\t{\"12:31\", \"America/New_York\", \"7:31\"},\n\t\t{\"08:08\", \"Australia/Sydney\", \"18:08\"},\n\t}\n\tfor _, tc := range testCases {\n\t\tt.Run(fmt.Sprintf(\"%s in %s\", tc.gmt, tc.loc), func(t *testing.T) {\n\t\t\tt.Parallel()\n\t\t\tloc, err := time.LoadLocation(tc.loc)\n\t\t\tif err != nil {\n\t\t\t\tt.Fatal(\"could not load location\")\n\t\t\t}\n\t\t\tgmt, _ := time.Parse(\"15:04\", tc.gmt)\n\t\t\tif got := gmt.In(loc).Format(\"15:04\"); got != tc.want {\n\t\t\t\tt.Errorf(\"got %s; want %s\", got, tc.want)\n\t\t\t}\n\t\t})\n\t}\n}\n" }, { "path": "code/src/chapter09/testing/t.go", "content": "package testing\n\nfunc Fib(n int) int {\n\tif n < 2 {\n\t\treturn n\n\t}\n\treturn Fib(n-1) + Fib(n-2)\n}\n" }, { "path": "code/src/chapter09/testing/t_test.go", "content": "package testing_test\n\nimport (\n\t\"bytes\"\n\t\"html/template\"\n\t\"testing\"\n\t\"time\"\n\n\t. \"chapter09/testing\"\n)\n\n// Table-Driven Test\nfunc TestFib_TableDrivenParallel(t *testing.T) {\n\tvar fibTests = []struct {\n\t\tname string\n\t\tin int // input\n\t\texpected int // expected result\n\t}{\n\t\t{\"1的Fib\", 1, 1},\n\t\t{\"2的Fib\", 2, 1},\n\t\t{\"3的Fib\", 3, 2},\n\t\t{\"4的Fib\", 4, 3},\n\t\t{\"5的Fib\", 5, 5},\n\t\t{\"6的Fib\", 6, 8},\n\t\t{\"7的Fib\", 7, 13},\n\t}\n\n\tfor _, tt := range fibTests {\n\t\ttt := tt\n\t\tt.Run(tt.name, func(t *testing.T) {\n\t\t\tt.Log(\"time:\", time.Now())\n\t\t\tt.Parallel()\n\t\t\ttime.Sleep(3 * time.Second)\n\t\t\tactual := Fib(tt.in)\n\t\t\tif actual != tt.expected {\n\t\t\t\tt.Errorf(\"Fib(%d) = %d; expected %d\", tt.in, actual, tt.expected)\n\t\t\t}\n\t\t})\n\t}\n\n\tfor _, tt := range fibTests {\n\t\tt.Log(\"time:\", time.Now())\n\t\tactual := Fib(tt.in)\n\t\tif actual != tt.expected {\n\t\t\tt.Errorf(\"Fib(%d) = %d; expected %d\", tt.in, actual, tt.expected)\n\t\t}\n\t}\n\n\tdefer func() {\n\t\tt.Log(\"time:\", time.Now())\n\t}()\n}\n\nfunc TestFib(t *testing.T) {\n\tvar (\n\t\tin = 7 // input\n\t\texpected = 13 // expected result\n\t)\n\tactual := Fib(in)\n\tif actual != expected {\n\t\tt.Errorf(\"Fib(%d) = %d; expected %d\", in, actual, expected)\n\t}\n}\n\n// Table-Driven Test\nfunc TestFib_TableDriven(t *testing.T) {\n\tvar fibTests = []struct {\n\t\tin int // input\n\t\texpected int // expected result\n\t}{\n\t\t{1, 1},\n\t\t{2, 1},\n\t\t{3, 2},\n\t\t{4, 3},\n\t\t{5, 5},\n\t\t{6, 8},\n\t\t{7, 13},\n\t}\n\n\tfor _, tt := range fibTests {\n\t\tactual := Fib(tt.in)\n\t\tif actual != tt.expected {\n\t\t\tt.Errorf(\"Fib(%d) = %d; expected %d\", tt.in, actual, tt.expected)\n\t\t}\n\t}\n}\n\nfunc BenchmarkFib1(b *testing.B) { benchmarkFib(1, b) }\nfunc BenchmarkFib2(b *testing.B) { benchmarkFib(2, b) }\nfunc BenchmarkFib3(b *testing.B) { benchmarkFib(3, b) }\nfunc BenchmarkFib10(b *testing.B) { benchmarkFib(10, b) }\nfunc BenchmarkFib20(b *testing.B) { benchmarkFib(20, b) }\nfunc BenchmarkFib40(b *testing.B) { benchmarkFib(40, b) }\n\nfunc benchmarkFib(i int, b *testing.B) {\n\tfor n := 0; n < b.N; n++ {\n\t\tFib(i)\n\t}\n}\n\nfunc BenchmarkTmplExucte(b *testing.B) {\n\tb.ReportAllocs()\n\n\ttempl := template.Must(template.New(\"test\").Parse(\"Hello, {{.}}!\"))\n\tb.RunParallel(func(pb *testing.PB) {\n\t\t// Each goroutine has its own bytes.Buffer.\n\t\tvar buf bytes.Buffer\n\t\tfor pb.Next() {\n\t\t\t// The loop body is executed b.N times total across all goroutines.\n\t\t\tbuf.Reset()\n\t\t\ttempl.Execute(&buf, \"World\")\n\t\t}\n\t})\n}\n" }, { "path": "code/src/chapter10/os_exec.go", "content": "package main\n\nimport (\n\t\"bytes\"\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\t\"os/exec\"\n)\n\nfunc main() {\n\targNum := len(os.Args)\n\tif argNum < 2 {\n\t\tlog.Printf(\"Usage:%s command\\n\", os.Args[0])\n\t\tos.Exit(1)\n\t}\n\n\targ := []string{}\n\tif argNum > 2 {\n\t\targ = os.Args[2:]\n\t}\n\n\tmainOutput(UsePipe(os.Args[1], arg...))\n}\n\nfunc mainOutput(out []byte, err error) {\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tfmt.Printf(\"The output of command %q is\\n%s\\n\", os.Args[1], out)\n}\n\n// 直接给 Cmd.Stdout 赋值\nfunc FillStd(name string, arg ...string) ([]byte, error) {\n\tcmd := exec.Command(name, arg...)\n\tvar out = new(bytes.Buffer)\n\n\tcmd.Stdout = out\n\tcmd.Stderr = out\n\n\terr := cmd.Run()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn out.Bytes(), nil\n}\n\nfunc UseOutput(name string, arg ...string) ([]byte, error) {\n\treturn exec.Command(name, arg...).Output()\n}\n\n// 使用 Pipe\nfunc UsePipe(name string, arg ...string) ([]byte, error) {\n\tcmd := exec.Command(name, arg...)\n\tstdout, err := cmd.StdoutPipe()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif err = cmd.Start(); err != nil {\n\t\treturn nil, err\n\t}\n\n\tvar out = make([]byte, 0, 1024)\n\tfor {\n\t\ttmp := make([]byte, 128)\n\t\tn, err := stdout.Read(tmp)\n\t\tout = append(out, tmp[:n]...)\n\t\tif err != nil {\n\t\t\tbreak\n\t\t}\n\t}\n\n\tif err = cmd.Wait(); err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn out, nil\n}\n" }, { "path": "code/src/chapter13/flag/nginx.go", "content": "package main\n\nimport (\n\t\"flag\"\n\t\"fmt\"\n\t\"os\"\n)\n\n// 实际中应该用更好的变量名\nvar (\n\th bool\n\n\tv, V bool\n\tt, T bool\n\tq *bool\n\n\ts string\n\tp string\n\tc string\n\tg string\n)\n\nfunc init() {\n\tflag.BoolVar(&h, \"h\", false, \"this help\")\n\n\tflag.BoolVar(&v, \"v\", false, \"show version and exit\")\n\tflag.BoolVar(&V, \"V\", false, \"show version and configure options then exit\")\n\n\tflag.BoolVar(&t, \"t\", false, \"test configuration and exit\")\n\tflag.BoolVar(&T, \"T\", false, \"test configuration, dump it and exit\")\n\n\t// 另一种绑定方式\n\tq = flag.Bool(\"q\", false, \"suppress non-error messages during configuration testing\")\n\n\t// 注意 `signal`。默认是 -s string，有了 `signal` 之后，变为 -s signal\n\tflag.StringVar(&s, \"s\", \"\", \"send `signal` to a master process: stop, quit, reopen, reload\")\n\tflag.StringVar(&p, \"p\", \"/usr/local/nginx/\", \"set `prefix` path\")\n\tflag.StringVar(&c, \"c\", \"conf/nginx.conf\", \"set configuration `file`\")\n\tflag.StringVar(&g, \"g\", \"conf/nginx.conf\", \"set global `directives` out of configuration file\")\n\n\t// 改变默认的 Usage\n\tflag.Usage = usage\n}\n\nfunc main() {\n\tflag.Parse()\n\n\tif h {\n\t\tflag.Usage()\n\t}\n}\n\nfunc usage() {\n\tfmt.Fprintf(os.Stderr, `nginx version: nginx/1.10.0\nUsage: nginx [-hvVtTq] [-s signal] [-c filename] [-p prefix] [-g directives]\n\nOptions:\n`)\n\tflag.PrintDefaults()\n}\n" }, { "path": "code/src/util/util.go", "content": "// Copyright 2013 The StudyGolang Authors. All rights reserved.\n// Use of this source code is governed by a BSD-style\n// license that can be found in the LICENSE file.\n// http://studygolang.com\n// Author：polaris\tstudygolang@gmail.com\n\npackage util\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"path\"\n\t\"path/filepath\"\n\t\"strings\"\n)\n\n// 获得项目根目录\nfunc GetProjectRoot() string {\n\tbinDir, err := executableDir()\n\tif err != nil {\n\t\treturn \"\"\n\t}\n\treturn path.Dir(binDir)\n}\n\n// 获得可执行程序所在目录\nfunc executableDir() (string, error) {\n\tpathAbs, err := filepath.Abs(os.Args[0])\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\treturn filepath.Dir(pathAbs), nil\n}\n\nfunc Welcome() {\n\tfmt.Println(\"***********************************\")\n\tfmt.Println(\"*******欢迎来到Go语言中文网*******\")\n\tfmt.Println(\"***********************************\")\n}\n\n// strings.Index的UTF-8版本\n// 即 Utf8Index(\"Go语言中文网\", \"学习\") 返回 4，而不是strings.Index的 8\nfunc Utf8Index(str, substr string) int {\n\tasciiPos := strings.Index(str, substr)\n\tif asciiPos == -1 || asciiPos == 0 {\n\t\treturn asciiPos\n\t}\n\tpos := 0\n\ttotalSize := 0\n\treader := strings.NewReader(str)\n\tfor _, size, err := reader.ReadRune(); err == nil; _, size, err = reader.ReadRune() {\n\t\ttotalSize += size\n\t\tpos++\n\t\t// 匹配到\n\t\tif totalSize == asciiPos {\n\t\t\treturn pos\n\t\t}\n\t}\n\treturn pos\n}\n" }, { "path": "directory.md", "content": "# 目录\n- 第1章：[输入和输出](chapter01/01.0.md)\n\t- 1.1 [io — 基本的 IO 接口](chapter01/01.1.md)\n\t- 1.2 [ioutil — 方便的IO操作函数集](chapter01/01.2.md)\n\t- 1.3 [fmt — 格式化IO](chapter01/01.3.md)\n\t- 1.4 [ bufio — 缓存IO](chapter01/01.4.md)\n- 第2章：[文本](chapter02/02.0.md)\n\t- 2.1 [strings — 字符串操作](chapter02/02.1.md)\n\t- 2.2 [bytes — byte slice 便利操作](chapter02/02.2.md)\n\t- 2.3 [strconv — 字符串和基本数据类型之间转换](chapter02/02.3.md)\n\t- 2.4 [regexp — 正则表达式](chapter02/02.4.md)\n\t- 2.5 [unicode — Unicode码点、UTF-8/16编码](chapter02/02.5.md)\n- 第3章：[数据结构与算法](chapter03/03.0.md)\n\t- 3.1 [sort —— 排序算法](chapter03/03.1.md)\n\t- 3.3 [container — 容器数据类型：heap、list和ring](chapter03/03.3.md)\n- 第4章：[日期与时间](chapter04/04.0.md)\n\t- 4.1 [主要类型概述](chapter04/04.1.md)\n\t- 4.2 [时区](chapter04/04.2.md)\n\t- 4.3 [Time 类型详解](chapter04/04.3.md)\n\t- 4.4 [定时器](chapter04/04.4.md)\n- 第5章：数学函数\n\t- 5.1 [math — 基本数学函数](chapter05/05.1.md)\n- 第6章：[文件系统](chapter06/06.0.md)\n\t- 6.1 [os — 平台无关的操作系统功能实现](chapter06/06.1.md)\n\t- 6.2 [path/filepath — 兼容操作系统的文件路径操作](chapter06/06.2.md)\n- 第7章：[数据持久存储与交换](chapter07/07.0.md)\n\t- 7.1 [database/sql — SQL/SQL-Like 数据库操作接口](chapter07/07.1.md)\n- 第8章：[数据压缩与归档](chapter08/08.0.md)\n\t- 8.1 [flate - DEFLATE 压缩算法](chapter08/08.1.md)\n- 第9章：[测试](chapter09/09.0.md)\n\t- 9.1 [testing - 单元测试](chapter09/09.1.md)\n\t- 9.2 [testing - 基准测试](chapter09/09.2.md)\n\t- 9.3 [testing - 子测试与子基准测试](chapter09/09.3.md)\n\t- 9.4 [testing - 运行并验证示例](chapter09/09.4.md)\n\t- 9.5 [testing - 其他功能](chapter09/09.5.md)\n\t- 9.6 [httptest - HTTP 测试辅助工具](chapter09/09.6.md)\n\t- 9.7 [总结](chapter09/09.7.md)\n- 第10章：[进程、线程和 goroutine](chapter10/10.0.md)\n - 10.1 [创建进程](chapter10/10.1.md)\n - 10.2 [进程属性和控制](chapter10/10.2.md)\n - 10.3 [线程](chapter10/10.3.md)\n- 第13章：[应用构建 与 debug](chapter13/13.0.md)\n - 13.1 [flag - 命令行参数解析](chapter13/13.1.md)\n - 13.3 [expvar - 公共变量的标准化接口](chapter13/13.3.md) \n- 第15章：\n - 15.2 [非类型安全操作](chapter15/15.02.md)\n\n- 第16章：\n - 16.1 [sync - 处理同步需求](chapter16/16.01.md)\n - 16.2 [sync/atomic - 原子操作](chapter16/16.02.md)\n - 16.3 [os/signal - 信号](chapter16/16.03.md)\n \n" } ]