Go 1.27 go/scanner.Scanner.End 怎么定位 token 末端：起止位置与诊断范围

做 Go 源码检查器时，最容易出现一种“看起来只差一格”的问题：错误提示标到了标识符前面，或者高亮区域少了最后一个字符。很多实现只拿 Scanner.Scan() 返回的起点，再用 len(lit) 猜终点；遇到 Unicode 标识符、注释或自动插入的分号后，这个范围就不稳了。

Go 1.27 给 go/scanner.Scanner 增加了 End()。它返回最近一次扫描 token 之后的位置；第一次调用 Scan 之前则返回 token.NoPos。对于需要做诊断、高亮或局部重写的工具，最小可靠组合是“Scan 的起点 + End 的末端 + token.File.Offset 的字节偏移”。

诊断范围为什么会偏：起点有了，末端却靠猜

旧代码通常长这样：保存 pos 和 lit，然后把 pos 加上 len(lit)。这在纯 ASCII 标识符上可能暂时没问题，但它混合了两个不同坐标系：len(lit) 是 UTF-8 字节数，而诊断展示经常使用行列位置；对于非字面量 token，lit 还可能是空字符串，根本不能代表源码跨度。

另外，扫描器返回的是一个个 token。注释、关键字、运算符和自动插入的分号各有自己的跨度。工具真正关心的是“这一次 Scan 消费到哪里”，不是某个字符串字段有多长。

Scan 起点和 End 末端要放在同一条证据链

最小写法如下。示例只展示 API 的配合关系，不依赖某个特定项目目录：

func nextRange(src []byte) (token.Position, token.Position, token.Token, string) {
    fset := token.NewFileSet()
    file := fset.AddFile("snippet.go", fset.Base(), len(src))

    var s scanner.Scanner
    s.Init(file, src, nil, scanner.ScanComments)

    start, tok, lit := s.Scan()
    if tok == token.EOF {
        return token.Position{}, token.Position{}, tok, lit
    }

    end := s.End()
    return fset.Position(start), fset.Position(end), tok, lit
}

这里的关键不是函数名，而是 end := s.End() 必须紧跟在对应的 Scan 之后。End 说的是“最近一次扫描 token 的末端”，不会替你返回整个文件的末端，也不会根据下一次扫描自动保留历史范围。

把这条证据链写成完整 API 名称，就是 scanner.Scanner.Scan 产生 token.Pos start，scanner.Scanner.End 提供末端，再交给 token.File.Offset 转成诊断所需的字节边界。

如果工具需要做替换或高亮，位置对象还要落到字节下标。可以保留 token.Pos 参与行列展示，同时用 file.Offset(start) 和 file.Offset(end) 取出 src[startOffset:endOffset]。这样“屏幕上的行列”和“源码切片的字节区间”各自使用合适的坐标。

token.File.Offset 才是切片边界，别把列号当下标

token.Position.Column 适合给人读，token.File.Offset 适合访问 []byte。两者不能互换。尤其是中文标识符或字符串，列号与 UTF-8 字节偏移并不是简单的一一对应。

startPos, tok, _ := s.Scan()
if tok != token.EOF {
    endPos := s.End()
    startOffset := file.Offset(startPos)
    endOffset := file.Offset(endPos)
    tokenBytes := src[startOffset:endOffset]
    _ = tokenBytes
}

切片前要确保两次位置都有效，并确认 startOffset 。如果要输出错误行号，用 fset.Position 转换；如果要保存原文片段、生成补丁或计算哈希，使用字节区间更合适。

token.NoPos、Unicode 和 EOF 的边界

End 在尚未调用 Scan 时返回 token.NoPos。这不是源码的第一个位置，也不是可以传给 file.Offset 的普通坐标。初始化扫描器后先检查状态，别在“预览下一 token”的代码里提前计算范围。

Unicode 也不需要单独用 len(lit) 修补。扫描器和 token.File 共同维护的是源码字节位置；把 start 与 End() 交给同一个 token.File，再决定是显示行列还是切源码，就不会把字符宽度问题混进范围算法。

读到 token.EOF 时，当前调用已经完成了文件末端判断。通常不应把 EOF 当成要高亮的业务 token；如果工具要报告“文件尾缺少内容”，应单独建立 EOF 诊断位置，而不是把空的 lit 当成一个普通 token 范围。

扫描器返回 token 不等于源码完全正确

scanner.Scanner 的设计允许在遇到语法错误时尽量返回可用 token。于是“没有看到 token.ILLEGAL”并不能证明输入无错。初始化时可以传入错误处理函数，也可以在扫描结束后检查 ErrorCount。

var errors []string
var s scanner.Scanner
s.Init(file, src, func(pos token.Position, msg string) {
    errors = append(errors, fmt.Sprintf("%s: %s", pos, msg))
}, 0)

for {
    _, tok, _ := s.Scan()
    if tok == token.EOF {
        break
    }
}
if s.ErrorCount != len(errors) {
    // 以 ErrorCount 作为最终兜底核对项
}

范围和错误是两条数据：Scan 与 End 负责 token 边界，错误回调或 ErrorCount 负责语法状态。把两者混成“扫描到 token 就算成功”，后面做自动修复时很容易留下半截结果。

落地检查：把旧的长度计算换成位置核对

改造已有工具时，建议只检查几个具体点：是否在每次 Scan 后立即读取 End；是否始终使用同一个 token.File 转换偏移；是否把 token.NoPos 和 token.EOF 单独处理；是否仍保留错误回调或 ErrorCount 检查。

如果输出的是编辑器诊断，保存 fset.Position(start) 和 fset.Position(end)；如果输出的是补丁，保存 file.Offset(start) 与 file.Offset(end)。两套数据都来自同一个扫描结果，后续就能复查“显示范围”和“修改范围”是否一致。

常见问题

Scanner.End 返回的是当前 token 的最后一个位置吗？

它返回的是紧跟在最近一次扫描 token 后的位置，也就是常见半开区间的右边界。做切片时可以把它作为结束偏移，但展示时要按具体位置格式化。

第一次调用 End 为什么是 token.NoPos？

因为扫描器还没有消费任何 token。先调用 Scan，再读取 End；不要把 NoPos 传给 token.File.Offset。

有了 End 还需要检查 ErrorCount 吗？

需要。End 只说明最近一次扫描到哪里，不代表源码没有语法错误。工具仍应保留错误回调或检查 ErrorCount。

Go 1.27 的 Scanner.End 解决的是 token 末端定位，不是完整的语法诊断框架。把它和 Scan 的起点、token.File.Offset 的字节转换放在一起，再单独处理 NoPos、EOF 和错误计数，范围偏移这类小问题就有了清晰的复查边界。