third-party-integration

第三方集成

目录

• 概述
• 适用场景
• 快速开始
• 参考指南
• 最佳实践

概述

使用标准化模式处理 API 调用、错误处理、身份验证和数据转换，构建稳健的外部服务集成。

适用场景

• 集成支付处理服务（Stripe、PayPal）
• 使用消息服务（SendGrid、Twilio）
• 连接分析平台（Mixpanel、Segment）
• 与存储服务同步（AWS S3、Google Cloud）
• 集成 CRM 系统（Salesforce、HubSpot）
• 构建多服务架构

快速开始

最简可运行示例：

const axios = require("axios");

class ThirdPartyClient {
  constructor(config) {
    this.apiKey = config.apiKey;
    this.baseUrl = config.baseUrl;
    this.timeout = config.timeout || 30000;
    this.retryAttempts = config.retryAttempts || 3;
    this.retryDelay = config.retryDelay || 1000;
    this.client = axios.create({
      baseURL: this.baseUrl,
      timeout: this.timeout,
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
        "Content-Type": "application/json",
      },
    });
  }

  async request(method, endpoint, data = null, options = {}) {
    let lastError;

    for (let attempt = 0; attempt < this.retryAttempts; attempt++) {
      try {
        const response = await this.client({
// ... (see reference guides for full implementation)

参考指南

references/ 目录中的详细实现：

指南	内容
第三方客户端封装	第三方客户端封装
支付处理服务集成（Stripe）	支付处理服务集成（Stripe）
电子邮件服务集成（SendGrid）	电子邮件服务集成（SendGrid）
Python 第三方集成	Python 第三方集成
数据转换	数据转换

最佳实践

✅ 应做

• 使用指数退避实现重试逻辑
• 验证 Webhook 签名
• 记录所有 API 交互
• 使用环境变量存储密钥
• 将 API 响应转换为内部模型
• 为关键服务实现熔断器
• 监控 API 配额和速率限制
• 添加适当的错误处理
• 合理设置超时时间
• 使用沙盒/测试 API 密钥进行测试

❌ 不要做

• 将 API 密钥硬编码
• 无限重试所有错误
• 记录敏感数据
• 信任未经验证的 Webhook 数据
• 忽略速率限制
• 发起同步阻塞调用
• 向客户端暴露特定供应商的细节
• 跳过错误处理
• 在测试中使用生产密钥