# 使用指南：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 | 请求体过大 | 文件上传超限 |

#### 财务相关错误 (1050-1069)

| 错误码 | 名称 | HTTP 状态 | 消息 | 使用场景 |
|--------|------|-----------|------|----------|
| 1050 | CodeInvalidStatus | 400 | 状态不允许此操作 | 资源状态不允许执行当前操作 |
| 1051 | CodeInsufficientBalance | 400 | 余额不足 | 钱包余额不足以完成操作 |
| 1052 | CodeWithdrawalNotFound | 404 | 提现申请不存在 | 提现记录未找到 |
| 1053 | CodeWalletNotFound | 404 | 钱包不存在 | 钱包记录未找到 |
| 1054 | CodeInsufficientQuota | 400 | 额度不足 | 套餐分配额度不足 |
| 1055 | CodeExceedLimit | 400 | 超过限制 | 超过系统限制（如设备绑定卡数） |

### 服务端错误 (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
}
```

---

## Handler 层参数校验安全实践

### ❌ 错误示例：泄露内部细节

```go
func (h *ShopHandler) Create(c *fiber.Ctx) error {
    var req dto.CreateShopRequest
    
    // ❌ 错误：直接暴露解析错误
    if err := c.BodyParser(&req); err != nil {
        return errors.New(errors.CodeInvalidParam, "参数解析失败: "+err.Error())
        // 可能泄露：json: cannot unmarshal number into Go struct field CreateShopRequest.ShopCode of type string
    }
    
    // ❌ 错误：直接暴露 validator 错误
    if err := h.validator.Struct(&req); err != nil {
        return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
        // 可能泄露：Key: 'CreateShopRequest.ShopName' Error:Field validation for 'ShopName' failed on the 'required' tag
    }
    
    // ...
}
```

**安全风险**：
- 泄露内部字段名（ShopCode、ShopName）
- 泄露数据类型（string、number）
- 泄露验证规则（required、min、max 等）
- 攻击者可根据错误消息推断 API 内部结构

### ✅ 正确示例：安全的参数校验

```go
func (h *ShopHandler) Create(c *fiber.Ctx) error {
    var req dto.CreateShopRequest
    
    // ✅ 正确：通用错误消息 + 结构化日志（WARN 级别）
    if err := c.BodyParser(&req); err != nil {
        logger.GetAppLogger().Warn("参数解析失败", 
            zap.String("path", c.Path()),
            zap.String("method", c.Method()),
            zap.Error(err),
        )
        return errors.New(errors.CodeInvalidParam, "请求参数格式错误")
    }
    
    // ✅ 正确：使用默认消息 + 结构化日志（WARN 级别）
    if err := h.validator.Struct(&req); err != nil {
        logger.GetAppLogger().Warn("参数验证失败",
            zap.String("path", c.Path()),
            zap.String("method", c.Method()),
            zap.Error(err),
        )
        return errors.New(errors.CodeInvalidParam)  // 使用默认消息
    }
    
    // 业务逻辑...
    shop, err := h.service.Create(c.UserContext(), &req)
    if err != nil {
        return err
    }
    
    return response.Success(c, shop)
}
```

**安全优势**：
- 对外：统一返回通用消息（"参数验证失败"）
- 日志：记录详细错误信息用于排查
- 包含 request_id：便于日志关联和问题追踪

### 单元测试示例

```go
func TestShopHandler_Create_ParamValidation(t *testing.T) {
    // 准备测试环境
    app := fiber.New()
    handler := NewShopHandler(mockService, mockValidator, logger)
    app.Post("/shops", handler.Create)
    
    tests := []struct {
        name           string
        requestBody    string
        expectedCode   int
        expectedMsg    string
    }{
        {
            name:        "参数解析失败",
            requestBody: `{"shop_code": 123}`, // 类型错误
            expectedCode: errors.CodeInvalidParam,
            expectedMsg:  "请求参数格式错误",
        },
        {
            name:        "必填字段缺失",
            requestBody: `{"shop_code": ""}`, // ShopName 缺失
            expectedCode: errors.CodeInvalidParam,
            expectedMsg:  "参数验证失败",
        },
        {
            name:        "正常请求",
            requestBody: `{"shop_code": "SH001", "shop_name": "测试店铺"}`,
            expectedCode: errors.CodeSuccess,
            expectedMsg:  "操作成功",
        },
    }
    
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            req := httptest.NewRequest("POST", "/shops", strings.NewReader(tt.requestBody))
            req.Header.Set("Content-Type", "application/json")
            
            resp, _ := app.Test(req)
            defer resp.Body.Close()
            
            var result map[string]interface{}
            json.NewDecoder(resp.Body).Decode(&result)
            
            assert.Equal(t, tt.expectedCode, int(result["code"].(float64)))
            assert.Equal(t, tt.expectedMsg, result["msg"])
            
            // ✅ 验证：错误消息不泄露内部细节
            assert.NotContains(t, result["msg"], "ShopCode")
            assert.NotContains(t, result["msg"], "ShopName")
            assert.NotContains(t, result["msg"], "required")
        })
    }
}
```

---

## 客户端错误处理

### 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
// 参数解析失败
if err := c.BodyParser(&req); err != nil {
    logger.GetAppLogger().Warn("参数解析失败",
        zap.String("path", c.Path()),
        zap.String("method", c.Method()),
        zap.Error(err),
    )
    return errors.New(errors.CodeInvalidParam, "请求参数格式错误")
}

// 参数验证失败
if err := h.validator.Struct(&req); err != nil {
    logger.GetAppLogger().Warn("参数验证失败",
        zap.String("path", c.Path()),
        zap.String("method", c.Method()),
        zap.Error(err),
    )
    return errors.New(errors.CodeInvalidParam)  // 使用默认消息
}
```

❌ **错误示例 - 泄露内部细节**：
```go
// ❌ 危险：泄露 validator 规则和字段名
if err := h.validator.Struct(&req); err != nil {
    return errors.New(errors.CodeInvalidParam, "参数验证失败: "+err.Error())
}
// 可能返回："Field validation for 'Username' failed on the 'required' tag"

// ❌ 危险：泄露类型信息
if err := c.BodyParser(&req); err != nil {
    return errors.New(errors.CodeInvalidParam, "参数解析失败: "+err.Error())
}
// 可能返回："Unmarshal type error: expected=uint got=string field=shop_id"
```

**安全原则**：
- 对外统一返回通用消息（"参数验证失败"）
- 详细错误信息仅记录到日志
- 使用 WARN 级别（客户端错误）
- 必须包含请求上下文（path、method）

### 3. 错误消息编写

✅ **正确示例**：
```go
// 清晰、具体的错误消息（不泄露内部细节）
errors.New(errors.CodeInvalidParam, "用户名长度必须在 3-20 个字符之间")
errors.New(errors.CodeNotFound, "用户不存在")
errors.New(errors.CodeConflict, "邮箱已被注册")
```

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

// 不要暴露敏感信息和内部细节
errors.New(errors.CodeDatabaseError, "SQL error: SELECT * FROM users WHERE password = '...'")
errors.New(errors.CodeInvalidParam, "Field 'Username' validation failed") // 泄露字段名
```

### 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) - 完整错误码列表

---

## Service 层错误处理实战案例

### 案例 1：套餐服务 - 资源查询

**场景**：获取套餐详情，需处理不存在和数据库错误

```go
// internal/service/package/service.go
func (s *Service) Get(ctx context.Context, id uint) (*dto.PackageResponse, error) {
    pkg, err := s.packageStore.GetByID(ctx, id)
    if err != nil {
        // ✅ 业务错误：资源不存在
        if err == gorm.ErrRecordNotFound {
            return nil, errors.New(errors.CodeNotFound, "套餐不存在")
        }
        // ✅ 系统错误：数据库查询失败
        return nil, errors.Wrap(errors.CodeInternalError, err, "获取套餐失败")
    }
    
    return s.toResponse(ctx, pkg), nil
}
```

**错误返回示例**：
- 套餐不存在（404）：
  ```json
  {"code": 1006, "msg": "套餐不存在", "data": null}
  ```
- 数据库错误（500）：
  ```json
  {"code": 2001, "msg": "内部服务器错误", "data": null}
  ```
  日志中记录详细错误：`获取套餐失败: connection refused`

### 案例 2：分佣提现 - 复杂业务校验

**场景**：提现审核，需验证余额、状态等

```go
// internal/service/commission_withdrawal/service.go
func (s *Service) Approve(ctx context.Context, id uint, req *dto.ApproveWithdrawalReq) (*dto.WithdrawalApprovalResp, error) {
    // ✅ 业务错误：资源不存在
    withdrawal, err := s.commissionWithdrawalReqStore.GetByID(ctx, id)
    if err != nil {
        return nil, errors.New(errors.CodeNotFound, "提现申请不存在")
    }
    
    // ✅ 业务错误：状态不允许
    if withdrawal.Status != constants.WithdrawalStatusPending {
        return nil, errors.New(errors.CodeInvalidStatus, "申请状态不允许此操作")
    }
    
    // ✅ 业务错误：余额不足
    wallet, err := s.walletStore.GetShopCommissionWallet(ctx, withdrawal.ShopID)
    if err != nil {
        return nil, errors.New(errors.CodeNotFound, "店铺佣金钱包不存在")
    }
    if wallet.FrozenBalance < amount {
        return nil, errors.New(errors.CodeInsufficientBalance, "钱包冻结余额不足")
    }
    
    // ✅ 系统错误：事务执行失败
    err = s.db.Transaction(func(tx *gorm.DB) error {
        if err := s.walletStore.DeductFrozenBalanceWithTx(ctx, tx, wallet.ID, amount); err != nil {
            return errors.Wrap(errors.CodeInternalError, err, "扣除冻结余额失败")
        }
        // ...其他事务操作
        return nil
    })
    
    if err != nil {
        return nil, err
    }
    
    return &dto.WithdrawalApprovalResp{...}, nil
}
```

### 案例 3：店铺管理 - 重复性检查

**场景**：创建店铺，需检查代码重复和层级限制

```go
// internal/service/shop/service.go
func (s *Service) Create(ctx context.Context, req *dto.CreateShopRequest) (*dto.ShopResponse, error) {
    // ✅ 业务错误：重复检查
    existing, _ := s.shopStore.GetByCode(ctx, req.ShopCode)
    if existing != nil {
        return nil, errors.New(errors.CodeDuplicate, "店铺代码已存在")
    }
    
    // ✅ 业务错误：层级限制
    level := 1
    if req.ParentID != nil {
        parent, err := s.shopStore.GetByID(ctx, *req.ParentID)
        if err != nil {
            return nil, errors.New(errors.CodeNotFound, "上级店铺不存在")
        }
        level = parent.Level + 1
        if level > 7 {
            return nil, errors.New(errors.CodeInvalidParam, "店铺层级超过限制")
        }
    }
    
    // ✅ 系统错误：数据库操作
    shop := &model.Shop{...}
    if err := s.shopStore.Create(ctx, shop); err != nil {
        return nil, errors.Wrap(errors.CodeInternalError, err, "创建店铺失败")
    }
    
    return s.toResponse(shop), nil
}
```

### 错误处理原则总结

| 场景类型 | 使用方式 | HTTP 状态码 | 示例 |
|---------|---------|-----------|------|
| 资源不存在 | `errors.New(CodeNotFound)` | 404 | 套餐、店铺、用户不存在 |
| 状态不允许 | `errors.New(CodeInvalidStatus)` | 400 | 订单已取消、提现已审核 |
| 参数错误 | `errors.New(CodeInvalidParam)` | 400 | 层级超限、金额无效 |
| 重复操作 | `errors.New(CodeDuplicate)` | 409 | 代码重复、用户名已存在 |
| 余额不足 | `errors.New(CodeInsufficientBalance)` | 400 | 钱包余额不足 |
| 数据库错误 | `errors.Wrap(CodeInternalError, err)` | 500 | 查询失败、创建失败 |
| 队列错误 | `errors.Wrap(CodeInternalError, err)` | 500 | 任务提交失败 |

**核心原则**：
1. 业务错误（4xx）：使用 `errors.New(Code4xx, msg)`
2. 系统错误（5xx）：使用 `errors.Wrap(Code5xx, err, msg)`
3. 错误消息保持中文，便于日志排查
4. 禁止 `fmt.Errorf` 直接对外返回，避免泄露内部细节

---

**版本历史**:
- v1.1.0 (2026-01-29): 补充 Service 层错误处理实战案例
- v1.0.0 (2025-11-15): 初始版本
