Go / 系统课时
恢复处理器 Panic
恢复处理器 Panic
HTTP 处理器一旦发生 panic,当前请求会被打断;如果只依赖服务端兜底,客户端通常得不到统一的错误响应。本节实现一个请求级恢复中间件:在同一 goroutine 内捕获 panic、记录堆栈,并通过缓冲响应保证“正常结果”和“统一 500”不会混在一起。
学习目标
- 用
defer、recover和debug.Stack建立请求级 panic 边界。 - 通过缓冲
ResponseWriter在响应提交前实现原子化的成功或 500 输出。 - 识别跨 goroutine、流式响应和
http.ErrAbortHandler等恢复边界。
把恢复逻辑放在请求边界
recover 只有在发生 panic 的同一 goroutine 中,并且从延迟调用的函数里执行时才有效。因此恢复中间件必须包住业务处理器,让它的 defer 在处理器因 panic 展开调用栈时获得控制权。标准 net/http 服务端也会在连接级别兜底恢复大多数处理器 panic 并记录堆栈,但通常会关闭连接或重置 HTTP/2 流,不会替应用生成统一的 JSON 500。
另一个关键点是响应是否已经提交。处理器一旦向真实 ResponseWriter 调用 WriteHeader 或写出响应体,状态码和部分内容可能已经发给客户端,之后再写 500 不能撤回。要严格保证“成功响应或统一 500”二选一,可以先把下游的状态码、响应头和响应体写入内存缓冲,只有处理器正常返回后才一次性提交。

实现可验证的恢复中间件
下面的主示例故意让业务处理器先写入“半成品”响应,再触发 panic。bufferedWriter 隔离下游输出;captureWriter 只用于在 main 中观察最终响应,因此不依赖测试工具包。对于 http.ErrAbortHandler,示例选择重新 panic,保留 net/http 用它主动中止请求而不打印普通 panic 堆栈的语义。
package main
import (
"bytes"
"fmt"
"io"
"log"
"net/http"
"runtime/debug"
"strings"
)
type bufferedWriter struct {
header http.Header
body bytes.Buffer
status int
wroteHeader bool
}
func newBufferedWriter() *bufferedWriter {
return &bufferedWriter{
header: make(http.Header),
status: http.StatusOK,
}
}
func (w *bufferedWriter) Header() http.Header { return w.header }
func (w *bufferedWriter) WriteHeader(status int) {
if w.wroteHeader {
return
}
w.status = status
w.wroteHeader = true
}
func (w *bufferedWriter) Write(p []byte) (int, error) {
if !w.wroteHeader {
w.WriteHeader(http.StatusOK)
}
return w.body.Write(p)
}
type captureWriter struct {
header http.Header
body bytes.Buffer
status int
wroteHeader bool
}
func newCaptureWriter() *captureWriter {
return &captureWriter{header: make(http.Header)}
}
func (w *captureWriter) Header() http.Header { return w.header }
func (w *captureWriter) WriteHeader(status int) {
if w.wroteHeader {
return
}
w.status = status
w.wroteHeader = true
}
func (w *captureWriter) Write(p []byte) (int, error) {
if !w.wroteHeader {
w.WriteHeader(http.StatusOK)
}
return w.body.Write(p)
}
func recovery(next http.Handler, logger *log.Logger) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
bw := newBufferedWriter()
defer func() {
if v := recover(); v != nil {
if v == http.ErrAbortHandler {
panic(v)
}
// 丢弃缓冲区,只把诊断信息写入服务端日志。
logger.Printf("panic recovered: %v\n%s", v, debug.Stack())
responseHeader := w.Header()
responseHeader.Set("Content-Type", "application/json")
w.WriteHeader(http.StatusInternalServerError)
_, _ = io.WriteString(w, `{"error":"internal_server_error"}`)
return
}
// 只有正常返回时,才把完整缓冲结果提交给真实 writer。
for key, values := range bw.header {
for _, value := range values {
w.Header().Add(key, value)
}
}
w.WriteHeader(bw.status)
_, _ = io.Copy(w, &bw.body)
}()
next.ServeHTTP(bw, r)
})
}
func main() {
var logs bytes.Buffer
logger := log.New(&logs, "", 0)
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("X-Partial", "should-not-escape")
_, _ = io.WriteString(w, "partial response")
panic("database invariant broken")
})
req, err := http.NewRequest(http.MethodGet, "http://service.local/orders/42", nil)
if err != nil {
log.Fatal(err)
}
out := newCaptureWriter()
recovery(handler, logger).ServeHTTP(out, req)
fmt.Println("status:", out.status)
fmt.Println("body:", out.body.String())
fmt.Println("partial header escaped:", out.Header().Get("X-Partial") != "")
fmt.Println("stack logged:", strings.Contains(logs.String(), "goroutine"))
}预期输出
status: 500
body: {"error":"internal_server_error"}
partial header escaped: false
stack logged: truedebug.Stack 会包含 goroutine 编号、函数名和文件行号,这些值随构建和运行环境变化,所以这里只验证日志中确实出现了堆栈,而不把动态内容写死。示例中的 URL 仅用于构造请求,不会发起网络访问。
明确 recover 的边界
恢复中间件适合隔离单个请求中的意外 panic,例如数组越界、空指针解引用或遗留代码主动 panic;它不应替代正常错误处理。可预期的业务失败仍应通过 error 返回,并显式映射为合适的 4xx 或 5xx。
recover 不能跨 goroutine。处理器自行启动 goroutine 后,如果该 goroutine 发生 panic,就必须在那个 goroutine 的入口单独设置恢复边界;当前请求的中间件捕获不到它。对于 http.ErrAbortHandler 这类有特殊语义的 panic,也不要无条件转换成普通 500,否则会改变标准库预期的中止行为。
生产环境还要确认响应能力
全量缓冲适合体积可控的 JSON API,但它会占用与响应体大小近似的额外内存,而且示例包装器没有实现 http.Flusher、http.Hijacker、io.ReaderFrom 等可选能力,因此不适合大文件、SSE、流式下载或 WebSocket。此类端点应使用不依赖全量缓冲的恢复策略,或者在路由层明确排除。
恢复日志至少应关联请求 ID、方法、路径、panic 值和堆栈,但不要把 Authorization、Cookie 等敏感头整包写入日志。这样既能把单请求故障收束在清晰边界内,也不会因为“成功捕获 panic”而掩盖真正需要终止进程的严重故障。