用途:通过专用适配器集成外部服务,集中强制超时、重试策略、适用场景下的幂等、错误映射到共享分类体系,以及与仓库标准一致的日志/指标/追踪。目标是防止“HTTP 调用散落各处”。
输入:外部 API/服务名称与基础 URL(或 SDK);所需操作列表;认证机制(token、key、oauth,不含密钥);预期失败情况(超时、限流、无效响应);仓库配置(推荐 <repo>/REPO_PROFILE.json)。
输出:窄接口的适配器模块;重试/超时配置;错误映射到共享分类;契约测试或 mock(推荐);最小可观测性埋点。
工作流:创建适配器边界(ExternalServiceClient 或模块函数);实现调用时使用显式超时、安全场景下的有界重试(含退避)、需要且支持时使用幂等键;将外部错误归一化映射到内部分类;添加契约测试/mock,验证请求构造、响应解析与错误处理;添加基础可观测性,如存在则传播关联 ID;按配置运行验证。
检查:该集成的外部调用只存在于适配器中;超时显式;重试策略有界且安全(无无限循环);若引入重试、退避、限流或多步外部工作流,建议用 system/state-machine-mapper 显式建模外部交互状态;错误映射到内部分类;测试覆盖成功、超时或重试场景、错误响应解析。
失败模式:重试安全性不明确时默认不重试并记录原因;遇到限流时增加退避并尽量遵守响应头;外部契约不稳定时增加 mock/契约测试并收紧解析;新增重试/退避逻辑但未显式状态建模时,要求先使用 system/state-machine-mapper 再发布。
非目标:不实现领域规则(用 backend/domain-logic-module);不构建编排/任务(用 backend/job-worker-orchestration);不在代码中存储密钥。
遥测日志包含:skill: backend/integration-adapter、service: <name>、retries: none | bounded、timeout。