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

收尾:写一个能装到机器上的统计小工具
隔壁老康难度 ★☆☆☆☆ · 前置:够用的那十几个标准库 | 一句话结论:一个真能用的命令行工具只需要 flag、bufio、strings、sort 四个包,剩下的都是把这四样接起来。
前面十一篇每篇只讲一件事,这一篇把它们拼起来。之所以要拼这么一次,是因为单独看书里任何一节,你都觉得懂了,可一旦要自己写点东西,就会发现懂的是每一块,串起来的地方全是空的:参数进不来、文件打不开、错误不知道往哪报、装到机器上又不知道该复制哪个文件。这一篇就是专门填这些缝的。目标是写一个数词频的小工具:给它几个文本文件,它告诉你出现最多的词是哪几个。代码一共七十来行,但里面每一行前十一篇都讲过。你会用到四样东西,flag 接命令行参数,os 打开文件,bufio 一行一行读,strings 把一行切成词,最后用 sort 排个序打出来。这东西不复杂,但它完整,有参数、有输入、有输出、有错误处理、有退出码,还能装到机器上直接敲命令跑。写完这一篇,你手上就不是练习代码了,是一个能交给别人的东西。
这东西的价值不在代码量。前面十一篇每篇都只回答一个问题,答案之间不串门,你读到 H11 的时候大概已经把 H1 的细节忘掉一半了。这一篇是唯一一次把它们放在一起用的机会,参数怎么接、文件怎么开、错误怎么报、二进制怎么装,这四件事只有拼在一个能跑的东西里才会显出它们的关系。单看的话,flag 就是几个函数,bufio 就是几个函数,放一起你才看得见一个工具的骨架是长什么样的,哪一层该管什么事,哪一处出错该由谁来接。所以别只是读,照着敲一遍,敲完再改。改的过程比读的过程有用得多,因为你改的时候会撞上我没写到的需求,那才是真正开始学的地方。
建项目,就三行命令
先建目录、初始化模块、写一个空文件试试能不能跑通。go mod init count 后面那个 count 是模块名,这一篇只有一个 main 包,模块名随便起都行,但它决定了你以后 import 自己写的子包时那个前缀长什么样,所以早养成用有意义名字的习惯。go mod tidy 那两行提示是例行公事,这个工具只用标准库,没有第三方依赖,跑不跑都一样。
1 | $ mkdir count && cd count |
参数用 flag,不要自己切 os.Args
我刚写 Go 的时候干过一件事:从 os.Args[1] 开始一个个读,看到 -top 就认为下一个数是它的值,-min 同理,遇到不认识的就跳过。这写法在我的机器上跑了两个月都没出事,直到有个同事把它挂进脚本,把一个文件名叫 -min 的文件传进来,它二话不说把人家当成开关吃了。这活儿 flag 包已经干得很好,你自己写只会写出一堆边界 bug,比如 -top 后面忘了给数字、或者给了个 abc、或者用户把 -top 3 写成了 -top=3 又写成了 --top 3。flag.Int 一次声明一个整数开关,返回的是指针,三个参数分别是开关名、默认值、帮助文字。那个帮助文字不是写给你看的,是写给 -h 的输出看的,写得好不好直接决定别人会不会用你的工具,我一开始嫌它啰嗦,后来发现它是我唯一能跟陌生用户说话的地方。
1 | top := flag.Int("top", 5, "打印前几名") |
声明完必须 flag.Parse()。这一句不写,开关一个都不生效,程序会拿到默认值安安静静跑完,你会以为是自己传错了参数。剩下的位置参数从 flag.Args() 拿,已经帮你把开关和值都剥掉了,flag.NArg() 就是位置参数的个数,一个都没有说明用户什么文件都没给。
1 | if flag.NArg() == 0 { |
这个判断看着琐碎。
省掉它会很难看。
文件要逐行读,不是一口气吞
小文件 os.ReadFile 一次读进来没问题,但这个工具是拿来数词频的,输入可能是几十兆的日志,一口气读进来就是几十兆内存,而且这份内存要一直占到程序结束。我拿一篇八百多兆的 nginx 日志试过,os.ReadFile 版本直接被系统杀掉,连报错的机会都没有。bufio.Scanner 版本跑同样的文件,内存曲线是平的,从头到尾都只占几十个字节的缓冲。这个差距不是优化技巧,是两种写法在内存模型上的本质区别:一个把整个文件搬进内存,一个只是从管道里一勺一勺舀。bufio.Scanner 按行给,内存占用是常量,读一行算一行,读完就忘。os.Open 返回两个值,第二个是错误,Go 里打开文件失败不是抛异常,是给你一个非 nil 的 error,你必须自己看一眼,这就是 if err != nil 的用处。sc.Scan() 返回 bool,读到末尾给 false,所以直接拿它当循环条件,循环体里用 sc.Text() 拿当前行,不含换行符。
1 | f, err := os.Open(name) |
循环结束后还要再查一次 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 | for _, w := range strings.Fields(sc.Text()) { |
计数用 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 | type pair struct { |
第二行那个 ps[i].Word < ps[j].Word 不是装饰。没有它,次数相同的词谁前谁后每次跑都可能不一样,同一份输入两次输出不同,这种不稳定的输出没法拿去做测试,也没法贴进文档。Go 1.21 之后也可以 slices.SortFunc(ps, cmp),写法更现代一点,但 sort.Slice 到现在仍然是最通用的写法。
出错的时候该说什么
这是命令行工具跟练习代码最大的区别:它得跟不认识你的人打交道。练习代码出错崩了没人管,工具出错崩了,用户的第一反应是这软件有毛病,而不是去看你的错误信息写得对不对。所以每一个 exit 之前都该问一句,用户看到这行字知道下一步干什么吗。我把四种错都真跑了一遍。
1 | $ ./count.exe |
一个文件都没给,程序往 stderr 打一行用法,退出码 2。注意 stdout 什么都没打,那行用法在 stderr 里,这个区分很重要:用法错误走 stderr,正常输出走 stdout,别人用 count.exe a.txt > out.txt 重定向时,用法提示不会混进结果文件。
1 | $ ./count.exe nope.txt |
文件打不开,退出码 1。那行错误里 %v 打出来的是 os.Open 返回的错误原文,它自己带上了文件名和系统给的原因。不要自己拼一句文件不存在,系统那句更准,而且分得清没有权限和找不到这两种情况,你自己拼的那句会把它们抹平成同一个。
1 | $ ./count.exe -topp 3 sample.txt |
开关名拼错,flag 包自己把错和用法都打出来了,退出码 2。这行用法是它按你声明的那些开关自动拼的,这就是为什么帮助文字要写好,你写什么它打什么。
最后一个是 -h,退出码 0 而不是 2。
看帮助不算错误。
四种错对应三个不同的退出码。
报错也是接口的一部分。
它得让人知道下一步干什么。
装到机器上,build 和 install 差在哪
go build 把二进制落在当前目录,go install 落在 $GOBIN,$GOBIN 没设就落在 $GOPATH/bin,然后那个目录一般已经在 PATH 里。两个命令编出来的文件一样大,2727424 字节,差别只在落在哪:build 落在你现在站的目录,install 落在 PATH 里,想在任何目录都能直接敲 count 就用 install。
1 | $ go build -o count.exe . |
go install 有个容易踩的地方,GOBIN 必须是绝对路径。想临时指定一个目录,得给完整的绝对路径,相对路径它直接拒绝。
1 | $ GOBIN=/tmp/h12bin go install . |
顺便记一组编译时间。清掉编译缓存之后编这一个工具要 5.13 秒,第二次 0.23 秒,差了二十多倍。
1 | $ go clean -cache && time go build -o count2.exe . |
标准库的编译结果会被缓存,所以第一次慢不代表你的代码慢,我一开始以为是自己哪里写复杂了,白查了半天。
中文会栽在哪一行
上面切词那行我写的是 len([]rune(w))。要是图省事写成 len(w),中文就会出问题,而且不报错,只是结果不对。len 数的是字节,UTF-8 里一个汉字占三个字节,所以“你好”是 6,len([]rune(w)) 数的才是字符个数,是 2。
1 | go len=2 runeLen=2 |
这个差别在 -min 上直接体现出来。给一个中文文件用 -min 2,两个字的中文词按字符算是 2,刚好过线,全都能出来;要是按字节算 6 也过线,看起来同样没问题,所以这个 bug 在这一步不会暴露。改成 -min 3 就露馅了,跑出来一片空白,因为按字符算两个字的中文词长度是 2,比 3 小,全被过滤掉了。
1 | $ count.exe -min 2 zh.txt |
我写的时候在这里绕了两圈才理顺。
记住一句就够,想要几个字就用 []rune,想要几个字节就用 len。这两个数在纯英文里永远相等,所以这个 bug 只在遇到中文时才浮出来,而且它不会报错,只会悄悄给你一份错的结果。
现在你手上有什么
回头看这十二篇:H1 让屏幕上出现一行字,H2 把变量和类型的规矩立住,H3 到 H6 是控制流、函数、集合、结构体,H7 和 H8 是 Go 里最像对象的东西和最常见的那句 if err != nil,H9 和 H10 让你能拆包、能查文档,H11 让你写的代码有测试兜着。这一篇是最后一环,把这些拼成一个能交给别人的东西,所以它不求新知识,只求你把前十一篇的东西认出来。
拿它去数自己的日志,改几个开关加上 -json 输出,或者把 flag 换成读配置文件,都可以。改的过程比读的过程有用得多,因为你改的时候会撞上我没写到的需求,那才是真正开始学的地方。
从零到能写,你走完了,剩下的都在进阶线里。











