定义统一响应结构体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语言免费学习笔记（深入）”；
<pre class="brush:php;toolbar:false;">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: %vn", 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)) }
这样既保证了响应格式统一，又实现了错误的分级处理与日志追踪。
基本上就这些，核心是结构清晰、错误可追溯、前后端约定明确。不复杂但容易忽略细节。
js 前端 json go golang app 后端 switch 路由 状态码 web接口 golang 中间件 gin echo 常量 封装 Error 结构体 接口 数据库 http