Go scanner.ErrorList 为空时怎样返回 nil 错误

在 Go 里收集扫描诊断时，空的 scanner.ErrorList 不应该直接作为 error 返回。推荐调用 list.Err()：列表为空时得到真正的 nil，列表非空时得到包含诊断信息的错误。这个方法正好把“有没有错误”和“如何显示错误”分开。

官方文档：https://pkg.go.dev/go/scanner#ErrorList.Err

先区分 ErrorList.Err 与 Error

scanner.ErrorList 的零值就是空列表。标准库为它提供了两个容易混淆的方法：Err 面向错误返回语义，Error 面向字符串格式化。前者检查列表长度，空列表返回 nil；后者即使列表为空，也可以返回描述文本。

因此，诊断函数的判断条件应建立在 Err 上，而不是比较 Error() 的结果。可以把两者的职责理解成：Err 把列表转换成调用方熟悉的 error，Error 只负责把已有列表写成可读文本。

在诊断函数中返回 list.Err

如果函数内部会累计多个扫描错误，最小写法是在结束时统一返回 list.Err()。这样无错误路径可以直接被调用方的 if err != nil 判断识别；一旦有诊断，列表本身仍保留为一个可格式化的错误。

package main

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

// scanSource 只演示错误列表到 error 的返回边界。
func scanSource(addError bool) error {
    var list scanner.ErrorList
    if addError {
        // Add 保存位置和消息，便于上层统一展示诊断。
        list.Add(token.Position{Filename: "input.go", Line: 3, Column: 7}, "示例诊断")
    }
    // 空列表返回真正的 nil，非空列表返回可继续处理的 error。
    return list.Err()
}

func main() {
    err := scanSource(false)
    if err != nil {
        // 只有存在诊断时才进入错误分支。
        fmt.Println(err)
        return
    }
    fmt.Println("扫描完成")
}

这里的关键不是把列表清空，而是让 Err 负责完成接口转换。非空时，返回值仍带有 ErrorList 的格式化能力；调用方可以直接打印，也可以把它继续包装进更高层错误。

避开 error 接口的动态类型陷阱

下面两种写法看起来接近，语义却不同：

var list scanner.ErrorList

// 直接赋值后，error 接口里仍保存着动态类型 scanner.ErrorList。
var wrong error = list

// 调用 Err 才会按列表长度返回真正的 nil。
var right error = list.Err()

fmt.Println(wrong == nil) // false：接口有动态类型，虽然列表长度为 0
fmt.Println(right == nil) // true：Err 返回了 nil 接口值

wrong 不是空接口，因为它包含一个动态类型和值；这个值只是一个长度为零的 ErrorList。它的 Error() 还可以返回 no errors，所以“能生成错误文本”不代表“应该进入错误分支”。right 则是 Err 根据长度做出的语义转换。

非空列表怎样保留诊断信息

当列表有一条或多条诊断时，Err 返回列表本身，而不是只返回第一条字符串。这样既能通过 error 接口向上传递，也能保留列表已有的排序、去重和格式化能力。是否调用这些辅助方法，应由诊断收集阶段的需求决定，不必为了返回 nil 而提前把错误信息拼成字符串。

func report(addError bool) error {
    var list scanner.ErrorList
    if addError {
        // 非空列表保留位置，调用方可以得到更具体的诊断文本。
        list.Add(token.Position{Filename: "config.go", Line: 8}, "字段格式不正确")
    }
    // 统一出口避免把空列表误当成非 nil 错误。
    return list.Err()
}

如果上层只需要记录一段文本，可以在确认 err != nil 后再格式化；如果上层需要区分多条诊断，则保留 ErrorList 的返回结果，不要过早调用 Error() 丢掉结构信息。

按场景选择返回形式

可以记住一句话：Error() 回答“怎么写出来”，Err() 回答“是否应该作为错误返回”。在扫描、解析或批量校验函数中，把 list.Err() 放在统一返回点，通常就是最清楚的边界。

常见问题

空 ErrorList 的 Error() 是 nil 吗？

不是。Error() 返回字符串；空列表的文本是 no errors。需要判断错误是否存在时，应使用 Err()。

非空 ErrorList.Err() 会只返回第一条吗？

不会。它返回包含诊断条目的列表错误，后续格式化仍由 ErrorList 自己完成。

为什么不能只写 var err error = list？

因为接口值保存了动态类型 scanner.ErrorList，即使底层列表长度为零，接口本身仍然不是 nil。用 list.Err() 才能得到与列表状态一致的返回值。