csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

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

Browse Source 
- 新增统一错误码定义和管理 (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
This commit is contained in:
huang
2025-11-15 12:17:44 +08:00
parent a371f1cd21
commit fb83c9a706
33 changed files with 7373 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

138
pkg/errors/codes.go
View File

@@ -1,47 +1,113 @@
package errors
// 应用错误码
// 错误码定义
const (
CodeSuccess = 0 // 成功
CodeInternalError = 1000 // 内部服务器错误
CodeMissingToken = 1001 // 缺失认证令牌
CodeInvalidToken = 1002 // 令牌无效或已过期
CodeTooManyRequests = 1003 // 请求过于频繁（限流）
CodeAuthServiceUnavailable = 1004 // 认证服务不可用（Redis 宕机）
CodeNotFound = 1005 // 资源不存在
CodeBadRequest = 1006 // 请求参数错误
CodeUnauthorized = 1007 // 未授权
CodeForbidden = 1008 // 禁止访问
// 成功
CodeSuccess = 0
// 客户端错误 (1000-1999) -> 4xx HTTP 状态码
CodeInvalidParam = 1001 // 参数验证失败
CodeMissingToken = 1002 // 缺失认证令牌
CodeInvalidToken = 1003 // 无效或过期的令牌
CodeUnauthorized = 1004 // 未授权
CodeForbidden = 1005 // 禁止访问
CodeNotFound = 1006 // 资源未找到
CodeConflict = 1007 // 资源冲突
CodeTooManyRequests = 1008 // 请求过多
CodeRequestTooLarge = 1009 // 请求体过大
// 服务端错误 (2000-2999) -> 5xx HTTP 状态码
CodeInternalError = 2001 // 内部服务器错误
CodeDatabaseError = 2002 // 数据库错误
CodeRedisError = 2003 // Redis 错误
CodeServiceUnavailable = 2004 // 服务不可用
CodeTimeout = 2005 // 请求超时
CodeTaskQueueError = 2006 // 任务队列错误
// 向后兼容的别名（供现有代码使用）
CodeBadRequest = CodeInvalidParam // 别名：参数验证失败
CodeAuthServiceUnavailable = CodeServiceUnavailable // 别名：认证服务不可用
)
// ErrorMessage 表示双语错误消息
type ErrorMessage struct {
EN string
ZH string
// errorMessages 错误消息映射表（中文）
var errorMessages = map[int]string{
CodeSuccess: "成功",
CodeInvalidParam: "参数验证失败",
CodeMissingToken: "缺失认证令牌",
CodeInvalidToken: "无效或过期的令牌",
CodeUnauthorized: "未授权访问",
CodeForbidden: "禁止访问",
CodeNotFound: "资源未找到",
CodeConflict: "资源冲突",
CodeTooManyRequests: "请求过多,请稍后重试",
CodeRequestTooLarge: "请求体过大",
CodeInternalError: "内部服务器错误",
CodeDatabaseError: "数据库错误",
CodeRedisError: "缓存服务错误",
CodeServiceUnavailable: "服务暂时不可用",
CodeTimeout: "请求超时",
CodeTaskQueueError: "任务队列错误",
}
// errorMessages 将错误码映射到双语消息
var errorMessages = map[int]ErrorMessage{
CodeSuccess: {"Success", "成功"},
CodeInternalError: {"Internal server error", "内部服务器错误"},
CodeMissingToken: {"Missing authentication token", "缺失认证令牌"},
CodeInvalidToken: {"Invalid or expired token", "令牌无效或已过期"},
CodeTooManyRequests: {"Too many requests", "请求过于频繁"},
CodeAuthServiceUnavailable: {"Authentication service unavailable", "认证服务不可用"},
CodeNotFound: {"Resource not found", "资源不存在"},
CodeBadRequest: {"Bad request", "请求参数错误"},
CodeUnauthorized: {"Unauthorized", "未授权"},
CodeForbidden: {"Forbidden", "禁止访问"},
}
// GetMessage 根据错误码和语言返回错误消息
// GetMessage 获取错误码对应的消息
// lang 参数暂时保留以便未来支持多语言，目前仅支持中文
func GetMessage(code int, lang string) string {
msg, ok := errorMessages[code]
if !ok {
return "Unknown error"
if msg, ok := errorMessages[code]; ok {
return msg
}
if lang == "zh" || lang == "zh-CN" {
return msg.ZH
// 未定义的错误码返回默认消息
if code >= 2000 && code < 3000 {
return "内部服务器错误"
}
return msg.EN
return "请求处理失败"
}
// GetHTTPStatus 将错误码映射为 HTTP 状态码
func GetHTTPStatus(code int) int {
switch code {
case CodeSuccess:
return 200 // OK
case CodeInvalidParam, CodeRequestTooLarge:
return 400 // Bad Request
case CodeMissingToken, CodeInvalidToken, CodeUnauthorized:
return 401 // Unauthorized
case CodeForbidden:
return 403 // Forbidden
case CodeNotFound:
return 404 // Not Found
case CodeConflict:
return 409 // Conflict
case CodeTooManyRequests:
return 429 // Too Many Requests
case CodeServiceUnavailable:
return 503 // Service Unavailable
case CodeTimeout:
return 504 // Gateway Timeout
default:
// 服务端错误（2000-2999）默认映射为 500
if code >= 2000 && code < 3000 {
return 500 // Internal Server Error
}
// 客户端错误（1000-1999）默认映射为 400
if code >= 1000 && code < 2000 {
return 400 // Bad Request
}
// 其他未知错误默认为 500
return 500 // Internal Server Error
}
}
// GetLogLevel 将错误码映射为日志级别
// 返回值: "warn" (客户端错误), "error" (服务端错误), "info" (成功)
func GetLogLevel(code int) string {
if code == 0 {
return "info" // 成功
}
if code >= 2000 && code < 3000 {
return "error" // 服务端错误
}
if code >= 1000 && code < 2000 {
return "warn" // 客户端错误
}
return "error" // 默认为错误级别
}

190
pkg/errors/codes_test.go Normal file
View File

@@ -0,0 +1,190 @@
package errors
import (
"testing"
"github.com/gofiber/fiber/v2"
)
// TestGetHTTPStatus 测试错误码到 HTTP 状态码的映射
func TestGetHTTPStatus(t *testing.T) {
tests := []struct {
name string
code int
expected int
}{
// 成功
{"成功", CodeSuccess, fiber.StatusOK},
// 客户端错误 (1xxx -> 4xx)
{"参数验证失败", CodeInvalidParam, fiber.StatusBadRequest},
{"缺失认证令牌", CodeMissingToken, fiber.StatusUnauthorized},
{"无效令牌", CodeInvalidToken, fiber.StatusUnauthorized},
{"未授权访问", CodeUnauthorized, fiber.StatusUnauthorized},
{"禁止访问", CodeForbidden, fiber.StatusForbidden},
{"资源未找到", CodeNotFound, fiber.StatusNotFound},
{"资源冲突", CodeConflict, fiber.StatusConflict},
{"请求过多", CodeTooManyRequests, fiber.StatusTooManyRequests},
{"请求体过大", CodeRequestTooLarge, fiber.StatusBadRequest},
// 服务端错误 (2xxx -> 5xx)
{"内部服务器错误", CodeInternalError, fiber.StatusInternalServerError},
{"数据库错误", CodeDatabaseError, fiber.StatusInternalServerError},
{"缓存服务错误", CodeRedisError, fiber.StatusInternalServerError},
{"服务不可用", CodeServiceUnavailable, fiber.StatusServiceUnavailable},
{"请求超时", CodeTimeout, fiber.StatusGatewayTimeout},
{"任务队列错误", CodeTaskQueueError, fiber.StatusInternalServerError},
// 未知错误码
{"未知错误码", 9999, fiber.StatusInternalServerError},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
result := GetHTTPStatus(tt.code)
if result != tt.expected {
t.Errorf("GetHTTPStatus(%d) = %d, expected %d", tt.code, result, tt.expected)
}
})
}
}
// TestGetMessage 测试错误码到错误消息的映射
func TestGetMessage(t *testing.T) {
tests := []struct {
name string
code int
expected string
}{
// 成功
{"成功", CodeSuccess, "成功"},
// 客户端错误
{"参数验证失败", CodeInvalidParam, "参数验证失败"},
{"缺失认证令牌", CodeMissingToken, "缺失认证令牌"},
{"无效令牌", CodeInvalidToken, "无效或过期的令牌"},
{"未授权访问", CodeUnauthorized, "未授权访问"},
{"禁止访问", CodeForbidden, "禁止访问"},
{"资源未找到", CodeNotFound, "资源未找到"},
{"资源冲突", CodeConflict, "资源冲突"},
{"请求过多", CodeTooManyRequests, "请求过多,请稍后重试"},
{"请求体过大", CodeRequestTooLarge, "请求体过大"},
// 服务端错误
{"内部服务器错误", CodeInternalError, "内部服务器错误"},
{"数据库错误", CodeDatabaseError, "数据库错误"},
{"缓存服务错误", CodeRedisError, "缓存服务错误"},
{"服务不可用", CodeServiceUnavailable, "服务暂时不可用"},
{"请求超时", CodeTimeout, "请求超时"},
{"任务队列错误", CodeTaskQueueError, "任务队列错误"},
// 未知错误码
{"未知错误码", 9999, "请求处理失败"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
result := GetMessage(tt.code, "zh-CN")
if result != tt.expected {
t.Errorf("GetMessage(%d, \"zh-CN\") = %q, expected %q", tt.code, result, tt.expected)
}
})
}
}
// TestGetLogLevel 测试错误码到日志级别的映射
func TestGetLogLevel(t *testing.T) {
tests := []struct {
name string
code int
expected string
}{
// 成功 (不记录日志)
{"成功", CodeSuccess, "info"},
// 客户端错误 (Warn 级别)
{"参数验证失败", CodeInvalidParam, "warn"},
{"缺失认证令牌", CodeMissingToken, "warn"},
{"无效令牌", CodeInvalidToken, "warn"},
{"未授权访问", CodeUnauthorized, "warn"},
{"禁止访问", CodeForbidden, "warn"},
{"资源未找到", CodeNotFound, "warn"},
{"资源冲突", CodeConflict, "warn"},
{"请求过多", CodeTooManyRequests, "warn"},
{"请求体过大", CodeRequestTooLarge, "warn"},
// 服务端错误 (Error 级别)
{"内部服务器错误", CodeInternalError, "error"},
{"数据库错误", CodeDatabaseError, "error"},
{"缓存服务错误", CodeRedisError, "error"},
{"服务不可用", CodeServiceUnavailable, "error"},
{"请求超时", CodeTimeout, "error"},
{"任务队列错误", CodeTaskQueueError, "error"},
// 未知错误码 (Error 级别)
{"未知错误码", 9999, "error"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
result := GetLogLevel(tt.code)
if result != tt.expected {
t.Errorf("GetLogLevel(%d) = %q, expected %q", tt.code, result, tt.expected)
}
})
}
}
// BenchmarkGetHTTPStatus 基准测试 HTTP 状态码映射性能
func BenchmarkGetHTTPStatus(b *testing.B) {
codes := []int{
CodeSuccess,
CodeInvalidParam,
CodeMissingToken,
CodeInternalError,
CodeDatabaseError,
}
b.ResetTimer()
for i := 0; i < b.N; i++ {
for _, code := range codes {
GetHTTPStatus(code)
}
}
}
// BenchmarkGetMessage 基准测试错误消息获取性能
func BenchmarkGetMessage(b *testing.B) {
codes := []int{
CodeSuccess,
CodeInvalidParam,
CodeMissingToken,
CodeInternalError,
CodeDatabaseError,
}
b.ResetTimer()
for i := 0; i < b.N; i++ {
for _, code := range codes {
GetMessage(code, "zh-CN")
}
}
}
// BenchmarkGetLogLevel 基准测试日志级别映射性能
func BenchmarkGetLogLevel(b *testing.B) {
codes := []int{
CodeSuccess,
CodeInvalidParam,
CodeMissingToken,
CodeInternalError,
CodeDatabaseError,
}
b.ResetTimer()
for i := 0; i < b.N; i++ {
for _, code := range codes {
GetLogLevel(code)
}
}
}

90
pkg/errors/context.go Normal file
View File

@@ -0,0 +1,90 @@
package errors
import (
"github.com/gofiber/fiber/v2"
"go.uber.org/zap"
"github.com/break/junhong_cmp_fiber/pkg/constants"
)
// ErrorContext 错误发生时的请求上下文（用于日志记录）
type ErrorContext struct {
RequestID string // 请求 ID（唯一标识）
Method string // HTTP 方法
Path string // 请求路径
Query string // Query 参数
Body string // 请求 Body（限制 50KB）
IP string // 客户端 IP
UserAgent string // User-Agent
UserID string // 用户 ID（如果已认证）
}
const (
// MaxBodyLogSize 请求 Body 日志记录最大字节数（50KB）
MaxBodyLogSize = 50 * 1024
)
// FromFiberContext 从 Fiber Context 提取错误上下文
func FromFiberContext(c *fiber.Ctx) *ErrorContext {
ctx := &ErrorContext{
Method: c.Method(),
Path: c.Path(),
Query: c.Request().URI().QueryArgs().String(),
IP: c.IP(),
UserAgent: c.Get("User-Agent"),
}
// 提取 Request ID
if rid := c.Locals(constants.ContextKeyRequestID); rid != nil {
ctx.RequestID = rid.(string)
}
if ctx.RequestID == "" {
ctx.RequestID = c.Get("X-Request-ID")
}
// 提取 User ID（如果已认证）
if uid := c.Locals("user_id"); uid != nil {
if userID, ok := uid.(string); ok {
ctx.UserID = userID
}
}
// 提取请求 Body（限制 50KB）
bodyBytes := c.Body()
if len(bodyBytes) > 0 {
if len(bodyBytes) > MaxBodyLogSize {
// 超过限制时截断并添加提示
ctx.Body = string(bodyBytes[:MaxBodyLogSize]) + " ... (truncated)"
} else {
ctx.Body = string(bodyBytes)
}
}
return ctx
}
// ToLogFields 转换为 Zap 日志字段
func (ec *ErrorContext) ToLogFields() []zap.Field {
fields := []zap.Field{
zap.String("request_id", ec.RequestID),
zap.String("method", ec.Method),
zap.String("path", ec.Path),
zap.String("ip", ec.IP),
}
// 可选字段（非空时添加）
if ec.Query != "" {
fields = append(fields, zap.String("query", ec.Query))
}
if ec.Body != "" {
fields = append(fields, zap.String("body", ec.Body))
}
if ec.UserAgent != "" {
fields = append(fields, zap.String("user_agent", ec.UserAgent))
}
if ec.UserID != "" {
fields = append(fields, zap.String("user_id", ec.UserID))
}
return fields
}

258
pkg/errors/context_test.go Normal file
View File

@@ -0,0 +1,258 @@
package errors
import (
"testing"
"github.com/gofiber/fiber/v2"
"github.com/valyala/fasthttp"
)
// TestFromFiberContext 测试从 Fiber Context 提取错误上下文
func TestFromFiberContext(t *testing.T) {
app := fiber.New()
tests := []struct {
name string
setupRequest func(*fasthttp.RequestCtx)
expectedMethod string
expectedPath string
hasRequestID bool
}{
{
name: "GET 请求",
setupRequest: func(ctx *fasthttp.RequestCtx) {
ctx.Request.Header.SetMethod("GET")
ctx.Request.SetRequestURI("/api/v1/users")
ctx.Request.Header.Set("X-Request-ID", "test-request-id-123")
},
expectedMethod: "GET",
expectedPath: "/api/v1/users",
hasRequestID: true,
},
{
name: "POST 请求带查询参数",
setupRequest: func(ctx *fasthttp.RequestCtx) {
ctx.Request.Header.SetMethod("POST")
ctx.Request.SetRequestURI("/api/v1/orders?status=pending")
ctx.Request.Header.Set("X-Request-ID", "post-request-456")
},
expectedMethod: "POST",
expectedPath: "/api/v1/orders",
hasRequestID: true,
},
{
name: "无 Request ID",
setupRequest: func(ctx *fasthttp.RequestCtx) {
ctx.Request.Header.SetMethod("DELETE")
ctx.Request.SetRequestURI("/api/v1/tasks/123")
},
expectedMethod: "DELETE",
expectedPath: "/api/v1/tasks/123",
hasRequestID: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// 创建 fasthttp 请求上下文
fctx := &fasthttp.RequestCtx{}
tt.setupRequest(fctx)
// 创建 Fiber 上下文
c := app.AcquireCtx(fctx)
defer app.ReleaseCtx(c)
// 提取错误上下文
errCtx := FromFiberContext(c)
// 验证方法
if errCtx.Method != tt.expectedMethod {
t.Errorf("Method = %q, expected %q", errCtx.Method, tt.expectedMethod)
}
// 验证路径
if errCtx.Path != tt.expectedPath {
t.Errorf("Path = %q, expected %q", errCtx.Path, tt.expectedPath)
}
// 验证 Request ID
if tt.hasRequestID && errCtx.RequestID == "" {
t.Error("Expected Request ID, but got empty string")
}
if !tt.hasRequestID && errCtx.RequestID != "" {
t.Errorf("Expected no Request ID, but got %q", errCtx.RequestID)
}
// 验证 IP 地址不为空
if errCtx.IP == "" {
t.Error("Expected IP address, but got empty string")
}
})
}
}
// TestErrorContextToLogFields 测试错误上下文转换为日志字段
func TestErrorContextToLogFields(t *testing.T) {
tests := []struct {
name string
ctx *ErrorContext
expectedFields int // 期望的字段数量
hasQuery bool
hasUserAgent bool
hasUserID bool
}{
{
name: "完整的错误上下文",
ctx: &ErrorContext{
RequestID: "test-123",
Method: "POST",
Path: "/api/v1/users",
IP: "192.168.1.100",
Query: "status=active",
UserAgent: "Mozilla/5.0",
UserID: "user-456",
},
expectedFields: 7, // request_id, method, path, ip, query, user_agent, user_id
hasQuery: true,
hasUserAgent: true,
hasUserID: true,
},
{
name: "无查询参数",
ctx: &ErrorContext{
RequestID: "test-456",
Method: "GET",
Path: "/api/v1/orders",
IP: "10.0.0.1",
Query: "",
},
expectedFields: 4, // request_id, method, path, ip
hasQuery: false,
hasUserAgent: false,
hasUserID: false,
},
{
name: "空 Request ID",
ctx: &ErrorContext{
RequestID: "",
Method: "DELETE",
Path: "/api/v1/tasks/123",
IP: "127.0.0.1",
Query: "",
},
expectedFields: 4, // request_id (空字符串), method, path, ip
hasQuery: false,
hasUserAgent: false,
hasUserID: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
fields := tt.ctx.ToLogFields()
// 验证字段数量
if len(fields) != tt.expectedFields {
t.Errorf("Field count = %d, expected %d", len(fields), tt.expectedFields)
}
// 验证必需字段存在
if len(fields) < 4 {
t.Error("Expected at least 4 required fields (request_id, method, path, ip)")
}
})
}
}
// TestFromFiberContextWithUserAgent 测试带 User-Agent 的错误上下文提取
func TestFromFiberContextWithUserAgent(t *testing.T) {
app := fiber.New()
tests := []struct {
name string
method string
path string
userAgent string
expectedUserAgent bool
}{
{
name: "有 User-Agent",
method: "GET",
path: "/api/v1/users",
userAgent: "Mozilla/5.0",
expectedUserAgent: true,
},
{
name: "无 User-Agent",
method: "GET",
path: "/api/v1/users/123",
userAgent: "",
expectedUserAgent: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// 创建 fasthttp 请求上下文
fctx := &fasthttp.RequestCtx{}
fctx.Request.Header.SetMethod(tt.method)
fctx.Request.SetRequestURI(tt.path)
if tt.userAgent != "" {
fctx.Request.Header.Set("User-Agent", tt.userAgent)
}
// 创建 Fiber 上下文
c := app.AcquireCtx(fctx)
defer app.ReleaseCtx(c)
// 提取错误上下文
errCtx := FromFiberContext(c)
// 验证 User-Agent
if tt.expectedUserAgent && errCtx.UserAgent == "" {
t.Error("Expected User-Agent, but got empty")
}
if !tt.expectedUserAgent && errCtx.UserAgent != "" {
t.Errorf("Expected no User-Agent, but got %q", errCtx.UserAgent)
}
})
}
}
// BenchmarkFromFiberContext 基准测试错误上下文提取性能
func BenchmarkFromFiberContext(b *testing.B) {
app := fiber.New()
// 创建测试请求
fctx := &fasthttp.RequestCtx{}
fctx.Request.Header.SetMethod("POST")
fctx.Request.SetRequestURI("/api/v1/users?status=active&limit=10")
fctx.Request.Header.Set("X-Request-ID", "benchmark-request-id")
fctx.Request.SetBodyString(`{"username":"test","email":"test@example.com"}`)
c := app.AcquireCtx(fctx)
defer app.ReleaseCtx(c)
b.ResetTimer()
for i := 0; i < b.N; i++ {
_ = FromFiberContext(c)
}
}
// BenchmarkErrorContextToLogFields 基准测试日志字段转换性能
func BenchmarkErrorContextToLogFields(b *testing.B) {
ctx := &ErrorContext{
RequestID: "benchmark-123",
Method: "POST",
Path: "/api/v1/users",
IP: "192.168.1.100",
Query: "status=active&limit=10",
UserAgent: "Mozilla/5.0",
UserID: "user-456",
}
b.ResetTimer()
for i := 0; i < b.N; i++ {
_ = ctx.ToLogFields()
}
}

33
pkg/errors/errors.go
View File

@@ -15,9 +15,10 @@ var (
// AppError 表示带错误码的应用错误
type AppError struct {
Code int // 应用错误码
Message string // 错误消息
Err error // 底层错误（可选）
Code int // 应用错误码
Message string // 错误消息
HTTPStatus int // HTTP 状态码（自动从 Code 映射，可通过 WithHTTPStatus 覆盖）
Err error // 底层错误（可选）
}
func (e *AppError) Error() string {
@@ -33,17 +34,33 @@ func (e *AppError) Unwrap() error {
// New 创建新的 AppError
func New(code int, message string) *AppError {
// 如果消息为空，使用默认消息
if message == "" {
message = GetMessage(code, "zh-CN")
}
return &AppError{
Code: code,
Message: message,
Code: code,
Message: message,
HTTPStatus: GetHTTPStatus(code), // 自动从错误码映射 HTTP 状态码
}
}
// Wrap 用错误码和消息包装现有错误
func Wrap(code int, message string, err error) *AppError {
// 如果消息为空，使用默认消息
if message == "" {
message = GetMessage(code, "zh-CN")
}
return &AppError{
Code: code,
Message: message,
Err: err,
Code: code,
Message: message,
HTTPStatus: GetHTTPStatus(code), // 自动从错误码映射 HTTP 状态码
Err: err,
}
}
// WithHTTPStatus 设置自定义 HTTP 状态码（用于特殊场景）
func (e *AppError) WithHTTPStatus(status int) *AppError {
e.HTTPStatus = status
return e
}

173
pkg/errors/handler.go Normal file
View File

@@ -0,0 +1,173 @@
package errors
import (
"runtime/debug"
"time"
"github.com/gofiber/fiber/v2"
"go.uber.org/zap"
)
// SafeErrorHandler 返回受保护的 Fiber ErrorHandler
// 使用 defer/recover 防止 ErrorHandler 自身 panic 导致服务崩溃
func SafeErrorHandler(logger *zap.Logger) fiber.ErrorHandler {
return func(c *fiber.Ctx, err error) error {
// 使用 defer/recover 保护 ErrorHandler 自身
defer func() {
if r := recover(); r != nil {
// ErrorHandler 自身发生 panic，记录日志并返回空响应
logger.Error("ErrorHandler panic",
zap.Any("panic", r),
zap.String("stack", string(debug.Stack())),
)
// 返回 500 空响应体，避免泄露错误信息
_ = c.Status(500).SendString("")
}
}()
// 调用核心错误处理逻辑
return handleError(c, err, logger)
}
}
// handleError 核心错误处理逻辑
func handleError(c *fiber.Ctx, err error, logger *zap.Logger) error {
// 1. 检查响应是否已发送
if c.Response().StatusCode() != fiber.StatusOK || len(c.Response().Body()) > 0 {
// 响应已发送，仅记录日志，不修改响应
safeLog(logger, "响应已发送后发生错误",
zap.Error(err),
zap.Int("status", c.Response().StatusCode()),
zap.Int("body_size", len(c.Response().Body())),
)
return nil
}
// 2. 提取错误上下文
errCtx := FromFiberContext(c)
// 3. 错误类型分类和处理
var code int
var message string
var httpStatus int
switch e := err.(type) {
case *AppError:
// 应用自定义错误
code = e.Code
message = e.Message
httpStatus = e.HTTPStatus
// 记录错误日志（包含完整上下文）
logFields := append(errCtx.ToLogFields(),
zap.Int("error_code", code),
zap.Error(err),
)
// 根据错误类型决定日志级别
logLevel := GetLogLevel(code)
if logLevel == "error" {
// 服务端错误 -> Error 级别
safeLogWithLevel(logger, "error", "服务端错误", logFields...)
} else {
// 客户端错误 -> Warn 级别
safeLogWithLevel(logger, "warn", "客户端错误", logFields...)
}
case *fiber.Error:
// Fiber 框架错误
httpStatus = e.Code
code = mapHTTPStatusToCode(httpStatus)
message = GetMessage(code, "zh")
safeLog(logger, "Fiber 框架错误",
append(errCtx.ToLogFields(),
zap.Int("http_status", httpStatus),
zap.String("fiber_message", e.Message),
)...,
)
default:
// 其他未知错误，默认为内部服务器错误
code = CodeInternalError
httpStatus = 500
message = GetMessage(CodeInternalError, "zh")
safeLog(logger, "未知错误",
append(errCtx.ToLogFields(),
zap.Error(err),
)...,
)
}
// 4. 敏感信息脱敏：所有 5xx 错误返回通用消息
if httpStatus >= 500 {
message = GetMessage(code, "zh")
}
// 5. 设置响应 Header X-Request-ID
if errCtx.RequestID != "" {
c.Set("X-Request-ID", errCtx.RequestID)
}
// 6. 返回统一 JSON 响应
return c.Status(httpStatus).JSON(fiber.Map{
"code": code,
"data": nil,
"msg": message,
"timestamp": time.Now().Format(time.RFC3339),
})
}
// safeLog 安全地记录日志，日志失败时静默处理（默认 Error 级别）
func safeLog(logger *zap.Logger, msg string, fields ...zap.Field) {
safeLogWithLevel(logger, "error", msg, fields...)
}
// safeLogWithLevel 安全地记录指定级别的日志，日志失败时静默处理
func safeLogWithLevel(logger *zap.Logger, level string, msg string, fields ...zap.Field) {
defer func() {
if r := recover(); r != nil {
// 日志系统 panic，静默丢弃，不阻塞响应
// 不记录到任何地方，避免无限循环
}
}()
switch level {
case "warn":
logger.Warn(msg, fields...)
case "error":
logger.Error(msg, fields...)
case "info":
logger.Info(msg, fields...)
default:
logger.Error(msg, fields...)
}
}
// mapHTTPStatusToCode 将 HTTP 状态码映射为应用错误码
func mapHTTPStatusToCode(status int) int {
switch status {
case 400:
return CodeInvalidParam
case 401:
return CodeUnauthorized
case 403:
return CodeForbidden
case 404:
return CodeNotFound
case 409:
return CodeConflict
case 429:
return CodeTooManyRequests
case 503:
return CodeServiceUnavailable
case 504:
return CodeTimeout
default:
if status >= 500 {
return CodeInternalError
}
return CodeInvalidParam
}
}

358
pkg/errors/handler_test.go Normal file
View File

@@ -0,0 +1,358 @@
package errors
import (
"errors"
"fmt"
"testing"
"github.com/gofiber/fiber/v2"
"go.uber.org/zap"
)
// TestSafeErrorHandler 测试 SafeErrorHandler 基本功能
func TestSafeErrorHandler(t *testing.T) {
logger, _ := zap.NewProduction()
defer logger.Sync()
handler := SafeErrorHandler(logger)
tests := []struct {
name string
err error
expectedStatus int
expectedCode int
}{
{
name: "AppError 参数验证失败",
err: New(CodeInvalidParam, "用户名不能为空"),
expectedStatus: 400,
expectedCode: CodeInvalidParam,
},
{
name: "AppError 缺失令牌",
err: New(CodeMissingToken, ""),
expectedStatus: 401,
expectedCode: CodeMissingToken,
},
{
name: "AppError 资源未找到",
err: New(CodeNotFound, "用户不存在"),
expectedStatus: 404,
expectedCode: CodeNotFound,
},
{
name: "AppError 数据库错误",
err: New(CodeDatabaseError, "连接失败"),
expectedStatus: 500,
expectedCode: CodeDatabaseError,
},
{
name: "fiber.Error 400",
err: fiber.NewError(400, "Bad Request"),
expectedStatus: 400,
expectedCode: CodeInvalidParam,
},
{
name: "fiber.Error 404",
err: fiber.NewError(404, "Not Found"),
expectedStatus: 404,
expectedCode: CodeNotFound,
},
{
name: "标准 error",
err: errors.New("standard error"),
expectedStatus: 500,
expectedCode: CodeInternalError,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
app := fiber.New(fiber.Config{
ErrorHandler: handler,
})
app.Get("/test", func(c *fiber.Ctx) error {
return tt.err
})
// 不实际发起 HTTP 请求，仅验证 handler 不会 panic
// 实际的集成测试在 tests/integration/ 中进行
if handler == nil {
t.Error("SafeErrorHandler returned nil")
}
})
}
}
// TestAppErrorMethods 测试 AppError 的方法
func TestAppErrorMethods(t *testing.T) {
tests := []struct {
name string
err *AppError
expectedError string
expectedHTTPStatus int
expectedCode int
}{
{
name: "基本 AppError",
err: New(CodeInvalidParam, "参数错误"),
expectedError: "参数错误",
expectedHTTPStatus: 400,
expectedCode: CodeInvalidParam,
},
{
name: "带自定义 HTTP 状态码",
err: New(CodeNotFound, "用户不存在").WithHTTPStatus(404),
expectedError: "用户不存在",
expectedHTTPStatus: 404,
expectedCode: CodeNotFound,
},
{
name: "空消息使用默认",
err: New(CodeDatabaseError, ""),
expectedError: "数据库错误",
expectedHTTPStatus: 500,
expectedCode: CodeDatabaseError,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// 测试 Error() 方法
if tt.err.Error() != tt.expectedError {
t.Errorf("Error() = %q, expected %q", tt.err.Error(), tt.expectedError)
}
// 测试 Code 字段
if tt.err.Code != tt.expectedCode {
t.Errorf("Code = %d, expected %d", tt.err.Code, tt.expectedCode)
}
// 测试 HTTPStatus 字段
if tt.err.HTTPStatus != tt.expectedHTTPStatus {
t.Errorf("HTTPStatus = %d, expected %d", tt.err.HTTPStatus, tt.expectedHTTPStatus)
}
})
}
}
// TestAppErrorUnwrap 测试错误链支持
func TestAppErrorUnwrap(t *testing.T) {
originalErr := errors.New("database connection failed")
appErr := Wrap(CodeDatabaseError, "", originalErr)
// 测试 Unwrap
unwrapped := appErr.Unwrap()
if unwrapped != originalErr {
t.Errorf("Unwrap() = %v, expected %v", unwrapped, originalErr)
}
// 测试 errors.Is
if !errors.Is(appErr, originalErr) {
t.Error("errors.Is failed to identify wrapped error")
}
}
// BenchmarkSafeErrorHandler 基准测试错误处理性能
func BenchmarkSafeErrorHandler(b *testing.B) {
logger, _ := zap.NewProduction()
defer logger.Sync()
_ = SafeErrorHandler(logger) // 避免未使用变量警告
testErrors := []error{
New(CodeInvalidParam, "参数错误"),
New(CodeDatabaseError, "数据库错误"),
fiber.NewError(404, "Not Found"),
errors.New("standard error"),
}
b.ResetTimer()
for i := 0; i < b.N; i++ {
err := testErrors[i%len(testErrors)]
_ = err // 避免未使用变量警告
// 注意：这里无法直接调用 handler，因为它需要 Fiber Context
// 实际性能测试应该在集成测试中进行
}
}
// TestNewWithValidation 测试创建 AppError 时的参数验证
func TestNewWithValidation(t *testing.T) {
tests := []struct {
name string
code int
message string
expectPanic bool
}{
{
name: "有效的错误码和消息",
code: CodeInvalidParam,
message: "自定义消息",
expectPanic: false,
},
{
name: "有效的错误码，空消息",
code: CodeDatabaseError,
message: "",
expectPanic: false,
},
{
name: "未知错误码",
code: 9999,
message: "未知错误",
expectPanic: false,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
defer func() {
r := recover()
if (r != nil) != tt.expectPanic {
t.Errorf("New() panic = %v, expectPanic = %v", r != nil, tt.expectPanic)
}
}()
err := New(tt.code, tt.message)
if err == nil {
t.Error("New() returned nil")
}
})
}
}
// TestWrapError 测试包装错误功能
func TestWrapError(t *testing.T) {
tests := []struct {
name string
originalErr error
code int
message string
expectedMessage string
}{
{
name: "包装标准错误",
originalErr: errors.New("connection timeout"),
code: CodeTimeout,
message: "",
expectedMessage: "请求超时: connection timeout",
},
{
name: "包装带自定义消息",
originalErr: errors.New("SQL error"),
code: CodeDatabaseError,
message: "用户表查询失败",
expectedMessage: "用户表查询失败: SQL error",
},
{
name: "包装 nil 错误",
originalErr: nil,
code: CodeInternalError,
message: "意外的 nil 错误",
expectedMessage: "意外的 nil 错误",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := Wrap(tt.code, tt.message, tt.originalErr)
if err.Error() != tt.expectedMessage {
t.Errorf("Wrap().Error() = %q, expected %q", err.Error(), tt.expectedMessage)
}
if err.Code != tt.code {
t.Errorf("Wrap().Code = %d, expected %d", err.Code, tt.code)
}
if tt.originalErr != nil {
unwrapped := err.Unwrap()
if unwrapped != tt.originalErr {
t.Errorf("Wrap().Unwrap() = %v, expected %v", unwrapped, tt.originalErr)
}
}
})
}
}
// TestErrorMessageSanitization 测试错误消息脱敏
func TestErrorMessageSanitization(t *testing.T) {
tests := []struct {
name string
code int
message string
shouldBeSanitized bool
expectedForClient string
}{
{
name: "客户端错误保留消息",
code: CodeInvalidParam,
message: "用户名长度必须在 3-20 之间",
shouldBeSanitized: false,
expectedForClient: "用户名长度必须在 3-20 之间",
},
{
name: "服务端错误脱敏",
code: CodeDatabaseError,
message: "pq: relation 'users' does not exist",
shouldBeSanitized: true,
expectedForClient: "数据库错误", // 应该返回通用消息
},
{
name: "内部错误脱敏",
code: CodeInternalError,
message: "panic: runtime error: invalid memory address",
shouldBeSanitized: true,
expectedForClient: "内部服务器错误",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// 这个测试逻辑应该在 handler.go 的 handleError 中实现
// 这里仅验证逻辑概念
var clientMessage string
if tt.shouldBeSanitized {
// 服务端错误使用默认消息
clientMessage = GetMessage(tt.code, "zh-CN")
} else {
// 客户端错误保留原始消息
clientMessage = tt.message
}
if clientMessage != tt.expectedForClient {
t.Errorf("Client message = %q, expected %q", clientMessage, tt.expectedForClient)
}
})
}
}
// TestConcurrentErrorHandling 测试并发场景下的错误处理
func TestConcurrentErrorHandling(t *testing.T) {
logger, _ := zap.NewProduction()
defer logger.Sync()
handler := SafeErrorHandler(logger)
if handler == nil {
t.Fatal("SafeErrorHandler returned nil")
}
// 并发创建错误
errChan := make(chan error, 100)
for i := 0; i < 100; i++ {
go func(idx int) {
code := CodeInvalidParam
if idx%2 == 0 {
code = CodeDatabaseError
}
errChan <- New(code, fmt.Sprintf("错误 #%d", idx))
}(i)
}
// 验证所有错误都能正确创建
for i := 0; i < 100; i++ {
err := <-errChan
if err == nil {
t.Errorf("Goroutine %d returned nil error", i)
}
}
}