installerbuilder/tasks/task03-错误处理框架.md

任务03：错误处理框架

任务描述

实现Installer Builder项目的错误处理框架，提供统一的错误类型定义、错误包装和错误上下文信息。该框架将使错误处理更加一致，并提供丰富的错误信息，便于调试和问题排查。

实现步骤

1. 定义错误接口：

   • 在internal/common/errors包中创建error.go文件
   • 定义Error接口，扩展标准error接口：

     type Error interface {
         error
         // Code 返回错误代码
         Code() string
         // Component 返回发生错误的组件
         Component() string
         // Details 返回详细错误信息
         Details() map[string]interface{}
         // Unwrap 返回原始错误（符合Go 1.13+错误链）
         Unwrap() error
     }
     

2. 实现基础错误类型：

   • 创建BuildError结构体，实现Error接口：

     type BuildError struct {
         code      string
         component string
         message   string
         details   map[string]interface{}
         cause     error
     }
     

   • 实现必要的方法和构造函数

3. 定义错误代码常量：

   • 创建错误代码常量，分类管理：

     const (
         // 配置错误
         ErrConfigParse       = "CONFIG_PARSE_ERROR"
         ErrConfigValidation  = "CONFIG_VALIDATION_ERROR"
     
         // 构建错误
         ErrBuildFailed       = "BUILD_FAILED"
         ErrBuildEnvironment  = "BUILD_ENVIRONMENT_ERROR"
     
         // 平台错误
         ErrPlatformNotSupported = "PLATFORM_NOT_SUPPORTED"
         // ... 其他错误代码
     )
     

4. 实现错误创建函数：

   • 创建NewError函数，用于创建新的错误实例
   • 创建Wrap函数，用于包装现有错误并添加上下文
   • 创建WithDetails函数，用于添加详细信息

5. 实现错误处理工具函数：

   • 创建Is函数，用于错误类型检查
   • 创建As函数，用于错误类型转换
   • 创建GetErrorChain函数，用于获取完整错误链

6. 实现错误格式化：

   • 自定义错误的字符串表示
   • 支持详细和简洁两种格式
   • 包含错误代码、组件、消息和详情

7. 实现错误上下文传递：

   • 支持在错误中添加上下文信息
   • 支持从错误中提取上下文信息

单元测试要求

1. 测试错误接口实现：

   • 验证所有方法按预期工作
   • 测试错误链功能

2. 测试错误创建和包装：

   • 验证错误创建函数
   • 测试错误包装和上下文添加

3. 测试错误处理工具函数：

   • 验证Is和As函数的正确性
   • 测试GetErrorChain函数

4. 测试错误格式化：

   • 验证错误的字符串表示
   • 测试详细和简洁格式

5. 测试与标准库兼容性：

   • 验证与fmt.Errorf和%w的兼容性
   • 测试与errors.Is和errors.As的兼容性

依赖关系

• 依赖任务01（项目初始化）
• 依赖任务02（日志系统实现）
• 被大多数后续任务依赖

完成标准

1. Error接口已定义并文档完善
2. BuildError实现了所有接口方法
3. 错误代码常量已定义
4. 错误创建和包装函数已实现
5. 错误处理工具函数已实现
6. 错误格式化已实现
7. 所有单元测试通过
8. 代码符合项目的Go语言开发规范
9. 与Go标准库错误处理机制兼容