3.6 KiB
3.6 KiB
Metadata API 源 Org 实现复盘
元数据
- 需求编号：003
- 创建时间：2026-02-03
- 创建人：AI Assistant
- 状态：已完成
复盘概述
本次复盘对 Metadata API 源 Org 实现的开发过程进行了全面回顾。该需求旨在实现 Metadata 连接管理功能，作为 Metadata API 的基础设施，为后续的元数据操作（如 Retrieve, Deploy）提供连接支持。
目标与实际产出对比
目标
- 实现 MetadataConnectionFactory，支持 Partner URL 自动转换为 Metadata URL。
- 集成 SessionManager，复用现有认证机制。
- 提供 REST API 接口，管理连接生命周期（状态、测试、刷新、关闭）。
- 记录连接日志，追踪连接状态。
- 遵循 SSOT 流程，确保文档和代码的一致性。
实际产出
- 成功实现 MetadataConnectionFactory，使用 AbstractConnectionFactory 模式，支持 URL 自动转换（/u/ -> /m/）。
- 成功集成 SessionManager，无需重复登录。
- 提供了 4 个 REST API 接口（/status, /test, /refresh, /close），通过 Postman 测试验证通过。
- 实现了数据库日志记录，连接状态可追溯。
- 全程遵循 SSOT 流程，产出了需求、设计、决策、提示词、代码、变更日志等全套文档。
成功经验
- 模式复用：直接复用了
datai-salesforce-auth和datai-salesforce-apex中的AbstractConnectionFactory模式，大大减少了设计和开发时间，同时保证了代码风格的一致性。 - 精准的 Prompt 设计：在 Phase 5 生成的 Prompt 中，明确指出了 Metadata API URL 的特殊性（需要将 Partner URL 的 /u/ 替换为 /m/），避免了连接失败的常见坑。
- 基础设施复用：有效利用了现有的
SessionManager和datai-salesforce-common中的异常类，避免了重复造轮子。
改进点
- 测试覆盖率：目前的测试主要依赖手动调用 REST API，虽然功能验证通过，但缺乏自动化的单元测试覆盖，特别是针对 URL 转换等边界情况。
- 错误处理粒度：目前的错误处理主要依赖通用的
SalesforceAuthException和SalesforceOperationException，对于 Metadata API 特有的错误（如 INVALID_SESSION_ID）可以进一步细化。
问题分析
- 问题 1：Metadata API 连接初始化需要 SessionHeader。
- 根因：Metadata API 与 Partner API 不同，除了 Session ID 外，必须显式设置 SessionHeader 才能进行某些操作。
- 解决方案：在 Factory 中创建 Connection 后，立即设置 SessionHeader。
行动计划
- 针对改进点 1：在后续迭代中补充
MetadataConnectionFactory的单元测试，特别是针对 URL 转换逻辑。 - 针对改进点 2：在后续开发 Metadata 具体操作（如 Deploy/Retrieve）时，根据实际返回的错误码，细化异常处理逻辑。
提取模式
有效的 Prompt 技巧
- 显式指出 URL 规则：对于 Salesforce API，不同协议（Partner, Metadata, Tooling）的 Endpoint URL 规则不同，在 Prompt 中显式指出转换规则（如 /u/ -> /m/）非常有效。
- 指定基类和接口：明确要求继承
AbstractConnectionFactory和实现特定接口，确保了代码结构的一致性。
避免的坑
- 忽略 SessionHeader：在 Metadata API 中，SessionHeader 是必须的，不能只依赖 ConnectorConfig 中的 Session ID。
模板迭代
当前模板适用，无需迭代。