Kris
2e6f087732
- 完成REQ-010-17（性能优化和限流处理）的所有6个阶段 - 创建ADR文档：0026-performance-optimization.md - 创建Prompt文档：027-performance-optimization.md - 创建会话记录：20260119-performance-optimization.md - 创建变更记录：20260119-performance-optimization.md - 创建复盘报告：20260119-performance-optimization-retro.md - 更新index.md和CHANGELOG.md - 完成REQ-010-2（基础实体类和Mapper创建）的前3个阶段 - 更新ADR文档：0011-entity-mapper-create.md - 创建Prompt文档：002-entity-mapper-create.md - 更新index.md 所有文档均按照SSOT方法论创建，包括需求定义、架构决策、提示词资产化、执行会话、变更记录和闭环复盘。
560 lines
17 KiB
Markdown
560 lines
17 KiB
Markdown
# Prompt - 异常处理机制完善
|
||
|
||
## 输入引用
|
||
|
||
引用相关的 docs 文档链接：
|
||
|
||
- [REQ-010-16.md](../requirements/REQ-010-16.md) - 异常处理机制完善需求文档
|
||
- [0025-exception-handling.md](../decisions/adr/0025-exception-handling.md) - 异常处理机制完善架构决策
|
||
- [REQ-010.md](../requirements/REQ-010.md) - Salesforce元数据拉取和部署主需求文档
|
||
- [REQ-010-5.md](../requirements/REQ-010-5.md) - Metadata API客户端封装需求文档
|
||
- [REQ-010-6.md](../requirements/REQ-010-6.md) - 元数据拉取核心功能需求文档
|
||
- [REQ-010-8.md](../requirements/REQ-010-8.md) - 元数据部署核心功能需求文档
|
||
- [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明（唯一真源）
|
||
- [index.md](../reference-code/com/docs/index.md) - Salesforce SOAP API Java 客户端参考文档（唯一真源）
|
||
|
||
## Context Maps
|
||
|
||
强制列出本次 Prompt 依赖的 Canvas 文件：
|
||
|
||
- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
||
- **相关节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **相关节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
|
||
- **快照时间**: 2026-01-19 00:00:00
|
||
|
||
## 目标
|
||
|
||
完善异常处理机制，包括异常捕获、异常分类、异常处理、异常恢复、异常告警、异常日志。支持捕获和处理各种异常情况，提供友好的错误提示和恢复机制。
|
||
|
||
## 输出格式
|
||
|
||
代码示例（语言：Java）
|
||
|
||
### 1. 异常类型枚举
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception.enums;
|
||
|
||
import lombok.Getter;
|
||
|
||
@Getter
|
||
public enum ExceptionType {
|
||
NETWORK("网络异常"),
|
||
API_CALL("API调用异常"),
|
||
FILE_OPERATION("文件操作异常"),
|
||
DATABASE_OPERATION("数据库操作异常"),
|
||
BUSINESS_LOGIC("业务逻辑异常");
|
||
|
||
private final String description;
|
||
|
||
ExceptionType(String description) {
|
||
this.description = description;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 异常级别枚举
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception.enums;
|
||
|
||
import lombok.Getter;
|
||
|
||
@Getter
|
||
public enum ExceptionLevel {
|
||
INFO("信息"),
|
||
WARN("警告"),
|
||
ERROR("错误"),
|
||
FATAL("致命错误");
|
||
|
||
private final String description;
|
||
|
||
ExceptionLevel(String description) {
|
||
this.description = description;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 异常来源枚举
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception.enums;
|
||
|
||
import lombok.Getter;
|
||
|
||
@Getter
|
||
public enum ExceptionSource {
|
||
METADATA_RETRIEVE("元数据拉取"),
|
||
METADATA_DEPLOY("元数据部署"),
|
||
FILE_STORAGE("文件存储"),
|
||
DATABASE("数据库");
|
||
|
||
private final String description;
|
||
|
||
ExceptionSource(String description) {
|
||
this.description = description;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 自定义异常类
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception;
|
||
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionType;
|
||
import lombok.Getter;
|
||
|
||
@Getter
|
||
public class BaseException extends RuntimeException {
|
||
|
||
private final ExceptionType exceptionType;
|
||
private final ExceptionLevel exceptionLevel;
|
||
private final ExceptionSource exceptionSource;
|
||
private final String exceptionCode;
|
||
|
||
public BaseException(ExceptionType exceptionType,
|
||
ExceptionLevel exceptionLevel,
|
||
ExceptionSource exceptionSource,
|
||
String exceptionCode,
|
||
String message) {
|
||
super(message);
|
||
this.exceptionType = exceptionType;
|
||
this.exceptionLevel = exceptionLevel;
|
||
this.exceptionSource = exceptionSource;
|
||
this.exceptionCode = exceptionCode;
|
||
}
|
||
|
||
public BaseException(ExceptionType exceptionType,
|
||
ExceptionLevel exceptionLevel,
|
||
ExceptionSource exceptionSource,
|
||
String exceptionCode,
|
||
String message,
|
||
Throwable cause) {
|
||
super(message, cause);
|
||
this.exceptionType = exceptionType;
|
||
this.exceptionLevel = exceptionLevel;
|
||
this.exceptionSource = exceptionSource;
|
||
this.exceptionCode = exceptionCode;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 网络异常
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception;
|
||
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionType;
|
||
|
||
public class NetworkException extends BaseException {
|
||
|
||
public NetworkException(String exceptionCode, String message) {
|
||
super(ExceptionType.NETWORK, ExceptionLevel.ERROR, ExceptionSource.METADATA_RETRIEVE,
|
||
exceptionCode, message);
|
||
}
|
||
|
||
public NetworkException(String exceptionCode, String message, Throwable cause) {
|
||
super(ExceptionType.NETWORK, ExceptionLevel.ERROR, ExceptionSource.METADATA_RETRIEVE,
|
||
exceptionCode, message, cause);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. API调用异常
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception;
|
||
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionType;
|
||
|
||
public class ApiCallException extends BaseException {
|
||
|
||
public ApiCallException(String exceptionCode, String message) {
|
||
super(ExceptionType.API_CALL, ExceptionLevel.ERROR, ExceptionSource.METADATA_RETRIEVE,
|
||
exceptionCode, message);
|
||
}
|
||
|
||
public ApiCallException(String exceptionCode, String message, Throwable cause) {
|
||
super(ExceptionType.API_CALL, ExceptionLevel.ERROR, ExceptionSource.METADATA_RETRIEVE,
|
||
exceptionCode, message, cause);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7. 文件操作异常
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception;
|
||
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionType;
|
||
|
||
public class FileOperationException extends BaseException {
|
||
|
||
public FileOperationException(String exceptionCode, String message) {
|
||
super(ExceptionType.FILE_OPERATION, ExceptionLevel.ERROR, ExceptionSource.FILE_STORAGE,
|
||
exceptionCode, message);
|
||
}
|
||
|
||
public FileOperationException(String exceptionCode, String message, Throwable cause) {
|
||
super(ExceptionType.FILE_OPERATION, ExceptionLevel.ERROR, ExceptionSource.FILE_STORAGE,
|
||
exceptionCode, message, cause);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8. 数据库操作异常
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception;
|
||
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionType;
|
||
|
||
public class DatabaseOperationException extends BaseException {
|
||
|
||
public DatabaseOperationException(String exceptionCode, String message) {
|
||
super(ExceptionType.DATABASE_OPERATION, ExceptionLevel.ERROR, ExceptionSource.DATABASE,
|
||
exceptionCode, message);
|
||
}
|
||
|
||
public DatabaseOperationException(String exceptionCode, String message, Throwable cause) {
|
||
super(ExceptionType.DATABASE_OPERATION, ExceptionLevel.ERROR, ExceptionSource.DATABASE,
|
||
exceptionCode, message, cause);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 9. 业务逻辑异常
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception;
|
||
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionType;
|
||
|
||
public class BusinessLogicException extends BaseException {
|
||
|
||
public BusinessLogicException(String exceptionCode, String message) {
|
||
super(ExceptionType.BUSINESS_LOGIC, ExceptionLevel.WARN, ExceptionSource.METADATA_RETRIEVE,
|
||
exceptionCode, message);
|
||
}
|
||
|
||
public BusinessLogicException(String exceptionCode, String message, Throwable cause) {
|
||
super(ExceptionType.BUSINESS_LOGIC, ExceptionLevel.WARN, ExceptionSource.METADATA_RETRIEVE,
|
||
exceptionCode, message, cause);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 10. 全局异常处理器
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception.handler;
|
||
|
||
import com.datai.common.core.domain.R;
|
||
import com.datai.salesforce.metadata.exception.BaseException;
|
||
import lombok.extern.slf4j.Slf4j;
|
||
import org.springframework.web.bind.annotation.ExceptionHandler;
|
||
import org.springframework.web.bind.annotation.RestControllerAdvice;
|
||
|
||
@Slf4j
|
||
@RestControllerAdvice
|
||
public class GlobalExceptionHandler {
|
||
|
||
@ExceptionHandler(BaseException.class)
|
||
public R<Void> handleBaseException(BaseException e) {
|
||
log.error("业务异常: {}", e.getMessage(), e);
|
||
return R.fail(e.getExceptionCode(), e.getMessage());
|
||
}
|
||
|
||
@ExceptionHandler(Exception.class)
|
||
public R<Void> handleException(Exception e) {
|
||
log.error("系统异常: {}", e.getMessage(), e);
|
||
return R.fail("SYSTEM_ERROR", "系统异常，请联系管理员");
|
||
}
|
||
}
|
||
```
|
||
|
||
### 11. 异常日志实体类
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception.entity;
|
||
|
||
import com.baomidou.mybatisplus.annotation.IdType;
|
||
import com.baomidou.mybatisplus.annotation.TableId;
|
||
import com.baomidou.mybatisplus.annotation.TableName;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionType;
|
||
import lombok.Data;
|
||
|
||
import java.time.LocalDateTime;
|
||
|
||
@Data
|
||
@TableName("datai_exception_log")
|
||
public class ExceptionLog {
|
||
|
||
@TableId(type = IdType.AUTO)
|
||
private Long id;
|
||
|
||
private ExceptionType exceptionType;
|
||
|
||
private ExceptionLevel exceptionLevel;
|
||
|
||
private ExceptionSource exceptionSource;
|
||
|
||
private String exceptionCode;
|
||
|
||
private String exceptionMessage;
|
||
|
||
private String exceptionStack;
|
||
|
||
private LocalDateTime exceptionTime;
|
||
|
||
private LocalDateTime createTime;
|
||
}
|
||
```
|
||
|
||
### 12. 恢复点实体类
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception.entity;
|
||
|
||
import com.baomidou.mybatisplus.annotation.IdType;
|
||
import com.baomidou.mybatisplus.annotation.TableId;
|
||
import com.baomidou.mybatisplus.annotation.TableName;
|
||
import lombok.Data;
|
||
|
||
import java.time.LocalDateTime;
|
||
|
||
@Data
|
||
@TableName("datai_recovery_point")
|
||
public class RecoveryPoint {
|
||
|
||
@TableId(type = IdType.AUTO)
|
||
private Long id;
|
||
|
||
private Long jobExecutionId;
|
||
|
||
private String recoveryPointName;
|
||
|
||
private String recoveryPointData;
|
||
|
||
private String recoveryPointStatus;
|
||
|
||
private LocalDateTime recoveryPointTime;
|
||
|
||
private LocalDateTime createTime;
|
||
}
|
||
```
|
||
|
||
### 13. 异常告警实体类
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception.entity;
|
||
|
||
import com.baomidou.mybatisplus.annotation.IdType;
|
||
import com.baomidou.mybatisplus.annotation.TableId;
|
||
import com.baomidou.mybatisplus.annotation.TableName;
|
||
import lombok.Data;
|
||
|
||
import java.time.LocalDateTime;
|
||
|
||
@Data
|
||
@TableName("datai_exception_alarm")
|
||
public class ExceptionAlarm {
|
||
|
||
@TableId(type = IdType.AUTO)
|
||
private Long id;
|
||
|
||
private Long exceptionLogId;
|
||
|
||
private String alarmType;
|
||
|
||
private String alarmTitle;
|
||
|
||
private String alarmContent;
|
||
|
||
private String alarmStatus;
|
||
|
||
private LocalDateTime createTime;
|
||
}
|
||
```
|
||
|
||
### 14. 异常日志服务接口
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception.service;
|
||
|
||
import com.baomidou.mybatisplus.core.metadata.IPage;
|
||
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
|
||
import com.datai.salesforce.metadata.exception.entity.ExceptionLog;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
|
||
import com.datai.salesforce.metadata.exception.enums.ExceptionType;
|
||
|
||
import java.time.LocalDateTime;
|
||
import java.util.List;
|
||
|
||
public interface IExceptionLogService {
|
||
|
||
Long saveExceptionLog(ExceptionLog exceptionLog);
|
||
|
||
ExceptionLog getExceptionLog(Long id);
|
||
|
||
IPage<ExceptionLog> queryExceptionLogs(Page<ExceptionLog> page,
|
||
ExceptionType exceptionType,
|
||
ExceptionLevel exceptionLevel,
|
||
ExceptionSource exceptionSource,
|
||
LocalDateTime startTime,
|
||
LocalDateTime endTime);
|
||
|
||
boolean deleteExceptionLog(Long id);
|
||
|
||
boolean batchDeleteExceptionLogs(List<Long> ids);
|
||
}
|
||
```
|
||
|
||
### 15. 恢复服务接口
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception.service;
|
||
|
||
import com.datai.salesforce.metadata.exception.entity.RecoveryPoint;
|
||
|
||
import java.util.List;
|
||
|
||
public interface IRecoveryService {
|
||
|
||
Long createRecoveryPoint(RecoveryPoint recoveryPoint);
|
||
|
||
RecoveryPoint getRecoveryPoint(Long id);
|
||
|
||
List<RecoveryPoint> getRecoveryPointsByJobExecutionId(Long jobExecutionId);
|
||
|
||
boolean recoverFromPoint(Long recoveryPointId);
|
||
|
||
boolean deleteRecoveryPoint(Long id);
|
||
|
||
boolean batchDeleteRecoveryPoints(List<Long> ids);
|
||
}
|
||
```
|
||
|
||
### 16. 异常告警服务接口
|
||
|
||
```java
|
||
package com.datai.salesforce.metadata.exception.service;
|
||
|
||
import com.datai.salesforce.metadata.exception.entity.ExceptionAlarm;
|
||
|
||
import java.util.List;
|
||
|
||
public interface IExceptionAlarmService {
|
||
|
||
Long createExceptionAlarm(ExceptionAlarm exceptionAlarm);
|
||
|
||
ExceptionAlarm getExceptionAlarm(Long id);
|
||
|
||
boolean sendExceptionAlarm(Long exceptionLogId, String alarmType, String alarmTitle, String alarmContent);
|
||
|
||
List<ExceptionAlarm> getExceptionAlarmsByExceptionLogId(Long exceptionLogId);
|
||
|
||
boolean deleteExceptionAlarm(Long id);
|
||
|
||
boolean batchDeleteExceptionAlarms(List<Long> ids);
|
||
}
|
||
```
|
||
|
||
## 约束
|
||
|
||
- **技术栈限制**: 必须基于现有的 Spring Boot 3 + Vue 3 技术栈
|
||
- **架构约束**: 必须遵循 Authentication.canvas 中定义的架构和调用关系
|
||
- **模块约束**: 必须在 datai-salesforce-metadata 模块下实现
|
||
- **数据库约束**: 必须使用 MyBatis Plus 作为持久层框架
|
||
- **性能约束**: 异常处理性能必须满足要求，不能影响系统响应
|
||
- **依赖约束**: 必须依赖于 REQ-010-1, REQ-010-2, REQ-010-5, REQ-010-6, REQ-010-8
|
||
|
||
## Rule Set
|
||
|
||
"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"
|
||
|
||
**具体规则**：
|
||
- 必须使用 Canvas 中定义的类名和方法名
|
||
- 必须遵循 Canvas 中定义的调用关系
|
||
- 必须参考 Canvas 中的流程图逻辑
|
||
- 必须使用 SessionManager 进行会话管理和自动重新登录
|
||
- 必须使用现有的认证模块进行 OAuth 认证
|
||
- 必须使用现有的集成核心功能进行 API 调用
|
||
- 必须遵循现有的异常处理机制
|
||
- 必须遵循现有的日志记录规范
|
||
|
||
## 验收标准
|
||
|
||
定义验证输出质量的具体标准，例如：
|
||
|
||
- **功能完整性**: 所有异常处理功能能够正常工作
|
||
- 异常捕获功能正常工作
|
||
- 异常分类功能正常工作
|
||
- 异常处理功能正常工作
|
||
- 异常恢复功能正常工作
|
||
- 异常告警功能正常工作
|
||
- 异常日志功能正常工作
|
||
|
||
- **性能指标**: 异常处理性能满足要求，不影响系统响应
|
||
- 异常捕获响应时间 < 10ms
|
||
- 异常处理响应时间 < 100ms
|
||
- 异常恢复响应时间 < 1s
|
||
- 异常告警响应时间 < 1s
|
||
- 异常日志记录响应时间 < 10ms
|
||
|
||
- **完整性**: 异常信息完整详细，能够追溯异常发生原因
|
||
- 异常信息完整详细
|
||
- 能够追溯异常发生原因
|
||
|
||
- **代码规范性**: 代码符合项目编码规范，有清晰的注释
|
||
- 使用 Lombok 的 @Data、@RequiredArgsConstructor、@Slf4j 注解
|
||
- 使用 Spring 的 @ControllerAdvice、@ExceptionHandler、@RestControllerAdvice 注解
|
||
- 使用 MyBatis Plus 的 @TableName、@TableId 注解
|
||
|
||
- **可维护性**: 代码结构清晰，易于扩展和维护
|
||
- 服务接口和实现分离
|
||
- 控制器、服务、实体、Mapper 分层清晰
|
||
- 使用枚举管理异常类型、异常级别、异常来源
|
||
|
||
- **可测试性**: 代码易于单元测试和集成测试
|
||
- 编写单元测试，测试覆盖率 > 80%
|
||
- 编写集成测试，确保功能正常
|
||
|
||
## 风险
|
||
|
||
识别使用此提示词可能带来的风险，例如：
|
||
|
||
- **输出质量风险**: 代码质量可能不符合项目规范
|
||
- **缓解措施**: 使用代码审查，确保代码质量符合项目规范
|
||
|
||
- **技术实现风险**: 技术实现可能不符合架构决策
|
||
- **缓解措施**: 参考架构决策文档，确保技术实现符合架构决策
|
||
|
||
- **时间成本风险**: 开发周期可能较长
|
||
- **缓解措施**: 分阶段实施，优先实现核心功能，逐步完善
|
||
|
||
- **性能风险**: 异常处理性能可能不佳
|
||
- **缓解措施**: 使用异步异常处理，使用重试机制，使用事务回滚
|
||
|
||
## 使用记录
|
||
|
||
| 日期 | 使用场景 | 输入参数 | 输出结果 | 反馈 | 改进措施 |
|
||
|------|---------|---------|---------|------|----------|
|
||
| 2026-01-19 | 异常处理机制完善实现 | REQ-010-16, 0025-exception-handling | 异常处理机制完善代码 | 代码质量良好 | 无 |
|