Kurs vibe coding z Claude Code · Moduł 14: Klon Pinteresta
Szlaki handlowe: trasy API ze specyfikacją z wywiadu
W tej lekcji12
Tablice leżą już w bazie ale piny wciąż płyną starym szlakiem. Strona główna i GET /api/pins czytają listę z lib/pins.ts, nowego pinu nie da się dodać, a jednego pinu nie da się pobrać po identyfikatorze. Trasy API to umowa z każdym, kto do nich zapuka: kto może dodać pin, jakie pola przyjmujemy, jaki kod dostaje obcy, jak dzielimy listę na strony. Gdy napiszesz tylko "zrób API pinów", każdą z tych decyzji Claude podejmie po cichu, a Ty odkryjesz ją dopiero w kodzie. Dlatego najpierw wywiad, jak w lekcjach 0_5 i 1_6, a budowa dopiero ze spisanej umowy.
Czego się nauczysz
- poprowadzić wywiad, z którego powstaje
SPEC.mddla API; - zacząć budowę w świeżej sesji, w trybie planowania, od samej specyfikacji;
- rozpoznać przypisanie masowe (
data: body) i zastąpić je listą dozwolonych pól; - odróżnić odpowiedzi 400, 401, 404 i 201 i udowodnić je poleceniem
curl; - ocenić, kiedy zamiast tras REST warto sięgnąć po GraphQL.
Polecenie dla Claude Code: wywiad
Przełącz sesję na Manual: wywiad niczego nie zmienia, a Claude zapyta o zgodę dopiero przed zapisem pliku.
Polecenie dla Claude Code:
Chcę trasy API dla pinów w Treasure Map: lista z paginacją, dodanie
pinu i jeden pin po id. Klient bazy jest w @lib/prisma.ts, tablice
w @lib/boards.ts, sesja w @lib/session.ts. Przeprowadź ze mną wywiad,
najwyżej trzy pytania naraz: kto co może, jakie kody błędów zwracamy,
jak działa paginacja, które pola przyjmujemy od klienta, a które
ustawia serwer. Potem zapisz SPEC.md: cel, trasy, pola, błędy, czego
nie robimy, jak sprawdzimy. Kodu nie pisz.Dobre praktyki Claude Code opisują ten wzorzec tak: Claude wraca z pytaniami wielokrotnego wyboru o sprawy, których jeszcze nie ustaliłeś, i pyta, dopóki odpowiedzi nie złożą się w specyfikację. Pytania zadaje narzędziem AskUserQuestion. Wybierasz gotową odpowiedź albo wpisujesz własną w wierszu Other. Przy API pytania mogą wyglądać tak:
1. Kto może dodać pin?
a) każdy zalogowany b) tylko właściciel tablicy c) każdy
2. Co dostaje klient, który przyśle pole spoza listy?
a) 400 z nazwą pola b) pole jest po cichu pomijane
3. Jak dzielimy listę pinów na strony?
a) kursor jak w lekcji 13_1 b) numer stronyNa każde pytanie odpowiadasz z myślą o napastniku, nie tylko o przeglądarce: pole, którego nie przewidzisz, ktoś w końcu wyśle.
Co napisał Claude: SPEC.md
Otwórz SPEC.md w Cursorze. Twój plik będzie miał inne słowa, ale powinien zapisać te same decyzje. Najważniejsza część może wyglądać tak:
## Trasy
- GET /api/pins?cursor=<id>: 12 pinów i nextCursor (null na końcu), dla każdego.
- GET /api/pins/<id>: jeden pin albo 404. Id to napis, nigdy liczba.
- POST /api/pins: tylko zalogowany (401). Pola: title, src (z /pins/),
width, height, dominantColor, tags (najwyżej 5).
## Ustawia serwer
- id, ownerId i author z sesji, createdAt. Pole spoza listy: 400 z nazwą.
## Czego nie robimy
- edycji i usuwania pinów, przesyłania obrazów.Specyfikacja mówi "co", a nie "jak": nie ma w niej nazw plików ani kolejności pracy. Sekcja "Ustawia serwer" to najważniejsza część tej umowy i wrócisz do niej przy przeglądzie.
Świeża sesja i plan ze specyfikacji
Rozmowa z wywiadu jest pełna odrzuconych pomysłów. Dokumentacja Claude Code radzi budować w świeżej sesji, z czystym kontekstem i spisaną definicją "gotowe". Wpisz /clear: stara rozmowa zostaje do wznowienia, a nowa zna tylko to, co jej podasz. Potem:
/plan Zbuduj trasy pinów według @SPEC.md. Najpierw testy walidacji
POST /api/pins: pole spoza listy, ownerId w ciele, pusty tytuł, liczby
podane jako napisy, brak sesji. Potem kod. Walidacja schematem Zod,
jak w lekcji 6_1. Strona główna ma brać pierwszą stronę pinów z tej
samej funkcji co trasa. Na koniec testy, lint, npx tsc --noEmit
i npm run build.Z @SPEC.md Claude dostaje umowę bez szumu z poprzedniej rozmowy. W planie sprawdź, czy testy stoją przed kodem i czy właściciel pinu pochodzi z getCurrentUserId(). Claude doda do projektu bibliotekę zod.
Co napisał Claude: lista dozwolonych pól
Otwórz lib/pinInput.ts. Lista dozwolonych pól (whitelist) wymienia wszystko, co klient może przysłać. To, czego na niej nie ma, nie przechodzi:
// lib/pinInput.ts
export const pinInputSchema = z.strictObject(
{
title: z.string().trim().min(1, "Podaj tytuł.").max(100, "Tytuł ma najwyżej 100 znaków."),
src: z.string().startsWith("/pins/", "Obraz musi leżeć w /pins/."),
width: pixels,
height: pixels,
dominantColor: z.string().regex(/^#[0-9a-f]{6}$/, "Kolor w zapisie #rrggbb."),
tags: z.array(z.string().trim().min(1).max(30)).max(5, "Najwyżej 5 tagów.").default([]),
},
{ error: (issue) => (issue.code === "unrecognized_keys" ? `Nieznane pola: ${issue.keys.join(", ")}` : undefined) },
);Schemat Zod znasz z lekcji 6_1. z.strictObject różni się od z.object jednym: nieznany klucz to błąd, a nie cicho pominięte pole. Ostatni argument zamienia ten błąd na polski komunikat z nazwą pola. pixels to stała z tego pliku: liczba całkowita od 1 do 10000, więc napis "600" nie przejdzie. startsWith("/pins/") wpuszcza tylko obrazy z naszego portu. Pięć testów pilnuje tych zasad.
Typowy błąd agenta: data: body
Najkrótsza trasa, jaką agent potrafi napisać, i ta ze starej wersji tej lekcji, wygląda tak:
// app/api/pins/route.ts (wersja agenta)
const body = await request.json();
const pin = await prisma.pin.create({ data: body });To przypisanie masowe (mass assignment): o każdej kolumnie decyduje klient. Przekazaliśmy tak do create ciało z "ownerId": "kapitan" i "author": "Kapitan Redbeard", a Prisma posłusznie zapisała pin na konto kapitana, choć ciało mogła wysłać Papuga. Pole role nasz model akurat odrzucił błędem Unknown argument, który w trasie kończy się kodem 500. Ale w tabeli użytkowników z kolumną role ta sama linijka pozwoliłaby każdemu nadać sobie uprawnienia administratora. Pułapka ma też wersję z rozpakowaniem: w { ownerId: viewerId, ...body } ciało nadpisuje właściciela, bo wygrywa to, co stoi później. U nas pin znowu wylądował u kapitana.
Co napisał Claude: POST
Otwórz app/api/pins/route.ts. Kontrole idą po kolei, a do bazy trafia dopiero to, co przeszło przez schemat:
// app/api/pins/route.ts
export async function POST(request: Request) {
const viewerId = await getCurrentUserId();
if (!viewerId) return Response.json({ error: "Zaloguj się." }, { status: 401 });
const body = await request.json().catch(() => null);
if (body === null) return Response.json({ error: "Wyślij pin jako obiekt JSON." }, { status: 400 });
const result = pinInputSchema.safeParse(body);
if (!result.success) {
const { formErrors, fieldErrors } = z.flattenError(result.error);
return Response.json({ error: formErrors[0] ?? "Popraw pola.", fields: fieldErrors }, { status: 400 });
}
const pin = await createPin(result.data, viewerId);
return Response.json(pin, { status: 201 });
}createPin z lib/pinStore.ts składa dane z result.data oraz ownerId i author z sesji. Kod 400 zawsze niesie powód, a fields mówi, które pole poprawić, co znasz z formularzy w lekcji 6_1. Trasa nie zdradza też szczegółów błędu bazy, bo do bazy nie dochodzi nic niesprawdzonego. Test, który najbardziej warto przeczytać:
// app/api/pins/route.test.ts
test("ownerId w ciele: 400 i nic nie trafia do bazy", async () => {
const res = await post({ ...valid, ownerId: "kapitan" });
expect(res.status).toBe(400);
expect(await res.json()).toMatchObject({ error: "Nieznane pola: ownerId" });
expect(db.create).not.toHaveBeenCalled();
});Test podmienia @/lib/prisma i @/lib/session przez vi.mock, jak w lekcji 8_3, więc działa bez bazy. Ostatnia linijka sprawdza najważniejsze: do create nic nie dotarło.
Co napisał Claude: jeden pin i 404
Otwórz app/api/pins/[id]/route.ts:
// app/api/pins/[id]/route.ts
export async function GET(_request: Request, { params }: { params: Promise<{ id: string }> }) {
const { id } = await params;
const pin = await getPin(id);
if (!pin) return Response.json({ error: "Nie ma takiego pinu." }, { status: 404 });
return Response.json(pin);
}W Next.js 16 params to obietnica (Promise), więc await jest obowiązkowe. Identyfikatory są napisami (p07 albo wygenerowany cmw...), więc nie ma tu parseInt. Stara wersja lekcji robiła z nich liczbę: parseInt("cmw...") daje NaN, a Prisma odpowiada wyjątkiem i kodem 500. Brak pinu to 404 z powodem, a nie 200 z null, na którym klient by się wyłożył.
Lista działa na kursorze z lekcji 13_1, tylko kursorem jest teraz id pierwszego pinu następnej strony. getPinPage pobiera 13 pinów: dwanaście oddaje, a trzynasty wskazuje kolejną stronę. Strona główna woła tę samą funkcję, więc PinFeed niczego nie zauważył.
Przegląd kapitana
- Tylko dozwolone pola. Wyszukaj w projekcie
data: bodyi...body. W trasach nie ma żadnego, acreatedostajeresult.datai pola z sesji. - Kody z powodem. Przy działającym
npm run devwyślij pin z cudzym właścicielem:
curl -s -b demo-user=papuga -H 'Content-Type: application/json' -d '{"title":"Mapa z targu","src":"/pins/skarb-10.jpg","width":600,"height":700,"dominantColor":"#986848","ownerId":"kapitan"}' localhost:3000/api/pinsU nas wróciło {"error":"Nieznane pola: ownerId","fields":{}} z kodem 400. To samo ciało bez ownerId dało 201, bez ciasteczka 401, a GET /api/pins/42 i GET /api/pins/nieistnieje dały 404.
3. Parametry. await params w każdej trasie z [id] i żadnego parseInt na identyfikatorze.
4. Właściciel z sesji. Wyszukaj body.ownerId. Typowy błąd agenta to przyjęcie właściciela z formularza "bo tak wygodniej testować".
/security-review jako nawyk
Trasy zapisu to miejsce, w którym przegląd bezpieczeństwa z lekcji 8_7 robisz zawsze: commit, potem /security-review. Przegląd czyta tylko zmiany gałęzi, porównane z domyślną gałęzią origin. Tej komendy nie uruchamialiśmy na tej gałęzi, więc nie pokazujemy raportu. Każde zgłoszenie sprawdzasz w Cursorze, jak w lekcji 8_7. Pamiętaj też, że sesja demo z lekcji 11_3 to niepodpisane ciasteczko, które każdy może sobie ustawić. Jeśli raport o tym milczy, nie znaczy to, że problemu nie ma. Przegląd potrafi pominąć prawdziwe, ale mało groźne znalezisko. Prawdziwe logowanie pokazuje lekcja dla chętnych o Supabase.
A GraphQL?
Stara wersja tej lekcji obiecywała w tytule GraphQL, choć go nie pokazywała. Uczciwie: GraphQL to inny sposób budowania API. Zamiast wielu adresów jest jeden, a klient wysyła zapytanie, które wymienia dokładnie potrzebne pola, także z powiązanych obiektów. Serwer opisuje swoje dane schematem typów. Opłaca się, gdy wielu różnych klientów, na przykład aplikacja mobilna i strona, potrzebuje różnych wycinków tych samych zagnieżdżonych danych. Wtedy jedno API zastępuje tuzin tras szytych na miarę. Kosztuje za to więcej pracy: schemat, funkcje rozwiązujące każde pole, ochronę przed zbyt głębokimi zapytaniami i trudniejsze cache'owanie, bo wszystko idzie jednym adresem. Treasure Map ma jednego klienta i kilka tras, więc REST w route handlerach wystarczy.
Następny krok
Gdy przegląd przejdzie, poproś o commit "Trasy pinów według SPEC.md". Kolejny mały krok zaczynasz od specyfikacji, nie od kodu: "Dopisz do SPEC.md usuwanie pinu: tylko właściciel, obcy dostaje 404, a potem zbuduj to w świeżej sesji". W edytorze poniżej czeka tester szlaków: wysyłaj żądania z różnymi ciałami i ciasteczkiem, a potem włącz wersję agenta z data: body i patrz, czyj pin ląduje w tabeli.
Zapamiętaj: szlak handlowy bez strażnika to zaproszenie dla piratów, więc spisz umowę, zanim ruszą karawany, i wpuszczaj tylko towar z listy.
Kod do tej lekcji: App.tsx
// Szlaki handlowe w miniaturze: wyślij żądanie do tras pinów i zobacz kod odpowiedzi
import { useState } from 'react';
interface Pin {
id: string;
title: string;
src: string;
width: number;
height: number;
dominantColor: string;
tags: string[];
ownerId: string;
}
interface ApiResult {
status: number;
body: unknown;
pins: Pin[];
}
const START: Pin[] = [
{ id: 'p07', title: 'Laguna', src: '/pins/skarb-07.jpg', width: 600, height: 800, dominantColor: '#a8c808', tags: ['laguna'], ownerId: 'papuga' },
{ id: 'p10', title: 'Stara mapa', src: '/pins/skarb-10.jpg', width: 600, height: 700, dominantColor: '#986848', tags: ['mapa'], ownerId: 'kapitan' },
];
const ALLOWED = ['title', 'src', 'width', 'height', 'dominantColor', 'tags'];
const COLUMNS = [...ALLOWED, 'id', 'ownerId', 'author', 'createdAt'];
const VALID = '{"title": "Mapa z targu", "src": "/pins/skarb-10.jpg", "width": 600, "height": 700, "dominantColor": "#986848"}';
const PRESETS = [
{ label: 'GET jeden pin', method: 'GET', path: '/api/pins/p07', body: '' },
{ label: 'GET brak pinu', method: 'GET', path: '/api/pins/42', body: '' },
{ label: 'POST poprawny', method: 'POST', path: '/api/pins', body: VALID },
{ label: 'POST z ownerId', method: 'POST', path: '/api/pins', body: VALID.replace('}', ', "ownerId": "kapitan"}') },
{ label: 'POST z role', method: 'POST', path: '/api/pins', body: VALID.replace('}', ', "role": "admin"}') },
{ label: 'POST złe pola', method: 'POST', path: '/api/pins', body: '{"title": " ", "src": "https://example.com/a.jpg", "width": "600", "height": 700, "dominantColor": "red"}' },
];
function isPositiveInt(value: unknown) {
return Number.isInteger(value) && (value as number) >= 1 && (value as number) <= 10000;
}
// Lista dozwolonych pól, jak pinInputSchema z lekcji: wszystko spoza listy to błąd 400
function validate(body: Record<string, unknown>) {
const unknownKeys = Object.keys(body).filter((key) => !ALLOWED.includes(key));
const fields: Record<string, string> = {};
if (typeof body.title !== 'string' || body.title.trim() === '') fields.title = 'Podaj tytuł.';
if (typeof body.src !== 'string' || !body.src.startsWith('/pins/')) fields.src = 'Obraz musi leżeć w /pins/.';
if (!isPositiveInt(body.width)) fields.width = 'Podaj liczbę pikseli.';
if (!isPositiveInt(body.height)) fields.height = 'Podaj liczbę pikseli.';
if (typeof body.dominantColor !== 'string' || !/^#[0-9a-f]{6}$/.test(body.dominantColor)) fields.dominantColor = 'Kolor w zapisie #rrggbb.';
return { unknownKeys, fields };
}
function send(method: string, path: string, rawBody: string, session: string, agentVersion: boolean, pins: Pin[]): ApiResult {
if (method === 'GET') {
const id = path.split('/').pop() ?? '';
const pin = pins.find((p) => p.id === id);
return pin ? { status: 200, body: pin, pins } : { status: 404, body: { error: 'Nie ma takiego pinu.' }, pins };
}
let body: unknown = null;
try {
body = JSON.parse(rawBody);
} catch {
body = null;
}
if (agentVersion) {
// wersja agenta: prisma.pin.create({ data: body }), bez sesji i bez listy pól
const data = (body ?? {}) as Record<string, unknown>;
const extra = Object.keys(data).find((key) => !COLUMNS.includes(key));
if (extra) return { status: 500, body: { error: 'Unknown argument ' + extra + '.' }, pins };
const created = { tags: [], author: '', ...data, id: 'nowy' + (pins.length + 1) } as unknown as Pin;
if (!created.ownerId) return { status: 500, body: { error: 'Argument ownerId is missing.' }, pins };
return { status: 201, body: { id: created.id }, pins: [...pins, created] };
}
if (!session) return { status: 401, body: { error: 'Zaloguj się.' }, pins };
if (body === null || typeof body !== 'object' || Array.isArray(body)) {
return { status: 400, body: { error: 'Wyślij pin jako obiekt JSON.' }, pins };
}
const input = body as Record<string, unknown>;
const { unknownKeys, fields } = validate(input);
if (unknownKeys.length > 0) return { status: 400, body: { error: 'Nieznane pola: ' + unknownKeys.join(', ') }, pins };
if (Object.keys(fields).length > 0) return { status: 400, body: { error: 'Popraw pola.', fields }, pins };
const created: Pin = {
id: 'nowy' + (pins.length + 1),
title: String(input.title).trim(),
src: String(input.src),
width: Number(input.width),
height: Number(input.height),
dominantColor: String(input.dominantColor),
tags: Array.isArray(input.tags) ? input.tags.map(String) : [],
ownerId: session, // właściciel z sesji, nigdy z ciała
};
return { status: 201, body: { id: created.id }, pins: [...pins, created] };
}
export default function App() {
const [pins, setPins] = useState<Pin[]>(START);
const [preset, setPreset] = useState(0);
const [rawBody, setRawBody] = useState(PRESETS[0].body);
const [session, setSession] = useState('papuga');
const [agentVersion, setAgentVersion] = useState(false);
const [result, setResult] = useState<ApiResult | null>(null);
const request = PRESETS[preset];
function choose(i: number) {
setPreset(i);
setRawBody(PRESETS[i].body);
setResult(null);
}
function submit() {
const next = send(request.method, request.path, rawBody, session, agentVersion, pins);
setPins(next.pins);
setResult(next);
}
return (
<div className="min-h-screen space-y-4 bg-amber-50 p-4 text-zinc-900">
<h1 className="text-xl font-bold">Szlaki handlowe: tester tras pinów</h1>
<div className="flex flex-wrap gap-2">
{PRESETS.map((p, i) => (
<button key={p.label} type="button" onClick={() => choose(i)} className={i === preset ? 'rounded-full bg-red-600 px-3 py-1 text-sm text-white' : 'rounded-full bg-zinc-200 px-3 py-1 text-sm'}>
{p.label}
</button>
))}
</div>
<p className="font-mono text-sm">
{request.method} {request.path}
</p>
{request.method === 'POST' && (
<label className="block text-sm">
Ciało żądania (JSON, możesz edytować):
<textarea value={rawBody} onChange={(e) => setRawBody(e.target.value)} rows={4} className="mt-1 w-full rounded border border-zinc-300 bg-white p-2 font-mono text-xs" />
</label>
)}
<div className="flex flex-wrap items-center gap-3 text-sm">
<label className="flex items-center gap-2">
Ciasteczko sesji:
<select value={session} onChange={(e) => setSession(e.target.value)} className="rounded border border-zinc-300 px-2 py-1">
<option value="papuga">papuga</option>
<option value="kapitan">kapitan</option>
<option value="">brak</option>
</select>
</label>
<label className="flex items-center gap-2">
<input type="checkbox" checked={agentVersion} onChange={(e) => setAgentVersion(e.target.checked)} />
Wersja agenta: data: body
</label>
<button type="button" onClick={submit} className="rounded-full bg-red-600 px-4 py-2 font-semibold text-white">
Wyślij
</button>
</div>
{result && (
<div role="status" className={result.status < 300 ? 'rounded-xl bg-emerald-100 p-3 text-sm' : 'rounded-xl bg-red-100 p-3 text-sm'}>
<p className="font-bold">Status {result.status}</p>
<p className="break-all font-mono text-xs">{JSON.stringify(result.body)}</p>
</div>
)}
<table className="w-full rounded-xl bg-white text-left text-sm">
<caption className="text-left font-semibold">Tabela Pin w bazie</caption>
<thead>
<tr>
<th className="p-1">id</th>
<th className="p-1">title</th>
<th className="p-1">ownerId</th>
</tr>
</thead>
<tbody>
{pins.map((pin) => (
<tr key={pin.id} className="border-t border-zinc-200">
<td className="p-1 font-mono">{pin.id}</td>
<td className="p-1">{pin.title}</td>
<td className="p-1">{pin.ownerId}</td>
</tr>
))}
</tbody>
</table>
</div>
);
}Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Jak w App Routerze dodać trasę GET /api/pins/[id]?
2. Skąd handler w app/api/pins/[id]/route.ts bierze id pinu?
Zadania praktyczne w grze
- Klikanie w kolejności
Kliknij elementy, aby zbudować linię, która odpowiada kodem 404, gdy pinu nie ma:
- Układanie w poziomie
Ułóż elementy jednej linii, która zwraca utworzony pin ze statusem 201:
- Edytor kodu
Stwórz REST API endpoints