统一管理业务错误码需遵循唯一性、可读性、可扩展性原则，采用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 } <p>type BizError struct { code string message string status int }</p><p>func (e <em>BizError) Code() string { return e.code } func (e </em>BizError) Message() string { return e.message } func (e *BizError) Status() int { return e.status }</p>通过接口抽象，可以灵活扩展数据库错误、第三方调用错误等不同类别。
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": "系统内部错误"}) } } <pre class='brush:php;toolbar:false;'> 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}) } }}
基本上就这些。关键是早定规范、集中管理、统一输出。