Wzorce rozwoju API

Twój endpoint POST /orders obciąża klientów dwukrotnie, gdy aplikacja mobilna ponawia żądanie przy niestabilnym połączeniu. Twoja paginacja kursorem po cichu gubi wiersze, gdy dwa rekordy mają to samo created_at. A specyfikacja OpenAPI, którą napisałeś ręcznie, rozjechała się z kodem trzy sprinty temu, więc wygenerowany klient kłamie każdemu frontendowcowi, który mu ufa. To są te błędy API, które przechodzą przez code review i wychodzą na jaw dopiero na produkcji — i właśnie tu agent AI zarabia na siebie, bo poprawka to znany wzorzec, a nie akt twórczy.

Ten przepis pokazuje prompty, które zamieniają „AI naszkicowało trasę” w „trasa jest idempotentna, prawidłowo paginowana i udokumentowana ze źródła prawdy”. Jako bazowy stack przyjmujemy Express + TypeScript + Zod, ale prompty przenoszą się bez problemu na Fastify, NestJS czy Route Handlers w Next.js.

Co z tego wyniesiesz

• Gotowy do wklejenia prompt, który generuje middleware z kluczem idempotencji, dzięki czemu ponowienia po stronie klienta nigdy nie obciążą dwukrotnie.
• Prompt do paginacji kursorem ze stabilnym sortowaniem złożonym, które nie gubi wierszy.
• Prompt OpenAPI 3.1 z handlerów, który wyprowadza specyfikację z Twoich schematów Zod, więc nie może się rozjechać.
• Trójnarzędziowy workflow szkicowania endpointu (Cursor, Claude Code, Codex) i kiedy które narzędzie błyszczy.
• Listę kontrolną „Gdy to się psuje” dla trybów awaryjnych, w jakie te wygenerowane przez AI wzorce wpadają na produkcji.

Szkicowanie endpointu w trzech narzędziach

Pierwszy ruch przy każdym nowym endpoincie jest taki sam: podaj agentowi swoje istniejące konwencje tras i pozwól mu je dopasować. Narzędzia różnią się tym, jak to napędzasz — inline w edytorze, w terminalu albo nieinteraktywnie w CI.

Cursor

Otwórz plik routera, by znalazł się w kontekście, następnie otwórz tryb Agent (Cmd/Ctrl + I) i odwołaj się do pliku jawnie:

Korzystając z konwencji w @src/routes/users.ts, dodaj trasę POST /orders do @src/routes/orders.ts. Zwaliduj ciało żądania schematem Zod (items: array of {sku, qty}, idempotencyKey: uuid), zwróć 201 z utworzonym zamówieniem oraz 409 przy zduplikowanym kluczu idempotencji. Podłącz to do istniejącego middleware obsługi błędów — nie wymyślaj nowych klas błędów.

Tryb Agent edytuje plik w miejscu i pokazuje diff dla każdego pliku. Użyj Checkpoints przed zaakceptowaniem, abyś mógł cofnąć całą zmianę, jeśli kształt walidacji jest błędny.

Claude Code

Z katalogu głównego repozytorium daj Claude Code tę samą instrukcję i pozwól mu samodzielnie odczytać konwencje:

claude "Read src/routes/users.ts for our route conventions, then add a POST /orders \
route in src/routes/orders.ts. Validate the body with Zod (items, idempotencyKey:uuid), \
return 201 on success and 409 on duplicate key, and reuse the existing error middleware."

Claude Code używa swoich narzędzi Read i Edit, by dopasować się do Twoich wzorców. Dodaj najpierw --permission-mode plan, jeśli chcesz, by zaproponował zmianę, zanim ruszy pliki.

Codex

Użyj codex exec dla skryptowego, nieinteraktywnego uruchomienia — idealnego, gdy chcesz, by zmiana wylądowała jako jeden commit do przejrzenia:

codex exec --ask-for-approval on-request \
"Add a POST /orders route in src/routes/orders.ts following the conventions in \
src/routes/users.ts. Zod-validate the body (items, idempotencyKey), return 201/409, \
and reuse the existing error middleware."

Do pracy interaktywnej pomiń exec i uruchom codex w trybie TUI. Codex Cloud może wykonać to samo zadanie w izolowanym worktree i otworzyć PR — przydatne, gdy endpoint dotyka migracji, które chcesz przejrzeć w izolacji.

Idempotentne endpointy: poprawka na podwójne obciążenie

Ponowiony POST to klasyczna pułapka systemów rozproszonych. Rozwiązaniem jest middleware z kluczem idempotencji, które zapisuje pierwszą odpowiedź i odtwarza ją przy każdym powtórzeniu tego samego klucza. To na tyle mechaniczne, że AI robi to poprawnie — o ile powiesz mu, gdzie przechowywać klucz i jak długo go trzymać.

Wskazówka

Prompt do wklejenia — middleware z kluczem idempotencji:

Write Express middleware idempotency() in TypeScript that:

• reads the Idempotency-Key header (reject with 400 if missing on POST/PATCH)
• on first request for a key, runs the handler, then stores {statusCode, body} in Redis under idem:{key} with a 24h TTL
• on a repeat key, returns the stored response with header Idempotent-Replay: true instead of re-running the handler
• handles the in-flight race: if a request with the same key is already processing, return 409 with Retry-After: 1
• uses the ioredis client already exported from src/lib/redis.ts

Show the middleware plus a Vitest test that fires the same request twice and asserts the second is a replay, not a second insert.

Gdy AI odda Ci to z powrotem, zweryfikuj dwie rzeczy, zanim mu zaufasz. Po pierwsze, blokadę w trakcie przetwarzania (in-flight lock): naiwna wersja zapisuje odpowiedź dopiero po zakończeniu handlera, więc dwa równoczesne ponowienia oba chybiają cache i oba obciążają. Wpis odtworzenia musi zostać zarezerwowany (np. SET idem:{key} "processing" NX), zanim handler się wykona. Po drugie, TTL kontra okno biznesowe: 24-godzinny TTL oznacza, że ponowienie drugiego dnia i tak obciąży dwukrotnie. Poproś AI, by uczyniło to okno jawnym i dopasowanym do polityki ponawiania Twojego klienta.

Paginacja kursorem, która nie gubi wierszy

Paginacja offsetowa (?page=3&limit=20) jest w porządku dla tabeli administracyjnej, ale rozsypuje się przy zapisach: wstaw wiersz, gdy użytkownik przegląda strony, a wszystko się przesuwa. Paginacja kursorem to produkcyjna odpowiedź, a błąd, który modele AI niezawodnie wprowadzają, to sortowanie po kolumnie nieunikalnej. Jeśli dwa zamówienia mają to samo created_at, kursor oparty na samym created_at pominie lub powtórzy wiersze na granicy strony.

Wskazówka

Prompt do wklejenia — paginacja kursorem typu keyset:

Implement cursor-based pagination for GET /orders in Express + TypeScript over a Postgres table orders(id uuid pk, created_at timestamptz, ...). Requirements:

• sort by (created_at DESC, id DESC) — a composite key so the cursor is always unique
• the cursor is an opaque base64 of {created_at, id}; decode it server-side and reject a malformed cursor with 400
• the SQL must use the keyset predicate (created_at, id) < ($1, $2) with LIMIT $3 + 1 to detect hasNextPage, NOT OFFSET
• response shape: { data: [...], pageInfo: { nextCursor, hasNextPage } }
• parameterize every value — no string interpolation into SQL

Include a test that inserts two rows with an identical created_at and proves neither is dropped or duplicated across a page boundary.

Sygnałem, że AI zrobiło to poprawnie, jest predykat złożony. WHERE created_at < $1 jest błędne; WHERE (created_at, id) < ($1, $2) jest poprawne. Jeśli zobaczysz gdziekolwiek OFFSET w wygenerowanym zapytaniu, odrzuć je — to ten błąd, którego przyszedłeś tu uniknąć.

OpenAPI ze źródła prawdy

Ręcznie utrzymywany OpenAPI się rozjeżdża. Trwałym rozwiązaniem jest wyprowadzenie specyfikacji z tych samych schematów Zod, którymi Twoje handlery i tak walidują, dzięki czemu kontrakt i runtime nie mogą się rozejść. Biblioteki takie jak @asteasolutions/zod-to-openapi czynią z tego krok generowania, a nie równoległy dokument.

Wskazówka

Prompt do wklejenia — generuj OpenAPI 3.1 z Zod:

We validate every route with Zod schemas defined alongside the handlers in src/routes/. Wire up @asteasolutions/zod-to-openapi so we generate an OpenAPI 3.1 document from those schemas:

• register each route’s request and response schemas with the OpenAPIRegistry
• emit openapi.json via a script npm run openapi:gen
• add a Vitest test that fails CI if openapi.json is stale relative to the registered schemas (regenerate in-memory and deep-compare)
• include security schemes for our Bearer JWT auth

Do not hand-write paths — derive everything from the registered Zod schemas so the spec can’t drift from the code.

Sprawdzenie nieaktualności w CI to część, która sprawia, że to się utrzymuje. Bez niej specyfikacja regeneruje się tylko wtedy, gdy ktoś pamięta, i wracasz do rozjazdu. Z nią zmiana schematu, która nie regeneruje dokumentu, wywala build.

Notatka

Gdy specyfikacja jest już wygenerowana, oficjalny zdalny serwer MCP GitHuba pozwala agentowi otworzyć PR, dołączyć zregenerowany openapi.json i podlinkować diff — przydatne, gdy zmiana kontraktu wymaga akceptacji zespołu frontendowego. To hostowany endpoint HTTP, więc nie ma czego instalować: dodaj go raz przez claude mcp add --transport http github https://api.githubcopilot.com/mcp/ (lub odpowiednik w konfiguracji MCP Cursora i Codexa) i workflow jest identyczny we wszystkich trzech narzędziach.

Gdy to się psuje

Uwaga

Tryby awaryjne, w jakie te wygenerowane przez AI wzorce wpadają na produkcji:

• Cache idempotencji ściga się sam ze sobą. Model zapisuje odpowiedź po zwróceniu przez handler, więc dwa równoczesne ponowienia oba chybiają. Wymagaj blokady „zarezerwuj przed uruchomieniem” i testu, który odpala równoczesne żądania.
• Paginacja kursorem po kolumnie nieunikalnej. Jeśli wygenerowane zapytanie sortuje po samym created_at, gubi wiersze na granicach stron. Nalegaj na złożony keyset (created_at, id) i odrzucaj wszelkie OFFSET.
• OpenAPI pisany ręcznie „dla oszczędności czasu”. AI może generować ścieżki ręcznie zamiast z Twoich schematów, odtwarzając problem rozjazdu. Sprawdź, czy rejestruje schematy i czy istnieje test nieaktualności w CI.
• Przeinżynierowany HATEOAS. Poproszony o „najlepsze praktyki RESTful”, model obkłada odpowiedzi kopertami _links, których żaden klient nie konsumuje. Dodawaj hipermedia tylko wtedy, gdy realny konsument je czyta.
• Wymyślone middleware lub pakiety. Wypatruj importów wiarygodnie brzmiących, ale nieistniejących pakietów (np. zmyślony express-idempotent-middleware). Uruchom npm view <pkg> version na wszystkim, czego nie miałeś już w package.json — jeśli zwraca 404 lub jest oznaczony jako przestarzały, nie podłączaj go.
• Zlokalizowane komunikaty błędów ujawniające wnętrzności. Wygenerowane handlery błędów czasem przekazują surowy błąd bazy w details. Usuwaj ślady stosu i SQL ze wszystkiego, co widzi klient; loguj je po stronie serwera z traceId.

Co dalej

• Wzorce rozwoju baz danych — prompty do optymalizacji zapytań i migracji bez przestoju stojące za tymi endpointami.
• Wzorce serverless do wdrażania tych API na edge.