定义统一的ErrorResponse结构，包含Code、Message和可选Detail字段；2. 封装writeError函数确保所有错误响应格式一致；3. 使用RecoverMiddleware中间件捕获panic并返回标准错误；4. 区分业务错误与系统错误类型，便于前端根据不同Code处理。
在 Golang Web 项目中，统一的 error 返回格式能提升前后端协作效率、增强 API 可读性，并便于前端统一处理错误。实现这一目标的关键是定义清晰的错误响应结构，并在整个项目中强制使用。
1. 定义统一的 Error 响应结构
建议使用 JSON 格式返回错误信息，包含必要的字段：状态码、错误消息、可选的错误码和详情。例如：
type ErrorResponse struct {
Code int `json:"code"` // HTTP 状态码或业务错误码
Message string `json:"message"` // 用户可读的错误描述
Detail string `json:"detail,omitempty"` // 可选，用于开发调试
}
这个结构可以满足大多数场景，前端通过 message 展示提示，后端通过 detail 记录日志或排查问题。
2. 封装错误响应函数
在 handler 层避免直接写 JSON 错误，而是封装一个通用函数，确保所有错误输出一致：
立即学习“go语言免费学习笔记（深入）”；
func writeError(w http.ResponseWriter, status int, message, detail string) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
errResp := ErrorResponse{
Code: status,
Message: message,
Detail: detail,
}
json.NewEncoder(w).Encode(errResp)
}
使用示例：
if user == nil {
writeError(w, http.StatusNotFound, "用户不存在", "user_id not found")
return
}
3. 结合中间件统一处理 panic 和未捕获错误
使用中间件捕获 handler 中的 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 {
log.Printf("panic: %v\n", err)
writeError(w, http.StatusInternalServerError, "服务器内部错误", fmt.Sprintf("%v", err))
}
}()
next.ServeHTTP(w, r)
})
}
将此中间件注册到路由中，即可保障异常情况下的格式统一。
4. 区分业务错误与系统错误
实际项目中建议定义常见错误类型，如：
- 参数错误（400）：请求参数缺失或格式错误
- 权限不足（403）：用户无权访问资源
- 资源未找到（404）：ID 对应记录不存在
- 服务器错误（500）：数据库查询失败等
每种错误对应不同的 Code 和 Message，前端可根据 Code 做不同处理，比如跳转登录页或重试。
基本上就这些。只要从结构定义、响应封装、中间件防护三方面入手，就能在 Golang Web 项目中实现清晰、可控、统一的 error 返回规范。
