本文永久链接 – https://tonybai.com/2026/11/19/go-test-user-defined-analyzers-proposal

大家好,我是Tony Bai。

【导读】

Go 的 go test 命令一直内置着一组静态分析检查,也就是我们熟悉的 go vet。但如果一个项目希望在测试时自动运行自己的静态分析器,例如检查项目特有的编码规范、资源配对规则,或者业务领域中的潜在错误,应该怎么办?

目前,Go 工具链并没有提供一种标准、统一的方式,让项目直接声明这些自定义 Analyzer,并让 go test 自动执行它们。

近日,Go 团队核心成员 Alan Donovan 提出了一个新的 Proposal:让 go test 能够运行由工作区或模块声明的自定义静态分析器。

这项提议看起来只是给 go test 增加一个能力,但它实际上触及了 Go 静态分析工具链的组织方式、项目级代码质量规则,以及未来 Go 开发工具之间的协作边界。

【文章要点】

  • 打破 go test 内置检查的藩篱:改变过去分析器完全由工具链写死的现状,允许项目和公共库自主声明静态分析规则,将项目专属的编码规范与架构约束原生融入日常单测循环;
  • 从源码注释演进为 go.vet:方案历经多轮社区攻防,摒弃了早期侵入源码的 goanalysis.go 注释方案,最终收敛为支持目录级自治、精确范围控制与快速禁用的独立配置文件 go.vet;
  • 深植生态并实现高效并行:继续基于成熟的 go/analysis 抽象,分析器按依赖关系构建为执行任务图,与单元测试并行跑通并深度复用 Go 构建缓存;
  • 明确 Go 静态分析的三层定位:Alan Donovan 首次清晰划分职责——内置 go vet 负责全语言基础底线、go.vet 承载模块自身强制规则、gopls 满足开发者个性偏好,将静态分析升维为针对源码结构的“静态测试”;
  • 积极争取 Go 1.28 实验尝鲜:作者已正式申请 Go 1.28 的 freeze exception(拟通过 GOEXPERIMENT=vetfiles 开启),期望尽早收集真实反馈;该机制未来有望成为 AI Coding Agent 获得实时工程约束反馈的关键基础设施。


为什么 go test 需要运行自定义 Analyzer?

在 Go 项目中,我们通常使用下面的命令运行测试:

go test ./...

除了执行测试函数,go test 还会运行一部分静态分析检查。这些检查来自 Go 内置的 go vet 分析器集合,用于发现一些编译器无法发现、但又很可能是程序错误的问题。

例如:

  • printf:检查 fmt.Printf 等格式化函数的格式字符串与参数是否匹配;
  • copylocks:检查是否意外复制了包含锁的值;
  • loopclosure:检查循环变量闭包引用等潜在问题。

这些检查很有价值。它们能够在代码运行之前发现问题,而且随着 go test 一起执行,开发者不需要额外记住一条命令。

但问题在于:项目自己的静态分析规则怎么办?

假设一个大型 Go 项目有一些特殊约束:

  • 每次调用 Lock,都必须有对应的 Unlock;
  • 每次调用 AddRef,都必须有对应的 DecRef;
  • 某些资源申请和释放函数必须成对出现;
  • 某些内部 API 不允许在特定目录或调用链中使用;
  • 项目希望强制执行自己定义的架构约束。

这些规则往往无法通过 Go 编译器直接检查。即使能写出对应的 go/analysis Analyzer,目前也需要开发者单独构建、配置和运行它们。

常见的解决方式包括:

  1. 在 CI 中单独执行自定义分析器;
  2. 使用 golangci-lint 等工具统一运行;
  3. 编写额外的脚本,把静态分析步骤接入项目流水线。

这些方式都能解决问题,但也带来了一些额外成本:开发者需要知道应该运行哪些工具,CI 需要维护独立配置,而且本地开发与 CI 环境可能出现规则不一致。

Alan Donovan 关注的正是这个问题:

能不能让项目直接声明需要运行的 Analyzer,然后让 go test 自动执行它们?

这样,静态分析就可以像普通测试一样,成为项目开发流程中默认的一部分。

Proposal 的演进:从 goanalysis.go 到 go.vet

Alan Donovan 最初提出的方案,是通过一个名为 goanalysis.go 的文件声明项目需要运行的 Analyzer。

这个文件使用 Go 代码描述分析器及其适用范围,并通过类似 //go:analyze 的声明表达具体配置。

初始方案希望支持不同的分析范围,例如:

  • 当前目录;
  • 当前目录及其子目录;
  • 当前模块的所有导入者。

这样的设计有一个明显优势:项目可以在代码仓库内部维护分析器配置,不需要额外依赖某个外部工具的配置文件格式。

不过,方案很快引发了社区讨论。

为什么不直接放进 go.mod?

Ian Lance Taylor 对最初方案提出了一个值得关注的问题:为什么需要引入一个新的 Go 源文件来声明分析器?能否直接把这些配置放进 go.mod?

毕竟,模块依赖和项目级构建配置本来就集中在 go.mod 中。如果分析器也是项目依赖和构建流程的一部分,将其放在这里似乎更自然。

Alan 对此作出了解释。

他更倾向于使用独立文件,主要考虑的是目录自治和配置管理问题。

Go 项目可以包含多个目录,每个目录可能有自己的分析需求。将配置放在独立文件中,可以让规则跟随代码所在目录,而不必把所有配置集中到模块根目录。

此外,独立文件也更容易表达目录级别的分析范围,并与 Go 模块依赖管理机制保持相对独立。

这场讨论实际上涉及一个更深层的问题:

项目级静态分析规则究竟应该属于模块配置,还是应该属于代码目录本身?

Mk.5:最终走向 go.vet

在后续讨论中,Alan 持续调整方案。

到 Mk.5 版本,配置文件的名称已经从最初的 goanalysis.go 调整为 go.vet。

这意味着项目可以通过一个专门的文件声明需要执行的静态分析器,而不必将配置写成普通 Go 源文件。

Mk.5 方案还引入了更明确的启用和禁用机制。

例如,可以通过类似下面的配置启用分析器:

enable . "myAnalyzer"

也可以禁用某个分析器:

disable . "printf"

这里的 . 表示配置适用的范围,后面的字符串则指定 Analyzer 的名称。

除了启用和禁用,方案还考虑了不同的分析作用域,以及如何在项目中组织这些规则。

Alan 还增加了调试相关的选项,例如:

go test -debug-vetconfig

用于查看最终生效的分析配置;以及分析性能相关的调试能力,帮助开发者理解分析器的执行情况。

从方案演进来看,Alan 并不是简单地把一组第三方分析器塞进 go test,而是在尝试为项目建立一种标准化的静态分析配置机制。

它准备如何工作?

这项 Proposal 的核心,是让 go test 能够识别项目中的 go.vet 文件,并根据其中的声明找到需要执行的 Analyzer。

整体过程可以概括为:

这里有几个值得关注的设计点。

Analyzer 仍然基于 go/analysis

Proposal 并没有另起炉灶设计一套静态分析 API,而是继续使用 Go 生态中已经广泛采用的 golang.org/x/tools/go/analysis 框架。

一个 Analyzer 通常通过 analysis.Analyzer 结构体描述自身:

var Analyzer = &analysis.Analyzer{
    Name: "myAnalyzer",
    Doc:  "check project-specific rules",
    Run:  run,
}

Analyzer 可以声明自己依赖的其他 Analyzer,也可以通过 Requires、FactTypes 等机制组织分析过程。

这意味着现有基于 go/analysis 开发的静态分析器,有机会直接进入这套机制。

分析器可以形成依赖关系

Analyzer 并不总是孤立运行的。

一个分析器可能依赖另一个分析器的结果。例如,某个分析器需要先获取类型信息,或者需要其他分析器提供的事实数据。

因此,执行系统不能只是简单地遍历配置文件中的 Analyzer 列表,然后逐个调用。

它需要理解分析器之间的依赖关系,并组织成一个任务图。

这种任务图也为并行执行和缓存提供了基础。

分析与测试的协作

这项设计希望将静态分析自然地融入 go test 的执行流程。

从开发者视角看,依然只需要执行:

go test ./...

而不必再记住一组额外的静态分析命令。

这也意味着项目可以把自定义静态分析规则纳入日常测试和 CI 流程,让每次代码修改都接受相应的静态检查。

当然,具体的执行顺序、任务调度、缓存和错误处理等实现细节,仍然需要结合后续设计文档和实现进一步观察。

这项 Proposal 与 go/analysis 标准化有什么关系?

值得注意的是,#82464 并不是孤立出现的。

Alan Donovan 还提出了另一个相关 Proposal:#82465,希望将 go/analysis 中的核心 API 纳入 Go 标准库。

两项提议之间存在明显的关联:

  • #82465 关注静态分析 API 的标准化;
  • #82464 关注如何让 Go 工具链直接使用这些 Analyzer。

如果两项提议都能推进,Go 静态分析生态就可能出现一个重要变化:

Analyzer 不再只是某个外部工具的插件,而是能够成为 Go 项目本身可以声明、组织和执行的一等开发工具。

不过,这两项 Proposal 的推进节奏和最终设计仍需分别观察,不能简单地将它们视为一个已经确定的整体变更。

最新进展:Alan 进一步解释了这项设计的长期定位

截至 2026 年 11 月 18 日,#82464 已经不只是一个初步的设计提议。Alan Donovan 已公开设计文档草稿,持续回应社区反馈,并开始推动实验性实现。

最近的评论中,有几处值得特别关注。

设计文档已经公开征求意见

11 月 6 日,Alan 表示已经准备好设计文档初稿,并邀请社区对设计提出意见。

这意味着讨论已经从最初的方案探索,进一步进入相对系统的设计评审阶段。

在后续讨论中,社区还提出了一些很实际的问题。

例如,能否将多个 Analyzer 打包成一个可复用的分析套件?

Alan 的回答是:可以通过 Go 包导出一个 Analyzer 列表,其他项目依赖这个包,再在自己的 go.vet 文件中选择全部或部分 Analyzer。

例如,某个分析套件可以导出:

var MySuite = []*analysis.Analyzer{
    analyzerA,
    analyzerB,
    analyzerC,
}

项目可以根据需要选择整个套件,也可以只选择其中一部分。

但 Alan 也指出,直接依赖一个庞大的 Analyzer 套件可能带来依赖膨胀:项目可能因此引入并不需要的重量级分析器。

所以,他更倾向于让项目在本地按需选择 Analyzer,而不是鼓励所有项目都依赖一个大而全的套件。

Analyzer 的配置能力不会无限扩张

社区还讨论了能否在 go.vet 中配置每个 Analyzer 的 Flags。

Alan 对此并不热衷。

原因在于,不同的分析器驱动程序可能拥有不同的配置方式:命令行工具、gopls 和 staticcheck 都有自己的配置机制。如果 go.vet 再试图统一管理这些配置,反而可能让用户面对一套更加复杂、难以理解的配置体系。

另外,Analyzer 的 Flags 也可能与并发执行产生冲突。

这说明 Alan 希望这项 Proposal 聚焦于一件事情:声明项目需要运行哪些 Analyzer,以及它们适用于什么范围。

至于每个 Analyzer 的具体参数配置,暂时不打算让这套机制承担。

为什么不把 Analyzer 简化成普通函数?

社区还提出过一个 API 层面的建议:能否将 *analysis.Analyzer 结构体简化成普通函数,类似 Go 测试中的:

func TestX(t *testing.T)

Alan 表示,他确实考虑过这种可能性,但最终认为收益有限。

一个 Analyzer 不只是一个执行函数。它还需要声明自身的名称、文档、依赖关系、Fact 类型等元数据。

如果将这些信息放进特殊注释或者其他隐式机制,反而不如现有的类型化结构体字段清晰。

更重要的是,Go 生态中已经存在大量基于 analysis.Analyzer 的分析器。为了省掉少量定义代码而改变现有 API,代价并不值得。

因此,保留现有 analysis.Analyzer 结构体仍然是更合理的方向。

Alan 解释了 Go 静态分析的三层定位

我认为,最近讨论中最有价值的一条,是 Alan 对 Go 静态分析工具定位的解释。

社区有人提出了一个现实问题:Go 生态已经有 go vet、gopls、staticcheck、golangci-lint 等工具,它们之间存在一定的功能重叠。为什么还要让 go test 承担更多静态分析职责?

Alan 的回答并不是简单地强调工具整合,而是给出了一个分层思路:

使用者 静态分析机制 关注点
Go 项目整体 Go 内置的 go vet 分析器集合 所有 Go 项目都应该接受的基础检查
Module 维护者 本 Proposal 引入的 go.vet 项目自身希望强制执行的静态分析规则
个人 Go 开发者 gopls 分析器集合及个人配置 开发者自己的编码习惯和偏好

这个划分很有启发性。

Alan 还解释了为什么静态分析应该进入 go test。

他认为,现有的动态测试可以看作行为测试(behavior tests),而新增的静态分析器则可以看作源代码层面的静态测试(static tests)。

例如,一个项目要求每次调用 Lock 都必须对应 Unlock,每次 AddRef 都必须对应 DecRef,或者某个 push 操作必须与 pop 操作配对。

这类规则如果只依靠动态测试,很难保证所有执行路径都被覆盖;但静态分析器可以直接检查源代码结构,并在每次代码修改时自动运行。

这类能力不仅对大型企业项目有价值,对个人项目同样有价值。

Alan 还提到,他希望未来 gopls 和 go vet 也能够执行工作区声明的 Analyzer。不过,这引出一个重要问题:运行项目自己声明的分析器,本质上涉及信任边界和安全问题。

例如,用户打开一个陌生仓库时,是否应该允许仓库中的配置自动触发任意 Analyzer?

这需要进一步考虑用户授权和信任机制。Alan 认为,这个问题不应该阻碍 go test 先支持项目级 Analyzer。

Alan 开始争取 Go 1.28 的 freeze exception

11 月 17 日,Alan 又提出了一个值得关注的请求:申请 Go 1.28 的 freeze exception。

他的目标是让这项实验性功能能够提前约六个月交到用户手中,让开发者有机会在正式定型之前试用并反馈。

为了降低风险,当前实现计划由:

GOEXPERIMENT=vetfiles

控制。

也就是说,相关功能默认不会影响普通 Go 用户的生产行为。只有显式启用实验开关,才会进入相应的代码路径。

Alan 还表示,为了隔离实验性实现,相关代码会尽可能放在独立文件中,并通过实验开关控制。

他的期望是在 freeze 之前完成主要实现,之后主要处理 bug。

这里需要特别说明:截至 2026 年 11 月 18 日,这仍然是 Alan 提出的 freeze exception 申请,并不代表申请已经获批,更不代表该功能已经确定进入 Go 1.28。

目前 #82464 仍处于 Open 状态,带有 Proposal 和 Analysis 标签。

不过,从设计文档公开、社区讨论持续推进,到 GOEXPERIMENT=vetfiles 实验开关及相关实现 CL 的出现,这项提议显然已经从概念讨论走向了实际工程验证。

小结

我认为,#82464 值得关注的地方,并不只是 go test 将来可能多运行几个静态分析器。

它背后反映的是 Go 工具链的一种演进方向:让项目能够以标准化的方式声明自己的代码质量规则,并将这些规则融入开发者每天都会执行的工作流。

过去,一个团队想要强制执行某些代码规范,往往需要自己维护一套 lint 工具链、CI 配置和开发文档。即使规则已经写成了 Analyzer,也不意味着每个开发者都会在本地及时运行它。

如果未来 go test 能够直接识别项目的 go.vet 配置,那么项目级静态分析就有机会像普通测试一样,成为 Go 开发流程中默认的一部分。

这对 AI Coding Agent 时代也有特别的意义。

当越来越多的代码由 AI Agent 生成时,单纯依赖代码评审和测试用例,可能不足以约束代码生成过程中的细节。项目可以通过自定义 Analyzer,把一些难以通过测试覆盖的约束显式化,让工具在每次修改后自动检查。

例如,资源配对、API 使用约束、内部架构规则等,都可以成为项目自己的静态检查规则。

当然,Proposal 仍在讨论中,最终设计、配置格式和执行机制都可能继续调整。Go 1.28 的 freeze exception 也还只是申请。

但无论最终方案如何演进,Go 工具链开始认真考虑如何让项目级静态分析成为标准开发体验,这本身就是一个值得关注的信号。

当代码越来越容易生成,如何让项目的工程约束自动、持续地得到执行,可能会成为下一阶段 Go 工具链演进的重要方向。

参考资料:


还在为写 Agent 框架频频死循环、上下文爆炸而束手无策?我的新专栏 《从0 开始构建 Agent Harness》 将带你:

  • 抛弃臃肿框架,回归“驾驭工程 (Harness Engineering)”的第一性原理
  • 用 Go 语言手写 ReAct 循环、并发拦截与上下文压缩引擎等,复刻极简OpenClaw
  • 构建坚不可摧的 Safety Middleware 与飞书人工审批防线
  • 在底层实现 Token 成本审计、链路追踪与自动化跑分评估
  • 从“调包侠”进化为掌控大模型边界的“AI 操作系统架构师”

扫描下方二维码,开启从 0 开始构建Agent Harness 的实战之旅。


你的Go技能,是否也卡在了“熟练”到“精通”的瓶颈期?

  • 想写出更地道、更健壮的Go代码,却总在细节上踩坑?
  • 渴望提升软件设计能力,驾驭复杂Go项目却缺乏章法?
  • 想打造生产级的Go服务,却在工程化实践中屡屡受挫?

继《Go语言第一课》后,我的《Go语言进阶课》终于在极客时间与大家见面了!

我的全新极客时间专栏 《Tony Bai·Go语言进阶课》就是为这样的你量身打造!30+讲硬核内容,带你夯实语法认知,提升设计思维,锻造工程实践能力,更有实战项目串讲。

目标只有一个:助你完成从“Go熟练工”到“Go专家”的蜕变! 现在就加入,让你的Go技能再上一个新台阶!


商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求,请扫描下方公众号二维码,与我私信联系。