3.5 KiB
3.5 KiB
ADR-003-06: 检索操作技术选型
状态
已接受
日期
2026-02-03
背景
Salesforce 元数据检索 (Retrieve) 操作是一个异步过程，最终会生成一个包含元数据的 ZIP 文件。该文件可能非常大（几十 MB 甚至更大）。 在实现该功能时，我们需要解决以下关键问题：
- 如何处理和传输生成的 ZIP 文件？
- 如何持久化操作记录以满足审计需求？
- 如何与现有的异步轮询策略保持一致？
决策
1. ZIP 文件处理：不持久化到数据库
我们决定 不将检索到的 ZIP 文件内容存储在数据库中，而是直接在 API 响应中返回给客户端（Base64 编码或二进制流）。
理由：
- 数据库性能：ZIP 文件属于二进制大对象 (BLOB)，存入关系型数据库会导致表空间迅速膨胀，影响备份、恢复和查询性能。
- 使用场景：检索操作通常是即时性的（用于 IDE 下载或 CI/CD 流程），不需要在数据库中长期归档 ZIP 文件。
- 系统简化：避免了引入额外的对象存储（如 S3）或文件系统管理的复杂度。
2. 状态管理：专用历史表
创建 datai_metadata_retrieve 表来专门记录检索操作的生命周期（Async ID, Status, Timestamp, User）。
理由：
- 审计追踪：必须记录谁在什么时候检索了什么（通过 Request 参数记录）。
- 状态同步：异步操作需要一个地方存储中间状态，以便轮询时更新。
3. 架构模式：复用通用异步策略
遵循 ADR-003-04 的决策，Service 层提供阻塞式轮询方法 pollRetrieveResult，Controller 层提供对应的 REST 接口。
理由：
- 一致性：保持与部署、删除等其他异步操作一致的交互体验。
- 简化客户端：客户端可以选择长轮询等待结果，无需编写复杂的定时器逻辑。
后果
正面影响
- 轻量级数据库：避免了数据库成为存储瓶颈。
- 高性能：文件流直接传输，减少了内存复制和 IO 开销。
- 可追溯：完整的操作历史记录满足了审计需求。
负面影响
- 结果易失性：由于 ZIP 文件不持久化，如果客户端在接收响应时网络中断，必须重新发起检索请求（无法从历史记录中“重新下载”）。
- 内存压力：在并发检索大文件时，JVM 内存压力较大（需要将 ZIP 加载到内存中返回），需要注意堆内存配置。
替代方案
方案 2：ZIP 文件存入数据库
- 描述：在
datai_metadata_retrieve表中增加zip_contentBLOB 字段。 - 优点：数据完整性高，随时可以重新下载。
- 缺点：严重影响数据库性能，维护成本极高。
方案 3：ZIP 文件存入文件系统/对象存储
- 描述：将 ZIP 保存到服务器磁盘或 S3，数据库只存路径。
- 优点：支持重新下载，不影响数据库性能。
- 缺点：引入了新的基础设施依赖（文件系统/S3），需要设计文件清理策略（定期删除旧文件），增加了实现复杂度。当前需求暂不需要此功能。