通过统一错误响应格式、自定义错误类型、结构化日志和中间件捕获panic，提升API稳定性；使用ErrorResponse结构和AppError封装错误，结合zap记录上下文，避免暴露敏感信息。
在Go语言开发的API服务中，错误处理和日志记录是保障系统稳定性和可维护性的关键环节。一个设计良好的错误处理机制不仅能帮助开发者快速定位问题，还能提升用户体验。结合结构化日志记录，可以实现高效的监控与排查。
统一错误响应格式
为了使客户端能一致地解析错误信息，建议定义统一的错误响应结构。
例如：
type ErrorResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Detail string `json:"detail,omitempty"`
}
在HTTP handler中使用：
立即学习“go语言免费学习笔记（深入）”；
func writeError(w http.ResponseWriter, code int, message, detail string) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(code)
json.NewEncoder(w).Encode(ErrorResponse{
Code: code,
Message: message,
Detail: detail,
})
}
这样所有接口返回的错误都遵循相同结构，便于前端处理。
自定义错误类型与上下文增强
Go 的 error 是接口，我们可以封装带有状态码、描述和元数据的自定义错误。
定义一个业务错误类型：
type AppError struct {
Code int
Message string
Err error
}
func (e *AppError) Error() string {
if e.Err != nil {
return e.Message + ": " + e.Err.Error()
}
return e.Message
}
使用时可包装底层错误：
if err := db.QueryRow(...); err != nil {
return &AppError{Code: 500, Message: "数据库查询失败", Err: err}
}
在中间件中识别并处理这类错误，避免暴露敏感细节给客户端。
集成结构化日志（如 zap 或 logrus）
推荐使用 zap，它性能高且支持结构化日志输出。
初始化 logger：
logger, _ := zap.NewProduction() defer logger.Sync()
记录错误时带上上下文：
logger.Error("用户登录失败",
zap.String("ip", r.RemoteAddr),
zap.String("user", username),
zap.Error(appErr),
)
结构化字段便于在 ELK 或 Grafana 中检索分析。
错误处理中间件自动捕获 panic 与错误
编写中间件统一处理 handler 中的异常：
func RecoverMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
logger.Error("panic recovered", zap.Any("error", err), zap.String("path", r.URL.Path))
writeError(w, 500, "系统内部错误", "")
}
}()
next.ServeHTTP(w, r)
})
}
也可在此层拦截返回的 error 类型，自动转为 HTTP 响应。
基本上就这些。通过统一错误结构、增强错误上下文、结构化日志输出和中间件兜底，能显著提升 API 服务的可观测性与健壮性。不复杂但容易忽略的是：始终避免将原始错误直接返回给前端，日志要包含足够上下文但不过度泄露信息。
