kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/docs/archive/decisions/adr/0031-file-controller-api.md

11 KiB
Raw Permalink Blame History

架构决策记录：文件上传下载 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 的具体节点或快照：

Status

  • Draft
  • Accepted
  • Superceded

参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源。