261 lines
11 KiB
Markdown
261 lines
11 KiB
Markdown
|
# 架构决策记录 (ADR) - 基础设施和枚举定义
|
|||
|
|
|
|||
|
|
## 背景
|
|||
|
|
|
|||
|
|
REQ-011-1 需求要求在 datai-salesforce-common 模块定义文件上传下载所需的基础设施，包括：
|
|||
|
|
- 文件对象类型枚举（FileObjectType）
|
|||
|
|
- 文件上传下载参数类（DTO/VO）
|
|||
|
|
- 文件上传下载异常类
|
|||
|
|
- 文件验证工具类
|
|||
|
|
|
|||
|
|
这些基础设施将被后续的文件上传下载功能（REQ-011-2/3/4/5/6）使用，需要确保设计的合理性和可扩展性。
|
|||
|
|
|
|||
|
|
**约束条件**：
|
|||
|
|
- 必须基于现有的 Spring Boot 3 技术栈
|
|||
|
|
- 必须遵循 Authentication.canvas 中定义的架构和调用关系
|
|||
|
|
- 必须在 datai-salesforce-common 模块下实现
|
|||
|
|
- 必须遵循 SSOT 方法论
|
|||
|
|
|
|||
|
|
**业务需求**：
|
|||
|
|
- 支持 Attachment、ContentDocument、Document 三种文件对象类型
|
|||
|
|
- 提供统一的参数验证和响应封装
|
|||
|
|
- 提供完善的异常处理机制
|
|||
|
|
- 支持文件大小和类型验证
|
|||
|
|
|
|||
|
|
## 决策
|
|||
|
|
|
|||
|
|
采用**策略模式 + 枚举 + 统一异常处理**的架构设计方案：
|
|||
|
|
|
|||
|
|
1. **文件对象类型枚举（FileObjectType）**：
|
|||
|
|
- 使用 Java 枚举定义 ATTACHMENT、CONTENT_DOCUMENT、DOCUMENT 三个枚举值
|
|||
|
|
- 每个枚举值包含：描述、文件大小限制、推荐等级、API 类型、必填字段等元数据
|
|||
|
|
- 提供静态方法进行枚举值与字符串的转换
|
|||
|
|
- 提供获取文件大小限制和推荐等级的方法
|
|||
|
|
|
|||
|
|
2. **参数类设计**：
|
|||
|
|
- FileUploadRequest：包含组织配置 ID、文件对象类型、文件、关联记录 ID、文件名、描述等字段
|
|||
|
|
- FileDownloadRequest：包含组织配置 ID、文件对象类型、文件 ID、保存路径等字段
|
|||
|
|
- FileUploadResponse：包含文件 ID、文件名、文件大小、文件类型、上传时间、操作状态等字段
|
|||
|
|
- FileDownloadResponse：包含文件名、文件大小、保存路径、下载时间、操作状态等字段
|
|||
|
|
- 使用 Lombok 注解简化代码（@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor）
|
|||
|
|
- 使用 JSR-303 验证注解（@NotNull、@NotBlank、@Size、@Valid）
|
|||
|
|
|
|||
|
|
3. **异常类设计**：
|
|||
|
|
- 继承自 datai-salesforce-common 模块的 RuntimeException 基类
|
|||
|
|
- 提供错误代码枚举（FileErrorCode）
|
|||
|
|
- 每个异常类包含：错误代码、错误消息、异常链（cause）
|
|||
|
|
- 异常类包括：FileUploadException、FileDownloadException、FileSizeExceededException、FileTypeNotSupportedException、FileObjectNotFoundException、OrgConfigNotFoundException、FileValidationException
|
|||
|
|
|
|||
|
|
4. **验证工具类设计**：
|
|||
|
|
- FileValidationUtils：提供文件大小验证、文件类型验证、文件名验证、文件扩展名获取、文件 MIME 类型获取等静态方法
|
|||
|
|
- 使用 Apache Tika 获取文件 MIME 类型
|
|||
|
|
- 提供可配置的文件大小限制和文件类型白名单
|
|||
|
|
|
|||
|
|
## 备选方案
|
|||
|
|
|
|||
|
|
### 方案一：策略模式 + 枚举 + 统一异常处理（已选择）
|
|||
|
|
|
|||
|
|
**优点**：
|
|||
|
|
- 枚举提供类型安全和编译时检查
|
|||
|
|
- 策略模式易于扩展新的文件对象类型
|
|||
|
|
- 统一异常处理机制便于维护
|
|||
|
|
- 参数类使用 Lombok 和 JSR-303 注解，代码简洁
|
|||
|
|
- 验证工具类提供可复用的验证逻辑
|
|||
|
|
|
|||
|
|
**缺点**：
|
|||
|
|
- 需要引入 Apache Tika 依赖
|
|||
|
|
- 枚举扩展需要修改代码
|
|||
|
|
|
|||
|
|
### 方案二：配置文件 + 反射 + 动态验证
|
|||
|
|
|
|||
|
|
**优点**：
|
|||
|
|
- 文件对象类型配置化，无需修改代码即可扩展
|
|||
|
|
- 验证规则可配置，灵活性高
|
|||
|
|
|
|||
|
|
**缺点**：
|
|||
|
|
- 失去编译时类型安全
|
|||
|
|
- 反射影响性能
|
|||
|
|
- 配置复杂度增加
|
|||
|
|
- 维护成本高
|
|||
|
|
|
|||
|
|
### 方案三：继承体系 + 抽象类
|
|||
|
|
|
|||
|
|
**优点**：
|
|||
|
|
- 面向对象设计，符合 OOP 原则
|
|||
|
|
- 可以通过继承扩展功能
|
|||
|
|
|
|||
|
|
**缺点**：
|
|||
|
|
- 类层次结构复杂
|
|||
|
|
- 三种文件对象类型差异较大，难以抽象
|
|||
|
|
- 违反"组合优于继承"原则
|
|||
|
|
|
|||
|
|
## 影响
|
|||
|
|
|
|||
|
|
### 系统架构影响
|
|||
|
|
|
|||
|
|
1. **datai-salesforce-common 模块**：
|
|||
|
|
- 新增枚举类：FileObjectType
|
|||
|
|
- 新增参数类：FileUploadRequest、FileDownloadRequest、FileUploadResponse、FileDownloadResponse
|
|||
|
|
- 新增异常类：FileUploadException、FileDownloadException、FileSizeExceededException、FileTypeNotSupportedException、FileObjectNotFoundException、OrgConfigNotFoundException、FileValidationException
|
|||
|
|
- 新增错误代码枚举：FileErrorCode
|
|||
|
|
- 新增工具类：FileValidationUtils
|
|||
|
|
|
|||
|
|
2. **依赖管理**：
|
|||
|
|
- 需要引入 Apache Tika 依赖（用于文件 MIME 类型检测）
|
|||
|
|
- 需要引入 Lombok 依赖（如果尚未引入）
|
|||
|
|
- 需要引入 Spring Validation 依赖（如果尚未引入）
|
|||
|
|
|
|||
|
|
### 开发流程影响
|
|||
|
|
|
|||
|
|
1. **后续子需求开发**：
|
|||
|
|
- REQ-011-2/3/4 可以直接使用 FileObjectType 枚举
|
|||
|
|
- REQ-011-2/3/4 可以直接使用 FileUploadRequest 和 FileDownloadRequest
|
|||
|
|
- REQ-011-2/3/4 可以直接使用 FileUploadResponse 和 FileDownloadResponse
|
|||
|
|
- REQ-011-2/3/4 可以直接使用异常类和验证工具类
|
|||
|
|
|
|||
|
|
2. **测试流程**：
|
|||
|
|
- 需要为枚举类编写单元测试
|
|||
|
|
- 需要为参数类编写单元测试
|
|||
|
|
- 需要为异常类编写单元测试
|
|||
|
|
- 需要为验证工具类编写单元测试
|
|||
|
|
|
|||
|
|
### 运维管理影响
|
|||
|
|
|
|||
|
|
1. **配置管理**：
|
|||
|
|
- 文件大小限制和文件类型白名单可以通过配置文件管理
|
|||
|
|
- 无需修改代码即可调整验证规则
|
|||
|
|
|
|||
|
|
2. **日志管理**：
|
|||
|
|
- 异常类提供详细的错误信息和错误代码
|
|||
|
|
- 便于日志分析和问题排查
|
|||
|
|
|
|||
|
|
## 风险
|
|||
|
|
|
|||
|
|
### 技术风险
|
|||
|
|
|
|||
|
|
1. **Apache Tika 依赖冲突**：
|
|||
|
|
- 风险描述：Apache Tika 可能与项目现有依赖冲突
|
|||
|
|
- 影响程度：中
|
|||
|
|
- 缓解措施：使用 Maven 依赖树检查冲突，必要时使用 exclusions
|
|||
|
|
|
|||
|
|
2. **枚举扩展性**：
|
|||
|
|
- 风险描述：未来可能需要支持更多文件对象类型，需要修改枚举
|
|||
|
|
- 影响程度：低
|
|||
|
|
- 缓解措施：枚举设计时考虑扩展性，提供清晰的扩展文档
|
|||
|
|
|
|||
|
|
### 业务风险
|
|||
|
|
|
|||
|
|
1. **文件大小限制调整**：
|
|||
|
|
- 风险描述：Salesforce 可能调整文件大小限制
|
|||
|
|
- 影响程度：低
|
|||
|
|
- 缓解措施：文件大小限制配置化，便于调整
|
|||
|
|
|
|||
|
|
2. **文件类型白名单维护**：
|
|||
|
|
- 风险描述：文件类型白名单需要定期维护
|
|||
|
|
- 影响程度：低
|
|||
|
|
- 缓解措施：提供配置文件，便于运维人员维护
|
|||
|
|
|
|||
|
|
### 实施风险
|
|||
|
|
|
|||
|
|
1. **参数验证复杂性**：
|
|||
|
|
- 风险描述：参数验证逻辑可能过于复杂
|
|||
|
|
- 影响程度：中
|
|||
|
|
- 缓解措施：使用 JSR-303 验证注解，简化验证逻辑
|
|||
|
|
|
|||
|
|
2. **异常类设计不完善**：
|
|||
|
|
- 风险描述：异常类设计可能不够完善，遗漏某些异常场景
|
|||
|
|
- 影响程度：中
|
|||
|
|
- 缓解措施：参考现有的异常类定义，提供详细的错误代码
|
|||
|
|
|
|||
|
|
## 回滚策略
|
|||
|
|
|
|||
|
|
如果决策实施后出现问题，可以采用以下回滚策略：
|
|||
|
|
|
|||
|
|
1. **Apache Tika 依赖冲突**：
|
|||
|
|
- 回滚方案：移除 Apache Tika 依赖，使用 Java 内置的 Files.probeContentType() 方法
|
|||
|
|
- 回滚步骤：
|
|||
|
|
1. 在 pom.xml 中移除 Apache Tika 依赖
|
|||
|
|
2. 修改 FileValidationUtils，使用 Files.probeContentType() 方法
|
|||
|
|
3. 重新编译和测试
|
|||
|
|
|
|||
|
|
2. **枚举扩展性不足**：
|
|||
|
|
- 回滚方案：将枚举改为配置文件 + 反射
|
|||
|
|
- 回滚步骤：
|
|||
|
|
1. 创建 file-object-types.yml 配置文件
|
|||
|
|
2. 修改 FileObjectType 为配置类
|
|||
|
|
3. 使用反射动态加载配置
|
|||
|
|
4. 重新编译和测试
|
|||
|
|
|
|||
|
|
3. **参数验证逻辑复杂**：
|
|||
|
|
- 回滚方案：简化参数验证，只保留核心验证逻辑
|
|||
|
|
- 回滚步骤：
|
|||
|
|
1. 移除复杂的自定义验证注解
|
|||
|
|
2. 只保留 JSR-303 基础验证注解
|
|||
|
|
3. 重新编译和测试
|
|||
|
|
|
|||
|
|
## 验收标准
|
|||
|
|
|
|||
|
|
定义验证该决策有效性的具体标准和测试方法：
|
|||
|
|
|
|||
|
|
1. **功能验证**：
|
|||
|
|
- [ ] FileObjectType 枚举包含 ATTACHMENT、CONTENT_DOCUMENT、DOCUMENT 三个枚举值
|
|||
|
|
- [ ] FileObjectType 枚举提供描述、文件大小限制、推荐等级等元数据
|
|||
|
|
- [ ] FileObjectType 枚举提供枚举值与字符串的转换方法
|
|||
|
|
- [ ] FileUploadRequest 包含所有必需字段
|
|||
|
|
- [ ] FileDownloadRequest 包含所有必需字段
|
|||
|
|
- [ ] FileUploadResponse 包含所有必需字段
|
|||
|
|
- [ ] FileDownloadResponse 包含所有必需字段
|
|||
|
|
- [ ] 所有异常类继承自 RuntimeException
|
|||
|
|
- [ ] 所有异常类提供错误代码和错误消息
|
|||
|
|
- [ ] FileValidationUtils 提供所有必需的验证方法
|
|||
|
|
|
|||
|
|
2. **代码质量验证**：
|
|||
|
|
- [ ] 代码符合项目编码规范
|
|||
|
|
- [ ] 代码有清晰的注释
|
|||
|
|
- [ ] 代码通过 SonarQube 静态代码分析
|
|||
|
|
- [ ] 代码通过 Checkstyle 检查
|
|||
|
|
|
|||
|
|
3. **单元测试验证**：
|
|||
|
|
- [ ] FileObjectType 枚举单元测试覆盖率 ≥ 90%
|
|||
|
|
- [ ] 参数类单元测试覆盖率 ≥ 90%
|
|||
|
|
- [ ] 异常类单元测试覆盖率 ≥ 90%
|
|||
|
|
- [ ] FileValidationUtils 单元测试覆盖率 ≥ 90%
|
|||
|
|
|
|||
|
|
4. **集成测试验证**：
|
|||
|
|
- [ ] 后续子需求（REQ-011-2/3/4）能够正常使用这些基础设施
|
|||
|
|
- [ ] 文件上传下载功能能够正常工作
|
|||
|
|
|
|||
|
|
## 视觉锚点
|
|||
|
|
|
|||
|
|
### Visual Reference
|
|||
|
|
|
|||
|
|
引用 Canvas 的具体节点或快照：
|
|||
|
|
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
|
|||
|
|
- **具体节点**: [通用常量](node_common_constant) - 定义Salesforce相关的常量
|
|||
|
|
- **具体节点**: [通用异常](node_common_exception) - 定义Salesforce相关的异常类
|
|||
|
|
|
|||
|
|
### Status
|
|||
|
|
|
|||
|
|
- [x] Draft
|
|||
|
|
- [ ] Accepted
|
|||
|
|
- [ ] Superceded
|
|||
|
|
|
|||
|
|
## 参考资料
|
|||
|
|
|
|||
|
|
列出与该决策相关的参考资料，包括文档、文章或其他资源：
|
|||
|
|
|
|||
|
|
1. [REQ-011.md](../requirements/REQ-011.md) - 父需求文档
|
|||
|
|
2. [REQ-011-1.md](../requirements/REQ-011-1.md) - 子需求文档
|
|||
|
|
3. [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
|
|||
|
|
4. [Attachment文件上传.md](../reference-code/data-dump/Attachment文件上传.md) - Salesforce Attachment 上传实现逻辑
|
|||
|
|
5. [Attachment文件下载.md](../reference-code/data-dump/Attachment文件下载.md) - Salesforce Attachment 下载实现逻辑
|
|||
|
|
6. [Document上传下载.md](../reference-code/data-dump/Document上传下载.md) - Salesforce Document 上传下载实现逻辑
|
|||
|
|
7. [ContentVersion上传下载.md](../reference-code/data-dump/ContentVersion上传下载.md) - Salesforce ContentVersion 上传下载实现逻辑
|
|||
|
|
8. [大文件上传下载.md](../reference-code/data-dump/大文件上传下载.md) - 大文件上传下载实现逻辑
|
|||
|
|
9. [CommonServiceImpl.java](../reference-code/data-dump/CommonServiceImpl.java) - 现有的文件上传下载实现逻辑
|
|||
|
|
10. [DataImportNewServiceImpl.java](../reference-code/data-dump/DataImportNewServiceImpl.java) - 现有的文件上传下载实现逻辑
|
|||
|
|
11. [Java 枚举最佳实践](https://docs.oracle.com/javase/tutorial/java/javaOO/enum.html) - Oracle 官方文档
|
|||
|
|
12. [JSR-303 Bean Validation](https://beanvalidation.org/2.0/spec/) - Bean Validation 规范
|
|||
|
|
13. [Apache Tika 文档](https://tika.apache.org/) - Apache Tika 官方文档
|
|||
|
|
14. [Lombok 文档](https://projectlombok.org/) - Lombok 官方文档
|