317 lines
11 KiB
Markdown
317 lines
11 KiB
Markdown
# 架构决策记录：文件上传下载 Controller 和 API 接口
|
||
|
||
## 背景
|
||
|
||
REQ-011-5 需求要求创建 FileController，提供文件上传下载的 RESTful API 接口，支持 Attachment、ContentDocument、Document 三种文件对象类型。用户可以通过 HTTP 请求上传和下载 Salesforce 的三种文件对象，支持指定组织配置 ID。
|
||
|
||
### 面临的问题
|
||
|
||
1. **Controller 设计**: 需要设计合理的 Controller，支持三种文件对象类型的上传下载功能
|
||
2. **API 设计**: 需要设计符合 RESTful 规范的 API 接口
|
||
3. **参数验证**: 需要设计合理的参数验证机制，确保 API 接口的健壮性
|
||
4. **响应封装**: 需要设计统一的响应格式，提高 API 接口的一致性
|
||
5. **策略模式应用**: 需要使用策略模式根据文件对象类型调用不同的 Service
|
||
6. **文档生成**: 需要生成清晰的 API 文档，提高 API 接口的可用性
|
||
|
||
### 约束条件
|
||
|
||
1. **技术栈限制**: 必须基于现有的 Spring Boot 3 技术栈
|
||
2. **架构约束**: 必须遵循 Authentication.canvas 中定义的架构和调用关系
|
||
3. **模块约束**: 必须在 datai-salesforce-integration 模块下实现
|
||
4. **认证约束**: 必须使用 SessionManager 进行会话管理和自动重新登录
|
||
5. **API约束**: 必须遵循 RESTful 设计规范
|
||
6. **文档约束**: 必须遵循 SSOT 方法论
|
||
7. **设计模式约束**: 必须使用策略模式封装三种文件对象的上传下载逻辑
|
||
8. **验证约束**: 必须使用 JSR-303 验证注解进行参数验证
|
||
9. **文档约束**: 必须使用 Swagger/OpenAPI 注解生成 API 文档
|
||
|
||
## 决策
|
||
|
||
### 1. Controller 设计
|
||
|
||
**决策**: 创建 FileController，使用 @RestController 和 @RequestMapping 注解
|
||
|
||
**理由**:
|
||
- @RestController 是 Spring Boot 推荐的 RESTful Controller 注解
|
||
- @RequestMapping 可以指定基础路径，便于 API 管理
|
||
- 符合 Spring Boot 最佳实践
|
||
- 代码简洁，易于维护
|
||
|
||
**实现方案**:
|
||
- 使用 @RestController 注解标记 FileController
|
||
- 使用 @RequestMapping("/files") 注解指定基础路径
|
||
- 使用 @Slf4j 注解记录日志
|
||
- 使用 @Autowired 注入 AttachmentFileService、ContentVersionFileService、DocumentFileService
|
||
|
||
### 2. API 设计
|
||
|
||
**决策**: 设计符合 RESTful 规范的 API 接口
|
||
|
||
**理由**:
|
||
- RESTful 是业界公认的 API 设计规范
|
||
- 提高 API 接口的一致性和可维护性
|
||
- 便于前端调用和集成
|
||
- 符合业界最佳实践
|
||
|
||
**实现方案**:
|
||
- 文件上传接口：POST /files/upload
|
||
- 文件下载接口：GET /files/download
|
||
- 使用 @PostMapping 和 @GetMapping 注解
|
||
- 使用 @RequestParam 和 @RequestPart 注解接收参数
|
||
- 使用 @Valid 注解进行参数验证
|
||
- 返回统一的响应格式
|
||
|
||
### 3. 参数验证
|
||
|
||
**决策**: 使用 JSR-303 验证注解进行参数验证
|
||
|
||
**理由**:
|
||
- JSR-303 是 Java 标准的验证规范
|
||
- Spring Boot 3.5.7 内置 JSR-303 支持
|
||
- 提供丰富的验证注解，如 @NotNull、@NotBlank、@Size 等
|
||
- 可以自定义验证注解
|
||
- 提高代码的可读性和可维护性
|
||
|
||
**实现方案**:
|
||
- 使用 @Valid 注解进行参数验证
|
||
- 使用 @NotNull、@NotBlank、@Size 等验证注解
|
||
- 自定义验证注解（如果需要）
|
||
- 提供详细的错误信息
|
||
|
||
### 4. 响应封装
|
||
|
||
**决策**: 使用统一的响应格式
|
||
|
||
**理由**:
|
||
- 提高 API 接口的一致性
|
||
- 便于前端处理响应
|
||
- 便于错误处理和日志记录
|
||
- 符合业界最佳实践
|
||
|
||
**实现方案**:
|
||
- 定义统一的响应格式，包含 code、message、data 字段
|
||
- 成功响应返回 200 状态码
|
||
- 失败响应返回 4xx 或 5xx 状态码
|
||
- 提供详细的错误信息
|
||
|
||
### 5. 策略模式应用
|
||
|
||
**决策**: 使用策略模式根据文件对象类型调用不同的 Service
|
||
|
||
**理由**:
|
||
- 策略模式可以很好地支持多种文件对象类型的上传下载功能
|
||
- 符合开闭原则，易于扩展新的文件对象类型
|
||
- 代码结构清晰，易于维护
|
||
- 符合单一职责原则
|
||
|
||
**实现方案**:
|
||
- 使用 switch-case 语句根据 FileObjectType 调用不同的 Service
|
||
- Attachment 类型调用 AttachmentFileService
|
||
- ContentDocument 类型调用 ContentVersionFileService
|
||
- Document 类型调用 DocumentFileService
|
||
|
||
### 6. 文档生成
|
||
|
||
**决策**: 使用 Swagger/OpenAPI 注解生成 API 文档
|
||
|
||
**理由**:
|
||
- Swagger/OpenAPI 是业界标准的 API 文档规范
|
||
- 自动生成 API 文档，减少维护成本
|
||
- 提供在线 API 测试功能
|
||
- 提高开发效率和用户体验
|
||
|
||
**实现方案**:
|
||
- 使用 @Tag 注解标记 Controller
|
||
- 使用 @Operation 注解标记方法
|
||
- 使用 @Parameter 注解标记参数
|
||
- 使用 @ApiResponse 注解标记响应
|
||
- 配置 Swagger UI
|
||
|
||
## 备选方案
|
||
|
||
### 方案 1: 使用 GraphQL API
|
||
|
||
**优点**:
|
||
- GraphQL API 灵活强大
|
||
- 可以一次性获取多个数据
|
||
- 减少网络请求次数
|
||
|
||
**缺点**:
|
||
- GraphQL API 对文件上传下载支持有限
|
||
- 实现复杂度高
|
||
- 不符合 RESTful 规范
|
||
- 前端需要学习 GraphQL
|
||
|
||
**评估**: 不推荐使用
|
||
|
||
### 方案 2: 使用 gRPC API
|
||
|
||
**优点**:
|
||
- gRPC 性能优异
|
||
- 支持多种语言
|
||
- 使用 Protocol Buffers 序列化
|
||
|
||
**缺点**:
|
||
- gRPC 不适合文件上传下载
|
||
- 实现复杂度高
|
||
- 不符合 RESTful 规范
|
||
- 前端需要学习 gRPC
|
||
|
||
**评估**: 不推荐使用
|
||
|
||
### 方案 3: 使用自定义验证逻辑
|
||
|
||
**优点**:
|
||
- 可以完全控制验证逻辑
|
||
- 不依赖第三方库
|
||
|
||
**缺点**:
|
||
- 代码冗余，不易维护
|
||
- 不符合 JSR-303 标准
|
||
- 增加开发成本
|
||
|
||
**评估**: 不推荐使用
|
||
|
||
### 方案 4: 使用自定义响应格式
|
||
|
||
**优点**:
|
||
- 可以完全控制响应格式
|
||
- 不依赖第三方库
|
||
|
||
**缺点**:
|
||
- 代码冗余，不易维护
|
||
- 不符合业界最佳实践
|
||
- 增加开发成本
|
||
|
||
**评估**: 不推荐使用
|
||
|
||
## 影响
|
||
|
||
### 系统架构影响
|
||
|
||
1. **新增模块**: 在 datai-salesforce-integration 模块下新增 FileController
|
||
2. **新增接口**: 新增文件上传下载 API 接口
|
||
3. **新增依赖**: 新增 Swagger/OpenAPI 依赖
|
||
4. **新增验证**: 新增 JSR-303 验证注解
|
||
|
||
### 开发流程影响
|
||
|
||
1. **开发流程**: 需要按照 SSOT 方法论进行开发，包括需求定义、方案决策、提示词资产化、执行会话、变更记录、闭环复盘
|
||
2. **代码规范**: 需要遵循项目编码规范，使用 Lombok 注解、JSR-303 验证注解、Swagger/OpenAPI 注解等
|
||
3. **测试要求**: 需要编写单元测试和集成测试，确保测试覆盖率 ≥ 90%
|
||
|
||
### 运维管理影响
|
||
|
||
1. **监控要求**: 需要监控 API 接口的性能和错误率
|
||
2. **日志要求**: 需要记录详细的日志，便于问题排查
|
||
3. **文档要求**: 需要维护 API 文档，确保文档的准确性和及时性
|
||
|
||
## 风险
|
||
|
||
### 技术风险
|
||
|
||
1. **API 设计风险**: API 接口设计可能不够完善
|
||
- **缓解措施**: 提前进行 API 设计评审，参考业界最佳实践
|
||
2. **参数验证风险**: 参数验证可能不够严格
|
||
- **缓解措施**: 使用 JSR-303 验证注解，提供详细的错误信息
|
||
3. **响应封装风险**: 响应封装可能不够统一
|
||
- **缓解措施**: 定义统一的响应格式，使用统一的响应封装逻辑
|
||
4. **并发风险**: 并发上传下载可能导致资源竞争
|
||
- **缓解措施**: 使用线程池，限制并发数，监控并发性能
|
||
|
||
### 业务风险
|
||
|
||
1. **兼容性风险**: 前端可能不兼容新的 API 接口
|
||
- **缓解措施**: 提供详细的 API 文档，提供前端集成指南
|
||
2. **性能风险**: API 接口性能可能不达标
|
||
- **缓解措施**: 提前进行性能测试，优化代码性能
|
||
|
||
### 实施风险
|
||
|
||
1. **开发风险**: 开发过程中可能遇到技术难题
|
||
- **缓解措施**: 提前进行技术调研，参考官方文档和示例代码
|
||
2. **测试风险**: 测试过程中可能发现性能问题
|
||
- **缓解措施**: 提前进行性能测试，优化代码性能
|
||
|
||
## 回滚策略
|
||
|
||
### 回滚条件
|
||
|
||
1. **功能不满足需求**: 如果实现的功能不满足需求，可以进行回滚
|
||
2. **性能不达标**: 如果性能不达标，可以进行回滚或优化
|
||
3. **严重Bug**: 如果发现严重Bug，可以进行回滚或修复
|
||
|
||
### 回滚步骤
|
||
|
||
1. **代码回滚**: 使用 Git 回滚代码到上一个稳定版本
|
||
2. **配置回滚**: 如果有配置变更，需要回滚配置
|
||
3. **通知用户**: 通知用户回滚的原因和影响
|
||
|
||
### 回滚后调整
|
||
|
||
1. **问题分析**: 分析回滚的原因，找出问题所在
|
||
2. **方案优化**: 优化方案，解决存在的问题
|
||
3. **重新实施**: 重新实施优化后的方案
|
||
|
||
## 验收标准
|
||
|
||
### 功能验收标准
|
||
|
||
1. **上传功能**: 能够成功上传本地文件到 Salesforce Attachment、ContentDocument、Document 对象
|
||
2. **下载功能**: 能够成功从 Salesforce Attachment、ContentDocument、Document 对象下载文件到本地
|
||
3. **参数验证**: 能够正确验证参数，提供详细的错误信息
|
||
4. **异常处理**: 能够正确处理异常，提供详细的错误信息
|
||
5. **日志记录**: 能够记录详细的日志，便于问题排查
|
||
6. **API 文档**: 能够生成清晰的 API 文档，便于前端调用和集成
|
||
|
||
### 性能验收标准
|
||
|
||
1. **上传性能**: 文件上传性能良好，不影响系统响应
|
||
2. **下载性能**: 文件下载性能良好，不影响系统响应
|
||
3. **并发性能**: 并发上传下载性能良好，不出现资源竞争
|
||
|
||
### 代码质量验收标准
|
||
|
||
1. **代码规范**: 代码符合项目编码规范，有清晰的注释
|
||
2. **设计模式**: 使用策略模式封装三种文件对象的上传下载逻辑
|
||
3. **单一职责**: 遵循单一职责原则和开闭原则
|
||
4. **测试覆盖**: 测试覆盖率 ≥ 90%
|
||
|
||
### API 文档验收标准
|
||
|
||
1. **文档完整性**: API 文档包含所有接口的详细信息
|
||
2. **文档准确性**: API 文档与实际接口一致
|
||
3. **文档可读性**: API 文档清晰易懂，便于前端调用和集成
|
||
|
||
## 视觉锚点
|
||
|
||
### Visual Reference
|
||
|
||
引用 Canvas 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 项目架构视觉化展示
|
||
- **具体节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
|
||
- **具体节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [ ] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源。
|
||
|
||
- [REQ-011.md](../requirements/REQ-011.md) - Salesforce文件上传下载功能
|
||
- [REQ-011-1.md](../requirements/REQ-011-1.md) - 基础设施和枚举定义
|
||
- [REQ-011-2.md](../requirements/REQ-011-2.md) - Attachment 文件上传下载功能
|
||
- [REQ-011-3.md](../requirements/REQ-011-3.md) - ContentDocument/ContentVersion 文件上传下载功能
|
||
- [REQ-011-4.md](../requirements/REQ-011-4.md) - Document 文件上传下载功能
|
||
- [REQ-011-5.md](../requirements/REQ-011-5.md) - 文件上传下载 Controller 和 API 接口
|
||
- [0028-attachment-upload-download.md](0028-attachment-upload-download.md) - Attachment 文件上传下载架构决策
|
||
- [0029-contentversion-upload-download.md](0029-contentversion-upload-download.md) - ContentVersion 文件上传下载架构决策
|
||
- [0030-document-upload-download.md](0030-document-upload-download.md) - Document 文件上传下载架构决策
|
||
- [Spring Boot REST API 文档](https://spring.io/guides/gs/rest-service/) - Spring Boot REST API 官方文档
|
||
- [Spring Boot Validation 文档](https://spring.io/guides/gs/validating-form-input/) - Spring Boot Validation 官方文档
|
||
- [SpringDoc OpenAPI 文档](https://springdoc.org/) - SpringDoc OpenAPI 官方文档
|