统一管理业务错误码需遵循唯一性、可读性、可扩展性原则，采用SSS-TT-NNN格式编码，通过ErrorCode接口和BizError结构体封装错误信息，集中定义在独立包中按模块维护，结合pkg/errors实现堆栈追踪，利用中间件统一API返回格式并处理错误，提升代码可读性与系统可观测性。
在 Go 项目中，统一管理业务错误码不仅能提升代码可读性，还能让前后端协作更高效。一个清晰的 error code 设计规范，有助于日志排查、监控告警和用户提示。以下是 Golang 中业务 errorCode 的设计思路与实现方式。
1. 错误码设计原则
良好的错误码体系应满足以下几个核心要求：
- 唯一性：每个错误码在整个系统中唯一，避免冲突
- 可读性：通过结构化编码（如模块+类型+序号）快速识别来源
- 可扩展性：支持新增模块或错误类型而不影响现有逻辑
- 国际化友好：错误码只做标识，错误信息可通过 i18n 动态加载
建议格式：SSS-TT-NNN
- SSS：服务/模块编号（3位数字）
- TT：错误类型（2位数字）
- NNN：具体错误序号（3位数字）
例如：101-01-001 表示「用户服务 - 参数错误 - 用户名不能为空」。
立即学习“go语言免费学习笔记（深入）”；
2. 定义错误码结构体与接口
使用结构体封装错误码、消息和 HTTP 状态码，便于统一处理。
type ErrorCode interface {
Code() string
Message() string
Status() int
}
type BizError struct {
code string
message string
status int
}
func (e BizError) Code() string { return e.code }
func (e BizError) Message() string { return e.message }
func (e *BizError) Status() int { return e.status }
通过接口抽象，可以灵活扩展数据库错误、第三方调用错误等不同类别。
3. 集中定义错误码常量
在独立包中（如 pkg/errors）集中管理所有错误码：
var (
ErrUsernameRequired = &BizError{code: "101-01-001", message: "用户名不能为空", status: 400}
ErrUserNotFound = &BizError{code: "101-02-001", message: "用户不存在", status: 404}
ErrInvalidToken = &BizError{code: "102-03-001", message: "无效的访问令牌", status: 401}
)
按模块建立子包或文件（user_errors.go, order_errors.go），提高维护性。
4. 结合 errors.Wrap 实现堆栈追踪
使用 github.com/pkg/errors 包保留调用栈：
if user == nil {
return errors.Wrap(ErrUserNotFound, "query failed")
}
在日志中可通过 %+v 输出完整堆栈，便于定位问题根因。
同时提供转换函数，提取原始错误码：
func GetErrorCode(err error) string {
if e, ok := err.(*BizError); ok {
return e.Code()
}
// 解包 wrapped error
if wrapped := errors.Cause(err); wrapped != nil {
if e, ok := wrapped.(*BizError); ok {
return e.Code()
}
}
return "UNKNOWN"
}
5. 统一返回格式与中间件处理
API 返回结构标准化：
{
"code": "101-02-001",
"message": "用户不存在",
"data": null
}
使用 Gin 或其他框架时，可通过中间件自动捕获 panic 和业务错误：
func ErrorHandler() gin.HandlerFunc {
return func(c *gin.Context) {
defer func() {
if err := recover(); err != nil {
c.JSON(500, gin.H{"code": "999-99-999", "message": "系统内部错误"})
}
}
c.Next()
// 检查是否有设置错误
if len(c.Errors) > 0 {
e := c.Errors[0]
code := GetErrorCode(e.Err)
msg := GetErrorMessage(code) // 可结合语言配置
status := GetHttpStatus(e.Err)
c.JSON(status, gin.H{"code": code, "message": msg})
}
}}
基本上就这些。关键是早定规范、集中管理、统一输出。
