错误（errors）与哨兵错误（sentinel errors）的区别及使用疑问

算力阿峰

2026-8-21

Go哨兵错误：搞懂本质和边界

一、别被字面定义误导，哨兵错误的核心是「预定义的可识别场景」

你看到的定义说哨兵错误表示"无法启动或执行"，但这只是它的常见表现，不是本质。任何错误都可能导致流程中断，但哨兵错误是开发者提前预判、在包级预定义的特定错误类型——它的存在是为了让调用方能明确识别这个错误场景，进而做针对性处理，而不是把它当成一个模糊的"意外故障"。

官方给出的规范其实是在强化这个核心：

Sentinel errors are usually used to indicate that you cannot start or proceed.
Sentinel errors are among the few variables declared at the package level. Their names start with Err（例外情况如io.EOF），应视为只读（Go编译器无法强制约束）。
定义哨兵错误前需确认必要性，一旦定义它就会成为公共API的一部分，需在所有向后兼容的后续版本中提供。

简单说：哨兵错误是对外暴露的"约定错误标识"，不是内部随便扔出来的临时错误。

二、不是处理方式，是「预定义+约定识别」决定了它是哨兵错误

你问是不是处理方式决定了哨兵错误，答案是否定的。关键看两个点：

它是不是包级预定义的变量（或符合命名规范的例外，比如io.EOF）；
调用方是不是可以通过**相等性判断（==）**来识别它，进而做专属处理。

举个直观的对比

哨兵错误的正确用法

package payment

import "errors"

// ErrInsufficientFunds 包级预定义：余额不足
var ErrInsufficientFunds = errors.New("insufficient funds")

func Transfer(from, to *Account, amount int) error {
	if from.Balance < amount {
		// 返回预定义的哨兵错误
		return ErrInsufficientFunds
	}
	// 转账逻辑...
	return nil
}

调用方的处理：

err := payment.Transfer(myAcc, targetAcc, 500)
if err == payment.ErrInsufficientFunds {
    // 针对性处理：提示用户充值
    fmt.Println("余额不足，请先充值后再尝试转账")
} else if err != nil {
    // 其他未知错误：统一打日志报警
    log.Printf("转账失败：%v", err)
}

这里ErrInsufficientFunds是提前约定好的错误，调用方一眼就能识别，知道该怎么处理。

普通错误的例子

func ReadConfig(path string) error {
    f, err := os.Open(path)
    if err != nil {
        // 直接返回系统生成的错误，没有预定义
        return fmt.Errorf("读取配置失败：%w", err)
    }
    // ...
}

调用方没法用==判断这是"文件不存在"还是"权限不够"，只能靠字符串匹配或者类型断言（不推荐），这类就是普通的运行时错误。

三、你的定义有偏差

你说"在运行时需重点监控、并在包根目录显式定义为变量（或常量）的错误就是哨兵错误"，问题出在两点：

"重点监控"不是哨兵错误的核心属性：比如io.EOF是正常的流结束标识，根本不需要监控，但它是标准的哨兵错误；反过来，有些普通错误（比如数据库连接失败）需要重点监控，但它不是哨兵错误。
核心应该是：供调用方通过相等性判断识别、并做针对性处理的包级约定错误，和监控需求无关。

四、你的示例代码分析

你写的这段代码是标准的哨兵错误用法，我把它加上中文注释再理一遍：

package main

import (
	"errors"
	"fmt"
)

// ErrInsufficientFunds 典型的哨兵错误：余额不足
var ErrInsufficientFunds = errors.New("insufficient funds")

type Account struct {
	Balance int
}

func (a *Account) Withdraw(amount int) error {
	if amount > a.Balance {
		// 返回预定义的哨兵错误，而非临时生成的字符串错误
		return ErrInsufficientFunds
	}
	a.Balance -= amount
	return nil
}

func main() {
	acc := &Account{Balance: 100}

	err := acc.Withdraw(150)
	if err == ErrInsufficientFunds {
		// 明确识别错误场景，做专属处理
		fmt.Println("取款失败：账户余额不足，请检查余额")
	} else if err != nil {
		fmt.Printf("取款失败：%v\n", err)
	} else {
		fmt.Printf("取款成功，当前余额：%d\n", acc.Balance)
	}
}

如果把代码改成下面这样，就不是哨兵错误了：

func (a *Account) Withdraw(amount int) error {
	if amount > a.Balance {
		// 返回临时拼接的错误，调用方无法用==识别
		return fmt.Errorf("取款失败：当前余额%d，需要%d", a.Balance, amount)
	}
	// ...
}

此时调用方只能解析错误字符串，没法精准判断场景，这就是普通错误。

内容的提问来源于stack exchange，提问作者user3025289

错误（errors）与哨兵错误（sentinel errors）的区别及使用疑问

一、别被字面定义误导，哨兵错误的核心是「预定义的可识别场景」 #

二、不是处理方式，是「预定义+约定识别」决定了它是哨兵错误 #

举个直观的对比 #