Go错误码设计必须用具名类型（如ErrorCode int）和结构体（如*BizError）实现，禁止直接用int；需分模块编号、查表映射HTTP状态码，并通过errors.As提取，确保类型安全与语义清晰。
Go 里没有“错误码体系”这回事，只有你愿不愿意用类型把错误语义显式表达出来。硬塞 int、拼字符串、靠 err.Error() 匹配，都是在绕开 Go 的错误哲学，迟早掉坑里。
为什么不能直接用 int 定义错误码
看似省事：const ErrUserNotFound = 404，但实际会立刻引发三类问题：
-
ErrUserNotFound和http.StatusNotFound类型相同、语义冲突，调用方根本分不清这是业务逻辑错还是传输层错 - 不同模块都定义
ErrNotFound = 1001，但一个指“用户不存在”，另一个指“订单不存在”，查日志时完全无法定位 - 编译器不拦你，IDE 跳不到定义，
if err == ErrUserNotFound直接报错（error和int不可比），最后退化成脆弱的字符串匹配
正确做法是用具名类型封装，比如：type ErrorCode int，再为每个业务错误定义专属常量，且必须带注释说明触发条件和重试建议。
怎么让错误既带码又可断言
核心是结构体 + 接口实现，不是继承，也不靠反射。所有业务错误统一走 *BizError 类型，它必须满足两个条件：
立即学习“go语言免费学习笔记（深入）”；
- 实现
error接口（只暴露Error()方法，返回用户友好的提示，不含码） - 提供
Code()方法（返回ErrorCode类型，供中间件或 handler 判断）
示例结构：
type BizError struct {
code ErrorCode
message string
cause error
}
func (e *BizError) Error() string { return e.message }
func (e *BizError) Code() ErrorCode { return e.code }
func (e *BizError) Unwrap() error { return e.cause }
使用时用 errors.As(err, &BizError{}) 安全提取，而不是 errors.Is(err, someErr) —— 后者只适合底层系统错误（如 os.IsNotExist）。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
错误码怎么分组才不会乱
分组不是为了好看，是为了让新增错误时不用翻几十个文件找空号。推荐按服务/模块切片，每段预留 500+ 号位：
-
user模块：1000–1499（ErrUserNotFound = 1001，ErrUserExists = 1002） -
order模块：2000–2499（ErrOrderNotFound = 2001，ErrInsufficientStock = 2002） -
payment模块：3000–3499（ErrBalanceInsufficient = 3001）
注意：范围之间留空档（比如 1500–1999 空着），方便未来拆分子模块；已发布的错误码含义绝不可变更，哪怕写错了也得加新码，否则客户端逻辑会静默崩坏。
HTTP 状态码映射为什么不能写死在错误里
因为状态码属于传输层语义，而错误码属于业务域语义，混在一起就等于把数据库字段直接当 API 响应字段用。常见错误是给 BizError 加个 httpStatus int 字段，结果改个 404 到 410 就得改遍所有实例。
正解是查表法，集中管理映射关系：
var httpStatusMap = map[ErrorCode]int{
ErrUserNotFound: http.StatusNotFound,
ErrInvalidParam: http.StatusBadRequest,
ErrInsufficientStock: http.StatusUnprocessableEntity,
}
handler 中统一做：
if errors.As(err, &bizErr) {
status = httpStatusMap[bizErr.Code()]
if status == 0 {
log.Warn("unmapped error code", "code", bizErr.Code())
status = http.StatusInternalServerError
}
}
漏配必须打日志告警——这比返回错状态码更危险，它会让前端永远收不到 404，只看到 500。
最易被忽略的一点：错误码本身不解决任何问题，它只是错误上下文的索引。真正关键的是 cause 字段是否保留了原始错误链，以及 message 是否能直接用于前端展示（或至少支持 i18n 插槽）。没这两样，再整齐的编码表也只是摆设。
