什么时候应该定义哨兵错误，什么时候使用自定义类型

只需要让调用方判断“是不是某个固定条件”时，优先定义哨兵错误；调用方还需要读取操作名、资源、位置、状态等结构化信息时，使用自定义错误类型。两者不是互斥选项：自定义类型也可以包装哨兵，让调用方既能用 errors.Is 判断类别，又能用 errors.As 取得详情。

Go 官方错误处理说明：https://go.dev/blog/go1.13-errors

选择标准不是“哪种写法更高级”，而是调用方是否只需要一个稳定的真假判断，还是需要拿到字段继续处理。

先按调用方需要回答的问题选择

设计错误 API 前，先写出调用方真正要问的问题。若问题是“资源是否不存在”“队列是否已关闭”“权限是否被拒绝”，答案只有是或否，哨兵错误最简洁。若问题是“哪个操作失败”“哪个路径有问题”“第几行解析失败”，则需要自定义类型承载字段。

固定条件优先用哨兵错误

哨兵错误通常是包级导出变量，名称以 Err 开头。它适合语义稳定、无需附加字段的条件。最小写法如下：

package catalog

import (
    "errors"
    "fmt"
)

var ErrNotFound = errors.New("catalog item not found") // 对外承诺的稳定错误条件

func Find(id string) error {
    if id == "" {
        return fmt.Errorf("find item %q: %w", id, ErrNotFound) // 增加上下文并保留哨兵语义
    }
    return nil
}

调用方不要写 err == ErrNotFound，因为外层一旦用 %w 增加上下文，直接相等就会失败。标准写法是：

err := catalog.Find("")
if errors.Is(err, catalog.ErrNotFound) {
    // 这里可以转成 404、空结果或业务提示
    handleMissingItem()
}

哨兵错误的代价是它会成为公开 API。调用方开始依赖它后，包就应持续保证相同条件仍可被 errors.Is 识别。因此不要为每条内部失败都导出一个变量，只有调用方确实需要分支处理的条件才值得公开。

需要结构化详情时使用自定义类型

错误文本里虽然也能写入路径、操作名和偏移量，但调用方不应解析字符串。自定义类型把这些信息变成稳定字段。标准库中的 fs.PathError 就包含 Op、Path 和 Err，并实现 Unwrap。

type ParseError struct {
    File string
    Line int
    Err  error
}

func (e *ParseError) Error() string {
    return fmt.Sprintf("parse %s at line %d: %v", e.File, e.Line, e.Err) // 文本用于人类排障
}

func (e *ParseError) Unwrap() error {
    return e.Err // 保留底层原因供 errors.Is 与 errors.As 遍历
}

func parseConfig(file string) error {
    return &ParseError{File: file, Line: 18, Err: ErrInvalidSyntax} // 字段供调用方结构化处理
}

调用方用 errors.As 取得类型，不要只对最外层做类型断言：

var parseErr *ParseError
if errors.As(err, &parseErr) {
    // 可按文件和行号生成定位信息，无需解析错误字符串
    reportLocation(parseErr.File, parseErr.Line)
}

类型字段一旦导出，同样会形成兼容性承诺。字段应尽量少而稳定，避免直接塞入数据库连接、HTTP 响应对象或第三方 SDK 类型。

同时需要类别和详情时组合两者

生产代码经常既需要稳定类别，也需要诊断详情。例如配置解析失败属于“无效配置”，同时还要知道文件和行号。此时让自定义类型包装哨兵即可：

var ErrInvalidConfig = errors.New("invalid config") // 提供稳定的类别判断

func loadConfig(file string) error {
    cause := fmt.Errorf("line 18: %w", ErrInvalidConfig) // 将类别放入错误树
    return &ParseError{File: file, Line: 18, Err: cause} // 自定义类型继续携带详情
}

func inspect(err error) {
    if errors.Is(err, ErrInvalidConfig) {
        // 类别判断不依赖 ParseError 的具体字段
        markConfigRejected()
    }

    var parseErr *ParseError
    if errors.As(err, &parseErr) {
        // 详情用于展示定位信息或结构化日志
        reportLocation(parseErr.File, parseErr.Line)
    }
}

如果不同值应匹配同一个模板，也可以给自定义类型实现 Is(error) bool。不过匹配规则应保持浅层，只比较当前错误和目标，不要在 Is 方法里再次调用 Unwrap，错误树遍历交给标准库完成。

把导出错误当作 API 权限边界

Go 官方文档强调，是否用 %w 包装底层错误是一项 API 决策。调用方一旦能通过 errors.Is 观察到 sql.ErrNoRows，数据库驱动就不再是纯内部细节。未来换存储实现时，为保持兼容，你仍可能被迫模拟原来的错误。

更稳妥的做法是在包边界转换语义：

func LookupUser(id string) error {
    err := queryUser(id)
    if errors.Is(err, sql.ErrNoRows) {
        return fmt.Errorf("lookup user %q: %w", id, ErrNotFound) // 将驱动错误收敛为领域哨兵
    }
    if err != nil {
        return fmt.Errorf("lookup user %q failed", id) // 不向调用方暴露不稳定的内部类型
    }
    return nil
}

安全边界也要考虑字段内容。自定义错误不要携带明文令牌、完整 SQL、密码、身份证号或未经清洗的请求体。需要排障的数据可以使用内部日志字段保存，返回给调用方的错误只保留必要信息。

日志记录与错误返回各负其责

错误类型负责传递语义，不应在 Error()、Unwrap() 或构造函数里自动写日志。否则同一个错误经过多层时可能被重复记录。通常在请求入口、任务边界或最终失败处记录一次，并用 errors.As 提取受控字段。

func logFailure(logger *slog.Logger, err error) {
    attrs := []any{"error", err.Error()} // 默认只记录通用错误文本

    var parseErr *ParseError
    if errors.As(err, &parseErr) {
        attrs = append(attrs, "file", parseErr.File, "line", parseErr.Line) // 只加入允许审计的结构化字段
    }

    logger.Error("request failed", attrs...) // 在统一边界记录一次
}

若日志平台会采集错误文本，还要审查 Error() 是否包含用户输入。结构化字段便于脱敏、索引和告警，也比解析错误字符串更稳定。

发布前用兼容性清单复查

错误 API 上线前，可以用下面的清单快速检查：

• 调用方只需真假判断时，是否误用了带大量字段的类型？
• 调用方需要字段时，是否仍在解析错误字符串？
• 导出的哨兵和类型是否真的是长期承诺，而不是驱动细节？
• 包装多层后，errors.Is 与 errors.As 是否仍能命中？
• 错误文本和公开字段是否可能泄露敏感信息？
• 日志是否只在责任边界记录一次？

func TestLookupUserNotFound(t *testing.T) {
    err := LookupUser("missing")
    if !errors.Is(err, ErrNotFound) {
        t.Fatalf("期望 ErrNotFound，实际为 %v", err) // 验证公开语义经过包装后仍保持稳定
    }
}

func TestParseErrorDetails(t *testing.T) {
    err := loadConfig("app.conf")
    var target *ParseError
    if !errors.As(err, &target) || target.Line != 18 {
        t.Fatalf("未取得 ParseError 或行号不正确：%v", err) // 验证调用方依赖的字段契约
    }
}

常见问题

哨兵错误应该导出还是保持包内私有？

只有外部调用方确实需要识别时才导出。若只用于包内分支，保持私有能减少兼容性负担。

自定义错误类型应该返回值还是指针？

通常返回指针更合适，避免复制较大的字段，也让 errors.As 的目标类型保持明确。关键是整个包内保持一致，并在文档和测试中固定用法。

可以同时定义很多哨兵错误吗？

可以，但每个导出变量都是调用方可能依赖的 API。若错误条件需要不断扩展字段，或类别数量开始膨胀，应考虑一个受控的自定义类型和少量稳定分类。

参考资料：Go 1.13 错误处理：https://go.dev/blog/go1.13-errors；errors 标准库：https://pkg.go.dev/errors；fmt.Errorf：https://pkg.go.dev/fmt#Errorf；fs.PathError：https://pkg.go.dev/io/fs#PathError