收尾:写一个能装到机器上的统计小工具

难度 ★☆☆☆☆ · 前置:够用的那十几个标准库 | 一句话结论:一个真能用的命令行工具只需要 flag、bufio、strings、sort 四个包,剩下的都是把这四样接起来。

前面十一篇每篇只讲一件事,这一篇把它们拼起来。之所以要拼这么一次,是因为单独看书里任何一节,你都觉得懂了,可一旦要自己写点东西,就会发现懂的是每一块,串起来的地方全是空的:参数进不来、文件打不开、错误不知道往哪报、装到机器上又不知道该复制哪个文件。这一篇就是专门填这些缝的。目标是写一个数词频的小工具:给它几个文本文件,它告诉你出现最多的词是哪几个。代码一共七十来行,但里面每一行前十一篇都讲过。你会用到四样东西,flag 接命令行参数,os 打开文件,bufio 一行一行读,strings 把一行切成词,最后用 sort 排个序打出来。这东西不复杂,但它完整,有参数、有输入、有输出、有错误处理、有退出码,还能装到机器上直接敲命令跑。写完这一篇,你手上就不是练习代码了,是一个能交给别人的东西。

这东西的价值不在代码量。前面十一篇每篇都只回答一个问题,答案之间不串门,你读到 H11 的时候大概已经把 H1 的细节忘掉一半了。这一篇是唯一一次把它们放在一起用的机会,参数怎么接、文件怎么开、错误怎么报、二进制怎么装,这四件事只有拼在一个能跑的东西里才会显出它们的关系。单看的话,flag 就是几个函数,bufio 就是几个函数,放一起你才看得见一个工具的骨架是长什么样的,哪一层该管什么事,哪一处出错该由谁来接。所以别只是读,照着敲一遍,敲完再改。改的过程比读的过程有用得多,因为你改的时候会撞上我没写到的需求,那才是真正开始学的地方。

建项目,就三行命令

先建目录、初始化模块、写一个空文件试试能不能跑通。go mod init count 后面那个 count 是模块名,这一篇只有一个 main 包,模块名随便起都行,但它决定了你以后 import 自己写的子包时那个前缀长什么样,所以早养成用有意义名字的习惯。go mod tidy 那两行提示是例行公事,这个工具只用标准库,没有第三方依赖,跑不跑都一样。

1
2
3
4
5
6
7
$ mkdir count && cd count
$ go mod init count
go: creating new go.mod: module count
go: to add module requirements and sums:
go mod tidy
$ go version
go version go1.27.2 windows/amd64

参数用 flag,不要自己切 os.Args

我刚写 Go 的时候干过一件事:从 os.Args[1] 开始一个个读,看到 -top 就认为下一个数是它的值,-min 同理,遇到不认识的就跳过。这写法在我的机器上跑了两个月都没出事,直到有个同事把它挂进脚本,把一个文件名叫 -min 的文件传进来,它二话不说把人家当成开关吃了。这活儿 flag 包已经干得很好,你自己写只会写出一堆边界 bug,比如 -top 后面忘了给数字、或者给了个 abc、或者用户把 -top 3 写成了 -top=3 又写成了 --top 3。flag.Int 一次声明一个整数开关,返回的是指针,三个参数分别是开关名、默认值、帮助文字。那个帮助文字不是写给你看的,是写给 -h 的输出看的,写得好不好直接决定别人会不会用你的工具,我一开始嫌它啰嗦,后来发现它是我唯一能跟陌生用户说话的地方。

1
2
3
top := flag.Int("top", 5, "打印前几名")
minLen := flag.Int("min", 1, "忽略长度小于这个值的词")
flag.Parse()

声明完必须 flag.Parse()。这一句不写,开关一个都不生效,程序会拿到默认值安安静静跑完,你会以为是自己传错了参数。剩下的位置参数从 flag.Args() 拿,已经帮你把开关和值都剥掉了,flag.NArg() 就是位置参数的个数,一个都没有说明用户什么文件都没给。

1
2
3
4
if flag.NArg() == 0 {
fmt.Fprintln(os.Stderr, "用法: count [-top N] [-min N] 文件...")
os.Exit(2)
}

这个判断看着琐碎。

省掉它会很难看。

文件要逐行读,不是一口气吞

小文件 os.ReadFile 一次读进来没问题,但这个工具是拿来数词频的,输入可能是几十兆的日志,一口气读进来就是几十兆内存,而且这份内存要一直占到程序结束。我拿一篇八百多兆的 nginx 日志试过,os.ReadFile 版本直接被系统杀掉,连报错的机会都没有。bufio.Scanner 版本跑同样的文件,内存曲线是平的,从头到尾都只占几十个字节的缓冲。这个差距不是优化技巧,是两种写法在内存模型上的本质区别:一个把整个文件搬进内存,一个只是从管道里一勺一勺舀。bufio.Scanner 按行给,内存占用是常量,读一行算一行,读完就忘。os.Open 返回两个值,第二个是错误,Go 里打开文件失败不是抛异常,是给你一个非 nil 的 error,你必须自己看一眼,这就是 if err != nil 的用处。sc.Scan() 返回 bool,读到末尾给 false,所以直接拿它当循环条件,循环体里用 sc.Text() 拿当前行,不含换行符。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
f, err := os.Open(name)
if err != nil {
fmt.Fprintf(os.Stderr, "打开 %s 失败: %v\n", name, err)
os.Exit(1)
}
sc := bufio.NewScanner(f)
for sc.Scan() {
// sc.Text() 是这一行,不含换行符
}
if err := sc.Err(); err != nil {
fmt.Fprintf(os.Stderr, "读 %s 出错: %v\n", name, err)
os.Exit(1)
}
f.Close()

循环结束后还要再查一次 sc.Err(),这一条我漏了很长一段时间。Scan() 返回 false 有两种原因,读完了,或者读的时候出错了,两种情况在循环里看起来一模一样。不查 Err() 就会把读到一半磁盘坏了当成读完了,然后安安静静输出一个少了一半的结果,这种 bug 比崩溃难查得多,因为它不报错。

切词、清洗、计数

有了行,切词用 strings.Fields,它按任意空白切,空格、Tab、换行都算,还能把连续的空格当一个处理。手写 strings.Split(line, " ") 遇到两个连续空格会切出一个空串,Fields 不会,这个差别在处理人写的文本时天天遇到。strings.Trim 的第二个参数是要剥掉的字符集合,不是前缀,这一点很容易跟 strings.TrimPrefix 记混,Trim(w, ".,") 会把词首尾所有的点号逗号都剥掉,剥几个都行。strings.ToLower 让 Go、go、GO 算成一个词,不然同一个概念会被拆成三份统计。

1
2
3
4
5
6
7
for _, w := range strings.Fields(sc.Text()) {
w = strings.Trim(w, ".,;:!?\"'()[]")
if len([]rune(w)) < *minLen {
continue
}
counts[strings.ToLower(w)]++
}

计数用 map,键是词,值是次数。一个从没出现过的词,counts[w] 读出来是 int 的零值 0,加一变成 1,map 自动建这个键。Go 的 map 不需要先声明键存不存在,这是零值给你省的第一笔事。

排序得自己写比较函数

map 不能排序,它的遍历顺序是故意打乱的,这一条进阶线那篇专门量过,同一份数据四次跑四个顺序。当时我还不太信,以为乱序只是偶尔,后来发现是每次都乱,跟数据量没关系,两个键的 map 也照样给你换顺序。这个设计不是偷懒,是故意的:它防止有人依赖遍历顺序写出能跑但脆弱的代码。所以你要稳定顺序,就必须自己排一次,sort 那几行看着多余,其实是把不确定性关在门外。要排序得先倒进切片,make([]pair, 0, len(counts)) 那个 len(counts) 是容量不是长度,先按需要的量把底层数组要下来,后面 append 就不会一次次扩容,这一步在小数据上看不出差别,几十万个词的时候能省掉十几次重新分配和复制。sort.Slice 收一个比较函数,返回 true 表示第 i 个应该排在第 j 个前面,这里的规则是次数多的在前,次数相同按字母序。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
type pair struct {
Word string
Count int
}

ps := make([]pair, 0, len(counts))
for w, c := range counts {
ps = append(ps, pair{w, c})
}

sort.Slice(ps, func(i, j int) bool {
if ps[i].Count != ps[j].Count {
return ps[i].Count > ps[j].Count
}
return ps[i].Word < ps[j].Word
})

第二行那个 ps[i].Word < ps[j].Word 不是装饰。没有它,次数相同的词谁前谁后每次跑都可能不一样,同一份输入两次输出不同,这种不稳定的输出没法拿去做测试,也没法贴进文档。Go 1.21 之后也可以 slices.SortFunc(ps, cmp),写法更现代一点,但 sort.Slice 到现在仍然是最通用的写法。

出错的时候该说什么

这是命令行工具跟练习代码最大的区别:它得跟不认识你的人打交道。练习代码出错崩了没人管,工具出错崩了,用户的第一反应是这软件有毛病,而不是去看你的错误信息写得对不对。所以每一个 exit 之前都该问一句,用户看到这行字知道下一步干什么吗。我把四种错都真跑了一遍。

1
2
3
$ ./count.exe
$ echo $?
2

一个文件都没给,程序往 stderr 打一行用法,退出码 2。注意 stdout 什么都没打,那行用法在 stderr 里,这个区分很重要:用法错误走 stderr,正常输出走 stdout,别人用 count.exe a.txt > out.txt 重定向时,用法提示不会混进结果文件。

1
2
3
4
$ ./count.exe nope.txt
打开 nope.txt 失败: open nope.txt: The system cannot find the file specified.
$ echo $?
1

文件打不开,退出码 1。那行错误里 %v 打出来的是 os.Open 返回的错误原文,它自己带上了文件名和系统给的原因。不要自己拼一句文件不存在,系统那句更准,而且分得清没有权限和找不到这两种情况,你自己拼的那句会把它们抹平成同一个。

1
2
3
4
5
6
7
8
9
$ ./count.exe -topp 3 sample.txt
flag provided but not defined: -topp
Usage of F:\Work\AI\Blog\_local\golab\h12\count\.\count.exe:
-min int
忽略长度小于这个值的词 (default 1)
-top int
打印前几名 (default 5)
$ echo $?
2

开关名拼错,flag 包自己把错和用法都打出来了,退出码 2。这行用法是它按你声明的那些开关自动拼的,这就是为什么帮助文字要写好,你写什么它打什么。

最后一个是 -h,退出码 0 而不是 2。

看帮助不算错误。

四种错对应三个不同的退出码。

报错也是接口的一部分。

它得让人知道下一步干什么。

装到机器上,build 和 install 差在哪

go build 把二进制落在当前目录,go install 落在 $GOBIN,$GOBIN 没设就落在 $GOPATH/bin,然后那个目录一般已经在 PATH 里。两个命令编出来的文件一样大,2727424 字节,差别只在落在哪:build 落在你现在站的目录,install 落在 PATH 里,想在任何目录都能直接敲 count 就用 install。

1
2
3
4
5
6
7
8
9
10
$ go build -o count.exe .
$ ls -l count.exe | awk '{print $5" bytes"}'
2727424 bytes

$ go env GOBIN
D:\Go\bin

$ go install .
$ ls -l "D:\Go\bin\count.exe"
-rwxrwxrwx 1 Devil Devil 2727424 Nov 17 11:42 D:\Go\bin\count.exe

go install 有个容易踩的地方,GOBIN 必须是绝对路径。想临时指定一个目录,得给完整的绝对路径,相对路径它直接拒绝。

1
2
3
4
5
6
7
$ GOBIN=/tmp/h12bin go install .
cannot install, GOBIN must be an absolute path

$ GOBIN='F:\Work\AI\Blog\_local\golab\h12\bin' go install .
$ count.exe -top 2 sample.txt
go 4
the 4

顺便记一组编译时间。清掉编译缓存之后编这一个工具要 5.13 秒,第二次 0.23 秒,差了二十多倍。

1
2
3
4
5
$ go clean -cache && time go build -o count2.exe .
5.13 s

$ time go build -o count2.exe .
0.23 s

标准库的编译结果会被缓存,所以第一次慢不代表你的代码慢,我一开始以为是自己哪里写复杂了,白查了半天。

中文会栽在哪一行

上面切词那行我写的是 len([]rune(w))。要是图省事写成 len(w),中文就会出问题,而且不报错,只是结果不对。len 数的是字节,UTF-8 里一个汉字占三个字节,所以“你好”是 6,len([]rune(w)) 数的才是字符个数,是 2。

1
2
3
go  len=2  runeLen=2
你好 len=6 runeLen=2
世界 len=6 runeLen=2

这个差别在 -min 上直接体现出来。给一个中文文件用 -min 2,两个字的中文词按字符算是 2,刚好过线,全都能出来;要是按字节算 6 也过线,看起来同样没问题,所以这个 bug 在这一步不会暴露。改成 -min 3 就露馅了,跑出来一片空白,因为按字符算两个字的中文词长度是 2,比 3 小,全被过滤掉了。

1
2
3
4
5
6
7
$ count.exe -min 2 zh.txt
你好 2
go 1
世界 1
很好 1

$ count.exe -top 9 -min 3 zh.txt

我写的时候在这里绕了两圈才理顺。

记住一句就够,想要几个字就用 []rune,想要几个字节就用 len。这两个数在纯英文里永远相等,所以这个 bug 只在遇到中文时才浮出来,而且它不会报错,只会悄悄给你一份错的结果。

现在你手上有什么

回头看这十二篇:H1 让屏幕上出现一行字,H2 把变量和类型的规矩立住,H3 到 H6 是控制流、函数、集合、结构体,H7 和 H8 是 Go 里最像对象的东西和最常见的那句 if err != nil,H9 和 H10 让你能拆包、能查文档,H11 让你写的代码有测试兜着。这一篇是最后一环,把这些拼成一个能交给别人的东西,所以它不求新知识,只求你把前十一篇的东西认出来。

拿它去数自己的日志,改几个开关加上 -json 输出,或者把 flag 换成读配置文件,都可以。改的过程比读的过程有用得多,因为你改的时候会撞上我没写到的需求,那才是真正开始学的地方。

从零到能写,你走完了,剩下的都在进阶线里。