S09-A18 · nil 接口不等于 nil：一个类型系统的小裂缝

一段代码判断 if err != nil { return err }，而调用方却收到了"非 nil 的 nil 错误"——err != nil 为真，但 err.Error() 里是空指针。原因是函数返回的是 (*MyError)(nil) 赋给 error 接口，接口本身非 nil（有类型、无值）。

这是 Go 里最经典的一个陷阱，而它的根源不是"设计缺陷"，而是接口的二元表示：类型 + 值。这个"二元表示"在语言规范里写得很清楚，但在类型转换的瞬间几乎看不出来：return e 这一行既可能是"返回一个值"，也可能是"把一个 nil 指针装进接口"。
两者任一非空，接口就非 nil。

1. 接口值的两个分量

分量	含义
动态类型（type）	具体类型
动态值（value）	该类型的值

接口等于 nil，当且仅当两个分量都为空。所以 (*T)(nil) 赋给接口后，类型分量非空，接口就不是 nil。

这个规则本身很清晰，问题在于代码里看不出来而 Go 的接口是"隐式实现"的，所以"这个类型实现了哪个接口"也不写在代码里——两件事叠加，让这类 bug 的定位成本很高。
：return nil 与 return (*T)(nil) 在阅读时几乎无法区分。

// 反例：函数返回 (*MyError)(nil)，接口非 nil
func do() error {
    var e *MyError = nil
    return e                       // 返回的 error 接口：type=*MyError, value=nil
}
if err := do(); err != nil {       // true！但 err.Error() 会 panic
    return err
}

// 正解：返回字面 nil
func do() error {
    var e *MyError = nil
    if e == nil { return nil }      // 显式返回 nil
    return e
}

2. 三种常见触发形态

形态	表现
返回具体指针类型	`return e`（e 为 nil 指针）
包装错误时保留类型	`fmt.Errorf("%w", e)`（e 为 nil）
结构体字段是接口	赋了 nil 指针

第三种（结构体字段是接口）在"依赖注入"时常见：注入了 nil 的具体实现（指针），而字段类型是接口，于是 if s.dep == nil 不成立，调用时 panic。
第二种值得展开：fmt.Errorf 在 %w 参数为 nil 指针时不会返回 nil，而是返回一个"包装了非 nil 接口"的错误。而 errors.Is 会走到那个 nil 指针上，可能 panic。

// 反例：nil 指针被包装
var e *MyError = nil
err := fmt.Errorf("wrap: %w", e)     // err != nil，但内部是 nil 指针
// 正解：先判空再包装
if e != nil { err = fmt.Errorf("wrap: %w", e) }

3. 怎么系统地避免

做法	效果
返回前显式判空	最直接
用 `error` 而非具体类型做返回值	类型与接口一致
单元测试断言 `err == nil`	能抓住
静态检查（`nilness`）	提前发现

第一项是最实用的：**只要函数返回 error，就不要 return e（e 是具体指针）**第一项的"自动化"方式很直接：约定"返回 error 的函数不许 return 具体指针"，靠 lint 或评审执行。这类"约定 + 检查"比"记住规则"有效得多。
，而是 if e != nil { return e }; return nil。

第二项从根上消除：函数签名就用 error，而不是 *MyError，于是不存在"指针赋给接口"这一步。

第四项的收益很高：go vet 的 nilness 分析能报出"把 nil 指针赋给接口"的模式，把它加进 CI 就长期免疫。

// 静态检查（能抓住大部分）
go vet ./...                      # 默认包含部分 nilness 检查
staticcheck ./...                 # SA4023: 与 nil 比较的接口可能恒真/恒假

4. 与 `errors.Is/As` 的交互

场景	结果
包装链里有 nil 指针	`Is/As` 可能 panic
自定义 `Is` 方法未判空	panic
`As` 到 nil 指针	返回 false（安全）

第二项（自定义 Is）的坑在于"它在链的中间"：调用方不知道链上有没有坏值，于是每个 Is 都要防 nil——而这很容易漏。
第一项的风险在"链上有坏值"：一次错误的包装会让后续所有判定都不安全。所以"包装前判空"是硬规则。

第二项在自定义错误类型里常见：func (e *MyError) Is(target error) bool 里直接访问 e.Code，而 e 可能是 nil。

// 自定义 Is 必须防 nil
func (e *MyError) Is(target error) bool {
    if e == nil { return false }        // 关键
    t, ok := target.(*MyError)
    return ok && t != nil && e.Code == t.Code
}

还有一个"反射"层面的相关问题：reflect.ValueOf(x).IsNil() 对非 nil 接口里的 nil 值返回 true，而 x == nil 返回 false。两者不一致，是同一个陷阱的另一种表现。

var e *MyError = nil
var err error = e
fmt.Println(err == nil)                    // false
fmt.Println(reflect.ValueOf(err).IsNil())  // true（能看到内部是 nil）
// 用法：调试时用 IsNil 确认"是不是 nil 指针装进了接口"

5. 相关的"零值可用"问题

类型	零值可用性
`map`	读可用，写 panic
`slice`	可 range、可 append
`chan`	读写永久阻塞
`func`	调用 panic
`interface{}`	与 nil 比较的陷阱

第一项（nil map）与第三项（nil chan）常出现在"字段没初始化"的场景第四项（nil func）与其它四项不同：它不是"返回零值"，而是直接 panic。所以"可选回调"字段的正确做法是"给一个空实现"，而不是"留 nil 再判空"。
：读 nil map 返回零值，于是"看起来正常"，直到某天写了它。

第四项（nil func）在"回调未设置"时：调用直接 panic，而不是"什么都不做"。所以回调字段应当先判空或给默认空实现。

测试能抓住一大半，而写法很便宜：对"返回错误"的路径，断言 err == nil 而不是 err.Error() == ""。前者会失败，后者会 panic 或通过。

// 测试：断言接口本身为 nil（而不是看消息）
_, err := do()
if err != nil {                     // 关键：判接口
    t.Fatalf("want nil error, got %v", err)
}
// 反例：if err != nil && err.Error() != "" → 掩盖了 nil 指针问题

6. 排错：五种"nil 判不住"

现象	成因	处理方向
`err != nil` 但无信息	返回 nil 指针	返回字面 nil
包装后判定失效	`%w` 包了 nil	先判空再包
`Is` 里 panic	自定义 Is 未判空	加 `e == nil`
map 写入 panic	nil map	初始化
回调 panic	nil func	判空或默认实现

第二项（包装后判定失效）有个"测试"上的表现：errors.Is(err, ErrX) 返回 false，而日志里明明写着包装了 ErrX。此时应当怀疑"链上有 nil 指针"而不是"包装写错了"。
第一项最隐蔽：错误信息为空意味着"日志里只有一行 nil"，而排障时完全看不出发生了什么。

最后一条"设计"层面的建议：用"错误哨兵 + 值类型"替代"指针类型错误"。值类型的零值不是 nil，于是"装进接口"永远安全——代价是"是否有值"要靠一个字段表达，而这是显式的。

// 值类型错误：零值有意义，装进接口不会"假非 nil"
type MyError struct {
    Code string          // 空串表示"没有错误"
    Msg  string
}
func (e MyError) Error() string { return e.Code + ": " + e.Msg }
func (e MyError) Valid() bool   { return e.Code != "" }
// 代价：每次返回都要判断 Valid()；收益：不存在 nil 陷阱

7. 边界：什么情况不必纠结

场景	为什么	做法
函数只返回 `error` 接口	无指针赋值	不会触发
不使用包装（直接返回）	链上无 nil	不会触发
值类型错误（非指针）	零值不是 nil	不适用
已启用 `nilness` 检查	由工具兜住	不操心

判断口径一句话：函数返回值是否可能"是具体指针类型、且值可能为 nil"。最后一条与"接口设计"有关的边界：返回接口时，尽量让"零值"也有意义。"一个空结构体实现"比"nil 指针 + 判空"更安全，因为它永远不会让接口变成 nil。
会，就必须在返回前显式判空；不会（直接用 error 接口），这个陷阱与你无关。

8. 自测

接口等于 nil 的充要条件是什么？为什么 (*T)(nil) 赋给接口后不等于 nil？
三种触发形态里，哪一种"包装"后最难发现？fmt.Errorf("%w", nilPtr) 返回什么？
为什么"函数签名用 error 而不是 *MyError"能从根上消除这个问题？
自定义 Is 方法为什么必须判 e == nil？不判会发生什么？
nil map、nil chan、nil func 的行为分别是什么？哪一个"看起来正常直到写它"？
判断"是否需要纠结 nil 接口"的那个问题是什么？