搜索错误码断言Go领域建模与架构设计 - 第1节
1.1 为什么需要错误码：从混沌到契约
在分布式系统与微服务架构中，服务之间的调用链路可能跨越数十个节点。当某个下游服务返回“处理失败”时，调用方需要知道：失败的原因是什么？、是否可以重试？、是否需要告警？。错误码正是为了解决这些核心问题而生的结构化契约。
核心价值：错误码将模糊的“失败”转化为可编程、可路由、可观测的精确信号。
错误码的三大设计目标
| 目标 | 说明 | 反例 |
|---|---|---|
| 可识别性 | 通过数字或字符串唯一标识一种错误类型 | 返回 "error" 或 "failed" |
| 可分类性 | 支持按前缀、范围或层级进行归类 | 所有错误使用同一段号段 |
| 可操作性 | 调用方能根据错误码决定下一步动作 | 错误码不区分“重试”与“终止” |
1.2 错误码与异常的本质区别
很多开发者将“抛出异常”等同于“返回错误码”，这是架构设计中常见的误解。两者在控制流、性能、可组合性三个维度存在根本差异。
| 对比维度 | 错误码（Error Code） | 异常（Exception） |
|---|---|---|
| 控制流 | 显式返回值，调用方必须检查 | 隐式栈展开，可被任意层捕获 |
| 性能开销 | 极低（仅一次整数比较） | 较高（栈追踪、对象分配） |
| 可组合性 | 强（支持按位与、范围匹配） | 弱（异常类型层次易膨胀） |
| 跨语言边界 | 天然友好（HTTP/gRPC 状态码） | 需序列化/反序列化 |
| 适用场景 | 预期内的业务逻辑失败 | 非预期的系统级故障 |
常见误区：在 Go 中，
panic 不等于异常。Go 的设计哲学明确将 panic 保留给“不可能发生”的程序错误（如数组越界），而非业务逻辑失败。业务错误应当通过返回值传递。
1.3 Go 语言错误处理哲学：显式与组合
Go 的错误处理哲学可以用一句话概括：错误是值（Errors are values）。这意味着错误不是特殊的控制流机制，而是与普通返回值地位相同的一等公民。
三大核心原则
- 显式检查：每个可能出错的调用都必须检查
err != nil，编译器不会帮你跳过。 - 错误即数据：错误可以携带上下文、可以被包装、可以被断言，就像操作普通结构体一样。
- 少用 panic：标准库中
panic的使用场景极其有限，99% 的错误都通过返回值传递。
// Go 错误处理的典型模式：显式检查 + 早期返回
func GetUser(ctx context.Context, id string) (*User, error) {
if id == "" {
return nil, ErrInvalidID // 返回预定义错误码
}
user, err := db.FindUser(ctx, id)
if err != nil {
return nil, fmt.Errorf("find user %s: %w", id, err) // 包装错误
}
return user, nil
}错误码在 Go 中的实现层次
设计建议：在 Go 中定义错误码时，优先使用
const + 整数类型（如 type ErrCode int），而非字符串。整数错误码在序列化、比较、日志聚合时性能更优，且天然支持按范围分类（如 1xxx 表示用户错误，2xxx 表示订单错误）。
错误码与领域边界的映射
错误码不仅仅是技术符号，更是领域知识的编码。一个设计良好的错误码体系，应当能够清晰地反映领域边界：
- 前缀映射限界上下文：例如
1001属于“用户上下文”，2001属于“订单上下文”。 - 错误码不可跨域复用：同一个错误码在不同限界上下文中含义不同，必须隔离。
- 断言即边界检查：通过
errors.Is断言错误码，本质是在检查调用是否跨越了正确的领域边界。
// 领域边界示例：用户上下文 vs 订单上下文
type UserErrCode int
const (
ErrUserNotFound UserErrCode = 1001
ErrUserDisabled UserErrCode = 1002
)
type OrderErrCode int
const (
ErrOrderNotFound OrderErrCode = 2001
ErrOrderExpired OrderErrCode = 2002
)
// 断言时，调用方必须明确自己所在的领域
if errors.Is(err, ErrUserNotFound) {
// 处理用户领域的错误
}