Integracja API - Cursor

Scenariusz

Twoja firma potrzebuje integracji z Stripe do płatności, SendGrid do e-maili i Twilio do powiadomień SMS. Poprzedni programista rozpoczął pracę, ale zostawił niekompletny kod bez dokumentacji. Musisz zbudować zunifikowany system powiadomień, który obsługuje płatności, wysyła rachunki e-mailem i powiadamia użytkowników SMS-em - wszystko z odpowiednią obsługą błędów i logiką ponownych prób.

Cele nauczania

Po ukończeniu tej lekcji opanujesz:

Efektywną analizę i integrację zewnętrznych API
Budowanie solidnej obsługi błędów i mechanizmów ponownych prób
Tworzenie zunifikowanych interfejsów dla wielu usług
Implementację odpowiedniej autoryzacji i bezpieczeństwa
Testowanie integracji zewnętrznych API
Monitorowanie i debugowanie problemów API

Wymagania wstępne

Podstawowe zrozumienie REST API
Znajomość Node.js i TypeScript
Ukończone poprzednie lekcje lub równoważne doświadczenie
Klucze API do usług (lub użycie mock API)
Opcjonalnie: serwery MCP dla GitHub, Linear lub Jira (zobacz konfigurację MCP)

Wyzwanie

Zbuduj gotową do produkcji integrację, która:

Obsługuje wielu dostawców API z gracją
Implementuje exponential backoff dla ponownych prób
Zapewnia mechanizmy fallback
Utrzymuje najlepsze praktyki bezpieczeństwa
Zawiera kompleksowe logowanie
Wspiera zarówno operacje sync jak i async

Przewodnik implementacji

Faza 1: Analiza API i planowanie

Analiza istniejącego kodu

Zacznij z trybem Ask, aby zrozumieć co istnieje:

@src/integrations
"Przeanalizuj istniejący kod integracji:
- Które API są częściowo zaimplementowane?
- Jaka jest obecna architektura?
- Jaka obsługa błędów istnieje?
- Czego brakuje do użytku produkcyjnego?
- Luki bezpieczeństwa?"

Analiza dokumentacji API

"Pomóż mi zrozumieć te API:
- Stripe: Przepływ przetwarzania płatności
- SendGrid: Najlepsze praktyki API e-mail
- Twilio: Gwarancje dostarczenia SMS
Stwórz porównanie limitów, metod autoryzacji i kodów błędów"

Projektowanie zunifikowanej architektury

Przełącz na tryb Agent:

"Zaprojektuj architekturę zunifikowanego systemu powiadomień:
- Abstrakcyjny interfejs dla wszystkich powiadomień
- Implementacje specyficzne dla dostawców
- Strategie ponownych prób i fallback
- Zarządzanie konfiguracją
- Wzorce obsługi błędów
Stwórz diagram architektury i interfejsy"

Faza 1.5: Wykorzystanie serwerów MCP do integracji API

Dostępne serwery MCP API

Wiele API ma już dostępne serwery MCP:

# GitHub MCP - Pełny dostęp do GitHub API
claude mcp add --transport sse github https://api.githubcopilot.com/mcp/

# Linear MCP - Śledzenie zadań
claude mcp add --transport sse linear https://mcp.linear.app/sse

# Jira MCP - Integracja Atlassian
# Uwaga: Oficjalny endpoint Atlassian to https://mcp.atlassian.com/v1/sse (Beta)
# Do konfiguracji lokalnej użyj pakietów społeczności:
claude mcp add jira -- npx -y @mcp-devtools/jira

# Slack MCP - Integracja wiadomości
claude mcp add slack -- npx -y @modelcontextprotocol/server-slack

Używanie MCP do odkrywania API

Z zainstalowanym GitHub MCP:

"Używając GitHub MCP, pokaż mi:
- Jak tworzyć zadania programowo
- Konfigurację webhook dla zdarzeń PR
- Obsługę limitów żądań
- Przykłady zapytań GraphQL"

// MCP zapewnia bezpośredni dostęp do API:
"Utwórz zadanie GitHub w repozytorium 'myorg/myrepo' z:
- Tytułem: 'Integracja płatności nie działa'
- Etykietami: ['bug', 'high-priority']
- Przypisanym: '@username'"

MCP vs bezpośrednia integracja API

Z serwerem MCP
Bez MCP

// Bezpośrednie użycie narzędzi przez MCP
"Używając Linear MCP:
- Utwórz zadanie w projekcie 'Integracja API'
- Ustaw priorytet na pilny
- Dodaj do obecnego sprintu"

// MCP obsługuje:
// - Autoryzację
// - Limity żądań
// - Ponowne próby błędów
// - Parsowanie odpowiedzi

// Potrzebna ręczna implementacja
const linear = new LinearClient({
  apiKey: process.env.LINEAR_API_KEY
});

// Musisz zaimplementować:
// - Obsługę błędów
// - Logikę ponownych prób
// - Limity żądań
// - Definicje typów

Orkiestracja wielu MCP

"Koordynuj pomiędzy wieloma serwerami MCP:
1. Gdy płatność Stripe się powiedzie (używając naszej integracji)
2. Utwórz zadanie Linear do realizacji (Linear MCP)
3. Wyślij na kanał #sales w Slack (Slack MCP)
4. Zaktualizuj rekord klienta w bazie danych"

// AI może używać wielu MCP sekwencyjnie

MCP dla dokumentacji API

"Używając Context7 MCP, pobierz najnowszą dokumentację dla:
- Stripe Node.js SDK
- SendGrid API v3
- Webhook Twilio

Porównaj z naszą obecną implementacją"

Kiedy używać serwerów MCP vs własna integracja

Używaj serwerów MCP gdy:

Istnieje oficjalny serwer MCP dla API
Potrzebujesz szybkiego prototypowania
Standardowe operacje API wystarczają
Chcesz utrzymywane integracje

Buduj własne gdy:

Brak dostępnego serwera MCP
Potrzebujesz niestandardowej obsługi błędów
Wymagana złożona orkiestracja
Krytyczna optymalizacja wydajności

Faza 2: Budowanie warstwy integracji

Tworzenie bazowej klasy integracji

"Utwórz bazową klasę integracji z:
- Logiką ponownych prób z exponential backoff
- Wzorcem circuit breaker
- Logowaniem żądań/odpowiedzi
- Standaryzacją błędów
- Zbieraniem metryk
- Obsługą limitów żądań"

Przykład klasy bazowej:

export abstract class BaseIntegration {
  protected abstract readonly name: string;
  protected abstract readonly baseURL: string;
  protected abstract readonly maxRetries: number;

  private circuitBreaker: CircuitBreaker;
  private metrics: MetricsCollector;

  constructor(protected config: IntegrationConfig) {
    this.circuitBreaker = new CircuitBreaker({
      timeout: config.timeout || 30000,
      errorThreshold: config.errorThreshold || 50,
      resetTimeout: config.resetTimeout || 60000
    });

    this.metrics = new MetricsCollector(this.name);
  }

  protected async makeRequest<T>(
    method: string,
    endpoint: string,
    data?: any,
    options: RequestOptions = {}
  ): Promise<T> {
    const url = `${this.baseURL}${endpoint}`;

    return this.circuitBreaker.execute(async () => {
      const startTime = Date.now();

      try {
        const response = await this.executeWithRetry(
          method,
          url,
          data,
          options
        );

        this.metrics.recordSuccess(Date.now() - startTime);
        return response;
      } catch (error) {
        this.metrics.recordError(error);
        throw this.standardizeError(error);
      }
    });
  }

  private async executeWithRetry<T>(
    method: string,
    url: string,
    data?: any,
    options: RequestOptions = {}
  ): Promise<T> {
    let lastError: Error;

    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
      try {
        if (attempt > 0) {
          await this.delay(this.calculateBackoff(attempt));
        }

        return await this.executeRequest<T>(method, url, data, options);
      } catch (error) {
        lastError = error;

        if (!this.isRetryable(error) || attempt === this.maxRetries) {
          throw error;
        }

        logger.warn(`Próba ponowienia ${attempt + 1} dla ${url}`, { error });
      }
    }

    throw lastError!;
  }

  private calculateBackoff(attempt: number): number {
    const baseDelay = 1000;
    const maxDelay = 32000;
    const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
    return delay + Math.random() * 1000; // Dodaj jitter
  }

  protected abstract isRetryable(error: any): boolean;
  protected abstract standardizeError(error: any): IntegrationError;
}

Implementacja klas specyficznych dla dostawców

@integrations/base.ts
"Utwórz implementacje dostawców dla:
1. StripeIntegration rozszerzającą BaseIntegration
2. SendGridIntegration rozszerzającą BaseIntegration
3. TwilioIntegration rozszerzającą BaseIntegration
Uwzględnij odpowiednią autoryzację, obsługę błędów i funkcje specyficzne dla API"

Tworzenie zunifikowanego serwisu powiadomień

"Utwórz NotificationService który:
- Orkiestruje wszystkie trzy serwisy
- Obsługuje przepływ płatność → e-mail → SMS
- Implementuje strategie fallback
- Zapewnia zachowanie transakcyjne
- Wspiera operacje zbiorowe"

Faza 3: Bezpieczeństwo i konfiguracja

Implementacja bezpiecznej konfiguracji

"Utwórz bezpieczne zarządzanie konfiguracją:
- Ładowanie konfiguracji opartej na środowisku
- Zaszyfrowane przechowywanie kluczy API
- Obsługa rotacji kluczy
- Walidacja konfiguracji
- Aktualizacje konfiguracji w czasie wykonania"

Przykład konfiguracji:

export class IntegrationConfig {
  private static instance: IntegrationConfig;
  private configs: Map<string, ProviderConfig> = new Map();

  private constructor() {
    this.loadConfigurations();
    this.validateConfigurations();
    this.setupKeyRotation();
  }

  static getInstance(): IntegrationConfig {
    if (!IntegrationConfig.instance) {
      IntegrationConfig.instance = new IntegrationConfig();
    }
    return IntegrationConfig.instance;
  }

  getConfig(provider: string): ProviderConfig {
    const config = this.configs.get(provider);
    if (!config) {
      throw new Error(`Konfiguracja nie znaleziona dla dostawcy: ${provider}`);
    }

    // Odszyfruj klucze API na żądanie
    return {
      ...config,
      apiKey: this.decryptKey(config.encryptedApiKey)
    };
  }

  private loadConfigurations() {
    // Ładowanie z zmiennych środowiskowych lub bezpiecznego magazynu
    this.configs.set('stripe', {
      encryptedApiKey: process.env.STRIPE_API_KEY_ENCRYPTED!,
      webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
      apiVersion: '2023-10-16',
      timeout: 30000,
      maxRetries: 3
    });

    // Podobnie dla SendGrid i Twilio
  }

  private decryptKey(encryptedKey: string): string {
    // Implementacja bezpiecznego odszyfrowywania
    return decrypt(encryptedKey, process.env.MASTER_KEY!);
  }
}

Dodawanie podpisywania żądań i walidacji

"Implementuj bezpieczeństwo żądań:
- Walidacja podpisu webhook
- Podpisywanie żądań dla API które tego wymagają
- Rotacja kluczy API bez przestojów
- Logika odświeżania tokenów OAuth
- Parsowanie nagłówków limitów żądań"

Tworzenie middleware bezpieczeństwa

"Utwórz middleware dla:
- Sanityzacji danych wejściowych
- Filtrowania danych wyjściowych (usuń wrażliwe dane)
- Śledzenia ID żądań
- Logowania audytowego
- Wykrywania zagrożeń"

Faza 4: Obsługa błędów i odporność

Implementacja kompleksowej obsługi błędów

"Utwórz system obsługi błędów:
- Kategoryzuj błędy (limit żądań, autoryzacja, sieć, itp.)
- Implementuj odpowiednie strategie ponownych prób na typ
- Utwórz mechanizmy fallback
- Kolejka martwych liter dla nieudanych żądań
- Procedury odzyskiwania błędów"

Przykład obsługi błędów:

export class IntegrationError extends Error {
  constructor(
    message: string,
    public code: string,
    public provider: string,
    public isRetryable: boolean,
    public originalError?: any,
    public context?: Record<string, any>
  ) {
    super(message);
    this.name = 'IntegrationError';
  }

  static fromStripeError(error: any): IntegrationError {
    const retryableCodes = ['rate_limit', 'api_connection_error'];

    return new IntegrationError(
      error.message || 'Błąd Stripe API',
      error.code || 'unknown_error',
      'stripe',
      retryableCodes.includes(error.code),
      error,
      {
        type: error.type,
        param: error.param,
        requestId: error.requestId
      }
    );
  }

  static fromSendGridError(error: any): IntegrationError {
    const isRetryable = error.code >= 500 || error.code === 429;

    return new IntegrationError(
      error.message || 'SendGrid API błąd',
      `sendgrid_${error.code}`,
      'sendgrid',
      isRetryable,
      error,
      {
        response: error.response?.body
      }
    );
  }
}

Budowanie implementacji circuit breaker

"Implementuj wzorzec circuit breaker:
- Śledź wskaźniki awarii per serwis
- Otwórz obwód przy przekroczeniu progu
- Stan półotwarty do testowania odzyskiwania
- Konfigurowalne progi
- Metryki i alertowanie"

Tworzenie strategii fallback

"Implementuj mechanizmy fallback:
- Drugorzędny dostawca e-mail jeśli SendGrid nie działa
- Kolejka SMS dla awarii Twilio
- Odpowiedzi cache dla operacji odczytu
- Strategie graceful degradation
- Preferencje powiadomień użytkowników"

Faza 5: Testowanie i monitorowanie

Tworzenie kompleksowego zestawu testów

@integrations
"Wygeneruj testy dla:
- Testy jednostkowe z mock API
- Testy integracji z sandbox API
- Testowanie scenariuszy błędów
- Symulacja limitów żądań
- Zachowanie circuit breaker
- Obsługa webhook"

Przykład struktury testów:

describe('StripeIntegration', () => {
  let stripe: StripeIntegration;
  let mockServer: MockServer;

  beforeAll(async () => {
    mockServer = await createMockStripeServer();
    stripe = new StripeIntegration({
      apiKey: 'test_key',
      baseURL: mockServer.url
    });
  });

  describe('Przetwarzanie płatności', () => {
    it('powinno obsłużyć udaną płatność', async () => {
      mockServer.onPost('/charges').reply(200, {
        id: 'ch_test123',
        status: 'succeeded'
      });

      const result = await stripe.createCharge({
        amount: 1000,
        currency: 'usd'
      });

      expect(result.status).toBe('succeeded');
    });

    it('powinno ponowić próbę przy błędach sieciowych', async () => {
      let attempts = 0;
      mockServer.onPost('/charges').reply(() => {
        attempts++;
        if (attempts < 3) {
          throw new NetworkError('Connection reset');
        }
        return [200, { status: 'succeeded' }];
      });

      const result = await stripe.createCharge({
        amount: 1000,
        currency: 'usd'
      });

      expect(attempts).toBe(3);
      expect(result.status).toBe('succeeded');
    });
  });
});

Implementacja monitorowania i alertowania

"Utwórz system monitorowania:
- Śledzenie czasu odpowiedzi API
- Wskaźniki sukcesu/porażki per endpoint
- Monitorowanie użycia limitów żądań
- Alertowanie wskaźnika błędów
- Śledzenie kosztów per serwis"

Budowanie narzędzi debug

"Utwórz narzędzia debugowania:
- Narzędzie replay żądań/odpowiedzi
- Wizualizacja timeline wywołań API
- Analiza wzorców błędów
- Profilowanie wydajności
- Generatory danych testowych"

Kluczowe zademonstrowane techniki

Technika 1: Wzorzec odkrywania API

Pozwól AI efektywnie analizować dokumentację API:

// Metoda 1: Używanie serwerów MCP (jeśli dostępne)
"Używając GitHub MCP, pokaż mi:
- Endpointy API repozytorium
- Wzorce autoryzacji
- Szczegóły limitów żądań
- Konfigurację webhook"

// Metoda 2: Używanie Context7 MCP dla dokumentacji
"Używając Context7 MCP, pobierz najnowsze:
- Referencję Stripe API
- Najlepsze praktyki dla idempotentności
- Wytyczne bezpieczeństwa webhook"

// Metoda 3: Ręczna analiza dokumentacji
@stripe-api-docs.md
"Wyciągnij kluczowe informacje:
- Metoda autoryzacji
- Limity żądań
- Kody błędów i znaczenia
- Obsługa idempotentności
- Zdarzenia webhook
Stwórz przewodnik referencyjny"

Technika 2: Testowanie kontraktów

Zapewnij kompatybilność API:

"Wygeneruj testy kontraktów z dokumentacji API:
- Schematy żądań/odpowiedzi
- Pola wymagane vs opcjonalne
- Definicje typów
- Reguły walidacji
- Wykrywanie breaking change"

Technika 3: Inteligentna logika ponownych prób

Implementuj smart retry:

// Różne strategie dla różnych błędów
const retryStrategies = {
  rate_limit: {
    shouldRetry: true,
    backoffMultiplier: 1,
    maxRetries: 10,
    respectRetryAfter: true
  },
  network_error: {
    shouldRetry: true,
    backoffMultiplier: 2,
    maxRetries: 3,
    addJitter: true
  },
  invalid_request: {
    shouldRetry: false
  }
};

Częste pułapki integracji

Problem: Uderzanie w limity API podczas operacji zbiorowych

Rozwiązanie:

// Implementuj algorytm token bucket
class RateLimiter {
  async executeWithRateLimit<T>(
    operation: () => Promise<T>
  ): Promise<T> {
    await this.acquireToken();
    return operation();
  }
}

Problem: Endpointy webhook narażone na ataki replay

Rozwiązanie:

// Walidacja podpisów i znaczników czasu
function validateWebhook(payload, signature, timestamp) {
  if (Date.now() - timestamp > 300000) { // 5 minut
    throw new Error('Znacznik czasu webhook zbyt stary');
  }
  // Weryfikuj podpis
}

Problem: Częściowe awarie w operacjach wieloserwisowych

Rozwiązanie:

// Implementuj wzorzec saga dla transakcji rozproszonych
class NotificationSaga {
  async execute(transaction: NotificationTransaction) {
    const steps = this.planSteps(transaction);
    const completed = [];

    try {
      for (const step of steps) {
        await step.execute();
        completed.push(step);
      }
    } catch (error) {
      // Kompensuj w odwrotnej kolejności
      for (const step of completed.reverse()) {
        await step.compensate();
      }
      throw error;
    }
  }
}

Rozszerzone wyzwanie

Ulepsz swój system integracji:

Redundancja wielu dostawców
- Dodaj zapasowych dostawców dla każdego serwisu
- Implementuj inteligentny wybór dostawcy
- Równoważ obciążenie między dostawcami
- Śledź metryki niezawodności dostawców
Zaawansowane funkcje
- Operacje API batch
- Streaming zdarzeń webhook
- Synchronizacja w czasie rzeczywistym
- Kolejka offline z synchronizacją
Optymalizacja wydajności
- Pooling połączeń
- Cache odpowiedzi
- Predykcyjne prefetching
- Warstwa agregacji GraphQL
Orkiestracja serwerów MCP
- Buduj workflow łączące wiele serwerów MCP
- Utwórz automatyzację GitHub→Linear→Slack
- Implementuj dashboard monitorowania oparty na MCP
- Zaprojektuj łańcuchy fallback używając alternatyw MCP

Mierzenie sukcesu

Twoja integracja jest gotowa do produkcji gdy:

✅ Wszystkie API zintegrowane z mniej niż 1% wskaźnikiem błędów
✅ Średni czas odpowiedzi poniżej 200ms
✅ Zero luk bezpieczeństwa
✅ 100% wskaźnik dostarczenia webhook
✅ Automatyczne odzyskiwanie po awariach
✅ Osiągnięta optymalizacja kosztów
✅ Kompleksowe monitorowanie na miejscu
✅ Pełne pokrycie testami włącznie z przypadkami brzegowymi

Metryki ze świata rzeczywistego

Zespoły używające tych wzorców raportują:

95% redukcja incydentów związanych z integracją
60% szybszy rozwój integracji API
80% spadek nieudanych transakcji
99.9% osiągnięty wskaźnik dostarczenia wiadomości

Lista kontrolna integracji

Przed wdrożeniem:

Wszystkie klucze API bezpiecznie przechowane
Limity żądań zaimplementowane
Logika ponownych prób przetestowana
Webhook zabezpieczone
Monitorowanie skonfigurowane
Obsługa błędów kompletna
Dokumentacja zaktualizowana
Testy obciążeniowe wykonane

Kluczowe wnioski

Abstrakcja wspólnych wzorców: Buduj klasy bazowe wielokrotnego użytku dla integracji
Planuj na porażkę: Każde zewnętrzne wywołanie może się nie powieść - bądź przygotowany
Bezpieczeństwo przede wszystkim: Nigdy nie idź na kompromis w bezpieczeństwie API
Monitoruj wszystko: Nie możesz naprawić tego czego nie mierzysz
Testuj realistycznie: Uwzględnij problemy sieciowe i limity API w testach

Inwestycja czasu

Początkowa architektura: 2 godziny
Bazowa implementacja: 3 godziny
Integracje dostawców: 2 godziny każda
Testowanie i wzmocnienie: 4 godziny
Razem: ~13 godzin (vs 40+ godzin tradycyjnie)

Następne kroki

Opanowałeś wzorce integracji API. Gotowy na więcej?

Buduj API Gateway

Stwórz zunifikowaną bramę API dla wszystkich integracji

Dodaj warstwę GraphQL

Zbuduj warstwę GraphQL nad REST API

Utwórz SDK

Zapakuj swoje integracje jako SDK wielokrotnego użytku

Kontynuuj do Projektowanie bazy danych →