P22 · 工具链深潜与文档工程：从"能编译"到"能交付"

这章学完你能干什么：给一个 Go 服务采 CPU/heap/goroutine profile 并读出瓶颈；给包写 godoc 级注释并用工具验证覆盖率；发布 v1.2.3 的 module 让别人 go get。读者：读完 P1（速通）。这章是 P1 留下的深水区。
动手方式：pprof 部分对 httpkv 实采；文档部分用练习工具 docstats 统计本仓覆盖率。

体系背景：性能数据在运行时里，不在外部工具里

Rust 采 CPU profile 要 perf（内核采样器）+ cargo flamegraph；查内存要 valgrind 或自定义 allocator。Go 把五种 profile 全塞进了 runtime 本身：调度器记 CPU 时间片、分配器记分配栈、goroutine 管理器记栈状态。net/http/pprof 一行 import，就是把这些内存里的计数暴露成 HTTP 端点。

这个差异的根源还是编译模型：Go runtime 掌控一切（栈、分配、调度），所以一切可测；Rust 的零成本抽象哲学把运行时降到最小，代价就是观测要靠 OS 级工具。

pprof：完整取证流程

import _ "net/http/pprof"   // 把 /debug/pprof 挂到 DefaultServeMux
go http.ListenAndServe("localhost:6060", nil)  // 单独端口！

# 1. 采：CPU 采 30 秒（采样期间在打负载）
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
# 2. 瞬时类不需要 seconds：heap/goroutine/block/mutex 都是快照
go tool pprof http://localhost:6060/debug/pprof/heap
# 3. 读：终端 top、web 火焰图、文本调用树
(pprof) top5
(pprof) web          # 需要 graphviz
go tool pprof -http=:8080 cpu.pb.gz   # 自带火焰图 tab
# 4. 对比：改完再采一份，-base 差分定位"这次改动省了什么"
go tool pprof -base=before.pb.gz after.pb.gz

五种 profile 的分工（实测本仓 httpkv 服务，Apple M4；驻留/累计两列是快照值，随运行时长漂移，复核 2026-10-13 同为 kB 量级）：

profile	回答的问题	采集方式	本仓实测
CPU	时间花在哪个函数	`profile?seconds=N`	端点实采成功
heap	现在驻留内存谁占的	快照	2680.94kB 总驻留
allocs	累计分配谁贡献的（GC 压力）	快照（含已释放）	5329.16kB 累计
goroutine	多少 goroutine、卡在哪	快照	采到
block/mutex	锁等待/阻塞时长	需 SetBlockProfileRate	低频场景才开

goroutine 快照实拍（idle 的 httpkv，7 个 goroutine 全是 runtime 自留）：

text

$ go tool pprof -top 'http://localhost:6060/debug/pprof/goroutine'
Showing nodes accounting for 7, 100% of 7 total
      flat  flat%   sum%        cum   cum%
         5 71.43% 71.43%          5 71.43%  runtime.gopark
         1 14.29% 85.71%          1 14.29%  runtime.sigNoteSleep

泄漏排查就是"预期 7 个，实测 700 个"的差值定位：goroutine 类 profile 的 cum 路径直接显示每个卡在哪一行。

取证纪律：先 allocs（分配大户 = GC 税源头，dnsproxi LESSON 读数 4 实证 mark assist 8.1 万次/3s，E5 trace），再 CPU，最后才 trace。 heap 看驻留、allocs 看流量，搞反了会盯着"驻留小但分配疯狂"的对象错过优化点。

top 实拍（httpkv + 20 并发 GET 压测 4 秒采样，真机输出）：

text

File: httpkv
Type: cpu
Duration: 4.11s, Total samples = 1.44s (35.06%)
      flat  flat%   sum%        cum   cum%
     0.86s 59.72% 59.72%      0.86s 59.72%  syscall.rawsyscalln
     0.14s  9.72% 69.44%      0.14s  9.72%  runtime.pthread_cond_wait
     0.12s  8.33% 77.78%      0.12s  8.33%  runtime.kevent

读法：flat = 函数自身耗时，cum = 含被调用的总耗时；优化 flat 高的 leaf 函数、cum 高的调度路径。这份 top 里 syscall 占 60%：低负载服务的 CPU 大头在系统调用与调度，说明"优化前先看采样在哪"比"凭直觉优化热点"可靠。（复核 2026-10-13：ab -n 200000 -c 20 打负载 4s 采样，rawsyscalln 57.46% flat、kevent 13.10%、 pthread_cond_wait 9.01%，三函数名与占比量级复现。）

dlv：断点调试器（真机会话节选）

pprof 回答"哪里慢"，dlv 回答"为什么算错"。非交互可用（CI/脚本加 --allow-non-terminal-interactive=true）：

text

$ dlv test ./exercises/p21test/ -- --test.run TestBackoffTable
(dlv) break p21test.Backoff
Breakpoint 1 set at 0x105124b60 for golearn/exercises/p21test.Backoff()
    ./exercises/p21test/retry.go:18
(dlv) continue
> [Breakpoint 1] golearn/exercises/p21test.Backoff() (hits goroutine(35):1) (PC: 0x105124b60)
(dlv) print base
100000000
(dlv) print attempt
0
(dlv) print cap
1000000000

注意 break add 会撞上 runtime 里一堆同名 add（ambiguous，真机报 Location "add" ambiguous: regexp.(*machine).add, runtime.(*addrRanges).add, runtime.add…），断点要写全限定名 包名.函数。vs Rust：rust-gdb/rust-lldb 裸 gdb/lldb， dlv 是懂 goroutine/chan 的专用后端。

lint 与 generate

go vet 是编译器附带的静态检查（printf 格式串、锁拷贝、 unreachable），CI 必开。比 clippy 弱在"项目级规则"，补位工具 golangci-lint：

yaml

# .golangci.yml（能直接用的最小配置）
linters:
  enable:
    - errcheck # 未检查的 error
    - gocritic # rangeValCopy/rangeExprCopy 查 for range 拷贝大结构（P3 的坑）
    - gofumpt # gofmt 严格版

go:generate 是"代码生成器的统一入口"（不是构建步骤）：

//go:generate stringer -type=Level
type Level int

go generate ./...   # 人手动跑，生成结果提交进 git

三条纪律（对照 Rust build.rs 的立场相反）：

生成物提交进 git（Rust 的 OUT_DIR 产物不提交，Go 相反： go build 不跑 generate，消费者不该被要求装工具）。
生成文件头写 // Code generated ... DO NOT EDIT.（工具自动加）。
go:generate 只管"源码到源码"，构建钩子用 make/脚本。

GODEBUG 与 GOEXPERIMENT

行为微调两层，管的粒度不同：

体系	管什么	粒度	例子
GODEBUG	运行时行为的兼容开关	每开关一个行为	`gctrace=1`、`asyncpreemptoff=1`
GOEXPERIMENT	编译器/runtime 实验特性	整个工具链重编译	`jsonv2`、`nogreenteagc`（T4 实测）

GODEBUG 的关键机制：默认值跟 go.mod 里的 go 版本走。module 声明 go 1.22，asynctimerchan 等就按 1.22 语义跑，哪怕用 1.26 工具链编译。这是 Go 兼容承诺：升级工具链不改行为，想用新语义就显式改 go.mod 或环境变量。全表在 $(go env GOROOT)/src/internal/godebugs/table.go（26+ 项）。

GOEXPERIMENT 是"未定型的未来"：默认关的实验（jsonv2，P19 实测编译都过不去）、默认开可退回的 baseline（greenteagc，T4 双跑 GOEXPERIMENT=nogreenteagc 可关）。生产二进制别带非 baseline 实验；排查"升级后行为差异"先查 GODEBUG 默认值表。

GODEBUG 也是"现场取证旋钮"（真机，schedtrace=500 每 500ms 打一行调度器账）：

text

SCHED 0ms: gomaxprocs=10 idleprocs=8 threads=4 spinningthreads=1
  needspinning=0 idlethreads=0 runqueue=1 [ 0 0 0 0 0 0 0 0 0 0 ]

（复核 2026-10-13：GOMAXPROCS=10 GODEBUG=schedtrace=500 短程序复跑，首行同样落在 gomaxprocs=10 idleprocs=8 threads=4 形态， runqueue/runq 槽位逐跑漂移属正常。注：Go 1.26 起该行尾部新增 schedticks=[…] 字段。）

一行读出 GMP 现状：10 个 P 只有 2 个在干活（idleprocs=8）、 4 个内核线程、全局队列 1 个待跑。排查"goroutine 堆积但 CPU 很闲"时这行就是第一手证据（P3 的 GMP 落到工具上）。

go.work：多模块工作区

monorepo 里两个 module 互相引用，没工作区就得推 tag 才能 go get 自己人的改动：

go work init ./exercises ./dnsproxi-go   # 生成 go.work
go work use ./labs                        # 增补（无 -add 这个 flag）

go.work 是本地开发文件，不提交（CI 不认它，CI 靠 require/ replace）。replace 也能解，但改的是 go.mod（污染其他人的构建）， go.work 不碰 go.mod。cargo workspace 要求共享一个 Cargo.lock， go.work 各 module 独立 go.sum（更松，代价是重复下载）。

本仓单 module 用不上；拆多 module 的时机是"子目录想有独立版本号" （dnsproxi-go 已是独立 module）。

文档工程：注释即文档

Go 把文档当编译产物同级：pkg.go.dev 每个包的页面就是源码注释的渲染结果，没有手写站点。三层设施：

doc comment 语法（1.19+ 规范）

// Package docstats 解析 Go 包的文档覆盖率。
//
// 导出符号里，带 doc 注释的比例。用法：
//
//	r, err := docstats.Dir("./some/pkg")
//	fmt.Println(r.Ratio())
//
// 详情见 [Result] 与 [Dir]。
package docstats

规则：注释以标识符名开头；空行分段；缩进一格以上是代码块； [Symbol] 是 doc link。渲染器是标准库 go/doc/comment（简化版 Markdown）。

Example 测试：文档里的代码是跑过的

func ExampleDir() {
    r, _ := docstats.Dir("./exercises/p1tool")
    fmt.Println(r.Documented() > 0)
    // Output: true
}

ExampleXxx 放 _test.go，go test 执行并比对 // Output:： 文档代码从此不可能悄悄烂掉。rustdoc 的 doctest 立场相同。

可编程访问：文档也是数据

go/parser + go/doc 把包解析成结构化文档对象，练习工具 docstats 就是用 AST 统计导出符号的文档覆盖率：

$ go run ./exercises/p22tool/cmd/docstats ./exercises/p1tool
pkg: 5/6 documented (83%), missing: NotFoundError.Error   ← 退出码 1
$ go run ./exercises/p22tool/cmd/docstats ./exercises/p22tool
docstats: 8/8 documented (100%), missing:                 ← 退出码 0

发布纪律：版本号与 v2 路径

git tag v1.2.3 && git push origin v1.2.3
# v2+ 必须改 module path（Go 硬规则）：
#   module example.com/foo/v2

三条：语义化版本强制（golang.org/x/mod/semver 可编程比较）；主版本 ≥2 必须写进 module path（同仓库共存 v1/v2）；go get pkg@none 移除依赖。Rust 的 cargo publish 是中心化注册表，Go 是去中心化（module path 即地址，proxy.sum 兜底完整性）。

动手：练习 p22tool（30-45 分钟）

cd golearn
go test -race -count=1 ./exercises/p22tool/     # 4 测试全绿
go run ./exercises/p22tool/cmd/docstats ./exercises/p22tool   # 100% → 0
go run ./exercises/p22tool/cmd/docstats ./exercises/p1tool    # 83% → 1
go build -ldflags "-X golearn/exercises/p22tool.Version=v0.1.0" \
  -o /tmp/docstats ./exercises/p22tool/cmd/docstats/
/tmp/docstats -version    # v0.1.0：ldflags 注入

预测题（跑之前写答案；预测错的地方才是认知边界）。四个测试的看点：TestDirRealPackage（包自己统计自己是 100%）、 TestDirUndocumented（临时包 3 缺 1 覆盖，断言 Summary 精确串）、 TestDirSyntaxError（语法错误必须浮出，不静默跳文件）、 TestEmptyPackage（无导出符号的包覆盖率按 1 算）：

docstats 对 exercises/p21test 统计，覆盖率是多少？缺失符号是哪几个（提示：t 参数类型算导出吗）？
把 Result 的 doc 注释删掉，-d 输出怎么变？退出码呢？
方法 Result.Exporteds 在统计里的键名是什么？为什么不是裸 Exporteds（godoc 站点上方法挂在类型名下）？
go.work 该不该提交？replace 呢？
go tool pprof 采 CPU，一个 idle 的服务（没请求）会采到什么？（提示：idle 采样 Duration 计满但 Total samples = 0。）
break add 在 dlv 里能设上吗？断点名要写什么形态？

观察验证：上面命令块每条输出都实拍过（退出码 0/1/2 与 P20 惯例一致）。四个测试看点：TestDirRealPackage（包自统计 100%）、 TestDirUndocumented（临时包 3 缺 1，断言 Summary 精确串）、 TestDirSyntaxError（语法错误必须浮出）、TestEmptyPackage （无导出符号按 1 算）。

改造题：给 docstats 加 -min 0.9 参数（低于 90% 退出码 1），接进你的项目 CI。

Take-away

pprof 五种 profile 分工：CPU 采样、heap 驻留、allocs 流量、 goroutine 快照、block/mutex 低频。取证顺序 allocs → CPU → trace，-base 差分是优化验证的标准动作。
lint：vet 必开，golangci-lint 补项目级规则；generate 产物提交 git，与 build.rs 立场相反。
GODEBUG 默认值跟 go.mod 版本走；GOEXPERIMENT 是未定型未来，生产别带非 baseline 实验。
go.work 本地不提交，replace 会污染 go.mod；拆 module 的时机是 "要独立版本号"。
文档三层：doc comment 规范、Example 测试（文档代码是测试用例）、 go/doc 可编程访问。发布三条：semver 强制、v2 进 path、tag 即发布。

章末参考

速查：本章命令

命令	用途
`go tool pprof -http=:8080 <profile>`	交互界面（火焰图）
`go tool pprof -base=a.pb.gz b.pb.gz`	差分
`go vet ./...` / `golangci-lint run`	静态检查
`go generate ./...`	跑 go:generate 指令
`go work init/use`	多模块工作区（不提交）
`go get pkg@v2.0.0` / `@none`	升级/移除
`gofmt -l .`	格式漂移检查

GODEBUG 常用五项（正文用过的加粗）

开关	包	作用
gctrace=1	runtime	每轮 GC 打一行摘要
containermaxprocs	runtime	1.25+ 容器内按 cgroup 限额取 GOMAXPROCS
asynctimerchan	time	1.23 计时器语义回退开关
gotypesalias	go/types	泛型别名语义
http2client	net/http	HTTP/2 客户端开关

Rust 对照总表

主题	Go	Rust
CPU 火焰图	pprof（内置）	cargo flamegraph（perf 依赖）
任务观测	goroutine profile	tokio-console
heap profile	内置	无内置（valgrind/dhat）
lint	vet + golangci-lint	clippy
代码生成	go:generate（产物提交）	build.rs（产物不提交）
文档	doc comment + pkg.go.dev	rustdoc + docs.rs
文档代码测试	Example	doctest
发布	tag + module path 即地址	cargo publish（中心化）
行为开关	GODEBUG（跟 go.mod 走）	edition + RUSTFLAGS

深读路径

doc comment 官方规范：go.dev/doc/comment
pprof：go doc runtime/pprof
module 发布：go.dev/doc/modules/publishing
GODEBUG 全表：$(go env GOROOT)/src/internal/godebugs/table.go

P22 · 工具链深潜与文档工程：从"能编译"到"能交付" ​

体系背景：性能数据在运行时里，不在外部工具里 ​

pprof：完整取证流程 ​

dlv：断点调试器（真机会话节选） ​

lint 与 generate ​

GODEBUG 与 GOEXPERIMENT ​

go.work：多模块工作区 ​

文档工程：注释即文档 ​

doc comment 语法（1.19+ 规范） ​

Example 测试：文档里的代码是跑过的 ​

可编程访问：文档也是数据 ​

发布纪律：版本号与 v2 路径 ​

动手：练习 p22tool（30-45 分钟） ​

Take-away ​

章末参考 ​

速查：本章命令 ​

GODEBUG 常用五项（正文用过的加粗） ​

Rust 对照总表 ​

深读路径 ​

P22 · 工具链深潜与文档工程：从"能编译"到"能交付"

体系背景：性能数据在运行时里，不在外部工具里

pprof：完整取证流程

dlv：断点调试器（真机会话节选）

lint 与 generate

GODEBUG 与 GOEXPERIMENT

go.work：多模块工作区

文档工程：注释即文档

doc comment 语法（1.19+ 规范）

Example 测试：文档里的代码是跑过的

可编程访问：文档也是数据

发布纪律：版本号与 v2 路径

动手：练习 p22tool（30-45 分钟）

Take-away

章末参考

速查：本章命令

GODEBUG 常用五项（正文用过的加粗）

Rust 对照总表

深读路径