在Golang的Web开发中，错误处理并不是依靠传统的try-catch异常机制，而是通过将error作为函数返回值显式传递。每一个HTTP请求到达后，通常由路由派发到对应的handler函数，如果handler内部出现预期内错误（如参数校验失败、数据库查询为空）或预期外panic（如空指针访问），都需要被合理捕获并转换为友好的响应，否则会导致请求挂起或进程退出。
一、Golang错误模型与Web请求的关系
Golang内置的error是一个仅包含Error() string方法的接口。在Web开发中，handler函数签名通常是func(w http.ResponseWriter, r *http.Request) error或者直接返回void而在内部写响应。显式返回error的好处是调用链上的每一层都必须面对错误，无法像异常那样被悄悄忽略。这种模型迫使开发者在编写数据库访问、第三方调用等逻辑时，立即判断err是否为nil。
当错误沿着调用栈向上传递时，如果最上层handler不处理，就需要依靠中间件来统一拦截。因为Go的net/http在启动goroutine处理每个请求时，若handler中产生未恢复的panic，会触发连接断开并可能在日志中打印堆栈，但并不会自动转化为HTTP 500响应体。因此理解error接口与panic的区别，是设计Web错误处理的第一步。
1.1 error与panic的本质差异
error是普通的值，代表可预期的问题，例如用户传了错误格式的JSON。panic则是不可预期的运行时崩溃，例如数组越界。在Web层，我们应该把可预期错误转成4xx状态码，把panic通过recover转成5xx，并记录日志。
下面这段代码展示了一个最简单的handler，它显式返回error并由调用方处理：
package main
import (
"errors"
"net/http"
)
type appHandler func(w http.ResponseWriter, r *http.Request) error
func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if err := fn(w, r); err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
}
}
func getUser(w http.ResponseWriter, r *http.Request) error {
id := r.URL.Query().Get("id")
if id == "" {
return errors.New("missing id parameter")
}
// 模拟业务逻辑
w.Write([]byte("user:" + id))
return nil
}
func main() {
http.Handle("/user", appHandler(getUser))
http.ListenAndServe(":8080", nil)
}
二、使用中间件统一处理错误与panic
在真实项目中，不可能在每个handler里都手写响应错误逻辑。更优雅的做法是编写一个中间件，将handler包装为返回error的类型，并在中间件中集中写HTTP状态码与消息。同时，中间件内使用defer和recover捕获panic，防止单个请求拖垮整个服务。
这种集中式处理让业务代码保持干净，只需要返回具体错误，不用关心响应格式。此外，通过自定义错误类型，我们可以携带HTTP状态码和错误码，让前端精确区分业务异常。
2.1 自定义错误类型设计
定义一个携带状态码的结构体，并实现error接口。这样在中间件中可通过类型断言取出状态码，而不是所有错误都返回500。
package main
import (
"fmt"
"net/http"
)
type httpError struct {
Code int
Message string
}
func (e *httpError) Error() string {
return e.Message
}
func newHTTPError(code int, msg string) *httpError {
return &httpError{Code: code, Message: msg}
}
func recoverMiddleware(next http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
defer func() {
if rec := recover(); rec != nil {
// 记录日志后返回500
fmt.Println("panic recovered:", rec)
http.Error(w, "internal server error", http.StatusInternalServerError)
}
}()
next(w, r)
}
}
func businessHandler(w http.ResponseWriter, r *http.Request) {
// 模拟预期错误
err := newHTTPError(http.StatusBadRequest, "invalid token")
if err != nil {
// 此处直接写响应，也可结合上节appHandler返回
http.Error(w, err.Error(), err.Code)
return
}
}
func main() {
http.HandleFunc("/api", recoverMiddleware(businessHandler))
http.ListenAndServe(":8080", nil)
}
2.2 中间件与局部处理的对比
统一中间件方案适合大多数REST API，能保证错误响应格式一致；而局部处理适合需要特殊响应结构（如文件下载失败返回特定头部）的场景。实践中常将两者结合：中间件做兜底，特殊handler自行提前返回。
需要注意，recover只能捕获当前goroutine的panic，如果在handler中又启动了子goroutine，子goroutine中的panic不会被外层recover捕获，因此异步任务要有自己的错误上报机制。
三、错误日志与可观测性实践
仅仅返回错误给客户端还不够，服务端必须记录足够上下文。建议在错误产生时附带请求ID、用户ID和堆栈。可以使用标准库log或第三方结构化日志库，将错误写入集中式日志系统。
此外，对于频繁出现的5xx，应配置告警。通过Prometheus等工具统计错误率，能快速发现依赖服务异常。下面示例展示在中间件中记录请求信息和错误：
package main
import (
"log"
"net/http"
"time"
)
func loggingMiddleware(next http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
defer func() {
log.Printf("method=%s path=%s duration=%s", r.Method, r.URL.Path, time.Since(start))
}()
next(w, r)
}
}
func hello(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("ok"))
}
func main() {
http.HandleFunc("/", loggingMiddleware(hello))
http.ListenAndServe(":8080", nil)
}
四、常见误区与改进建议
一个典型误区是在handler中直接用panic传递业务错误，这会让recover难以区分真实崩溃与业务异常。另一个误区是把底层数据库错误原样返回给前端，可能暴露表结构。正确做法是包装错误并隐藏敏感信息。
改进方案包括：使用errors.Wrap类方法保留堆栈、定义业务错误码枚举、在网关层统一剥离内部细节。这样既能方便排查，又能保障安全。
4.1 使用errors.Is与As进行错误判定
Go 1.13之后支持errors.Is判断错误链中是否包含特定错误，errors.As提取特定类型。在Web层可用它们识别上下文取消等错误，避免误报为系统异常。
package main
import (
"errors"
"net/http"
)
var ErrNotFound = errors.New("resource not found")
func findResource() error {
return ErrNotFound
}
func handler(w http.ResponseWriter, r *http.Request) {
err := findResource()
if errors.Is(err, ErrNotFound) {
http.Error(w, "not found", http.StatusNotFound)
return
}
if err != nil {
http.Error(w, "error", http.StatusInternalServerError)
return
}
w.Write([]byte("found"))
}
通过上述分层设计与工具配合，Golang的Web请求异常处理可以做到既安全又易于维护。核心原则就是：显式处理error，统一兜panic，隐藏敏感信息，记录关键上下文。