定义统一响应结构并封装工具函数，通过中间件捕获错误，实现Go Web服务中规范的错误处理返回格式，提升API一致性和前端对接效率。
在Go语言开发Web服务时，统一错误处理返回格式能提升API的规范性和前端对接效率。通过设计一致的响应结构，可以让客户端更方便地解析结果，同时减少重复代码。
定义统一响应结构
创建一个通用的响应模型，包含状态码、消息、数据等字段：
type Response struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}
使用omitempty标签确保没有数据时，Data字段不会出现在JSON输出中。
封装返回工具函数
提供几个常用函数简化成功与错误的返回：
立即学习“go语言免费学习笔记（深入）”；
func Success(data interface{}) *Response {
return &Response{
Code: 200,
Message: "success",
Data: data,
}
}
func Error(code int, message string) *Response {
return &Response{
Code: code,
Message: message,
}
}
在HTTP处理器中直接返回结构化数据：
func GetUser(w http.ResponseWriter, r *http.Request) {
user, err := getUserFromDB(1)
if err != nil {
json.NewEncoder(w).Encode(Error(500, "获取用户失败"))
return
}
json.NewEncoder(w).Encode(Success(user))
}
中间件统一拦截错误
通过中间件捕获panic或自定义错误，保证所有异常都走统一格式：
func RecoverMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(Error(500, "系统内部错误"))
}
}()
next.ServeHTTP(w, r)
})
}
结合自定义error类型，可在中间件中判断错误种类并返回不同提示。
使用场景建议
- 业务错误使用Error函数返回，如参数校验失败、资源不存在
- 系统级错误通过中间件捕获，避免暴露敏感信息
- 成功响应始终用Success包装，保持格式一致
- 状态码设计建议参考HTTP标准，如400表示客户端错误，500表示服务端错误
基本上就这些。核心是结构统一、封装复用、层级清晰。不复杂但容易忽略细节。做好了能省去很多后期调整成本。
