4. 哨兵错误（Sentinel Error）：定义与使用场景

哨兵错误是 Go 语言中最基础、最广泛使用的错误处理模式之一。它通过预定义特定错误值作为“哨兵”，调用方使用 == 或 != 直接比较错误实例，从而判断是否发生了特定的错误条件。这种模式在标准库和主流开源项目中随处可见，是每位 Go 开发者必须掌握的核心错误处理技术。

4.1 定义与核心特征

哨兵错误本质上是一个包级别的公开错误变量，通常使用 var ErrXxx = errors.New("描述信息") 声明。它的核心特征包括：

• 全局唯一实例：整个程序中只存在一个该错误值的实例。
• 值比较语义：调用方通过 == 直接比较错误值，而非检查错误消息字符串。
• 包级导出：通常以 Err 前缀命名，作为包的公共 API 的一部分。
• 不可变：一旦定义，其值在程序生命周期内不会改变。

4.2 常见模式：以 io.EOF 为例

io.EOF 是 Go 标准库中最经典的哨兵错误，也是所有 Go 开发者最早接触的哨兵错误之一。它的定义和使用方式为整个 Go 生态树立了标杆：

// io.EOF 的定义（简化）
var EOF = errors.New("EOF")

// 典型使用场景：读取数据直到文件末尾
func readAll(r io.Reader) ([]byte, error) {
    var data []byte
    buf := make([]byte, 1024)
    for {
        n, err := r.Read(buf)
        if err != nil {
            if err == io.EOF {
                break // 正常结束，不是真正的错误
            }
            return nil, err // 真正的错误
        }
        data = append(data, buf[:n]...)
    }
    return data, nil
}

除了 io.EOF，标准库中还有大量哨兵错误的经典案例：

4.3 哨兵错误的使用场景

哨兵错误最适合以下场景：

1. 预期中的边界条件：如文件读取结束（io.EOF）、数据库查询无结果（sql.ErrNoRows）。这些不是真正的错误，而是正常的程序流程控制信号。
2. 资源状态检查：如连接已关闭（net.ErrClosed）、文件已存在（os.ErrExist）。调用方需要根据这些状态决定下一步操作。
3. 协议或格式验证：如 JSON 解析中的特定错误，调用方需要区分“格式错误”和“其他错误”。
4. 控制流替代：在某些场景下，哨兵错误可以替代 bool 返回值或 nil 检查，使代码语义更清晰。

4.4 哨兵错误的优缺点分析

4.5 哨兵错误与 errors.Is 的关系

Go 1.13 引入的 errors.Is 函数解决了哨兵错误的一个核心痛点：当错误被 fmt.Errorf 包装后，== 比较会失效。通过实现 Is 方法，哨兵错误可以兼容错误包装链：

// 自定义哨兵错误，支持 errors.Is
type SentinelError struct {
    msg string
}

func (e *SentinelError) Error() string { return e.msg }

func (e *SentinelError) Is(target error) bool {
    // 比较指针地址，确保是同一个哨兵实例
    return e == target
}

var ErrNotFound = &SentinelError{"resource not found"}

// 使用示例
func findResource(id int) error {
    // 错误被包装后，errors.Is 仍能匹配
    return fmt.Errorf("find resource %d: %w", id, ErrNotFound)
}

func main() {
    err := findResource(42)
    if errors.Is(err, ErrNotFound) {
        fmt.Println("资源未找到")
    }
}

4.6 哨兵错误定义规范

在团队开发中，定义哨兵错误应遵循以下规范：

• 命名规范：使用 Err 前缀，如 ErrTimeout、ErrPermission。
• 文档注释：每个哨兵错误必须附带注释，说明其触发条件和调用方应如何处理。
• 最小化原则：只在调用方确实需要区分时定义哨兵错误，避免为每个错误场景都定义哨兵。
• 不可变性：哨兵错误一旦发布，不应修改其错误消息或删除该变量，否则会破坏兼容性。
• 考虑 Is 方法：如果哨兵错误可能被包装，应实现 Is 方法以支持 errors.Is。

4.7 哨兵错误在审计中的关注点

在进行代码审计时，针对哨兵错误应重点检查以下方面：

4.8 哨兵错误流程图

下图展示了哨兵错误的定义、使用和审计检查的完整流程：

4.9 哨兵错误 vs 错误类型 vs 动态错误

为了帮助你在实际项目中做出正确的选择，下表对比了三种常见的错误处理模式：