Go types.Scope.Contains 为什么不能用行号直接判断

我在给 Go 源码分析工具加“当前节点属于哪个作用域”提示时，第一版很自然地把 AST 节点的行号拿出来比较：只要行号落在起止行之间，就认为 Scope.Contains 返回 true。这个基线看起来简单，遇到同一行的嵌套块、行尾边界和多文件位置后却会误判。

结论是：Scope.Contains 判断的是 token.Pos 是否位于作用域的源码区间，不接受“第几行”这种抽象值。官方文档还说明，作用域位置只有在类型检查后的 AST 具备完整位置信息时才保证有效。官方文档：https://pkg.go.dev/go/types#Scope

把 token.Pos 留给程序判断，把行号和列号留给日志、界面和报表。需要找最近作用域时，再使用 Innermost，不要把它退化成行号比较。

先区分 token.Pos、行号和作用域区间

我后来把排查记录拆成两个指标：判断输入是位置值，展示输出是行列值。token.Pos 是文件集合中的位置标识；它不是“第几行”，也不应该和 token.Position.Line 直接混用。Scope.Pos() 与 Scope.End() 描述作用域的源码范围，概念上是半开区间 [pos, end)。

行号比较最容易在三种场景失效：两个嵌套块共用一行；作用域结束符和目标节点处于同一行；多个文件各自从第一行开始计数。即使把行号和列号拼成坐标，也不如直接保留原始 token.Pos 稳定，因为作用域 API 的语义就是位置区间。

用 FileSet 把位置转换成可读行列

正确的做法是先用位置做判断，再在需要输出时转换。下面的辅助函数只负责展示位置，真正的范围判断仍使用 Contains：

package main

import (
    "fmt"
    "go/token"
    "go/types"
)

func containsAndDescribe(fset *token.FileSet, scope *types.Scope, pos token.Pos) bool {
    // Contains 接收原始 token.Pos；不要先取行号再比较。
    inside := scope != nil && scope.Contains(pos)
    if fset != nil && pos.IsValid() {
        // PositionFor 只把位置转换为日志可读的文件、行、列。
        p := fset.PositionFor(pos, false)
        fmt.Printf("位置=%s:%d:%d, within=%t\\n", p.Filename, p.Line, p.Column, inside)
    }
    return inside
}

这里的关键改动不是“换一种行号算法”，而是把判断和展示彻底分层：inside 是布尔范围结论，PositionFor 只是把同一个位置翻译成可读文本。多文件分析时，FileSet 也能保留文件名，避免跨文件只比较行号。

按半开区间和完整 AST 处理边界

第二版工具把边界写成可观察的对照：作用域起点包含在区间内，End() 对应的终点不再属于该区间。不要用“起始行 ≤ 目标行 ≤ 结束行”替换这个规则。

还要留意官方的前置条件：类型检查后的 AST 必须带有完整位置。如果解析阶段丢失了位置信息，或人为构造的节点没有有效 token.Pos，不能把 Contains(false) 当成可靠的“节点在作用域外”结论。

因此可以先做最小边界判断：

func scopeContains(scope *types.Scope, pos token.Pos) bool {
    // 无效位置不参与范围推断，避免把缺失位置信息当作作用域外。
    if scope == nil || !pos.IsValid() {
        return false
    }
    // Scope 的位置语义由 Pos/End 定义，Contains 负责执行同一规则。
    return scope.Contains(pos)
}

选择 Contains、Innermost 还是 LookupParent

我最后把三类需求分开，误判明显减少：

Contains 解决的是“范围”；Innermost 解决的是“最近的嵌套作用域”；LookupParent 还会沿父作用域查找，并可根据位置过滤尚未声明的对象。把这三者都写成行号比较，既丢失了嵌套关系，也无法表达声明先后。

常见问题

为什么同一行的两个代码块会让行号判断失效？

因为行号没有列和文件边界，两个块可以共享同一行；token.Pos 才能保留源码中的精确位置。

什么时候应该用 Innermost？

当目标是找“这个位置所在的最深一层作用域”时使用；如果只是验证一个已知作用域是否覆盖位置，使用 Contains 更直接。

需要判断声明是否在当前位置之前怎么办？

使用 LookupParent(name, pos)，不要自行遍历名字表再用行号过滤。

我的经验是：源码工具里凡是要做范围判断，都先保留原始位置值，把行列转换放到最后一层。这样做的改动很小，却能同时避开同一行嵌套、多文件和结束边界三类问题。