junhong_cmp_fiber/openspec/changes/archive/2026-01-30-handler-validation-security/proposal.md

Change: Handler 层参数校验安全加固

功能 ID: handler-validation-security-001

Why

防止参数校验错误泄露内部实现细节（validator 规则、字段名、类型信息），提升 API 安全性。

当前问题：

• Handler 层在参数解析/验证失败时，直接返回 err.Error() 给客户端
• 暴露了 validator 内部信息（如 Field validation for 'Username' failed on the 'required' tag）
• 泄露了 DTO 字段名、验证规则等内部实现细节
• 客户端可以根据错误信息进行反向工程和攻击探测

安全风险示例：

// ❌ 当前实现
if err := c.BodyParser(&req); err != nil {
    return response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败: "+err.Error())
    // 可能返回：参数解析失败: Unmarshal type error: expected=uint got=string field=shop_id offset=123
}

if err := validate.Struct(&req); err != nil {
    return response.Error(c, 400, errors.CodeInvalidParam, "参数验证失败: "+err.Error())
    // 可能返回：参数验证失败: Field validation for 'Username' failed on the 'required' tag
}

影响范围（基于实际扫描结果）：

• internal/handler/admin/** - 29 个文件，发现 8 处错误泄露
• internal/handler/h5/** - 3 个文件，发现 3 处错误泄露
• 总计: 32 个文件，11 处需要修复

What Changes

修复模式

1. 参数解析错误

// ❌ 当前（泄露细节）
if err := c.BodyParser(&req); err != nil {
    return response.Error(c, 400, 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 response.Error(c, 400, errors.CodeInvalidParam, "参数解析失败")
}

2. 参数验证错误

// ❌ 当前（泄露细节）
if err := validate.Struct(&req); err != nil {
    return response.Error(c, 400, errors.CodeInvalidParam, "参数验证失败: "+err.Error())
}

// ✅ 修复后（安全）
if err := validate.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)  // 使用默认 msg："参数验证失败"
}

3. 查询参数解析错误

// ❌ 当前（泄露细节）
page, err := strconv.Atoi(c.Query("page", "1"))
if err != nil {
    return response.Error(c, 400, errors.CodeInvalidParam, "页码格式错误: "+err.Error())
}

// ✅ 修复后（安全）
page, err := strconv.Atoi(c.Query("page", "1"))
if err != nil {
    logger.GetAppLogger().Warn("页码参数格式错误",
        zap.String("path", c.Path()),
        zap.String("page", c.Query("page")),
        zap.Error(err),
    )
    return response.Error(c, 400, errors.CodeInvalidParam, "页码格式错误")
}

修改清单

Admin Handler (29 个文件)

包含错误泄露的文件（优先修复）：

• auth.go - 后台认证（3 处错误）
• role.go - 角色管理（4 处错误）
• storage.go - 对象存储（1 处错误）

其他需检查的文件：

• account.go - 账号管理
• asset_allocation_record.go - 资产分配记录
• authorization.go - 权限授权
• carrier.go - 运营商管理
• commission_withdrawal.go - 分佣提现
• commission_withdrawal_setting.go - 提现设置
• customer_account.go - 客户账号
• device.go - 设备管理
• device_import.go - 设备导入
• enterprise.go - 企业管理
• enterprise_card.go - 企业卡管理
• enterprise_device.go - 企业设备管理
• iot_card.go - IoT 卡管理
• iot_card_import.go - IoT 卡导入
• my_commission.go - 我的分佣
• order.go - 订单管理
• package.go - 套餐管理
• package_series.go - 套餐系列
• permission.go - 权限管理
• shop.go - 店铺管理
• shop_account.go - 店铺账号
• shop_commission.go - 店铺分佣
• shop_package_allocation.go - 店铺套餐分配
• shop_package_batch_allocation.go - 批量套餐分配
• shop_package_batch_pricing.go - 批量套餐定价
• shop_series_allocation.go - 店铺系列分配

H5 Handler (3 个文件)

包含错误泄露的文件（优先修复）：

• auth.go - H5 认证（3 处错误）

其他需检查的文件：

• enterprise_device.go - H5 企业设备
• order.go - H5 订单

Decisions

错误消息策略

场景	对外返回	日志记录
参数解析失败	"参数解析失败"	完整 err.Error() + 请求路径
参数验证失败	"参数验证失败"	完整 validator 错误 + 请求路径
参数格式错误	"XX 格式错误"	完整错误 + 参数值
业务校验失败	业务错误消息	不记录（Service 层已记录）

日志级别

• 参数错误：WARN 级别（客户端错误）
• 包含必要上下文：path、method、query/body（脱敏后）

执行策略

1. 按目录分批：admin → h5 → personal
2. 搜索模式：grep 查找所有包含 err.Error() 的 handler 文件
3. 验证方式：为关键 Handler 补充参数校验测试

Impact

Security Improvements

• ✅ 隐藏 DTO 字段名和验证规则
• ✅ 防止反向工程和探测攻击
• ✅ 统一错误返回格式
• ✅ 保留完整日志用于问题排查

Breaking Changes

• 客户端收到的错误消息更通用（不再包含具体字段名）
• 需要前端调整错误提示逻辑（如根据 code 显示友好提示）

Testing Requirements

为关键 Handler 补充参数校验测试：

func TestHandler_InvalidParam(t *testing.T) {
    env := testutils.NewIntegrationTestEnv(t)
    
    t.Run("参数缺失 - 不泄露字段名", func(t *testing.T) {
        resp, err := env.AsSuperAdmin().Request("POST", "/api/admin/users", `{}`)
        require.NoError(t, err)
        assert.Equal(t, 400, resp.StatusCode)
        
        var result map[string]interface{}
        json.Unmarshal(resp.Body, &result)
        
        // 验证不包含 validator 内部细节
        msg := result["msg"].(string)
        assert.NotContains(t, msg, "Field validation")
        assert.NotContains(t, msg, "required")
        assert.NotContains(t, msg, "Username")
        assert.Equal(t, "参数验证失败", msg)
    })
    
    t.Run("参数类型错误 - 不泄露类型信息", func(t *testing.T) {
        resp, err := env.AsSuperAdmin().Request("POST", "/api/admin/users", `{"shop_id":"invalid"}`)
        require.NoError(t, err)
        assert.Equal(t, 400, resp.StatusCode)
        
        var result map[string]interface{}
        json.Unmarshal(resp.Body, &result)
        
        // 验证不包含类型转换细节
        msg := result["msg"].(string)
        assert.NotContains(t, msg, "Unmarshal")
        assert.NotContains(t, msg, "expected=")
        assert.NotContains(t, msg, "got=")
    })
}

Affected Specs

• UPDATE: openspec/specs/error-handling/spec.md
  • 补充 Handler 层参数校验规范
  • 添加安全加固说明

Verification Checklist

编译检查

go build -o /tmp/test_api ./cmd/api

搜索残留泄露点

# 查找所有可能泄露 err.Error() 的地方
grep -r "err.Error()" internal/handler/ | grep -v "_test.go"

# 查找可能拼接错误的地方
grep -r '"+err' internal/handler/ | grep -v "_test.go"
grep -r '"+.*Error()' internal/handler/ | grep -v "_test.go"

集成测试

source .env.local && go test -v ./tests/integration/...

手动验证

发送错误参数到关键接口，确认返回：

• ✅ 参数缺失：返回 "参数验证失败"（不包含字段名）
• ✅ 参数类型错误：返回 "参数解析失败"（不包含类型信息）
• ✅ 参数格式错误：返回通用格式错误（不包含具体值）
• ✅ 日志中包含完整错误信息（用于排查）

日志检查

检查 logs/app.log 确认：

• 参数错误记录为 WARN 级别
• 包含完整的 validator 错误（仅日志）
• 包含请求路径和方法

Estimated Effort

任务	预估时间
Admin Handler（29 个文件，8 处错误）	2h
H5 Handler（3 个文件，3 处错误）	0.5h
测试验证	1h
文档更新	0.5h

总计：约 4 小时