Budowanie integracji API z Cursor Agent

Poprzedni programista zostawił niedokończoną integrację ze Stripe. Handler webhooków po cichu połyka błędy. Wywołania SendGrid do wysyłki e-maili nie mają logiki ponownych prób. Kod Twilio do SMS-ów twardo się wywala, gdy API narzuca limity częstotliwości. A teraz potrzebujesz, żeby wszystkie trzy współpracowały: płatność się udaje, wysyłany jest e-mail z potwierdzeniem, po nim SMS — z prawidłową obsługą błędów na każdym etapie. Deadline masz w piątek.

Podłączanie zewnętrznych API to jedno z zadań, gdzie Cursor zapewnia największą dźwignię. AI widział tysiące integracji Stripe, SendGrid i Twilio i zna typowe pułapki — klucze idempotencji, weryfikacja podpisów webhooków, wykładniczy backoff — których ręczne opanowanie zajmuje godziny. Poniższy workflow pokazuje, jak zbudować warstwę integracji na poziomie produkcyjnym w ułamku tego czasu.

Co wyniesiesz z tej lekcji

• Bazową klasę integracji z wbudowaną logiką ponownych prób, circuit breakerami i ustrukturyzowaną obsługą błędów, którą możesz wykorzystać z dowolnym dostawcą API
• Gotowe do skopiowania prompty do analizy nieznanej dokumentacji API i generowania typowanego kodu klienta
• Szablon handlera webhooków z weryfikacją podpisów i ochroną przed atakami replay
• Strategię testowania z użyciem mock serverów, dzięki czemu twój pipeline CI nigdy nie wykonuje prawdziwych wywołań API
• Wiedzę o tym, kiedy serwery MCP całkowicie zastępują niestandardowy kod integracji

Workflow

Krok 1: Przeanalizuj istniejący bałagan

Zanim napiszesz nowy kod, zrozum, co zostawił poprzedni programista. Użyj trybu Ask, aby uzyskać jasny obraz aktualnego stanu.

Wskazówka

Prompt do skopiowania — Audyt integracji:

@src/integrations @src/services @src/lib

Przeprowadź audyt istniejącego kodu integracji API i zaraportuj:

1. Które API są zintegrowane i w jakim stanie jest każde z nich (kompletne, częściowe, uszkodzone)?
2. Jaka obsługa błędów istnieje? Czy jest spójna między dostawcami?
3. Czy klucze API są przechowywane bezpiecznie (zmienne środowiskowe, nie wpisane na stałe)?
4. Czy istnieje logika ponownych prób? Jeśli tak, czy jest per dostawca, czy generyczna?
5. Czy handlery webhooków weryfikują podpisy?
6. Co się dzieje, gdy wywołanie API nie powiedzie się w trakcie wieloetapowego procesu (płatność + e-mail + SMS)?
7. Czy istnieją zabezpieczenia przed przekroczeniem limitów częstotliwości?

Oceń każdą integrację: gotowa-do-produkcji, wymaga-pracy lub niebezpieczna.

Krok 2: Zaprojektuj architekturę integracji

Przełącz się na tryb Agent i stwórz solidne fundamenty przed implementacją poszczególnych dostawców.

@src/integrations

Zaprojektuj i zaimplementuj bazową warstwę integracji:

1. Utwórz src/integrations/base-client.ts z:
   - Konfigurowalnym ponawianiem z wykładniczym backoffem i jitterem
   - Circuit breakerem (otwarty po 5 błędach w 60 sekund, pół-otwarty po 30 sekundach)
   - Logowaniem żądań/odpowiedzi z redakcją wrażliwych danych
   - Konfiguracją timeoutu per dostawca
   - Detekcją limitów częstotliwości z nagłówków odpowiedzi (Retry-After, X-RateLimit-Remaining)

2. Utwórz src/integrations/types.ts z:
   - Klasą IntegrationError z polami: provider, code, isRetryable, originalError
   - Interfejsem IntegrationConfig
   - Enumem CircuitBreakerState

3. Utwórz src/integrations/errors.ts z konkretnymi klasami błędów:
   - RateLimitError, AuthenticationError, ValidationError, TimeoutError, NetworkError

Nie implementuj jeszcze żadnego konkretnego dostawcy -- tylko fundamenty do ponownego użycia.

Krok 3: Zaimplementuj klientów specyficznych dla dostawców

Mając bazową warstwę na miejscu, zaimplementuj każdego dostawcę, rozszerzając ją. Odwołuj się do klasy bazowej, aby Agent utrzymywał spójność.

Wskazówka

Prompt do skopiowania — Integracja Stripe:

@src/integrations/base-client.ts @src/integrations/types.ts

Zaimplementuj integrację płatności Stripe w src/integrations/stripe-client.ts:

1. Rozszerz BaseClient o konfigurację specyficzną dla Stripe
2. Zaimplementuj createPaymentIntent, confirmPayment, refundPayment i getPaymentStatus
3. Dodaj generowanie kluczy idempotencji dla wszystkich operacji mutujących
4. Obsłuż błędy specyficzne dla Stripe (card_declined, rate_limit, api_connection_error) i zmapuj je na nasze typy błędów
5. Parsuj nagłówki limitów częstotliwości i respektuj Retry-After
6. Dodaj weryfikację podpisów webhooków przy użyciu zalecanego podejścia Stripe (stripe.webhooks.constructEvent)
7. Typuj wszystkie parametry i wartości zwracane — żadnych typów any

Użyj pakietu npm stripe. Wersja API powinna być konfigurowalna przez zmienną środowiskową.

Powtórz ten wzorzec dla SendGrid i Twilio, dostosowując do specyfiki API każdego dostawcy:

@src/integrations/base-client.ts @src/integrations/stripe-client.ts

Teraz zaimplementuj integrację e-mail SendGrid w src/integrations/sendgrid-client.ts
zgodnie z tymi samymi wzorcami co klient Stripe:

1. Rozszerz BaseClient
2. Zaimplementuj sendTransactionalEmail, sendBatchEmails, getEmailStatus
3. Obsłuż błędy specyficzne dla SendGrid (429 limit częstotliwości, 401 auth, 5xx błędy serwera)
4. Wspieraj szablony e-mail ze zmiennymi dynamicznymi
5. Dodaj obsługę webhooków dotyczących odrzuceń i reklamacji
6. Loguj próby wysyłki e-mail z identyfikatorami wiadomości dla śledzenia

Krok 4: Zbuduj warstwę orkiestracji

Prawdziwa złożoność nie tkwi w poszczególnych wywołaniach API — tkwi w ich koordynacji. Kiedy płatność się udaje, ale e-mail nie dochodzi, co wtedy? Potrzebujesz wzorca saga lub przynajmniej niezawodnej sekwencji z akcjami kompensującymi.

Wskazówka

Prompt do skopiowania — Orkiestracja powiadomień:

@src/integrations/stripe-client.ts @src/integrations/sendgrid-client.ts @src/integrations/twilio-client.ts

Utwórz src/services/checkout-notification-service.ts, który orkiestruje przepływ po finalizacji zakupu:

1. Po udanej płatności: wyślij e-mail z potwierdzeniem przez SendGrid, następnie wyślij SMS z potwierdzeniem przez Twilio
2. Jeśli e-mail nie dojdzie: zaloguj błąd, zakolejkuj do ponowienia, ale NIE zawal checkoutu — płatność już się udała
3. Jeśli SMS nie dojdzie: zaloguj i zakolejkuj do ponowienia, nigdy nie zawalaj checkoutu przez SMS
4. Śledź status każdego kroku w tabeli notifications (payment_id, channel, status, attempt_count, last_error)
5. Zaimplementuj workera ponowień, który przetwarza kolejkę nieudanych powiadomień co 60 sekund
6. Dodaj kolejkę dead letter dla powiadomień, które nie powiodą się po 5 próbach

Kluczowa zasada: płatność jest źródłem prawdy. Niepowodzenia powiadomień to zdegradowane doświadczenie, nie niepowodzenie checkoutu.

Krok 5: Zabezpiecz handlery webhooków

Endpointy webhooków to publiczne URL-e, które odbierają dane od zewnętrznych serwisów. Bez odpowiedniego zabezpieczenia każdy może sfałszować payload webhooka.

@src/integrations

Utwórz bezpieczne middleware handlera webhooków w src/middleware/webhook-verify.ts:

1. Weryfikuj podpisy webhooków Stripe przy użyciu signing secret
2. Weryfikuj podpisy webhooków zdarzeń SendGrid przy użyciu ich klucza publicznego
3. Odrzucaj żądania ze znacznikami czasu starszymi niż 5 minut (ochrona przed replay)
4. Parsuj surowe body (ważne: webhooki potrzebują surowego body do weryfikacji podpisu, nie sparsowanego JSON-a)
5. Loguj wszystkie zdarzenia webhooków wraz z ich statusem weryfikacji
6. Zwracaj 200 natychmiast, aby zapobiec ponowieniom, a następnie przetwarzaj asynchronicznie
7. Obsługuj duplikaty dostarczeń idempotentnie (sprawdzaj event ID w tabeli przetworzonych zdarzeń)

Dodaj trasy webhooków w src/app/api/webhooks/stripe/route.ts i src/app/api/webhooks/sendgrid/route.ts.

Krok 6: Testuj bez uderzania w prawdziwe API

Wskazówka

Prompt do skopiowania — Zestaw testów integracyjnych:

@src/integrations @src/services/checkout-notification-service.ts

Utwórz kompleksowy zestaw testów dla warstwy integracji:

1. Skonfiguruj msw (Mock Service Worker) do przechwytywania wszystkich żądań HTTP do API Stripe, SendGrid i Twilio
2. Przetestuj happy path: płatność + e-mail + SMS — wszystko się udaje
3. Przetestuj częściowe awarie: płatność się udaje, ale e-mail nie dochodzi — zweryfikuj, że checkout nadal się udaje i e-mail jest zakolejkowany do ponowienia
4. Przetestuj circuit breaker: zasymuluj 5 kolejnych awarii Stripe i zweryfikuj, że circuit się otwiera
5. Przetestuj limit częstotliwości: zwróć 429 z nagłówkiem Retry-After i zweryfikuj, że klient czeka przed ponowieniem
6. Przetestuj weryfikację podpisów webhooków: prawidłowy podpis się udaje, zmodyfikowany payload jest odrzucany
7. Przetestuj idempotencję: wyślij to samo żądanie płatności dwa razy i zweryfikuj, że utworzone jest tylko jedno obciążenie

Użyj vitest. Żadne prawdziwe wywołania API nie powinny być wykonywane podczas testów.

Przyspieszanie z serwerami MCP

Jeśli masz skonfigurowane serwery MCP dla usług takich jak GitHub, Linear czy Slack, Agent w Cursor może używać ich bezpośrednio jako narzędzi. To eliminuje potrzebę pisania niestandardowego kodu integracji dla obsługiwanych operacji.

Na przykład z serwerem MCP GitHub skonfigurowanym w .cursor/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

Agent może bezpośrednio tworzyć issue, czytać PR-y i zarządzać repozytoriami bez pisania przez ciebie jakiegokolwiek kodu API GitHub. Używaj serwerów MCP do zadań operacyjnych (tworzenie issue, wysyłanie wiadomości), a niestandardowych integracji do kluczowych przepływów biznesowych (przetwarzanie płatności), gdzie potrzebujesz pełnej kontroli nad obsługą błędów i logiką ponownych prób.

Kiedy to się psuje

Limity częstotliwości na produkcji mimo przechodzących testów lokalnych. Testy lokalne z mock serverami nie testują prawdziwych limitów częstotliwości. Dodaj liczniki limitów do warstwy integracji, które śledzą wywołania na minutę per dostawca. Ustaw konserwatywne limity (80% deklarowanego limitu API) i kolejkuj nadmiarowe żądania.

Zdarzenia webhooków przychodzą w niewłaściwej kolejności. Stripe może w rzadkich przypadkach wysłać payment_intent.succeeded przed payment_intent.created. Projektuj handlery webhooków tak, aby były idempotentne i niezależne od kolejności. Używaj znacznika czasu created ze zdarzenia, a nie kolejności przybycia, do ustalania sekwencji.

Circuit breaker pozostaje otwarty zbyt długo. Jeśli sprawdzenie w stanie pół-otwartym nie powiedzie się raz, circuit otwiera się ponownie na kolejne 30 sekund. Przy borykającym się API może to oznaczać minuty przestoju. Zaimplementuj okno przesuwne: przepuszczaj 1 na 10 żądań w stanie pół-otwartym, zwiększając stosunek wraz z narastaniem sukcesów.

Logika ponownych prób powoduje podwójne obciążenia. Bez kluczy idempotencji ponawianie nieudanego żądania płatności, które faktycznie się powiodło (ale przekroczyło timeout), tworzy podwójne obciążenie. Zawsze używaj kluczy idempotencji do operacji mutujących. Stripe, SendGrid i większość głównych API je wspiera.

Mocki testowe rozmijają się z rzeczywistym zachowaniem API. Mock serwery zachowują się jak prawdziwe API tylko w momencie, gdy napisałeś mocki. Okresowo uruchamiaj swój zestaw testów przeciwko sandboxom/środowiskom testowym prawdziwych API (nie w CI, ale jako zaplanowane zadanie), aby wyłapać przełomowe zmiany.

Co dalej

Projektowanie schematu bazy danych Zaprojektuj model danych wspierający twoje integracje, w tym kolejkę powiadomień i tabelę zdarzeń webhooków.

Audyt bezpieczeństwa Sprawdź warstwę integracji pod kątem luk bezpieczeństwa: ujawnienie kluczy API, fałszowanie webhooków, ataki injection.

Konfiguracja serwerów MCP Skonfiguruj serwery MCP dla najczęściej używanych usług, aby wyeliminować szablonowy kod integracji.