234 lines
7.9 KiB
Markdown
234 lines
7.9 KiB
Markdown
# Requirements - 错误处理和异常机制完善
|
||
|
||
## 需求信息
|
||
|
||
- **需求名称**: 错误处理和异常机制完善
|
||
- **需求类型**: 功能需求
|
||
- **需求编号**: REQ-011-6
|
||
- **父需求**: [REQ-011](./REQ-011.md) - Salesforce文件上传下载功能（支持Attachment、ContentDocument、Document）
|
||
- **创建日期**: 2026-01-19
|
||
- **需求版本**: v1.0.0
|
||
- **需求提出人**: 系统管理员
|
||
- **需求状态**: 待审核
|
||
|
||
## 输入引用
|
||
|
||
引用相关的 docs 文档链接：
|
||
|
||
- [REQ-011.md](./REQ-011.md) - 父需求文档
|
||
- [REQ-011-1.md](./REQ-011-1.md) - 基础设施和枚举定义
|
||
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
||
|
||
## Context Maps
|
||
|
||
强制列出本次需求依赖的 Canvas 文件：
|
||
|
||
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
||
- **相关节点**: [通用异常](node_common_exception) - 定义Salesforce相关的异常类
|
||
|
||
## 需求目标
|
||
|
||
在 datai-salesforce-integration 模块实现完善的错误处理机制，包括自定义异常类、全局异常处理器、错误日志记录和错误信息封装，确保文件上传下载功能的健壮性和用户体验。
|
||
|
||
## 需求描述
|
||
|
||
### 概述
|
||
|
||
本需求旨在实现完善的错误处理机制，包括自定义异常类、全局异常处理器、错误日志记录和错误信息封装。通过统一的错误处理机制，提高系统的健壮性，提供清晰的错误信息，提升用户体验。
|
||
|
||
### 详细需求
|
||
|
||
#### 1. 自定义异常类定义
|
||
|
||
- **需求描述**: 定义文件上传下载相关的自定义异常类
|
||
- **优先级**: 高
|
||
- **验收标准**:
|
||
- 定义 FileUploadException 异常类
|
||
- 定义 FileDownloadException 异常类
|
||
- 定义 FileSizeExceededException 异常类
|
||
- 定义 FileTypeNotSupportedException 异常类
|
||
- 定义 FileObjectNotFoundException 异常类
|
||
- 定义 OrgConfigNotFoundException 异常类
|
||
- 定义 FileValidationException 异常类
|
||
- 所有异常类继承自 RuntimeException
|
||
- 提供详细的错误信息和错误代码
|
||
- 提供异常链支持（cause）
|
||
- 提供错误代码枚举
|
||
- **依赖关系**:
|
||
- 依赖于 datai-salesforce-common 模块的异常类
|
||
- 依赖于 REQ-011-1 的基础设施
|
||
- **实现建议**:
|
||
- 参考现有的异常类定义
|
||
- 使用统一的异常处理机制
|
||
- 提供错误代码枚举
|
||
- 提供详细的错误信息
|
||
|
||
#### 2. 错误代码枚举
|
||
|
||
- **需求描述**: 定义错误代码枚举，统一管理所有错误代码
|
||
- **优先级**: 高
|
||
- **验收标准**:
|
||
- 定义 FileErrorCode 枚举
|
||
- 包含所有文件上传下载相关的错误代码
|
||
- 包含错误代码的描述信息
|
||
- 包含错误代码的 HTTP 状态码
|
||
- 提供错误代码到描述的转换方法
|
||
- 提供错误代码到 HTTP 状态码的转换方法
|
||
- **依赖关系**: 无
|
||
- **实现建议**:
|
||
- 使用 Java 枚举定义错误代码
|
||
- 添加错误代码的描述字段
|
||
- 添加 HTTP 状态码字段
|
||
- 添加静态方法进行转换
|
||
|
||
#### 3. 全局异常处理器
|
||
|
||
- **需求描述**: 实现全局异常处理器，统一处理所有异常
|
||
- **优先级**: 高
|
||
- **验收标准**:
|
||
- 定义 FileGlobalExceptionHandler 类
|
||
- 使用 @RestControllerAdvice 注解
|
||
- 处理 FileUploadException 异常
|
||
- 处理 FileDownloadException 异常
|
||
- 处理 FileSizeExceededException 异常
|
||
- 处理 FileTypeNotSupportedException 异常
|
||
- 处理 FileObjectNotFoundException 异常
|
||
- 处理 OrgConfigNotFoundException 异常
|
||
- 处理 FileValidationException 异常
|
||
- 处理 MethodArgumentNotValidException 异常（参数验证失败）
|
||
- 处理 HttpRequestMethodNotSupportedException 异常（HTTP 方法不支持）
|
||
- 处理 HttpMediaTypeNotSupportedException 异常（Content-Type 不支持）
|
||
- 处理 MaxUploadSizeExceededException 异常（文件大小超限）
|
||
- 处理其他未捕获的异常
|
||
- 返回统一的错误响应格式
|
||
- 提供详细的错误信息
|
||
- 记录错误日志
|
||
- **依赖关系**:
|
||
- 依赖于 REQ-011-1 的基础设施
|
||
- 依赖于自定义异常类
|
||
- **实现建议**:
|
||
- 使用 @RestControllerAdvice 注解
|
||
- 使用 @ExceptionHandler 注解处理异常
|
||
- 使用 @Slf4j 记录日志
|
||
- 返回统一的错误响应格式
|
||
|
||
#### 4. 错误响应封装
|
||
|
||
- **需求描述**: 定义统一的错误响应格式，封装错误信息
|
||
- **优先级**: 高
|
||
- **验收标准**:
|
||
- 定义 ErrorResponse 响应类
|
||
- 包含错误代码字段
|
||
- 包含错误消息字段
|
||
- 包含错误详情字段（可选）
|
||
- 包含时间戳字段
|
||
- 包含请求路径字段（可选）
|
||
- 提供错误响应的构建方法
|
||
- 提供错误响应的序列化方法
|
||
- **依赖关系**: 无
|
||
- **实现建议**:
|
||
- 使用 Lombok 注解简化代码
|
||
- 统一响应格式
|
||
- 提供构建方法
|
||
|
||
#### 5. 错误日志记录
|
||
|
||
- **需求描述**: 实现错误日志记录，记录所有错误信息
|
||
- **优先级**: 高
|
||
- **验收标准**:
|
||
- 在全局异常处理器中记录错误日志
|
||
- 记录异常类型
|
||
- 记录错误信息
|
||
- 记录错误代码
|
||
- 记录请求参数
|
||
- 记录请求路径
|
||
- 记录时间戳
|
||
- 记录异常堆栈（可选）
|
||
- 使用 Slf4j 记录日志
|
||
- 提供日志级别配置
|
||
- **依赖关系**:
|
||
- 依赖于全局异常处理器
|
||
- **实现建议**:
|
||
- 使用 @Slf4j 记录日志
|
||
- 使用不同的日志级别
|
||
- 提供日志格式配置
|
||
- 记录关键信息
|
||
|
||
#### 6. 错误信息国际化
|
||
|
||
- **需求描述**: 实现错误信息国际化，支持多语言
|
||
- **优先级**: 中
|
||
- **验收标准**:
|
||
- 定义错误信息资源文件
|
||
- 支持中文和英文
|
||
- 提供错误信息的多语言支持
|
||
- 根据请求头 Accept-Language 返回对应语言的错误信息
|
||
- **依赖关系**:
|
||
- 依赖于错误响应封装
|
||
- **实现建议**:
|
||
- 使用 Spring 的 MessageSource
|
||
- 定义资源文件
|
||
- 根据请求头返回对应语言
|
||
|
||
## 约束
|
||
|
||
- **技术栈限制**: 必须基于现有的 Spring Boot 3 技术栈
|
||
- **架构约束**: 必须遵循 Authentication.canvas 中定义的架构和调用关系
|
||
- **模块约束**: 必须在 datai-salesforce-integration 模块下实现
|
||
- **文档约束**: 必须遵循 SSOT 方法论
|
||
- **代码规范**: 必须遵循项目编码规范
|
||
|
||
## Rule Set
|
||
|
||
"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"
|
||
|
||
**具体规则**：
|
||
- 必须使用 Canvas 中定义的类名和方法名
|
||
- 必须遵循 Canvas 中定义的调用关系
|
||
- 必须参考 Canvas 中的流程图逻辑
|
||
- 必须遵循现有的异常处理机制
|
||
- 必须遵循现有的日志记录规范
|
||
|
||
## 验收标准
|
||
|
||
- **功能完整性**: 错误处理机制能够正常工作，提供清晰的错误信息
|
||
- **代码规范性**:
|
||
- 代码符合项目编码规范，有清晰的注释
|
||
- 遵循单一职责原则和开闭原则
|
||
- **可维护性**:
|
||
- 代码结构清晰，易于扩展和维护
|
||
- 错误代码集中管理，易于维护
|
||
- **可测试性**:
|
||
- 代码易于单元测试和集成测试
|
||
- 提供完整的测试用例覆盖
|
||
|
||
## 风险
|
||
|
||
- **异常类设计风险**: 异常类设计可能不够完善
|
||
- **错误代码管理风险**: 错误代码可能不够统一
|
||
- **全局异常处理器风险**: 全局异常处理器可能影响其他模块
|
||
- **错误日志记录风险**: 错误日志记录可能不够详细
|
||
- **国际化风险**: 国际化实现可能不够完善
|
||
|
||
## 需求变更记录
|
||
|
||
| 日期 | 变更内容 | 变更原因 | 变更人 | 审核人 | 状态 |
|
||
|------|---------|---------|--------|--------|------|
|
||
| 2026-01-19 | 创建需求文档 | 从 REQ-011 拆分 | 系统管理员 | - | 待审核 |
|
||
|
||
## 相关人员
|
||
|
||
- **需求提出人**: 系统管理员 - 联系方式
|
||
- **需求负责人**: 系统管理员 - 联系方式
|
||
- **技术负责人**: 开发工程师 - 联系方式
|
||
- **测试负责人**: 测试工程师 - 联系方式
|
||
- **其他相关人员**: - 联系方式
|
||
|
||
## 评审信息
|
||
|
||
- **评审日期**: -
|
||
- **评审人员**: -
|
||
- **评审结果**: -
|
||
- **评审意见**: -
|
||
- **修改建议**: -
|