---
name: api-integration-pipeline
type: pipeline_procedure
when: '第三方接口对接, 外部服务集成, API集成, 接口联调, 服务对接, 第三方API'
scope:
  - backend
  - frontend
products:
  - '*'
id: ka-procedure-接口集成流水线
asset_kind: pipeline_procedure
lifecycle_status: active
authority: supporting
owner_mechanism_id: mc-artifact-contract
routes:
  - code_change
primary_triggers:
  - 接口集成流水线
secondary_triggers: []
negative_triggers: []
priority: P1
specificity: 5
consumes:
  - mc-artifact-contract
emits:
  - api_integration_plan
  - adapter_implementation
  - integration_test_result
required_evidence:
  - execution_evidence
version: 1.1.0
last_reviewed: '2026-06-01'
stages: ["编码与单元测试", "联调验证"]
---

# 接口对接管线

### 第1步：契约分析
梳理第三方 API 能力清单（认证方式、请求/响应格式、错误码、限流配额、沙箱环境）。识别核心交互场景和数据映射关系。
模版：接口对接方案模版.md
产出保存到：.soloforge/output/01-接口对接方案.md
工具：sf_classify

### 第2步：适配层实现
实现统一的 API 客户端封装（超时、重试、熔断、日志）。定义请求/响应 DTO 映射。配置 Mock 方案（沙箱/本地 Mock）支持独立开发。错误码映射为业务异常。
工具：sf_expand, sf_scaffold

### 第3步：联调测试
使用 Mock 环境验证基本流程。切换到沙箱环境验证真实交互。覆盖：正常流程、网络超时、服务端错误、限流响应、数据格式异常。
模版：测试计划模版.md
工具：sf_verify

### 第4步：验收上线
代码审查重点：超时配置、错误处理、敏感信息、日志脱敏。生产配置确认（URL、密钥、限流参数）。监控告警配置（调用成功率、响应时间）。
工具：sf_review, sf_verify, sf_deliver

### 第5步：契约管理与监控增强
定义接口契约（OpenAPI/Swagger），明确请求/响应格式、错误码、版本号。编写接口 Mock 服务，前后端并行开发。接口变更必须更新文档并通知消费方，给予充足迁移时间。集成测试覆盖正常流 + 异常流（超时、错误响应、边界值）。接口上线后配置监控告警（响应时间 P99、错误率、调用量）。

## 检查点
- [ ] 第三方 API 能力清单已梳理
- [ ] 适配层超时/重试/熔断已配置
- [ ] 沙箱联调通过
- [ ] 接口文档与实现一致
- [ ] Mock 服务可用
- [ ] 集成测试覆盖异常场景
- [ ] 接口监控告警已配置

## 注意事项
- 第三方接口必须有降级方案（Mock/缓存/默认值），避免外部故障拖垮主流程
- 外部接口调用必须设置超时（连接超时 + 读超时），禁止无限等待
- 接口重试必须有退避策略和最大重试次数限制
- 敏感数据传输必须加密（HTTPS + 敏感字段加密）
