3.8 KiB
3.8 KiB
ADR-003-08: 描述和列出元数据技术选型
状态
已接受
日期
2026-02-03
背景
描述 (DescribeMetadata) 和列出 (ListMetadata) 元数据是 Salesforce Metadata API 的基础功能。 DescribeMetadata 用于获取 Org 支持的元数据类型（如 CustomObject, ApexClass）。 ListMetadata 用于获取指定类型的具体成员列表（如 Account, MyClass）。
我们需要解决以下关键技术问题：
- API 交互方式：如何调用 Salesforce Metadata API？
- API 限制处理：Metadata API 的
listMetadata接口限制每次调用最多包含 3 个查询请求 (ListMetadataQuery)。如果客户端传入更多，如何处理？ - 审计策略：如何记录查询历史以满足审计需求？
决策
1. API 交互方式
选择 直接调用 WSC (Web Service Connector) 方案。
使用 metadata.jar 中的 MetadataConnection.describeMetadata() 和 MetadataConnection.listMetadata() 方法。
理由：
- 类型安全：直接使用生成的 Java 类，避免手动解析 XML/JSON。
- 一致性：与项目其他 Metadata API 模块（如部署、检索）保持一致。
2. ListMetadata 批处理策略
选择 服务层自动分批 (Service Layer Batching) 方案。
Service 层接收 List<ListMetadataQuery>，如果列表长度超过 3，则自动将其拆分为多个子列表（每组 3 个），依次调用 API，最后合并结果返回。
理由：
- 用户体验 (UX)：客户端无需关注 API 的底层限制，可以一次性请求任意数量的元数据类型。
- 健壮性：防止因超出 API 限制导致的运行时异常。
3. 审计记录策略
选择 同步数据库审计 (Synchronous Database Audit) 方案。
在 Service 层调用 API 后，立即将查询信息（操作类型、元数据类型、结果数量、耗时等）写入 datai_metadata_describe 表。
理由：
- 数据完整性：确保每一次 API 调用都有据可查。
- 粒度控制：对于
listMetadata的批量请求，将为原始请求中的每个ListMetadataQuery记录一条审计日志（或根据分批情况记录），确保审计粒度清晰。根据设计文档，决定为每个查询类型记录一条日志。
后果
正面影响
- 易用性：客户端调用简单，无需处理复杂的 API 限制。
- 可维护性：基于标准 WSC 实现，易于升级和维护。
- 可追溯性：完整的审计记录支持后续的使用分析和安全审计。
负面影响
- 性能开销：自动分批会导致串行调用多次 API，增加总耗时（但在 Metadata API 场景下，网络延迟通常远大于处理时间，可接受）。
- 数据库增长：高频查询可能导致审计表数据量快速增长，需要定期清理策略（未来考虑）。
替代方案
方案 2：ListMetadata 透传模式 (Pass-through)
- 描述：Service 层不做分批，直接透传请求给 API。如果超过 3 个，API 抛出异常。
- 优点：实现简单，逻辑透明。
- 缺点：客户端需要处理分批逻辑，增加了客户端复杂度。
- 结论：放弃，为了提供更好的平台服务能力，应在服务端解决限制问题。
方案 3：异步审计 (Async Audit)
- 描述：使用
@Async或消息队列记录审计日志。 - 优点：不阻塞主线程，响应更快。
- 缺点：引入了复杂性，且在服务器崩溃时可能丢失日志。
- 结论：放弃，Metadata 操作本身耗时较长（数百毫秒到秒级），同步写库（毫秒级）的开销可以忽略不计。