59 lines
3.6 KiB
Markdown
59 lines
3.6 KiB
Markdown
# 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 流程，产出了需求、设计、决策、提示词、代码、变更日志等全套文档。
|
||
|
||
## 成功经验
|
||
1. **模式复用**：直接复用了 `datai-salesforce-auth` 和 `datai-salesforce-apex` 中的 `AbstractConnectionFactory` 模式，大大减少了设计和开发时间，同时保证了代码风格的一致性。
|
||
2. **精准的 Prompt 设计**：在 Phase 5 生成的 Prompt 中，明确指出了 Metadata API URL 的特殊性（需要将 Partner URL 的 /u/ 替换为 /m/），避免了连接失败的常见坑。
|
||
3. **基础设施复用**：有效利用了现有的 `SessionManager` 和 `datai-salesforce-common` 中的异常类，避免了重复造轮子。
|
||
|
||
## 改进点
|
||
1. **测试覆盖率**：目前的测试主要依赖手动调用 REST API，虽然功能验证通过，但缺乏自动化的单元测试覆盖，特别是针对 URL 转换等边界情况。
|
||
2. **错误处理粒度**：目前的错误处理主要依赖通用的 `SalesforceAuthException` 和 `SalesforceOperationException`，对于 Metadata API 特有的错误（如 INVALID_SESSION_ID）可以进一步细化。
|
||
|
||
## 问题分析
|
||
1. **问题 1**：Metadata API 连接初始化需要 SessionHeader。
|
||
- **根因**：Metadata API 与 Partner API 不同，除了 Session ID 外，必须显式设置 SessionHeader 才能进行某些操作。
|
||
- **解决方案**：在 Factory 中创建 Connection 后，立即设置 SessionHeader。
|
||
|
||
## 行动计划
|
||
1. **针对改进点 1**：在后续迭代中补充 `MetadataConnectionFactory` 的单元测试，特别是针对 URL 转换逻辑。
|
||
2. **针对改进点 2**：在后续开发 Metadata 具体操作（如 Deploy/Retrieve）时，根据实际返回的错误码，细化异常处理逻辑。
|
||
|
||
## 提取模式
|
||
### 有效的 Prompt 技巧
|
||
1. **显式指出 URL 规则**：对于 Salesforce API，不同协议（Partner, Metadata, Tooling）的 Endpoint URL 规则不同，在 Prompt 中显式指出转换规则（如 /u/ -> /m/）非常有效。
|
||
2. **指定基类和接口**：明确要求继承 `AbstractConnectionFactory` 和实现特定接口，确保了代码结构的一致性。
|
||
|
||
### 避免的坑
|
||
1. **忽略 SessionHeader**：在 Metadata API 中，SessionHeader 是必须的，不能只依赖 ConnectorConfig 中的 Session ID。
|
||
|
||
## 模板迭代
|
||
当前模板适用，无需迭代。
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/2026-01-28-003-MetadataAPI源org实现.md)
|
||
- [设计文档](../design/2026-02-02-003-01-连接管理-设计.md)
|