本文介绍一种符合 Go 语言惯用法的错误分类方案：通过定义 UserError 接口统一标识可向用户暴露的错误，其余错误默认视为需隐藏的内部错误，从而避免多 error 返回、提升 API 清晰度与错误处理一致性。
本文介绍一种符合 go 语言惯用法的错误分类方案：通过定义 `usererror` 接口统一标识可向用户暴露的错误，其余错误默认视为需隐藏的内部错误，从而避免多 error 返回、提升 api 清晰度与错误处理一致性。
在 Go 应用开发中，清晰区分“用户输入错误”（如参数校验失败）与“系统内部错误”（如数据库连接中断、服务不可用）至关重要——前者应友好提示用户修正操作，后者则需记录日志并返回通用错误信息，绝不泄露敏感细节。然而，像 func ProcessInput(input string) (ProcessedValue, error, error) 这样返回多个 error 的设计违背 Go 的简洁哲学：签名语义模糊、调用方易误判、难以扩展，且破坏了 error 作为单一、可组合接口的核心价值。
推荐采用类型化错误分类模式：定义一个轻量接口 UserError，明确标识“可安全展示给用户”的错误类型：
type UserError interface {
error
UserError() string // 返回面向用户的友好提示
}该接口嵌入 error，确保兼容所有标准错误处理逻辑；额外的 UserError() 方法提供用户侧消息，与 Error()（用于日志或调试）解耦。实现示例如下：
// 用户输入为空
type EmptyInputError struct{}
func (e EmptyInputError) Error() string { return "empty input: internal validation failed" }
func (e EmptyInputError) UserError() string { return "输入不能为空" }
// 用户输入格式错误
type InvalidEmailError struct{ Email string }
func (e InvalidEmailError) Error() string { return fmt.Sprintf("invalid email format: %s", e.Email) }
func (e InvalidEmailError) UserError() string { return "邮箱格式不正确" }
// 内部错误（不实现 UserError）——自然落入“非用户错误”分支
var ErrDBUnavailable = errors.New("database is temporarily unavailable")业务函数统一返回单个 error，职责清晰：
func ProcessInput(input string) (*ProcessedValue, error) {
if input == "" {
return nil, EmptyInputError{}
}
if !isValidEmail(input) {
return nil, InvalidEmailError{Email: input}
}
// 模拟内部调用
if err := database.Save(input); err != nil {
return nil, ErrDBUnavailable // 不实现 UserError，即内部错误
}
return &ProcessedValue{Result: input}, nil
}HTTP 处理器等上层代码按类型断言即可分流处理：
func httpHandler(w http.ResponseWriter, r *http.Request) {
input := r.URL.Query().Get("input")
val, err := ProcessInput(input)
if err != nil {
if userErr, ok := err.(UserError); ok {
// ✅ 安全返回给前端
http.Error(w, userErr.UserError(), http.StatusBadRequest)
} else {
// ? 记录详细错误，返回通用提示
log.Printf("Internal error: %v", err) // 包含堆栈/上下文更佳
http.Error(w, "服务器繁忙，请稍后重试", http.StatusInternalServerError)
}
return
}
// 成功响应
json.NewEncoder(w).Encode(val)
}关键优势与注意事项：
- ✅ 签名简洁：函数签名回归 Go 标准形式 func(...) (T, error)，语义明确；
- ✅ 类型安全：编译期检查 UserError 实现，避免运行时误判；
- ✅ 可扩展：新增用户错误只需实现接口，无需修改调用逻辑；
- ⚠️ 避免 panic：切勿在 UserError.UserError() 中 panic 或执行耗时操作；
- ⚠️ 日志分级：内部错误务必记录完整 err.Error() 及上下文（如 trace ID），用户错误仅需记录发生频次；
- ? 进阶建议：结合 errors.Is() / errors.As() 支持错误链（Go 1.13+），或封装 NewUserError(msg string, cause error) 保留原始错误因果链。
这一模式已被诸多成熟 Go 项目（如 Caddy、Tailscale）采用，它不依赖框架、无侵入性、完全契合 Go 的接口哲学——用最小的抽象，解决最实际的工程问题。
