本文介绍了golang web开发中的两个实用错误处理技巧：1. 统一错误返回格式，通过定义通用错误结构体并封装处理函数，使前端能统一解析错误并便于后续扩展；2. 使用结构化日志记录错误，结合中间件记录请求上下文信息，提升日志的可读性和排查效率。此外还提到自定义错误类型、避免暴露敏感信息、错误日志调用栈、日志级别划分及错误码集中管理等关键细节，全面提升系统的可观测性与维护性。
在 Golang Web 开发中，错误处理常常是影响代码可读性和维护性的关键因素之一。一个良好的错误处理机制不仅能提高系统的健壮性，还能让调试和排查问题更高效。本文直接切入主题，重点讲两个实用技巧：统一错误返回格式 和 结构化日志记录方案。
统一错误返回格式
在开发 RESTful API 时，客户端通常期望一个结构一致的错误响应，而不是裸露的 HTTP 状态码或原始错误信息。统一错误返回格式有助于前端更好地解析错误内容，并给出友好的提示。
建议使用一个通用的错误结构体，例如：
立即学习“go语言免费学习笔记（深入）”；
type ErrorResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Detail string `json:"detail,omitempty"`
}然后在中间件或者统一的错误处理函数中封装错误返回逻辑：
func SendError(w http.ResponseWriter, err error, statusCode int) {
resp := ErrorResponse{
Code: statusCode,
Message: http.StatusText(statusCode),
Detail: err.Error(),
}
w.WriteHeader(statusCode)
json.NewEncoder(w).Encode(resp)
}这样做的好处是：
- 前端可以根据
code字段做统一处理； -
detail字段可用于调试，但上线后可以关闭输出； - 所有错误都走同一个出口，方便后续扩展（比如添加监控埋点）。
使用结构化日志记录错误
Golang 默认的 log 包功能有限，尤其在 Web 应用中，我们希望日志能包含更多信息，比如请求路径、用户 ID、错误堆栈等。推荐使用结构化日志库，比如 logrus 或 zap，它们支持字段化输出，便于日志收集系统（如 ELK 或 Loki）解析。
举个例子，在处理请求时记录上下文信息：
func loggingMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 可以从 context 中获取 user id 等信息
logger := log.WithFields(log.Fields{
"path": r.URL.Path,
"method": r.Method,
"ip": r.RemoteAddr,
})
// 将 logger 存入 context，供后续 handler 使用
ctx := context.WithValue(r.Context(), "logger", logger)
next.ServeHTTP(w, r.WithContext(ctx))
})
}在实际处理错误的地方：
logger := ctx.Value("logger").(*log.Entry)
logger.WithError(err).Error("处理请求失败")这样做可以让每条错误日志都有清晰的上下文，排查问题时效率翻倍。
错误分类与自定义错误类型
为了更精细地控制错误行为，可以定义自己的错误类型。比如区分业务错误和系统错误：
type AppError struct {
Code int
Message string
Err error
}
func (e *AppError) Error() string {
return e.Err.Error()
}然后在错误处理中判断类型：
if appErr, ok := err.(*AppError); ok {
SendError(w, appErr.Err, appErr.Code)
} else {
SendError(w, err, http.StatusInternalServerError)
}这种做法的好处是：
- 可以根据不同错误类型返回不同的状态码；
- 方便中间件统一处理错误逻辑；
- 避免“所有错误都扔 500”的粗暴做法。
一些容易忽略的细节
- 不要暴露敏感错误信息给客户端：比如数据库连接失败的具体原因，不应出现在生产环境的响应中。
-
错误日志要带上调用栈：使用
errors.WithStack()或者 zap 的WithCaller来帮助定位错误源头。 -
日志级别要分清楚：普通错误用
.Warn()，严重错误才用.Error()，避免日志污染。 -
错误码尽量统一管理：可以在项目中建一个
errors.go文件集中定义错误码和消息。
基本上就这些，错误处理看起来不复杂，但在大型项目中很容易被忽视。做好统一返回和结构化日志，能让整个项目的可观测性和可维护性提升一个档次。
