定义统一响应结构体Response包含Code、Message和Data字段，确保API返回格式一致；2. 提供Success和Error封装函数简化返回逻辑；3. 分层处理错误，使用errors.New创建基础错误，通过errors.Is和errors.As进行判断，服务层抛出带语义的业务错误；4. 定义常见错误码常量与错误变量，如ErrCodeInvalidParam、ErrInvalidParam等；5. 使用中间件Recovery捕获panic并转为标准响应，同时实现HandleAppError函数将不同错误类型映射为对应响应；6. 在控制器中优先校验参数，调用服务方法后根据结果返回Success或调用HandleAppError处理错误，保证响应格式统一与错误可追溯。
在构建 Golang Web 服务时，统一的响应格式和清晰的错误处理机制能显著提升前后端协作效率、增强 API 的可维护性。以下是一套经过实践验证的封装方案，适用于基于 net/http 或主流框架（如 Gin、Echo）的项目。
统一响应结构设计
定义一个通用的响应体结构，确保所有接口返回的数据格式一致：
type Response struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}
其中：
提供封装函数简化返回逻辑：
立即学习“go语言免费学习笔记（深入）”；
func Success(data interface{}) *Response {
return &Response{
Code: 0,
Message: "success",
Data: data,
}
}
func Error(code int, message string) *Response {
return &Response{
Code: code,
Message: message,
}
}
错误类型与分层处理
避免将数据库错误、网络错误等底层异常直接暴露给前端。建议按层级定义错误：
- 使用 errors.New 或 fmt.Errorf 创建基础错误
- 通过 errors.Is 和 errors.As 进行错误判断与类型断言
- 在服务层抛出带有语义的业务错误，例如：
ErrUserNotFound
定义常见错误码常量：
const (
ErrCodeInvalidParam = 4001
ErrCodeUnauthorized = 4002
ErrCodeServerInternal = 5001
)
var (
ErrInvalidParam = errors.New("invalid parameter")
ErrUnauthorized = errors.New("unauthorized")
)
中间件统一拦截异常
在 HTTP 路由中使用中间件捕获 panic 并转化为标准响应：
func Recovery() gin.HandlerFunc {
return func(c *gin.Context) {
defer func() {
if err := recover(); err != nil {
log.Printf("panic: %v\n", err)
c.JSON(500, Error(ErrCodeServerInternal, "internal error"))
c.Abort()
}
}()
c.Next()
}
}
同时可在中间件中实现错误映射，将不同类型的 error 映射为对应响应：
func HandleAppError(err error) *Response {
switch {
case errors.Is(err, ErrInvalidParam):
return Error(ErrCodeInvalidParam, "参数错误")
case errors.Is(err, ErrUnauthorized):
return Error(ErrCodeUnauthorized, "未授权")
default:
log.Println("unexpected error:", err)
return Error(ErrCodeServerInternal, "系统异常")
}
}
控制器中的实际用法
在业务 handler 中只需关注逻辑，出错时直接返回错误或中断：
func GetUser(c *gin.Context) {
id := c.Param("id")
if id == "" {
c.JSON(400, Error(ErrCodeInvalidParam, "ID 不能为空"))
return
}
user, err := userService.FindByID(id)
if err != nil {
if errors.Is(err, ErrUserNotFound) {
c.JSON(404, Error(4040, "用户不存在"))
} else {
c.JSON(500, HandleAppError(err))
}
return
}
c.JSON(200, Success(user))
}
这样既保证了响应格式统一，又实现了错误的分级处理与日志追踪。
基本上就这些，核心是结构清晰、错误可追溯、前后端约定明确。不复杂但容易忽略细节。
