refactor: 统一错误消息数据源,优化错误码与映射表管理
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 4m36s

主要改动:
- 改造 errors.New() 和 Wrap() 函数签名为可变参数,优先使用 errorMessages 映射表
- 添加 allErrorCodes 注册表和 init() 启动时校验,确保错误码与映射表一致
- 添加 TestAllCodesHaveMessages 和 TestNoOrphanMessages 测试防止映射表腐化
- 清理 109 处与映射表一致的冗余硬编码(service 层)
- 保留业务特定消息覆盖能力

新增 API 用法:
- errors.New(errors.CodeUnauthorized) // 使用映射表默认消息
- errors.New(errors.CodeNotFound, "提现申请不存在") // 覆盖为自定义消息
This commit is contained in:
2026-01-22 18:27:42 +08:00
parent b68e7ec013
commit 6821e5abcf
28 changed files with 665 additions and 81 deletions

View File

@@ -0,0 +1,54 @@
## Why
当前项目中错误消息存在**双数据源问题**
1. `pkg/errors/codes.go` 中定义了 `errorMessages` 映射表
2. 业务代码中 `errors.New(code, "硬编码消息")` 全部传入硬编码消息
结果是:
- 映射表的"自动填充"功能(当 message 为空时使用映射表)**从未被使用**(死代码)
- 新增错误码时可能忘记更新映射表,导致映射表逐渐腐化
- 长期开发后新人不知道该用哪种方式,造成使用混乱
- 同一错误码在不同地方可能返回不同消息,影响一致性
## What Changes
- **改造 `errors.New()` 函数签名**:优先使用映射表消息,允许可选覆盖
- **添加 `init()` 启动时校验**:确保所有错误码常量都有对应的映射表条目
- **添加 CI 测试**:防止映射表腐化,确保错误码与消息映射完整
- **清理业务代码中的冗余硬编码**:将与映射表一致的消息改为使用默认值
- **保留业务特定消息覆盖能力**:如 "提现申请不存在" 比 "资源未找到" 更清晰的场景
## Capabilities
### New Capabilities
- `error-code-validation`: 错误码与消息映射的编译时/运行时校验机制,确保所有 Code* 常量都有对应的 errorMessages 条目
### Modified Capabilities
无。此变更不改变现有 spec 的行为要求,仅加固内部实现。
## Impact
### 代码影响
| 文件/目录 | 影响 |
|-----------|------|
| `pkg/errors/errors.go` | 改造 `New()` 函数签名,添加 `init()` 校验 |
| `pkg/errors/codes.go` | 可能需要补充缺失的映射条目 |
| `pkg/errors/codes_test.go` | 添加完整性校验测试 |
| `internal/service/**/*.go` | 清理冗余硬编码(约 150+ 处) |
| `internal/handler/**/*.go` | 清理冗余硬编码(约 80+ 处) |
| `pkg/middleware/*.go` | 清理冗余硬编码(约 15 处) |
### API 影响
无。错误响应格式不变,仅内部消息来源统一。
### 风险评估
| 风险 | 等级 | 缓解措施 |
|------|------|----------|
| 消息文案变化影响前端展示 | 低 | 保留业务特定消息覆盖能力 |
| 遗漏错误码导致启动失败 | 中 | init() 校验会在启动时立即暴露问题 |
| 大规模代码变更引入 bug | 中 | 分阶段实施:先加校验,再清理代码 |