Rozwój API z Codex

Musisz zbudować nowe API do zarządzania zaproszeniami zespołowymi. Wymaga pięciu endpointów, walidacji danych wejściowych, middleware uwierzytelniania, limitowania zapytań, zapytań bazodanowych, powiadomień e-mail i kompleksowych testów. Specyfikacja mówi “dwa dni”. Mógłbyś przebijać się przez to sekwencyjnie. Albo mógłbyś zaplanować API w IDE, zeszkicować trasy w lokalnym wątku, napisać testy w równoległym worktree i zlecić Codex generowanie specyfikacji OpenAPI, podczas gdy ty przeglądasz logikę biznesową.

Czego się nauczysz

• Równoległy przepływ rozwoju API: szkicowanie tras, pisanie testów i generowanie dokumentacji jednocześnie
• Prompty do budowania endpointów z właściwą walidacją, obsługą błędów i middleware
• Techniki testowania API w Codex CLI z wbudowanym wykonywaniem poleceń
• Wzorzec utrzymywania specyfikacji OpenAPI zsynchronizowanej z implementacją za pomocą automatyzacji

Przepływ pracy

Krok 1: Najpierw zaprojektuj kontrakt API

Zacznij w rozszerzeniu IDE lub aplikacji Codex z promptem projektowym. Ustalenie kształtu API przed pisaniem kodu zapobiega kosztownym przeróbkom.

Wskazówka

Prompt do skopiowania — projektowanie API:

Design a REST API for team invitation management. Requirements:

- Create invitation (POST): send invite to email address with role assignment
- List invitations (GET): paginated, filterable by status (pending, accepted, expired)
- Resend invitation (POST): resend email for pending invitations
- Accept invitation (POST): accept via token (unauthenticated endpoint)
- Revoke invitation (PUT): cancel a pending invitation

For each endpoint, define:
1. HTTP method and path (following REST conventions)
2. Request body or query parameters with types
3. Response shape for success and each error case
4. Authentication requirements
5. Rate limiting rules

Output as an OpenAPI 3.1 YAML spec. Be opinionated about the design -- do not use generic placeholder names.

Przejrzyj specyfikację i iteruj przed implementacją. To stanie się twoim kontraktem.

Krok 2: Szkicuj trasy w lokalnym wątku

Z zdefiniowanym kontraktem API, zeszkicuj właściwe handlery endpointów. Użyj trybu Local, ponieważ chcesz pliki w swoim katalogu roboczym.

Wskazówka

Prompt do skopiowania — szkicowanie API:

Implement the team invitation API based on the OpenAPI spec we just designed.

For each endpoint, create:
1. Route handler in src/routes/invitations/
2. Zod schema for request validation in src/routes/invitations/schemas.ts
3. Service function in src/services/invitations.ts for business logic
4. Database queries in src/lib/db/queries/invitations.ts using Drizzle ORM

Patterns to follow:
- Read existing routes in src/routes/ for handler patterns
- Use the auth middleware from src/middleware/auth.ts
- Use the validate middleware for Zod schema validation
- Return consistent error responses: { error: string, details?: object }
- Use structured logging, not console.log

Do NOT implement the email sending logic yet. Stub it with a TODO comment.
Do NOT write tests yet. We will do that in a separate worktree.

Run the type checker after implementation. Fix any type errors.

Po wygenerowaniu plików przez Codex przejrzyj je w panelu recenzji aplikacji. Dodaj do staging i commituj szkic przed przejściem do równoległej pracy.

Krok 3: Pisz testy w równoległym worktree

Utwórz wątek Worktree oparty na gałęzi z twoimi zeszkicowanymi trasami. Agent testowy działa w pełnej izolacji — może wielokrotnie uruchamiać zestaw testów bez ingerencji w twój lokalny development.

Wskazówka

Prompt do skopiowania — generowanie testów API:

Write comprehensive tests for the team invitation API endpoints:

Unit tests (tests/unit/services/invitations.test.ts):
- Test each service function with mocked database
- Cover validation logic: valid inputs, missing fields, invalid email formats, expired tokens
- Cover business logic: duplicate invitations, revoking accepted invitations, self-invitation prevention

Integration tests (tests/integration/invitations.test.ts):
- Test each endpoint with supertest against a real database
- Test authentication: valid token, missing token, insufficient permissions
- Test pagination: page size, offset, total count
- Test status filtering: pending only, accepted only, all
- Test rate limiting: exceed the limit and verify 429 response

Follow existing test patterns in tests/. Set up and tear down test data properly.
Run all tests after writing them. Fix any failures.

Krok 4: Testuj endpointy interaktywnie w CLI

CLI jest doskonałe do szybkiego testowania API, ponieważ możesz wykonywać polecenia inline. Uruchom Codex z serwerem dev działającym w innym terminalu:

codex

Następnie testuj swoje endpointy interaktywnie:

Wskazówka

Prompt do skopiowania — interaktywne testowanie endpointów:

The dev server is running on localhost:3000. Test the invitation API:

1. Create a test user and get an auth token
2. POST /api/invitations with a valid invitation
3. POST /api/invitations with the same email (should fail with duplicate error)
4. GET /api/invitations to list all invitations
5. POST /api/invitations/:id/resend for the pending invitation
6. Try accepting with an invalid token (should fail)

Use curl for each request and show me the responses. Flag anything unexpected.

CLI wykonuje polecenia curl bezpośrednio i pokazuje ci odpowiedzi. To interaktywne testowanie łapie problemy, których testy jednostkowe nie wykryją — kolejność middleware, wymagania nagłówków, niespójności formatu odpowiedzi.

Krok 5: Generuj specyfikację OpenAPI z implementacji

Po przetestowaniu i uruchomieniu API wygeneruj (lub zaktualizuj) specyfikację OpenAPI z faktycznej implementacji:

Wskazówka

Prompt do skopiowania — generowanie OpenAPI:

Generate an OpenAPI 3.1 spec from the implemented invitation API routes in src/routes/invitations/.

Read the actual Zod schemas for request/response types.
Read the route handlers for HTTP methods, paths, and status codes.
Read the auth middleware for security scheme definitions.

Output as api/openapi.yaml. Include realistic examples in each endpoint.
Verify the spec is valid by checking the structure against the OpenAPI 3.1 standard.

Skonfiguruj automatyzację, aby utrzymywać specyfikację zsynchronizowaną:

Wskazówka

Prompt automatyzacji do skopiowania — wykrywanie dryfu OpenAPI:

Compare the OpenAPI spec in api/openapi.yaml against the actual route handlers and Zod schemas in src/routes/. If any endpoints, parameters, or response shapes have changed since the spec was last generated, update the spec to match. If the spec is current, report that no changes are needed.

Kiedy to nie działa

Schematy Zod i schemat bazy danych rozjeżdżają się. Jeśli definiujesz schematy walidacji Zod oddzielnie od schematu Drizzle ORM, mogą się rozjechać. Powiedz Codex: “Derive Zod schemas from the Drizzle schema types where possible. Do not duplicate type definitions.”

Testy przechodzą lokalnie, ale nie w worktree. Dzieje się tak, gdy baza danych worktree nie została skonfigurowana. Upewnij się, że twój skrypt konfiguracji lokalnego środowiska uruchamia migracje bazy danych. Sprawdź zintegrowany terminal (Cmd + J) pod kątem błędów skryptu konfiguracyjnego.

Testy limitowania zapytań są niestabilne. Testy limitów zapytań zależne od czasu są z natury niestabilne. Powiedz Codex: “For rate limiting tests, send requests in a tight loop without delays, and verify the status code switches from 200 to 429 after the configured limit. Do not rely on time-based windows in tests.”

Wygenerowana specyfikacja OpenAPI nie odpowiada oczekiwaniom konkretnego konsumenta. Codex generuje specyfikację z twojego kodu, ale konsumenci twojego API mogą oczekiwać innych nazw pól lub kształtów odpowiedzi. Po wygenerowaniu przejrzyj specyfikację pod kątem faktycznych wymagań konsumentów. Uwzględnij ograniczenia specyficzne dla konsumenta w wytycznych przeglądu AGENTS.md.

Co dalej

Operacje bazodanowe z Codex Zbuduj warstwę bazodanową zasilającą twoje endpointy API

Generowanie dokumentacji Generuj kompleksową dokumentację API równolegle z implementacją