成为全栈·Go 后端篇·三轮代码审阅之后：把可读性和证据做成工程规则

代码审阅不应只是给出一个分数或列一串偏好。有效审阅要指出可复现的问题、跟踪修复、用独立检查确认结果，也要允许实现者纠正报告里的技术依据。

审阅快照：提交 ceac4e0。三轮报告、回复及独立验证材料均保存在 docs/go-backend/review。

前言：审阅是工程活动，不是风格投票

三轮代码审阅下来，我改得最多的不是代码，而是态度------因为报告里有一条论证其实是错的，我得先证明它错，才敢不改。那条关于 go/doc 和 GOPROXY=off 的论证，我用源码实验重做了一遍。

M6 Go 后端经过三轮代码审阅。每一轮都提出风险、可读性和证据方面的意见。处理时没有把所有意见自动当成正确，也没有因为报告某处论证不准就否定整个审阅。我们将建议拆成具体主张：代码中是否存在相应行为？若存在会造成什么后果？修复是否改变契约？如何独立验证？

第三轮集中在领域文件可读性、Go 包说明、接口方法注释、模块路径和质量检查证据。处理结果包括重组部分领域代码、命名事务辅助函数、增加 AST 包说明检查和自检，并在回复中订正报告关于 go/doc 与 GOPROXY=off 的两处技术论证。

本文以审阅过程为例，说明怎样把审阅意见变成工程改进，而不是无条件迎合、逐条争辩或修改工具让报告变绿。

一、先把意见翻译成可验证命题

"文件太大"本身是评价；可验证问题可能是：一个文件是否同时承载不相关的业务规则？读者是否需要在多个状态机间切换？函数是否有可拆分且稳定的责任边界？把文件拆开后，调用顺序是否更容易定位？

"事务不清楚"则可以具体验证：事务在哪开启？锁对象是什么？写操作是否全部使用 tx？业务拒绝是否触发回滚？通知写失败时数据库后置状态如何？这些问题能沿代码和测试回答。

审阅问题可以分成四类：正确性/安全风险、项目约束与契约、维护性和可读性、个人偏好。前三类通常要落实或给出证据解释；个人偏好则结合工程约定和实际复杂度决定。分类不代表可以忽略低层意见，只是让改动理由和优先级清楚。

把三轮里几条真实意见摊开，翻译前后差别很明显：

原始意见	翻译成的命题	判据在哪
领域文件太大	一个文件是否同时承载不相关的业务规则？	按状态机切分，看一次变更要跨几个文件
事务不清楚	写操作是否全走 `tx`？业务拒绝是否回滚？	代码检索 + 故障注入后查库
包说明重复	同一个包是否有多份 package doc？	AST 遍历，按目录 + 包名分组
go/doc 只取一份说明	Go 的 reader 是否真的只读一份？	最小实验读源码，而不是查文档

最后一行是这轮最特别的：它不是"该不该改"，而是"这个说法对不对"。判断依据不在审阅工具的输出里，得回到标准库源码。

填不出第三列的意见，要么只是偏好，要么还没想清楚；两种都不该直接排进改动清单。

二、可读性改进要围绕业务概念

一次审阅指出领域文件包含多种业务变化，维护时需要在同一个文件中切换上下文。处理时没有为了每个函数单独建目录，而是按稳定概念拆成查询、变更、发现、目录等文件；事务辅助函数以调用者 tx 开头或以 Tx 收尾，让读者能从命名看出它不自行取得数据库连接或开启事务。

例如文章更新会在调用者事务中读取并锁文章、校验 owner、更新字段、同步标签、写通知。把 updateTx 明确标出来，可以向 reviewer 暴露事务所有权；若 helper 用全局 DB，自然更容易在代码审阅时发现事务逃逸。

拆分的目的不是文件更短这个数字。若多个小文件仍然让读者必须跳转十次才能理解一次状态变更，边界可能不合适。应以一条真实业务流程判断改动是否降低了上下文切换和误操作风险。

三、Go 包说明与独立 AST 门禁

第三轮采纳将包说明统一为中文、同一目录同一包只保留一份的项目约定，并补充对 WechatClient、Provider、Identity 等接口方法的职责说明。原报告建议的技术理由需要精确处理：重复包说明确实会让维护入口分散，但不能把某个审阅工具只显示一份的行为泛化成 Go 的 go/doc 永远只读一份。

项目添加基于 Go AST 的独立 doccheck，检查实际附着在 package 声明上的包说明，按相对目录与包名分组；缺失、重复或纯英文说明会失败。自检覆盖正常中文、同名包目录、重复、缺失和普通版权注释等合法/非法场景。

检查器的核心逻辑只有几十行，两段就够说明它在查什么：

go 复制代码

// 分组键是「目录 + 包名」，不是目录
key := filepath.ToSlash(filepath.Dir(relative)) + ":" + file.Name.Name
if file.Doc == nil {
	return nil                          // 没有说明不算问题，重复才算
}
packages[key].files = append(packages[key].files, filepath.ToSlash(relative))
if !strings.ContainsFunc(file.Doc.Text(), func(r rune) bool {
	return unicode.Is(unicode.Han, r)
}) {
	problems = append(problems, relative+": 包说明缺少中文")
}

// 收尾：一个包只允许一份说明
for key, docs := range packages {
	if len(docs.files) != 1 {
		problems = append(problems, fmt.Sprintf("%s: 包说明应为一份，实际 %d 份 %v",
			key, len(docs.files), docs.files))
	}
}

两个取舍值得说清楚。

分组键用了「目录 + 包名」 。同一目录下常常同时存在主包和 _test 包，只按目录分，两份说明会被算成"重复"然后误报。加上包名之后，internal/article 和 internal/article [article_test] 各算一组。

没有说明直接跳过，不算失败 。file.Doc == nil 就返回，因为这里要守的约束是"唯一"，不是"必须有"。真把"必须有"也加进来，加一个新文件就得先编一段话，门槛只会让人绕过检查。

这也就是它能力的边界：AST 能确认 package 声明上挂了几个 doc、里面有没有汉字，但判断不了这段话是否准确、是否解释了包在做什么。所以它能进 make verify，却不能替代读代码。

检查器有边界：检查含有汉字不能证明整段中文自然、说明准确或接口行为安全。语义判断仍需人工审阅。好的门禁针对机械可验证规则，不应冒充代码理解器。

四、不同意报告的论证时，保留可复核证据

第三轮回复纠正两处技术依据，但仍接受对应的工程建议。第一，报告认为 go/doc 普遍只取一份包说明；本地 Go 1.26.6 的 reader 会聚合多文件说明。回复保存 AST 实验源代码和输出，指出"只显示一处"是检查器的呈现行为，不能推广为 go/doc 规则。尽管理由不准确，统一说明仍有可读性价值，因此继续整改。

实验本身很小：两个文件、各挂一句 package 注释，跑两遍，一遍两份相同、一遍两份不同。

go 复制代码

for _, same := range []bool{true, false} {
	set := token.NewFileSet()
	var files []*ast.File
	for index := range 2 {
		text := "Package example 第一份中文说明。"
		if index == 1 && !same {
			text = "Package example 第二份中文说明。"
		}
		file, err := parser.ParseFile(set, fmt.Sprintf("file%d.go", index),
			"// "+text+"\npackage example\n", parser.ParseComments)
		if err != nil { panic(err) }
		files = append(files, file)
	}
	result, err := doc.NewFromFiles(set, files, "example")
	if err != nil { panic(err) }
	fmt.Printf("两份说明相同=%t，go/doc.Doc=%q\n", same, result.Doc)
}

输出把问题说完了：

text 复制代码

两份说明相同=true，go/doc.Doc="Package example 第一份中文说明。\n\nPackage example 第一份中文说明。\n"
两份说明相同=false，go/doc.Doc="Package example 第一份中文说明。\n\nPackage example 第二份中文说明。\n"

两份都被收进来，按换行拼接，一份没丢；内容相同时它也没有去重，照样拼两遍。所以"go/doc 只呈现一处"不成立------真正只显示一份的是那个审阅工具的扫描器，它按包取了第一条。

有意思的是结局：论据错了，结论对 。正因为 go/doc 会如实拼接，重复的包说明会真的让 go doc 输出两段同样的话，所以"一个包只留一份"这条整改仍然该做。纠正事实和采纳建议在这里并不冲突。

第二，GOPROXY=off 构建成功被描述成完整离线证明。它只表示本机缓存满足此次构建且模块代理关闭，不代表禁用了所有网络，或空缓存环境不需依赖下载。回复保留构建与 go mod verify 证据，同时限定结论。

反驳要带可复现材料，而不是用语气替代论证。报告中的结论、修改结果、工具边界与新增证据分别写清，留给下一轮独立评审继续检查。

五、静态门禁要公布失败范围

第三轮整改后，make verify、生产工艺门禁、自检和模块构建记录在案。生产门禁报告 13 项通过、0 项失败；缺陷注入自检 13 条全部捕获。包含测试源码的质量门禁仍有导出测试文档、测试包文档、函数长度和行长度等失败项，回复没有把"测试命令成功"误写成"含测试静态门禁全通过"。

四个口径各自覆盖哪些文件，摊开看就一目了然：

检查	结果	覆盖范围
生产工艺门禁	13 项通过 / 0 失败	`cmd`、`internal` 生产代码
缺陷注入自检	13 条全部捕获	门禁自身的灵敏度
含测试源码的质量门禁	有失败项	加上 `_test.go` 之后的全部 Go 文件
`make verify`	通过	gofmt、doccheck、vet、契约快照、go test

第三行和第四行的差别，正是要说清的那件事：make verify 通过，不等于把测试代码也算进去的静态检查也通过。两个口径覆盖的文件集不同，混着写就会得出"全部通过"的假结论。

这一区分非常重要。工程测试套件运行通过，和静态规范对全部测试代码无告警不是同一结论。若报告中保留失败，就要说明其范围、是否阻断发布，以及后续是否接受或计划修正，而不能把告警藏起来。

指标也不是本身的质量证明。AST 文件数、行数、函数数能辅助对比，却不能说明模块化已合理；自定义门禁可以被绕过或漏报，需通过缺陷注入检查其灵敏度。

六、跨多轮审阅管理代码基线

每轮都要绑定明确的源码提交，避免 reviewer 审阅的代码和回复所说的代码不一致。审阅报告、回复、整改结果和原始命令输出应一起归档。若后续有新的代码变化，应重新说明验证是否针对同一快照。

M6 在回复中明确哪些内容仅改注释、哪些新增开发期检查、哪些没有重跑。第三轮没有重跑旧有性能、三库、差分和客户端验收，就不把此前报告引用写成本轮重新执行。证据需要保留时间、环境、提交和命令，否则"以前跑通过"容易被误解成当前复核。

小结：接受建议和纠正事实可以同时成立

三轮审阅推进了代码领域边界、事务可见性、中文包文档、接口说明和独立检查；面对不准确论证，则用 Go 源码实验和构建边界纠正事实。整改没有改冻结契约或业务 SQL，也没有把所有静态测试失败包装为全绿。

收到代码审阅时，先把每条意见转换成命题，找到代码和行为证据，再决定修复、说明或反驳。最后按提交快照复跑适当检查，并记录未执行项。目标是让代码和理由都更可审阅，而不是让所有参与者说同一句话。

延伸阅读

如果这篇文章对你有帮助，欢迎订阅我的 CSDN 专栏 「成为全栈」：

🔗 专栏地址：https://blog.csdn.net/fungleo/category_13204651.html

📦 本系列配套代码仓库：https://github.com/fengcms/become-a-full-stack-developer