Przejdź do głównej zawartości

Wzorce tworzenia API dla agentów kodujących to trzy poprawki produkcyjne: middleware z kluczem idempotencji, dzięki któremu ponowiony POST nigdy nie obciąży klienta dwa razy, paginacja keyset po unikalnym kluczu złożonym, która nie gubi wierszy na granicy strony, oraz dokument OpenAPI generowany ze schematów Zod używanych przez handlery. Każdy wzorzec ma test, który go udowadnia bez czytania kodu linijka po linijce.

Ten przepis jest dla backendowców, którzy pozwalają agentowi pisać endpointy i chcą dowodu, że te wytrzymają ponowienia, równoległe zapisy i zmiany schematu. Twój POST /orders obciąża klienta dwukrotnie, gdy aplikacja mobilna ponawia żądanie na słabym zasięgu. „Następna strona” pomija zamówienie za każdym razem, gdy dwa zamówienia mają to samo created_at. Plik OpenAPI rozjechał się z kodem trzy sprinty temu, więc wygenerowany klient wprowadza w błąd każdego frontendowca, który mu ufa. Wszystkie trzy błędy przechodzą code review, bo kod wygląda poprawnie. Pokazuje je dopiero test, który odtwarza awarię.

Bazowy stack to Express, TypeScript, Zod, Postgres i Redis. Prompty przenosisz na Fastify, NestJS albo Route Handlers w Next.js zmianą jednej linijki. Jeśli kontrakt nie jest jeszcze zaprojektowany, zacznij od API spec-first z agentami; ta strona zaczyna się tam, gdzie trasy już istnieją.

  • Prompt dodający endpoint zgodny z konwencjami repozytorium i sposób uruchomienia go w każdym narzędziu.
  • Prompt na middleware z kluczem idempotencji, który rezerwuje klucz przed uruchomieniem handlera, więc dwa równoległe ponowienia nie obciążą klienta dwa razy.
  • Prompt na paginację keyset z sortowaniem złożonym, pasującym indeksem i kursorem, który zachowuje precyzję mikrosekund.
  • Prompt na OpenAPI 3.1 ze schematów Zod z krokiem CI, który pada, gdy specyfikacja jest nieaktualna.
  • Przebieg weryfikacji, który zamienia to wszystko w dowody do sprawdzenia zamiast czytania kodu handlerów.

Jak sprawić, żeby agent trzymał się istniejących konwencji tras?

Dział zatytułowany „Jak sprawić, żeby agent trzymał się istniejących konwencji tras?”

Daj agentowi jedną istniejącą trasę jako wzorzec i zabroń nowych abstrakcji. Agent bez wzorca wymyśla własne klasy błędów, koperty odpowiedzi i helpery walidacji. Ten prompt działa we wszystkich trzech narzędziach.

Sposób uruchomienia zależy od narzędzia. Zacznij w trybie planowania, żeby zatwierdzić listę plików, zanim cokolwiek zostanie zapisane.

W panelu Agent dołącz oba pliki z konwencjami przez @src/routes/users.ts i @src/middleware/errors.ts, a potem wklej prompt. Przy nowej trasie przełącz się najpierw na Plan Mode: Cursor tworzy plan implementacji przed napisaniem kodu, a ty zatwierdzasz listę plików. Potem pozwól agentowi uruchomić testy i przejrzyj diffy dla każdego pliku. Zacznij od pliku testów, nie od handlera.

Zapisz prompt jako prompts/add-orders-route.txt, żeby cały zespół uruchamiał ten sam. To samo dotyczy każdego promptu na tej stronie.

Jak powstrzymać ponowiony POST przed podwójnym obciążeniem?

Dział zatytułowany „Jak powstrzymać ponowiony POST przed podwójnym obciążeniem?”

Klient, któremu minął timeout, nie wie, czy serwer przetworzył żądanie, więc je ponawia. Rozwiązaniem jest nagłówek Idempotency-Key. Serwer zapisuje pierwszą odpowiedź pod tym kluczem i odtwarza ją przy każdym powtórzeniu. Agenci poprawnie piszą ścieżkę szczęśliwą. Gubią przypadek równoległy, bo naiwna wersja zapisuje odpowiedź dopiero po zakończeniu handlera. Dwa jednoczesne ponowienia trafiają wtedy na pusty cache i oba obciążają klienta.

Dwie decyzje zostają po twojej stronie i żadnej nie widać w diffie. Pierwsza to okno przechowywania: TTL 24 godziny oznacza, że ponowienie drugiego dnia znowu obciąży klienta. Dopasuj TTL do najdłuższego okna ponowień najwolniejszego klienta, na przykład kolejki offline w aplikacji mobilnej. Druga: Redis to cache. Eksmisja albo failover gubi klucze i dlatego prompt żąda ograniczenia unikalności na orders.idempotency_key. Baza odrzuci drugi insert, nawet gdy Redis zapomniał o pierwszym. Najważniejszy jest test 2. Jeśli przechodzi przy 10 równoległych żądaniach, wyścig jest zamknięty, niezależnie od tego, jak middleware wygląda w środku.

Jak paginować API bez gubienia i powtarzania wierszy?

Dział zatytułowany „Jak paginować API bez gubienia i powtarzania wierszy?”

Paginacja offsetowa (?page=3&limit=20) przesuwa się za każdym razem, gdy ktoś wstawi wiersz w trakcie przeglądania. Paginacja kursorem (keyset) to naprawia, ale agenci wprowadzają dwa cichsze błędy. Sortują po kolumnie nieunikalnej, więc wiersze o tym samym created_at znikają albo się powtarzają na granicy strony. Przepuszczają też znacznik czasu przez javascriptowy Date, który trzyma milisekundy, podczas gdy timestamptz w Postgresie przechowuje mikrosekundy. Efekt jest ten sam, nawet na danych, które wyglądają na unikalne.

Test 3 wyłącza skany sekwencyjne (albo wstawia do tabeli odpowiednio dużo wierszy), bo przy tabeli z 57 wierszami planer Postgresa słusznie wybiera skan sekwencyjny. Samo sprawdzenie EXPLAIN byłoby więc niestabilne, a agent, który zobaczy niestabilny test, osłabi go, zamiast poprawić zapytanie.

Żeby zaufać wynikowi, nie musisz czytać SQL-a. Test 1 to pełne przejście przez wszystkie strony: jeśli na dowolnej granicy strony zginie albo zdubluje się choć jeden wiersz, porównanie zbiorów pada. Żeby go poszerzyć, zamień stałe 57 wierszy na generowaną właściwość („dla dowolnego multizbioru znaczników czasu i dowolnego rozmiaru strony przejście przez strony zwraca każdy wiersz dokładnie raz”), tak jak opisuje to testowanie oparte na właściwościach z agentami. Test 3 pilnuje wydajnościowej połowy wzorca. Bez indeksu złożonego zapytanie keyset jest poprawne, ale skanuje tabelę, co wychodzi dopiero na produkcji przy dużej skali. Pracę z indeksami i planami zapytań wykraczającą poza ten endpoint opisują wzorce optymalizacji SQL.

Jak utrzymać specyfikację OpenAPI w zgodzie z kodem?

Dział zatytułowany „Jak utrzymać specyfikację OpenAPI w zgodzie z kodem?”

Ręcznie pisana specyfikacja się rozjeżdża, bo nic nie pada, gdy staje się nieaktualna. Generuj ją ze schematów Zod, których handlery i tak używają do walidacji, commituj wynik i pozwól CI paść, gdy zacommitowany plik różni się od świeżo wygenerowanego. @asteasolutions/zod-to-openapi (npm, 9.1.0 na 2026-09-26) buduje dokumenty OpenAPI 3.x z zarejestrowanych schematów Zod.

To krok git diff --exit-code utrzymuje specyfikację aktualną. Jest pewniejszy niż test porównujący w pamięci, bo sprawdza dokładnie ten plik, który pobierają konsumenci. Sprawdź wynik linterem: npx @redocly/cli lint openapi.json (Redocly CLI 2.54.3 na 2026-09-26), żeby wyłapać brakujące identyfikatory operacji i niezadeklarowane zabezpieczenia. Gdy trasa nie ma schematu, prompt każe agentowi się zatrzymać, a nie go wymyślać. Agent, który „uzupełnia lukę”, pisze dokładnie tę ręcznie utrzymywaną specyfikację, której próbujesz się pozbyć.

Jak zweryfikować kod API od agenta bez czytania każdej linijki?

Dział zatytułowany „Jak zweryfikować kod API od agenta bez czytania każdej linijki?”

Uruchom serwis i zaatakuj go jego własnym kontraktem. Schemathesis (PyPI, 4.28.0 na 2026-09-26) czyta openapi.json, generuje poprawne i niepoprawne żądania dla każdej operacji i sprawdza każdą odpowiedź względem specyfikacji: błędy serwera, kody statusu, schematy odpowiedzi i to, czy niepoprawne wejście jest odrzucane.

Okno terminala
# Terminal, with the API running locally on port 3000
uvx schemathesis run openapi.json --url http://localhost:3000 --checks all --max-time 120

Zielony przebieg Schemathesis, test równoległości i test przejścia przez strony razem dowodzą więcej niż uważna lektura handlerów. Oddaj cały przebieg agentowi i poproś o wynik w formie dowodów, a nie podsumowania.

W efekcie zmienia się to, co czyta recenzent. Czyta diff openapi.json (kontrakt) i tabelę dowodów, a nie middleware. Zmiana kontraktu, która usuwa albo zawęża pole, wymaga akceptacji zespołu, który konsumuje API. Zmiana bez diffu kontraktu i z zielonymi testami potrzebuje tylko akceptacji zespołu-właściciela. Strona o pakiecie dowodów, który musi nieść pull request agenta, zamienia to w kontrakt PR-a z kontrolą w CI. Ochrona wyroczni omawia regułę z ostatniej linijki promptu: agent nie może edytować testów, które go oceniają.

Jak otworzyć pull request ze zmianą API przez serwer MCP GitHuba?

Dział zatytułowany „Jak otworzyć pull request ze zmianą API przez serwer MCP GitHuba?”

Gdy specyfikacja się zmienia, agent może otworzyć pull request, dołączyć sekcję z dowodami i poprosić o review zespół konsumujący API przez oficjalny serwer MCP GitHuba. Zdalny serwer pod https://api.githubcopilot.com/mcp/ we wszystkich trzech klientach przyjmuje osobisty token dostępu GitHuba (PAT) w nagłówku Authorization. Polecenia poniżej używają PAT-u trzymanego w zmiennej środowiskowej, nigdy w zacommitowanym pliku.

Dodaj serwer github z adresem https://api.githubcopilot.com/mcp/ i nagłówkiem Authorization: Bearer w ~/.cursor/mcp.json (twoja konfiguracja użytkownika, poza repozytorium). Dokładny JSON znajdziesz w przewodniku po serwerze MCP GitHuba.

Jeśli agent ma już CLI gh i dostęp do powłoki, gh pr create --body-file evidence.md zrobi to samo mniejszym kosztem tokenów. Serwer MCP wybierz wtedy, gdy agent ma też czytać logi CI i komentarze z review bez dostępu do powłoki.

Kiedy wzorce API napisane przez agenta zawodzą na produkcji

Dział zatytułowany „Kiedy wzorce API napisane przez agenta zawodzą na produkcji”

Czy ten artykuł Ci pomógł?

Jedno kliknięcie, bez logowania.

wcale bardzo