feat: 实现统一错误处理系统 (003-error-handling)

- 新增统一错误码定义和管理 (pkg/errors/codes.go)
- 新增全局错误处理器和中间件 (pkg/errors/handler.go, internal/middleware/error_handler.go)
- 新增错误上下文管理 (pkg/errors/context.go)
- 增强 Panic 恢复中间件 (internal/middleware/recover.go)
- 新增完整的单元测试和集成测试
- 新增功能文档 (docs/003-error-handling/)
- 新增功能规范 (specs/003-error-handling/)
- 更新 CLAUDE.md 和 README.md

internal/middleware/error_handler.go

@@ -0,0 +1,14 @@
+package middleware
+
+import (
+	"github.com/gofiber/fiber/v2"
+	"go.uber.org/zap"
+
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// ErrorHandler 创建全局错误处理中间件
+// 包装 pkg/errors.SafeErrorHandler 以便在 internal 层使用
+func ErrorHandler(logger *zap.Logger) fiber.ErrorHandler {
+	return errors.SafeErrorHandler(logger)
+}

internal/middleware/recover.go

@@ -1,6 +1,7 @@
 package middleware
 
 import (
+	"fmt"
 	"runtime/debug"
 
 	"github.com/gofiber/fiber/v2"
@@ -8,10 +9,10 @@ import (
 
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
-	"github.com/break/junhong_cmp_fiber/pkg/response"
 )
 
 // Recover 创建自定义 panic 恢复中间件
+// panic 会被转换为 AppError 并传递给 ErrorHandler 统一处理
 func Recover(logger *zap.Logger) fiber.Handler {
 	return func(c *fiber.Ctx) error {
 		defer func() {
@@ -25,7 +26,7 @@ func Recover(logger *zap.Logger) fiber.Handler {
 				// 捕获堆栈跟踪
 				stack := debug.Stack()
 
-				// 记录 panic 信息
+				// 记录 panic 信息（包含完整堆栈）
 				logger.Error("Panic 已恢复",
 					zap.String("request_id", requestID),
 					zap.String("method", c.Method()),
@@ -34,8 +35,18 @@ func Recover(logger *zap.Logger) fiber.Handler {
 					zap.String("stack", string(stack)),
 				)
 
-				// 返回统一错误响应
-				_ = response.Error(c, 500, errors.CodeInternalError, errors.GetMessage(errors.CodeInternalError, "zh"))
+				// 将 panic 转换为 AppError
+				// 注意：这里不直接返回响应，而是返回错误让 ErrorHandler 处理
+				// 但由于我们在 defer 中，需要通过 c.Next() 返回错误
+				panicErr := errors.Wrap(
+					errors.CodeInternalError,
+					fmt.Sprintf("服务发生异常: %v", r),
+					fmt.Errorf("panic: %v", r),
+				)
+
+				// 直接调用 ErrorHandler（通过返回错误）
+				// Fiber 会将这个错误传递给 ErrorHandler
+				_ = c.App().Config().ErrorHandler(c, panicErr)
 			}
 		}()
 

internal/middleware/recover_test.go

@@ -0,0 +1,131 @@
+package middleware
+
+import (
+	"io"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gofiber/fiber/v2"
+	"github.com/gofiber/fiber/v2/middleware/requestid"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/logger"
+)
+
+// TestRecover_PanicCapture 测试 panic 捕获功能
+func TestRecover_PanicCapture(t *testing.T) {
+	// 初始化日志器
+	_ = logger.InitLoggers(
+		"debug",
+		true,
+		logger.LogRotationConfig{
+			Filename:   "../../tests/integration/logs/recover_test.log",
+			MaxSize:    10,
+			MaxBackups: 3,
+			MaxAge:     7,
+			Compress:   false,
+		},
+		logger.LogRotationConfig{
+			Filename:   "../../tests/integration/logs/access_test.log",
+			MaxSize:    10,
+			MaxBackups: 3,
+			MaxAge:     7,
+			Compress:   false,
+		},
+	)
+
+	appLogger := logger.GetAppLogger()
+
+	app := fiber.New(fiber.Config{
+		ErrorHandler: errors.SafeErrorHandler(appLogger),
+	})
+
+	// 注册 recover 中间件
+	app.Use(Recover(appLogger))
+	app.Use(requestid.New(requestid.Config{
+		Generator: func() string {
+			return uuid.NewString()
+		},
+	}))
+
+	// 创建会触发 panic 的路由
+	app.Get("/panic", func(c *fiber.Ctx) error {
+		panic("测试 panic")
+	})
+
+	// 发起请求
+	req := httptest.NewRequest("GET", "/panic", nil)
+	resp, err := app.Test(req, -1)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	// 验证响应状态码为 500 (内部错误)
+	assert.Equal(t, 500, resp.StatusCode, "panic 应转换为 500 错误")
+
+	// 验证响应体不为空
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+	assert.NotEmpty(t, body, "panic 响应体不应为空")
+
+	t.Log("✓ Panic 捕获测试通过")
+}
+
+// TestRecover_NilPointerPanic 测试空指针 panic
+func TestRecover_NilPointerPanic(t *testing.T) {
+	appLogger := logger.GetAppLogger()
+
+	app := fiber.New(fiber.Config{
+		ErrorHandler: errors.SafeErrorHandler(appLogger),
+	})
+
+	app.Use(Recover(appLogger))
+	app.Use(requestid.New(requestid.Config{
+		Generator: func() string {
+			return uuid.NewString()
+		},
+	}))
+
+	// 创建会触发空指针 panic 的路由
+	app.Get("/nil-panic", func(c *fiber.Ctx) error {
+		var ptr *string
+		_ = *ptr // 空指针引用会导致 panic
+		return nil
+	})
+
+	req := httptest.NewRequest("GET", "/nil-panic", nil)
+	resp, err := app.Test(req, -1)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, 500, resp.StatusCode, "空指针 panic 应转换为 500 错误")
+
+	t.Log("✓ 空指针 Panic 捕获测试通过")
+}
+
+// TestRecover_NormalRequest 测试正常请求不受影响
+func TestRecover_NormalRequest(t *testing.T) {
+	appLogger := logger.GetAppLogger()
+
+	app := fiber.New(fiber.Config{
+		ErrorHandler: errors.SafeErrorHandler(appLogger),
+	})
+
+	app.Use(Recover(appLogger))
+
+	// 创建正常的路由
+	app.Get("/normal", func(c *fiber.Ctx) error {
+		return c.JSON(fiber.Map{"status": "ok"})
+	})
+
+	req := httptest.NewRequest("GET", "/normal", nil)
+	resp, err := app.Test(req, -1)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, 200, resp.StatusCode, "正常请求应返回 200")
+
+	t.Log("✓ 正常请求测试通过")
+}