带类型 nil 的 error 如何避免返回非空接口

如果一个函数内部声明了 var typed *MyError，再把它直接作为 error 返回，即使指针本身是 nil，调用方的 err == nil 也可能得到 false。原因不是 nil 失效，而是接口里已经保存了动态类型 *MyError。

最稳妥的规则很简单：失败分支返回具体错误，成功分支直接写 return nil；不要把一个带具体类型的 nil 指针隐式转换成 error 返回。

官方资料：https://go.dev/doc/faq#nil_error

本文只讨论带类型 nil 的 error 返回问题，不把它扩展为所有接口 nil 或错误包装的通用教程。

先复现：指针是 nil，error 却不是 nil

排查时先不要猜调用方的判断是否写错，先把返回值拆成一个最小例子。下面的类型实现了 error 接口，但成功路径让 typed 保持为 nil，然后把它直接返回。

package main

import "fmt"

// MyError 是一个带指针接收者的具体错误类型。
type MyError struct {
	Message string
}

// Error 让 *MyError 满足 error 接口。
func (e *MyError) Error() string {
	return e.Message
}

// badReturn 演示把 typed nil 直接转成 error 的问题。
func badReturn() error {
	var typed *MyError
	// typed 的动态值为 nil，但它仍然拥有具体类型 *MyError。
	return typed
}

func main() {
	err := badReturn()
	fmt.Printf("err == nil: %v\\n", err == nil)
	fmt.Printf("err type: %T\\n", err)
}

这个例子的关键观察结果是：err == nil 为 false，而 %T 仍能打印出 *main.MyError。函数内部的指针变量确实为 nil，问题发生在它被装进接口的那一步。

err == nil: false
err type: *main.MyError

定位原因：接口的类型和值必须同时为空

可以把接口值先理解成两个部分：动态类型 T 和动态值 V。真正的 nil 接口是 T=nil、V 未设置；而把 (*MyError)(nil) 放进 error 后，结果更接近 T=*MyError、V=nil。

比较接口与 nil 时，比较的是整个接口值。只要动态类型存在，接口就不是 nil。因此下面两类代码的返回语义不同：

这里不应通过反射把所有接口都拆开再判断。对于一个声明为返回 error 的函数，修复返回契约通常比在调用方识别“某种带类型 nil”更直接，也更容易被测试覆盖。

修复函数：成功分支显式返回 nil

把函数的返回类型保留为 error，并将具体错误只放在失败路径。成功路径不返回一个具体错误类型的变量，而是显式返回无类型的 nil。

package main

import "fmt"

// MyError 保存需要返回给调用方的失败信息。
type MyError struct {
	Message string
}

// Error 实现 error 接口的方法。
func (e *MyError) Error() string {
	return e.Message
}

// checkInput 只在确实失败时返回具体错误，成功时返回真正的 nil 接口。
func checkInput(input string) error {
	if input == "" {
		// 失败分支可以返回具体的 *MyError。
		return &MyError{Message: "input 不能为空"}
	}

	// 显式 nil 不携带 *MyError 的动态类型。
	return nil
}

func main() {
	err := checkInput("ok")
	if err != nil {
		// 只有失败分支才进入这里。
		fmt.Println("检查失败:", err)
		return
	}
	fmt.Println("检查通过")
}

如果失败逻辑需要暂存一个具体错误，也应在返回前区分它是否存在，而不是无条件把变量转换为 error：

// checkValue 说明暂存具体错误时如何保留成功分支的 nil 语义。
func checkValue(value int) error {
	var typed *MyError
	if value 

再看两个容易复发的边界

第一种边界是统一返回函数。辅助函数如果返回具体类型，例如 func parse() *MyError，上层再直接 return parse()，同样可能把 typed nil 带进 error。更清楚的设计是让这个辅助函数本身就返回 error，或者在上层明确判断具体指针。

第二种边界是错误包装。只有在拿到一个非 nil 的具体错误时才调用 fmt.Errorf 或其他包装逻辑；不要把“无错误”包装成一个带类型的占位值。包装后的错误只要真实存在，调用方就应当把它当成失败处理。

import "fmt"

// loadConfig 用 error 作为边界类型，避免把具体 nil 泄漏给调用方。
func loadConfig(raw string) error {
	baseErr := parseConfig(raw)
	if baseErr != nil {
		// 只包装实际存在的错误，并保留原错误链。
		return fmt.Errorf("读取配置失败: %w", baseErr)
	}
	return nil
}

// parseConfig 的成功分支也必须返回显式 nil。
func parseConfig(raw string) error {
	if raw == "" {
		return &MyError{Message: "配置为空"}
	}
	return nil
}

如果调用方需要识别具体错误类型，使用 errors.As 处理真实的错误链；它解决的是“错误属于哪一类”，不是把 typed nil 当成成功返回的替代方案。

最后用测试复查返回契约

这个问题最值得测试的是成功路径，因为成功路径才最容易不小心返回 typed nil。测试应直接断言 err == nil，同时保留一个失败用例，确认真实错误仍会返回。

package main

import "testing"

func TestCheckInput(t *testing.T) {
	// 成功输入必须返回真正的 nil error。
	if err := checkInput("ok"); err != nil {
		t.Fatalf("success returned error: %v", err)
	}

	// 空输入应返回可识别的真实错误。
	if err := checkInput(""); err == nil {
		t.Fatal("empty input should return an error")
	}
}

复查清单可以压缩成三问：

1. 函数签名是否以 error 作为错误边界，而不是把具体错误指针直接暴露给上层？
2. 成功路径是否写了显式 return nil，而不是返回一个可能为 nil 的具体变量？
3. 测试是否同时覆盖成功的 err == nil 和失败的 err != nil？

总结：带类型 nil 的指针本身可以是 nil，但放进接口后动态类型仍然存在，所以接口不再是 nil。修复点应放在返回边界：失败时返回具体错误，成功时显式返回 nil，再用调用方判断和单元测试确认契约。

相关问题

• 为什么 err == nil 会是 false？因为接口保存了动态类型 *MyError，只有动态值是 nil。
• 能否在调用方统一用反射判断？可以做到，但会把返回契约问题转移成额外的运行时判断；优先修复返回端。
• 失败分支还能返回具体的 *MyError 吗？可以，前提是该指针确实非 nil。
• 错误包装和 typed nil 有什么关系？包装前先判断真实错误是否存在，成功路径仍然显式返回 nil。