在Golang的Web开发中，异常处理和错误响应是保障服务稳定性的重要环节。与某些语言使用try-catch不同，Golang通过error返回值和panic-recover机制处理错误。理解这两者的适用边界，才能写出健壮的HTTP服务。
一、Golang错误与panic的基本机制
Golang中大部分可预期的错误通过函数返回的error接口表达，调用方需要显式判断并处理。例如读取请求体失败时，http.Request的Body读取方法会返回error，开发者必须检查该值决定后续逻辑。这种方式让错误处理可见且可控，但也会导致业务代码中充斥大量的错误判断语句。
与之相对，panic用于表示不可恢复的程序异常，如数组越界、空指针调用或主动触发的崩溃。当panic在goroutine中未被recover捕获时，该goroutine会终止并向上冒泡，最终使整个进程退出。在Web服务中，若某个请求处理函数中发生panic且未被拦截，正在运行的HTTP服务器可能直接挂掉，所有在线请求都会失败。因此必须在请求入口处设置recover防线。
二、使用defer和recover捕获HTTP处理中的panic
Go的net/http包允许我们为每一个路由注册handler函数。我们可以编写一个中间件函数，在调用实际业务逻辑之前使用defer注册一个匿名函数，在其中调用recover拦截panic。一旦recover返回值不为nil，说明发生了崩溃，此时可以写日志并返回500错误，而不是让进程退出。
下面的代码展示了一个最基础的安全中间件。它包裹了原始的http.HandlerFunc，在内部通过defer捕获异常，并将错误转换为JSON响应。注意recover只能在同一个goroutine的defer函数中生效，所以不要在处理函数中启动新的goroutine去执行业务而不传递recover逻辑。
package main
import (
"encoding/json"
"log"
"net/http"
"runtime/debug"
)
// 安全中间件，捕获panic并返回500
func recoverMiddleware(next http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
log.Printf("panic caught: %vn%s", err, debug.Stack())
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusInternalServerError)
json.NewEncoder(w).Encode(map[string]string{
"code": "internal_error",
"message": "服务器内部错误",
})
}
}()
next(w, r)
}
}
func main() {
http.HandleFunc("/test", recoverMiddleware(func(w http.ResponseWriter, r *http.Request) {
panic("something went wrong")
}))
http.ListenAndServe(":8080", nil)
}
三、统一业务错误结构与响应方法
除了系统级的panic，业务代码中更需要处理可预期的错误，例如参数校验失败、用户不存在等。如果每次都手写w.WriteHeader和json编码，不仅重复而且容易格式不一致。推荐定义一个统一的错误类型，包含HTTP状态码、错误码和提示信息，并提供快捷的响应函数。
我们可以声明一个ApiError结构体，实现error接口，并在其中保存状态码。然后编写一个WriteError函数，接收ResponseWriter和ApiError，统一输出JSON。这样在handler中只需要返回具体的ApiError，由中间件或调用方统一写回响应，既清晰又便于前端解析。
package main
import (
"encoding/json"
"net/http"
)
// ApiError 统一业务错误
type ApiError struct {
Status int `json:"status"`
Code string `json:"code"`
Message string `json:"message"`
}
func (e *ApiError) Error() string {
return e.Message
}
// 写回错误响应
func WriteError(w http.ResponseWriter, err *ApiError) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(err.Status)
json.NewEncoder(w).Encode(err)
}
// 预定义常见错误
func NewBadRequest(msg string) *ApiError {
return &ApiError{Status: http.StatusBadRequest, Code: "bad_request", Message: msg}
}
四、结合中间件处理业务错误与panic
更完整的方案是在中间件中同时处理业务错误和panic。我们可以让handler返回一个error，中间件判断该error是否为ApiError类型，如果是则调用WriteError；如果不是或nil，则按正常流程处理。panic仍由defer recover捕获并转为500。
这种分层设计把异常分为两类：一类是程序员主动返回的业务错误，带有明确状态码；另一类是未预期的崩溃，统一归为系统错误。客户端总是收到结构一致的JSON，后端也能在日志中区分两者。以下示例展示了如何改造中间件以支持error返回。
package main
import (
"encoding/json"
"errors"
"log"
"net/http"
"runtime/debug"
)
type ApiError struct {
Status int `json:"status"`
Code string `json:"code"`
Message string `json:"message"`
}
func (e *ApiError) Error() string { return e.Message }
func WriteError(w http.ResponseWriter, err *ApiError) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(err.Status)
json.NewEncoder(w).Encode(err)
}
// 返回error的handler类型
type appHandler func(w http.ResponseWriter, r *http.Request) error
func middleware(h appHandler) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
defer func() {
if rec := recover(); rec != nil {
log.Printf("panic: %vn%s", rec, debug.Stack())
WriteError(w, &ApiError{Status: 500, Code: "internal", Message: "系统异常"})
}
}()
if err := h(w, r); err != nil {
var ae *ApiError
if errors.As(err, &ae) {
WriteError(w, ae)
} else {
WriteError(w, &ApiError{Status: 500, Code: "unknown", Message: err.Error()})
}
}
}
}
五、常见误区与注意事项
一个常见误区是在业务goroutine中panic却期望外层recover能捕获。由于recover只作用于当前goroutine，如果在handler中用了go func() { panic(...) }()，主goroutine的defer无法拦截，进程依旧会崩。此时应通过channel将错误传回主流程，或在子goroutine内部单独recover。
另一个误区是过度使用panic处理普通错误。Golang社区约定panic只用于真正异常的场景，普通错误应当用error返回。如果到处panic，不仅性能有损耗，也让控制流难以追踪。合理的方式是：预期内的失败返回error，预期外的崩溃由中间件兜底，这样才能构建可维护的Web异常体系。