Skip to content

third-party-integration.md

Latest commit

 

History

History
205 lines (168 loc) · 6.32 KB

third-party-integration.md

File metadata and controls

205 lines (168 loc) · 6.32 KB
Raw

第三方服务集成规范

目的

规范与外部 API/服务的集成方式，确保集成可靠、可维护、可降级，避免第三方服务故障拖垮自己的系统，同时管理好密钥和成本。

适用时机

  • 集成新的第三方 API/服务时（支付、邮件、短信、地图、AI 等）
  • 第三方服务变更 API 版本时
  • 第三方服务出现故障/降级时
  • 评估是否替换现有第三方服务时
  • 管理 API 密钥和配额时

流程步骤

第一部分：集成前评估

评估维度：

维度 关注点
功能匹配 是否满足需求？覆盖度多少？
可靠性 SLA 承诺？历史故障记录？
性能 延迟？吞吐量？限流策略？
成本 免费额度？计费方式？预估月费？
安全 数据传输加密？合规认证？
文档质量 文档是否清晰完整？有无 SDK？
锁定风险 迁移成本？数据可导出？
替代方案 有无备选？自研可行性？

评估结论模板：

## 第三方服务评估：[服务名]

- 用途：[解决什么问题]
- 候选方案：[列出 2-3 个]
- 选定方案：[最终选择]
- 选择理由：[为什么选这个]
- 风险评估：[主要风险及应对]
- 成本预估：[月/年费用]
- 退出策略：[如何迁移/替换]

第二部分：集成架构原则

核心原则：

  1. 隔离：第三方调用封装在独立模块/适配层
  2. 降级：第三方不可用时系统核心功能仍可用
  3. 超时：所有外部调用必须设置超时
  4. 重试：幂等操作可重试，非幂等需谨慎
  5. 熔断：连续失败时快速失败，不拖垮系统

适配层模式：

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  业务逻辑    │ ──→ │  适配层/网关   │ ──→ │  第三方 API  │
│  (不直接调用) │     │  (封装+降级)   │     │  (外部服务)  │
└─────────────┘     └──────────────┘     └─────────────┘

适配层职责：

  • 统一请求/响应格式转换
  • 错误处理和重试逻辑
  • 超时和熔断控制
  • 日志记录
  • 降级/兜底逻辑
  • API 版本兼容

第三部分：密钥与配置管理

密钥管理规则：

  • 永远不要硬编码 API Key
  • 使用环境变量或密钥管理服务
  • 不同环境使用不同密钥
  • 密钥定期轮换
  • 最小权限原则（只申请需要的 scope）
  • 密钥泄露立即轮换

配置结构：

# .env（不提交到版本控制）
PAYMENT_API_KEY=sk_live_xxx
PAYMENT_API_SECRET=xxx
PAYMENT_WEBHOOK_SECRET=whsec_xxx
PAYMENT_TIMEOUT_MS=5000
PAYMENT_RETRY_COUNT=3

第四部分：错误处理与降级

错误分类：

类型 示例 处理方式
暂时性错误 超时、429、503 重试（指数退避）
永久性错误 400、401、404 记录日志、返回友好错误
服务不可用 连接失败、DNS 错误 熔断 + 降级
数据错误 响应格式变化 告警 + 兜底

降级策略：

  • 缓存兜底：返回上次成功的缓存数据
  • 功能降级：关闭依赖第三方的非核心功能
  • 队列缓冲：请求入队，服务恢复后重试
  • 静态兜底：返回默认/静态内容
  • 用户提示：友好告知用户稍后重试

重试策略：

重试次数：最多 3 次
退避策略：指数退避 + 随机抖动
  第 1 次：1s + random(0-500ms)
  第 2 次：2s + random(0-500ms)
  第 3 次：4s + random(0-500ms)
幂等性：仅对 GET 或幂等操作重试

第五部分：Webhook 处理

Webhook 安全：

  • 验证签名（HMAC）
  • 验证来源 IP（如果提供）
  • 使用 HTTPS 端点
  • 幂等处理（同一事件可能重复发送）

Webhook 处理流程：

1. 验证签名
2. 快速返回 200（不阻塞）
3. 异步处理业务逻辑
4. 记录原始 payload（用于排查）
5. 处理失败时重试/告警

第六部分：监控与成本管理

监控指标：

  • 调用成功率（目标 > 99%）
  • 平均响应时间
  • 错误率及错误类型分布
  • 配额使用率
  • 费用趋势

成本管理：

  • 设置用量告警（达到预算 80% 时通知）
  • 了解计费模型（按次/按量/包月）
  • 缓存减少不必要调用
  • 批量操作减少请求次数
  • 定期审查是否有更优方案

第七部分：版本迁移与退出

API 版本升级：

  1. 关注第三方变更通知/Changelog
  2. 在适配层做版本兼容
  3. 新版本先在测试环境验证
  4. 灰度切换（如果支持）
  5. 确认稳定后移除旧版本代码

退出/替换策略：

  • 适配层设计时考虑可替换性
  • 数据定期导出备份
  • 了解数据迁移方案
  • 保持对替代方案的了解

检查清单

  • 集成前有评估记录
  • 第三方调用封装在适配层
  • 所有外部调用有超时设置
  • 实现了重试和熔断机制
  • 有降级/兜底方案
  • API 密钥通过环境变量管理
  • 密钥未提交到版本控制
  • Webhook 有签名验证
  • 有调用监控和告警
  • 了解费用和配额限制
  • 有退出/替换策略

输出物

输出物 格式 存放位置
服务评估文档 Markdown docs/integrations/eval-xxx.md
适配层代码 源代码 src/adapters/ 或 src/services/
集成配置 环境变量 .env / 密钥管理
监控面板 仪表盘 监控平台

常见误区

误区 正确做法
业务代码直接调用第三方 API 通过适配层隔离
不设超时 所有外部调用必须有超时
第三方挂了自己也挂 设计降级方案
密钥写在代码里 环境变量 + 密钥管理
不验证 Webhook 签名 必须验证，防伪造
无限重试 有限重试 + 指数退避 + 熔断
不考虑替换可能 适配层设计保持可替换

相关文档