# 使用指南：Fiber 错误处理集成

**功能编号**: 003-error-handling  
**版本**: 1.0.0  
**更新日期**: 2025-11-15

## 目录

1. [快速开始](#快速开始)
2. [错误码参考](#错误码参考)
3. [Handler 中使用错误](#handler-中使用错误)
4. [客户端错误处理](#客户端错误处理)
5. [错误日志查询](#错误日志查询)
6. [最佳实践](#最佳实践)
7. [常见问题](#常见问题)

---

## 快速开始

### 1. 在 Handler 中返回错误

```go
package handler

import (
    "github.com/break/junhong_cmp_fiber/pkg/errors"
    "github.com/break/junhong_cmp_fiber/pkg/response"
    "github.com/gofiber/fiber/v2"
)

func (h *UserHandler) GetUser(c *fiber.Ctx) error {
    userID := c.Params("id")
    
    // 参数验证失败
    if userID == "" {
        return errors.New(errors.CodeInvalidParam, "用户 ID 不能为空")
    }
    
    // 调用服务层
    user, err := h.service.GetByID(c.Context(), userID)
    if err != nil {
        // 包装底层错误
        return errors.Wrap(errors.CodeDatabaseError, "查询用户失败", err)
    }
    
    // 资源未找到
    if user == nil {
        return errors.New(errors.CodeNotFound, "用户不存在")
    }
    
    return response.Success(c, user)
}
```

### 2. 错误响应格式

所有错误自动转换为统一格式：

```json
{
  "code": 1001,
  "data": null,
  "msg": "参数验证失败",
  "timestamp": "2025-11-15T10:00:00+08:00"
}
```

HTTP Header 中包含 Request ID：
```
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
```

---

## 错误码参考

### 成功

| 错误码 | 名称 | HTTP 状态 | 消息 |
|--------|------|-----------|------|
| 0 | CodeSuccess | 200 | 操作成功 |

### 客户端错误 (1000-1999)

| 错误码 | 名称 | HTTP 状态 | 消息 | 使用场景 |
|--------|------|-----------|------|----------|
| 1001 | CodeInvalidParam | 400 | 参数验证失败 | 请求参数格式错误、必填字段缺失 |
| 1002 | CodeMissingToken | 401 | 缺少认证令牌 | 未提供 Token |
| 1003 | CodeInvalidToken | 401 | 无效的认证令牌 | Token 格式错误 |
| 1004 | CodeInvalidCredentials | 401 | 认证凭证无效 | Token 过期、验证失败 |
| 1005 | CodeForbidden | 403 | 禁止访问 | 无权限访问资源 |
| 1006 | CodeNotFound | 404 | 资源未找到 | 用户、订单等资源不存在 |
| 1007 | CodeConflict | 409 | 资源冲突 | 唯一性约束冲突 |
| 1008 | CodeTooManyRequests | 429 | 请求过多 | 触发限流 |
| 1009 | CodeRequestEntityTooLarge | 413 | 请求体过大 | 文件上传超限 |

### 服务端错误 (2000-2999)

| 错误码 | 名称 | HTTP 状态 | 消息 | 使用场景 |
|--------|------|-----------|------|----------|
| 2001 | CodeInternalError | 500 | 内部服务器错误 | 未分类的内部错误 |
| 2002 | CodeDatabaseError | 500 | 数据库错误 | 数据库连接失败、查询错误 |
| 2003 | CodeCacheError | 500 | 缓存服务错误 | Redis 连接失败 |
| 2004 | CodeServiceUnavailable | 503 | 服务暂时不可用 | 外部服务不可用 |
| 2005 | CodeTimeout | 504 | 请求超时 | 上游服务超时 |
| 2006 | CodeQueueError | 500 | 任务队列错误 | Asynq 任务投递失败 |

---

## Handler 中使用错误

### 1. 参数验证错误

```go
func (h *UserHandler) CreateUser(c *fiber.Ctx) error {
    var req CreateUserRequest
    if err := c.BodyParser(&req); err != nil {
        return errors.New(errors.CodeInvalidParam, "请求参数格式错误")
    }
    
    // 业务验证
    if len(req.Username) < 3 || len(req.Username) > 20 {
        return errors.New(errors.CodeInvalidParam, "用户名长度必须在 3-20 个字符之间")
    }
    
    if !isValidEmail(req.Email) {
        return errors.New(errors.CodeInvalidParam, "邮箱格式不正确")
    }
    
    // 继续处理...
}
```

### 2. 认证/授权错误

```go
func (h *OrderHandler) GetOrder(c *fiber.Ctx) error {
    // 检查用户是否登录
    userID := c.Locals("user_id")
    if userID == nil {
        return errors.New(errors.CodeMissingToken, "请先登录")
    }
    
    order, err := h.service.GetByID(c.Params("id"))
    if err != nil {
        return errors.Wrap(errors.CodeDatabaseError, "查询订单失败", err)
    }
    
    // 检查权限
    if order.UserID != userID.(string) {
        return errors.New(errors.CodeForbidden, "无权访问此订单")
    }
    
    return response.Success(c, order)
}
```

### 3. 资源未找到

```go
func (h *UserHandler) GetUser(c *fiber.Ctx) error {
    user, err := h.service.GetByID(c.Params("id"))
    if err != nil {
        return errors.Wrap(errors.CodeDatabaseError, "查询用户失败", err)
    }
    
    if user == nil {
        return errors.New(errors.CodeNotFound, fmt.Sprintf("用户 ID %s 不存在", c.Params("id")))
    }
    
    return response.Success(c, user)
}
```

### 4. 资源冲突

```go
func (h *UserHandler) CreateUser(c *fiber.Ctx) error {
    var req CreateUserRequest
    if err := c.BodyParser(&req); err != nil {
        return errors.New(errors.CodeInvalidParam, "请求参数错误")
    }
    
    // 检查用户名是否已存在
    exists, err := h.service.ExistsByUsername(req.Username)
    if err != nil {
        return errors.Wrap(errors.CodeDatabaseError, "检查用户名失败", err)
    }
    
    if exists {
        return errors.New(errors.CodeConflict, "用户名已被使用")
    }
    
    // 创建用户...
}
```

### 5. 外部服务错误

```go
func (h *NotificationHandler) SendEmail(c *fiber.Ctx) error {
    var req SendEmailRequest
    if err := c.BodyParser(&req); err != nil {
        return errors.New(errors.CodeInvalidParam, "请求参数错误")
    }
    
    // 调用外部邮件服务
    err := h.emailService.Send(req.To, req.Subject, req.Body)
    if err != nil {
        // 包装外部服务错误
        return errors.Wrap(errors.CodeServiceUnavailable, "邮件发送失败", err)
    }
    
    return response.Success(c, nil)
}
```

### 6. 自定义 HTTP 状态码（高级用法）

```go
func (h *Handler) SpecialCase(c *fiber.Ctx) error {
    // 默认 CodeInvalidParam 映射为 400
    // 但某些场景需要返回 422
    appErr := errors.New(errors.CodeInvalidParam, "数据验证失败")
    appErr = appErr.WithHTTPStatus(422)
    return appErr
}
```

---

## 客户端错误处理

### JavaScript/TypeScript

```typescript
async function fetchUser(userId: string) {
    try {
        const response = await fetch(`/api/v1/users/${userId}`);
        const data = await response.json();
        
        // 检查业务错误码
        if (data.code !== 0) {
            const requestId = response.headers.get('X-Request-ID');
            
            switch (data.code) {
                // 认证错误 - 跳转登录
                case 1002:
                case 1003:
                case 1004:
                    redirectToLogin();
                    break;
                
                // 权限错误 - 显示无权限提示
                case 1005:
                    showError('您没有权限访问此资源');
                    break;
                
                // 资源未找到 - 显示 404 页面
                case 1006:
                    showNotFoundPage();
                    break;
                
                // 服务端错误 - 显示错误并提供 Request ID
                case 2001:
                case 2002:
                case 2003:
                case 2004:
                    showError(`服务器错误，请联系管理员。Request ID: ${requestId}`);
                    break;
                
                // 限流错误 - 提示稍后重试
                case 1008:
                    showError('请求过于频繁，请稍后再试');
                    break;
                
                // 其他错误 - 显示错误消息
                default:
                    showError(data.msg);
            }
            
            return null;
        }
        
        return data.data;
    } catch (err) {
        // 网络错误
        showError('网络连接失败，请检查您的网络');
        return null;
    }
}
```

### Axios 拦截器

```typescript
import axios from 'axios';

const api = axios.create({
    baseURL: '/api/v1',
});

// 响应拦截器
api.interceptors.response.use(
    (response) => {
        const { code, data, msg } = response.data;
        
        if (code !== 0) {
            const requestId = response.headers['x-request-id'];
            
            // 根据错误码处理
            if ([1002, 1003, 1004].includes(code)) {
                // 认证失败，跳转登录
                redirectToLogin();
                return Promise.reject(new Error(msg));
            }
            
            if (code === 1005) {
                // 权限不足
                showError('您没有权限执行此操作');
                return Promise.reject(new Error(msg));
            }
            
            if (code >= 2000) {
                // 服务端错误
                console.error(`Server error: ${msg}, Request ID: ${requestId}`);
                showError(`服务器错误，Request ID: ${requestId}`);
                return Promise.reject(new Error(msg));
            }
            
            // 其他业务错误
            showError(msg);
            return Promise.reject(new Error(msg));
        }
        
        return data;
    },
    (error) => {
        // 网络错误
        showError('网络连接失败');
        return Promise.reject(error);
    }
);
```

---

## 错误日志查询

### 1. 通过 Request ID 查询

```bash
# 查询特定请求的所有日志
grep "550e8400-e29b-41d4-a716-446655440000" logs/app.log

# 使用 jq 格式化 JSON 日志
grep "550e8400-e29b-41d4-a716-446655440000" logs/app.log | jq .
```

### 2. 查询特定错误码

```bash
# 查询所有参数验证失败的错误
grep '"error_code":1001' logs/app.log | jq .

# 查询所有数据库错误
grep '"error_code":2002' logs/app.log | jq .
```

### 3. 查询 Panic 堆栈

```bash
# 查询所有 panic 日志
grep "panic recovered" logs/app.log

# 查询包含堆栈的完整 panic 日志
grep -A 20 "panic recovered" logs/app.log
```

### 4. 按时间范围查询

```bash
# 查询最近 1 小时的错误日志
grep '"level":"error"' logs/app.log | grep "$(date -u -d '1 hour ago' '+%Y-%m-%dT%H')"
```

---

## 最佳实践

### 1. 错误码选择

✅ **正确示例**：
```go
// 参数验证失败
return errors.New(errors.CodeInvalidParam, "用户名不能为空")

// 资源未找到
return errors.New(errors.CodeNotFound, "订单不存在")

// 数据库错误
return errors.Wrap(errors.CodeDatabaseError, "查询失败", err)
```

❌ **错误示例**：
```go
// 不要使用错误的错误码
return errors.New(errors.CodeDatabaseError, "用户名不能为空") // 应该用 CodeInvalidParam

// 不要返回空消息
return errors.New(errors.CodeNotFound, "") // 应该提供具体消息
```

### 2. 错误消息编写

✅ **正确示例**：
```go
// 清晰、具体的错误消息
errors.New(errors.CodeInvalidParam, "用户名长度必须在 3-20 个字符之间")
errors.New(errors.CodeNotFound, "用户 ID 123 不存在")
errors.New(errors.CodeConflict, "邮箱 test@example.com 已被注册")
```

❌ **错误示例**：
```go
// 不要使用模糊的消息
errors.New(errors.CodeInvalidParam, "错误")
errors.New(errors.CodeNotFound, "not found")

// 不要暴露敏感信息
errors.New(errors.CodeDatabaseError, "SQL error: SELECT * FROM users WHERE password = '...'")
```

### 3. 错误包装

✅ **正确示例**：
```go
// 包装底层错误，保留错误链
user, err := h.repo.GetByID(id)
if err != nil {
    return errors.Wrap(errors.CodeDatabaseError, "查询用户失败", err)
}
```

❌ **错误示例**：
```go
// 丢失原始错误信息
user, err := h.repo.GetByID(id)
if err != nil {
    return errors.New(errors.CodeDatabaseError, "查询用户失败") // 应该用 Wrap
}
```

### 4. 不要过度处理错误

✅ **正确示例**：
```go
func (h *Handler) GetUser(c *fiber.Ctx) error {
    user, err := h.service.GetByID(c.Params("id"))
    if err != nil {
        // 直接返回错误，让 ErrorHandler 统一处理
        return err
    }
    return response.Success(c, user)
}
```

❌ **错误示例**：
```go
func (h *Handler) GetUser(c *fiber.Ctx) error {
    user, err := h.service.GetByID(c.Params("id"))
    if err != nil {
        // 不要在 Handler 中手动构造错误响应
        return c.Status(500).JSON(fiber.Map{"error": err.Error()})
    }
    return response.Success(c, user)
}
```

### 5. Panic 使用建议

✅ **正确做法**：
```go
// 让代码正常返回错误，不要主动 panic
func (s *Service) Process() error {
    if invalidState {
        return errors.New(errors.CodeInternalError, "无效状态")
    }
    return nil
}
```

❌ **避免使用**：
```go
// 避免在业务代码中主动 panic
func (s *Service) Process() {
    if invalidState {
        panic("invalid state") // 不推荐
    }
}
```

**注意**：即使代码中有 panic，Recover 中间件也会自动捕获并转换为错误响应，确保服务不崩溃。

---

## 常见问题

### Q1: 如何自定义错误消息？

A: 使用 `errors.New()` 的第二个参数：

```go
return errors.New(errors.CodeInvalidParam, "自定义错误消息")
```

### Q2: 如何查看底层错误详情？

A: 底层错误会记录在日志中，通过 Request ID 查询：

```bash
grep "<request-id>" logs/app.log | jq .
```

### Q3: 客户端如何获取 Request ID？

A: 从响应 Header 中获取：

```javascript
const requestId = response.headers.get('X-Request-ID');
```

### Q4: 错误码冲突怎么办？

A: 参考 `pkg/errors/codes.go` 中的定义，避免使用已定义的错误码。如需新增错误码，请在对应范围内添加。

### Q5: 如何测试错误处理？

A: 参考 `tests/integration/error_handler_test.go` 中的示例：

```go
resp, _ := app.Test(httptest.NewRequest("GET", "/api/v1/users/invalid", nil))
assert.Equal(t, 400, resp.StatusCode)
```

### Q6: 如何关闭堆栈跟踪？

A: 堆栈跟踪仅在 panic 时记录，无法关闭。如需调整，修改 `internal/middleware/recover.go`。

---

## 更多信息

- [功能总结](./功能总结.md) - 功能概述和技术要点
- [架构说明](./架构说明.md) - 错误处理架构设计
- [错误码定义](../../pkg/errors/codes.go) - 完整错误码列表

---

**版本历史**:
- v1.0.0 (2025-11-15): 初始版本