junhong_cmp_fiber/openspec/specs/error-handling/spec.md

error-handling Specification

Purpose

定义本项目“错误产生、错误传递、错误返回”的统一规范，确保：

• 对外响应结构一致（{code, data, msg, timestamp}）
• 业务语义一致（可预期业务错误返回 4xx，非预期系统错误返回 5xx）
• 不泄露内部细节（校验细节、数据库/第三方错误细节仅写日志）
• 分层职责明确（Handler 只负责输入/输出，Service 负责业务与结构化错误）

Requirements

Requirement: Simplified AppError Structure

系统 SHALL 简化 AppError 结构，删除冗余的 HTTPStatus 字段。

Scenario: AppError 字段

• WHEN 创建 AppError
• THEN 结构体只包含 3 个字段：
  • Code: 业务错误码
  • Message: 错误消息
  • Err: 底层错误（可选）

Scenario: HTTP 状态码获取

• WHEN ErrorHandler 处理 AppError
• THEN 通过 GetHTTPStatus(code) 实时获取 HTTP 状态码
• AND 不从 AppError 字段中读取

Scenario: 禁止手动设置状态码

• WHEN 创建 AppError
• THEN 不提供 WithHTTPStatus() 方法
• AND Code 和 HTTPStatus 始终保持一致

Requirement: Unified Error Response Format

系统 SHALL 使用统一的 JSON 响应格式（错误和成功均使用相同字段）。

Scenario: 响应结构

• WHEN 返回任何响应时
• THEN JSON 结构仅包含 4 个字段：
  • code: 业务错误码（0 表示成功）
  • msg: 消息（错误消息或 "success"）
  • data: 响应数据（成功时有数据，错误时为 null）
  • timestamp: ISO 8601 时间戳

Scenario: 不返回 HTTP 状态码字段

• WHEN 返回响应时
• THEN JSON 不包含 httpstatus 或 http_status 字段
• AND HTTP 状态码仅在响应头中体现

Scenario: Handler 返回错误

• WHEN Handler 函数返回 error
• THEN 全局 ErrorHandler 拦截错误
• AND 根据错误类型构造统一格式响应

Requirement: Handler Error Return Convention

所有 Handler 函数 SHALL 通过返回 error 传递错误，由全局 ErrorHandler 统一处理。

Scenario: 业务错误

• WHEN Handler 遇到业务错误
• THEN 返回 errors.New(code, message) 创建的 AppError
• AND 不直接调用 response.Error()

Scenario: 参数验证错误

• WHEN 请求参数验证失败
• THEN 返回 errors.New(CodeInvalidParam)
• AND 不将 validator 的 err.Error() 直接返回给客户端（避免泄露内部字段和规则）
• AND 详细校验错误 SHALL 记录到日志（用于排查）

Requirement: Service Error Output Convention

Service 层 SHALL 对外输出结构化错误，禁止把普通 error 直接冒泡到 Handler。

Scenario: 预期业务错误

• WHEN 业务校验失败（例如：验证码错误、资源不存在、状态不允许）
• THEN 返回 errors.New(<4xx-code>[, message])

Scenario: 非预期系统错误

• WHEN 发生数据库/缓存/队列/第三方依赖错误
• THEN 返回 errors.Wrap(<5xx-code>, err, "业务动作失败")
• AND 客户端 msg 由全局错误映射表提供通用描述

Scenario: 禁止 fmt.Errorf 作为对外错误

• WHEN Service 需要对外返回错误
• THEN 不使用 fmt.Errorf(...) 作为返回值
• AND 必须转换为 AppError（errors.New/Wrap）

Scenario: 成功响应

• WHEN Handler 执行成功
• THEN 调用 response.Success(c, data)
• AND 返回 nil

Requirement: Standardized Error Codes

系统 SHALL 使用标准化的错误码，删除向后兼容的别名。

Scenario: 参数验证错误码

• WHEN 参数验证失败
• THEN 使用 CodeInvalidParam
• AND 不使用 CodeBadRequest（别名已删除）

Scenario: 服务不可用错误码

• WHEN 服务不可用
• THEN 使用 CodeServiceUnavailable
• AND 不使用 CodeAuthServiceUnavailable（别名已删除）

错误报错规范（必须遵守）

Handler 层

• ❌ 禁止直接返回/拼接底层错误信息给客户端
  • 例如："参数验证失败: " + err.Error()、直接返回 err.Error()
  • 原因：泄露内部字段名和校验规则，造成安全风险
• ✅ 参数校验失败统一返回 errors.New(errors.CodeInvalidParam)
  • 详细校验错误写日志，对外返回通用消息
• ✅ 详细错误信息记录到日志，用于排查问题
  • 日志级别：参数错误使用 WARN 级别（客户端错误）
  • 必须包含：path、method、完整错误信息
  • 使用结构化日志（zap.String、zap.Error）

Service 层

• ❌ 禁止对外返回 fmt.Errorf(...)
  • 原因：未结构化的错误消息会泄露实现细节
• ✅ 业务错误使用 errors.New(code[, msg])
  • 适用场景：资源不存在、状态不允许、参数错误等预期错误
• ✅ 系统错误使用 errors.Wrap(code, err[, msg])
  • 适用场景：数据库错误、Redis 错误、队列错误等非预期错误

示例对比

Handler 层参数校验：

// ❌ 错误：泄露校验细节
if err := c.BodyParser(&req); err != nil {
    return errors.New(errors.CodeInvalidParam, "参数解析失败: "+err.Error())
}

// ✅ 正确：通用消息 + 结构化日志
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)  // 使用默认消息
}

Service 层错误处理：

// ❌ 错误：使用 fmt.Errorf
if err := s.store.Create(ctx, data); err != nil {
    return fmt.Errorf("创建失败: %w", err)
}

// ✅ 正确：使用 errors.Wrap
if err := s.store.Create(ctx, data); err != nil {
    return errors.Wrap(errors.CodeInternalError, err, "创建失败")
}

Service 层错误处理规范

错误分类与映射表

场景分类	错误码	HTTP 状态码	使用方式
资源不存在	CodeNotFound	404	errors.New(errors.CodeNotFound, "资源不存在")
状态不允许	CodeInvalidStatus	400	errors.New(errors.CodeInvalidStatus, "状态不允许此操作")
参数错误	CodeInvalidParam	400	errors.New(errors.CodeInvalidParam)
重复操作	CodeDuplicate	409	errors.New(errors.CodeDuplicate, "资源已存在")
余额不足	CodeInsufficientBalance	400	errors.New(errors.CodeInsufficientBalance)
额度不足	CodeInsufficientQuota	400	errors.New(errors.CodeInsufficientQuota, "分配额度不足")
超过限制	CodeExceedLimit	400	errors.New(errors.CodeExceedLimit, "超过系统限制")
资源冲突	CodeConflict	409	errors.New(errors.CodeConflict, "资源冲突")
数据库错误	CodeInternalError	500	errors.Wrap(errors.CodeInternalError, err, "操作失败")
队列错误	CodeInternalError	500	errors.Wrap(errors.CodeInternalError, err, "任务提交失败")

实际案例

案例 1：套餐服务（package/service.go）

场景：获取套餐

// ❌ 错误：使用 fmt.Errorf
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, fmt.Errorf("获取套餐失败: %w", err)  // ❌ 直接返回系统错误
    }
    return s.toResponse(ctx, pkg), nil
}

// ✅ 正确：使用 errors.Wrap
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
}

案例 2：分佣提现（commission_withdrawal/service.go）

场景：余额不足

// ✅ 业务错误使用 errors.New
if wallet.FrozenBalance < amount {
    return nil, errors.New(errors.CodeInsufficientBalance, "钱包冻结余额不足")
}

// ✅ 事务中的数据库错误使用 errors.Wrap
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, "扣除冻结余额失败")
    }
    // ...
})

案例 3：店铺管理（shop/service.go）

场景：层级限制和重复检查

// ✅ 业务校验
if level > 7 {
    return nil, errors.New(errors.CodeInvalidParam, "店铺层级超过限制")
}

// ✅ 重复检查
existing, _ := s.shopStore.GetByCode(ctx, req.ShopCode)
if existing != nil {
    return nil, errors.New(errors.CodeDuplicate, "店铺代码已存在")
}

// ✅ 数据库操作
if err := s.shopStore.Create(ctx, shop); err != nil {
    return nil, errors.Wrap(errors.CodeInternalError, err, "创建店铺失败")
}

统一原则

1. 业务错误（4xx）：使用 errors.New(Code4xx, msg)

   • 资源不存在、状态不允许、参数错误、重复操作等

2. 系统错误（5xx）：使用 errors.Wrap(Code5xx, err, msg)

   • 数据库错误、Redis 错误、队列错误、外部服务错误等

3. 错误消息保持中文：便于日志排查和问题定位

4. 禁止 fmt.Errorf 对外返回：避免泄露内部实现细节