Wzorce rozwoju API

Wzorce rozwoju API dla asystentów AI rozwiązują awarie ujawniające się na produkcji: middleware z kluczem idempotencji powstrzymujący ponowione żądania POST przed podwójnym obciążeniem, paginację kursorem typu keyset sortowaną po kluczu złożonym, która nie gubi wierszy na granicy strony, oraz specyfikacje OpenAPI generowane ze schematów Zod, dzięki czemu kontrakt nie rozjeżdża się z kodem.

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 wyniesiesz z tych wzorców API

• 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 te wzorce API zawodzą na produkcji” 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 interaktywnie do lokalnego przebiegu z możliwością przeglądu i zapisem ograniczonym do workspace:

codex --sandbox workspace-write -c approval_policy=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 te wzorce API zawodzą na produkcji

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.

Dokąd dalej po wzorcach API

• 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.