Go analysis.Pass.Reportf 怎样提交带源码位置的诊断

在 Go 静态分析里，想让诊断落到具体源码位置，关键不是把行号拼进字符串，而是把一个能由当前 Pass.Fset 解释的 token.Pos 传给 pass.Reportf。如果位置来自 AST，通常直接使用节点的 Pos()；如果检查的是原始文本，则先把文件和内容注册到同一个 token.FileSet，再用 LineStart 取得位置。

官方地址：https://pkg.go.dev/golang.org/x/tools/go/analysis#Pass

Reportf(pos, format, args...) 的职责可以拆成两部分：pos 提供源码锚点，格式化参数提供诊断消息。位置必须与 pass.Fset 属于同一套文件位置关系，否则消息即使生成了，也可能无法正确映射到文件、行和列。

• AST 检查：从节点的 Pos() 或相关 token 取得位置。
• 原始文本检查：用 FileSet.AddFile 和 SetLinesForContent 建立位置表。
• 提交诊断：调用 pass.Reportf(pos, "...", args...)。
• 排查异常：优先检查 FileSet 是否一致、位置是否为有效 token.Pos、文件内容是否匹配。

先分清 Pass、FileSet 与 token.Pos

analysis.Pass 是一次分析器处理一个 Go 包时拿到的工作上下文。官方文档列出的 Fset、Files、Pkg 和 TypesInfo 分别承载文件位置、语法树、包和类型信息。Reportf 并不自己猜测文件名，它只接收一个位置值，之后由驱动结合 Fset 解释。

因此，源码位置不是普通的整数行号。token.Pos 只有放在对应的 token.FileSet 中才有意义。可以把它理解为“位置表中的索引”，而不是独立携带文件名、行号和列号的对象。

type Analyzer struct {
	Name string
	Doc  string
	Run  func(*analysis.Pass) (any, error)
}

func run(pass *analysis.Pass) (any, error) {
	// pass.Fset 负责解释 AST 节点的 token.Pos。
	// pass.Reportf 负责把位置和格式化消息交给分析驱动。
	_ = pass.Fset
	return nil, nil
}

这个职责划分很重要：分析器决定“哪里有问题、提示什么”，驱动决定“怎样展示诊断”。诊断的位置字段相对于当前 Pass.Fset 解释，消息的严重程度也不是由 Diagnostic 统一规定的。

从 AST 节点调用 Reportf

最常见的写法是遍历 pass.Files 中的 AST，发现目标节点后取它的 Pos()，再把这个位置交给 Reportf。下面的示例检查函数调用是否使用了一个示例名称，重点在位置传递，不在规则本身。

package main

import (
	"go/ast"
	"golang.org/x/tools/go/analysis"
)

func reportCalls(pass *analysis.Pass) {
	for _, file := range pass.Files {
		ast.Inspect(file, func(node ast.Node) bool {
			call, ok := node.(*ast.CallExpr)
			if !ok {
				return true
			}

			ident, ok := call.Fun.(*ast.Ident)
			if !ok || ident.Name != "legacyCall" {
				return true
			}

			// ident.Pos() 属于 pass.Fset，驱动可以把它映射回文件和行列。
			// %s 把规则名称写入消息，便于同一分析器区分多个提示。
			pass.Reportf(ident.Pos(), "请替换旧调用 %s", ident.Name)
			return true
		})
	}
}

这里的关键只有一行：pass.Reportf(ident.Pos(), ...)。第一个参数是位置锚点，后面的字符串和参数按照 fmt 风格生成消息。不要先把行号写进消息再传一个无关位置；那样展示文本和驱动定位会出现两套来源。

用节点的不同位置表达问题焦点

一个 AST 节点往往有起点和结束位置。选择哪个节点的 Pos()，取决于读者看到提示后首先要修改哪里。比如，规则针对函数名，就使用 *ast.Ident 的位置；规则针对整个调用表达式，可以使用 *ast.CallExpr 的位置。

func reportArgument(pass *analysis.Pass, call *ast.CallExpr) {
	if len(call.Args) == 0 {
		// CallExpr.Pos() 指向调用表达式的起点，适合提示“调用缺少参数”。
		pass.Reportf(call.Pos(), "调用至少需要一个参数")
		return
	}

	arg := call.Args[0]
	// 参数节点的位置比调用起点更聚焦，读者可以直接定位到需要修改的表达式。
	pass.Reportf(arg.Pos(), "第一个参数不应使用动态值")
}

本文只讨论 Reportf 的单点位置。若规则必须表达从起点到终点的范围，应结合分析包提供的范围型报告能力；不要为了模拟范围而在消息里手工拼接“第几行到第几行”。无论选择哪种报告方式，位置都必须来自同一套文件位置关系。

为原始文本建立位置映射

并非所有分析器都只看 AST。官方文档给出的思路是：先读取文件内容，再向 FileSet 添加一个文件，用 SetLinesForContent 设置行边界，最后用 LineStart 把目标行转换成 token.Pos。

func reportRawLine(pass *analysis.Pass, filename string, content []byte, line int) error {
	if line  tf.LineCount() {
		return fmt.Errorf("行号超出文件范围")
	}

	// LineStart 返回该行的 token.Pos，位置仍然属于 pass.Fset。
	pos := tf.LineStart(line)
	pass.Reportf(pos, "原始文本第 %d 行需要检查", line)
	return nil
}

上面的示例使用了 fmt.Errorf，因此完整文件需要导入 fmt 和相关位置类型等实际依赖；示例的核心是位置映射链路。传入的 content 必须就是待分析文件的字节内容，否则行起点会和实际文本错位。

SetLinesForContent 只解决“哪些字节是每一行的起点”，不会替你判断业务规则，也不会把错误的文件名自动纠正。文件名、内容长度、行号和当前 FileSet 应该来自同一次分析上下文。

让消息和源码位置各司其职

Reportf 的格式化消息应该告诉读者为什么这里值得关注，源码位置则告诉驱动把提示放在哪里。两者不要互相替代。一个好的消息可以包含规则名称、实际值和期望值，但不需要重复完整路径或人为编码行列号。

func reportName(pass *analysis.Pass, name *ast.Ident, want string) {
	if name.Name == want {
		return
	}

	// 位置指向具体标识符，消息只说明现值和期望值。
	pass.Reportf(name.Pos(), "名称 %q 不符合约定，期望 %q", name.Name, want)
}

如果调用方把 token.NoPos 或来自另一套 FileSet 的位置传入，驱动就无法像处理当前 AST 节点那样稳定地恢复文件和行列。遇到“有消息但没有文件位置”的现象，先回到位置来源，而不是继续增加消息文本。

诊断位置为空或跳行时怎样排查

1. 确认位置来源。 AST 检查应优先使用当前 pass.Files 中节点的 Pos()，不要缓存其他包或其他解析过程产生的位置。
2. 确认 FileSet 一致。 pos 必须能够由 pass.Fset 解释；原始文件映射也要调用这个 FileSet 的 AddFile。
3. 确认内容与长度。 SetLinesForContent 接收的字节内容应和文件内容一致，不能先改写内容再沿用旧行号。
4. 确认行号边界。 原始文本的行号从 1 开始，调用 LineStart 前要拒绝小于 1 的值，并按规则处理超出文件行数的输入。
5. 确认报告焦点。 如果提示总是落在调用开头，检查是否传入了外层节点的 Pos()，而不是目标标识符或参数节点的位置。

这套排查顺序对应了位置从“来源”到“解释”的完整链路：节点或文件内容产生位置，FileSet 保存映射，Reportf 组合消息，分析驱动再负责呈现。只改字符串通常解决不了位置缺失。

常见问题

Reportf 的第一个参数是普通行号吗？

不是。它是 token.Pos，必须放在能由当前 Pass.Fset 解释的文件位置集合中。AST 场景通常从节点的 Pos() 取得，原始文本场景则先建立文件映射。

为什么消息里已经写了行号，驱动仍然没有定位？

消息文本不会替代诊断的位置字段。应把真实的 token.Pos 传给 Reportf，行号只作为消息中的补充信息，而不是唯一定位依据。

可以把另一个解析器的 Pos 直接传给 Reportf 吗？

不要这样做。位置值必须和当前 pass.Fset 的文件集合匹配；如果内容来自另一套位置表，应重新在当前 FileSet 中建立映射。

AST 节点应该取哪个 Pos？

取最接近读者修改目标的节点。规则针对函数名就使用标识符位置，规则针对整个调用就使用调用表达式位置，消息则解释具体原因。

总结一下：analysis.Pass.Reportf 的位置参数不是装饰信息，而是诊断能否落到源码的锚点。AST 检查从当前节点取得 Pos()，原始文本检查通过 FileSet 建立行起点，再把这个位置和清楚的格式化消息一起提交。只要始终维护“位置属于哪个 FileSet”这条关系，诊断位置就更容易稳定、可读、可排查。