必须区分业务错误和系统错误：业务错误用自定义BizError结构体实现error接口并设唯一错误码，系统错误复用标准库错误；用errors.Is/errors.As判断而非字符串匹配；包装错误需克制且在边界处明确动词+名词；日志记录须保留原始错误链。
错误类型必须区分业务错误和系统错误
Go 的 error 接口本身是扁平的，但实际维护中若所有错误都用 errors.New 或 fmt.Errorf 生成，很快就会陷入“无法判断错误性质”的困境。业务错误（如订单不存在、库存不足）应可被上层逻辑识别并做特定处理；系统错误（如数据库连接失败、网络超时）则通常需重试或告警。
推荐做法是定义明确的错误类型：
- 用自定义结构体实现
error接口，内嵌error字段以保留原始错误链 - 为每类业务错误定义唯一错误码（
int或字符串常量），避免用字符串匹配判断错误类型 - 系统错误尽量复用标准库错误（如
os.IsTimeout、net.ErrClosed）或包装成带上下文的*fmt.wrapError
type BizError struct {
Code int
Message string
Err error // 可选：用于链式错误
}
func (e *BizError) Error() string {
return e.Message
}
func (e *BizError) Unwrap() error {
return e.Err
}
var (
ErrOrderNotFound = &BizError{Code: 1001, Message: "order not found"}
ErrInsufficientStock = &BizError{Code: 1002, Message: "insufficient stock"}
)
用 errors.Is 和 errors.As 替代字符串比较
很多人在判断错误时写 if err.Error() == "xxx" 或 strings.Contains(err.Error(), "timeout")，这极不可靠：错误消息可能随版本变化、多语言环境会改写、中间件可能加前缀。Go 1.13 引入的 errors.Is 和 errors.As 才是正确姿势。
关键点：
立即学习“go语言免费学习笔记（深入）”；
-
errors.Is(err, target)检查错误链中是否存在与target相等的错误（支持自定义Is方法） -
errors.As(err, &target)尝试将错误链中第一个匹配类型的错误赋值给target，适合提取业务错误详情 - 自定义错误类型建议实现
Is方法，例如：func (e *BizError) Is(target error) bool { return e.Code == getErrorCode(target) }
错误包装要克制，避免冗余上下文
用 fmt.Errorf("failed to process order: %w", err) 包装错误很常见，但过度包装会让错误栈变长、关键信息被埋没。不是每个调用都要加一层包装 —— 只有当新增的上下文对错误定位或处理有意义时才包装。
典型反例：
- 在每个函数入口都
return fmt.Errorf("in service layer: %w", err)→ 上下文无区分度 - 连续多层都用
%w包装同一错误 → 日志里看到 5 层 “failed to … caused by failed to …” - 包装时用了模糊动词（如 “handle”, “do”）→ 无法快速定位动作主体
推荐方式：
- 在边界处包装：比如从 DB 层返回错误，在 service 层转为业务语义错误（
"order creation failed: %w"） - 用动词+名词明确动作：如
"saving user profile"而非"in user handler" - 必要时附带关键 ID：
fmt.Errorf("saving order %s: %w", orderID, err)
日志记录错误时别丢原始错误链
很多团队习惯在日志中只打 err.Error()，结果丢失了错误类型、堆栈、底层原因。尤其当错误经过多次 %w 包装后，仅靠字符串无法调用 errors.As 或提取状态。
正确做法：
- 日志库（如
zap）应使用zap.Error(err)而非zap.String("err", err.Error()) - 若用标准库
log，至少用%+v格式符输出错误（需配合github.com/pkg/errors或 Go 1.17+ 的fmt增强） - 避免在记录前调用
errors.Unwrap或err.Error()—— 这等于主动切断错误链
一个容易被忽略的细节：HTTP handler 中返回错误响应时，如果只序列化 err.Error() 给前端，就彻底丢掉了错误码和分类能力。应该统一用结构体封装错误响应，包含 code、message、trace_id，而 code 来自 errors.As(err, &bizErr) 提取的 BizError.Code。
