Systemy rozproszone z pomocą AI

Twój serwis checkout zwraca sporadyczne błędy 500. Logi pokazują, że serwis płatności odpowiada poprawnie, ale serwis zamówień przekracza timeout czekając na zdarzenie, które serwis inwentarza powinien był opublikować. Trzy serwisy, trzy repozytoria, trzy różne zespoły — a narzędzie AI, którego używasz, widzi tylko jedno otwarte repozytorium. Debugowanie systemów rozproszonych z AI wymaga fundamentalnie innego podejścia niż rozwój jednoserwisowy.

Co wyniesiesz z tego rozdziału

Przepływy pracy kontraktowe, w których AI generuje i waliduje interfejsy serwisów
Strategie debugowania cross-serwisowego działające w ramach ograniczeń kontekstu jednego narzędzia
Wzorce koordynowania migracji schematów przez granice serwisów
Techniki analizy rozproszonego tracingu wspomaganej AI
Prompty do generowania spójnej obsługi błędów w serwisach

Problem kontekstu rozproszonego

Mikroserwisy dzielą twój system na repozytoria, języki i zespoły. Narzędzia AI widzą jedno repozytorium na raz. Rozwiązanie: zakoduj kontrakty i konwencje cross-serwisowe w każdym repozytorium, aby AI zawsze miało potrzebny kontekst integracyjny.

Rozwój kontraktowy

Definiuj kontrakty serwisów przed pisaniem kodu implementacyjnego. Narzędzia AI doskonale radzą sobie z generowaniem implementacji z dobrze zdefiniowanych interfejsów.

Przechowuj definicje kontraktów w repozytorium serwisu i odwołuj się do nich jawnie:

This service (order-service) communicates with:
- payment-service: REST API, OpenAPI spec at /contracts/payment-api.yaml
- inventory-service: Events via RabbitMQ, schemas at /contracts/inventory-events.json
- notification-service: Events via RabbitMQ, schemas at /contracts/notification-events.json

When implementing any integration:
1. Always read the relevant contract file first
2. Generate client code from the contract, do not hand-write it
3. Include retry logic with exponential backoff for all HTTP calls
4. Include dead-letter queue handling for all event consumers

Użyj @contracts/payment-api.yaml, aby wciągnąć kontekst kontraktu do konwersacji.

Claude Code może czytać pliki kontraktów bezpośrednio i generować implementacje:

Microservice: order-service
Contracts directory: /contracts/
- payment-api.yaml (OpenAPI 3.1) - payment-service REST API
- inventory-events.json (AsyncAPI 2.6) - inventory-service event schemas
- notification-events.json (AsyncAPI 2.6) - notification-service events

Integration rules:
- All HTTP clients must use the generated SDK in /src/clients/
- Regenerate clients when contracts change: npm run generate-clients
- All event publishers must validate against the schema before publishing
- Circuit breaker pattern required for all external service calls

Codex może uzyskiwać dostęp do wielu repozytoriów poprzez integrację z GitHub:

This is part of a microservices architecture. Related repos:
- org/payment-service - Payment processing
- org/inventory-service - Stock management
- org/notification-service - User notifications

Shared contracts are in org/service-contracts repo.
When making changes that affect service boundaries:
1. Check the contract in org/service-contracts first
2. Update the contract if needed (creates PR to service-contracts)
3. Implement the change in this service
4. Note any downstream services that need updates

Gotowy prompt do kontraktowego rozwoju serwisów:

I need to add a refund endpoint to the payment service. Work contract-first:
1. Read the existing OpenAPI spec at /contracts/payment-api.yaml
2. Add a POST /payments/{paymentId}/refund endpoint to the spec with:
   - Request body: { amount: number, reason: string, idempotencyKey: string }
   - Response 200: { refundId: string, status: "pending" | "completed", amount: number }
   - Response 404: Payment not found
   - Response 409: Refund already exists for this idempotency key
   - Response 422: Amount exceeds original payment
3. Generate the Express route handler from the contract
4. Generate the client SDK method from the contract
5. Generate integration test stubs from the contract

Show me the updated contract before generating any implementation code.

Debugowanie cross-serwisowe

Strategia: Debugowanie oparte na trace

Gdy problem rozproszony obejmuje serwisy, pracuj od trace wstecz.

Gotowy prompt do debugowania rozproszonego:

I have a distributed trace showing this sequence:
1. web-gateway receives POST /checkout (200ms)
2. order-service creates order (150ms)
3. payment-service charges card (800ms, success)
4. inventory-service.reserve event published (50ms)
5. inventory-service.reserve event consumed (TIMEOUT after 30s)
6. order-service times out waiting for inventory confirmation

The inventory service logs show the event was received but processing hung.
Analyze our inventory service event consumer at /src/consumers/reserve.consumer.ts
and identify:
- Where the processing could hang (database locks, external calls, deadlocks)
- Why it only fails intermittently (race conditions, connection pool exhaustion)
- What observability we're missing (metrics, structured logs, health checks)

Strategia: Wykrywanie naruszeń kontraktów

Narzędzia AI mogą weryfikować, czy serwisy dotrzymują swoich kontraktów, nawet gdy masz dostęp tylko do jednej strony.

Compare our order-service HTTP client for the payment service
against the payment-api.yaml contract:
1. Are we handling all documented error codes?
2. Are we sending all required headers?
3. Are we respecting rate limits and timeouts from the spec?
4. Are there any fields we're ignoring in responses that we should handle?

claude "Read /contracts/payment-api.yaml and /src/clients/payment-client.ts.
Perform a contract compliance audit:
- List every endpoint in the contract and whether our client implements it
- Check error handling for every documented error response
- Verify request/response types match the schema
- Check timeout and retry configurations against SLA requirements
Output as a compliance checklist with pass/fail for each item."

Audit contract compliance for the order-service against all its upstream contracts.
For each contract in /contracts/:
1. Find the corresponding client implementation in /src/clients/
2. Verify every endpoint, error code, and schema field is handled
3. Check for missing retry logic, circuit breakers, and timeout handling
4. Create issues for any violations found

Rozproszone migracje schematów

Zmiana formatu danych, który przekracza granice serwisów, wymaga koordynacji.

Zdefiniuj nową wersję schematu

Dodaj nowy schemat obok starego. Jeszcze go nie zastępuj.
Zaktualizuj producentów, aby publikowali obie wersje

Serwis produkujący wysyła zdarzenia w obu formatach — starym i nowym — w okresie przejściowym.
Zaktualizuj konsumentów, aby akceptowali obie wersje

Każdy konsumujący serwis obsługuje obie wersje schematu elegancko.
Zweryfikuj, że wszyscy konsumenci zostali zaktualizowani

Monitoruj, czy żaden serwis nie konsumuje jeszcze starego formatu.
Usuń stary schemat

Dopiero po migracji wszystkich konsumentów, przestań produkować stary format i usuń go.

Gotowy prompt do rozproszonej migracji schematu:

I need to add a `currency` field to the PaymentCompleted event that's consumed by
order-service, notification-service, and analytics-service.

Generate a backward-compatible migration plan:
1. Update the event schema in /contracts/payment-events.json to v2 with currency field
2. Modify the payment-service publisher to emit both v1 and v2 events
3. Generate a v2 event consumer that handles both versions (check for currency field, default to "USD" if missing)
4. Create a test that verifies backward compatibility with v1 events
5. Add a metric to track which consumers are still on v1

Start with the contract change and show me before proceeding.

Service Mesh i obserwowalność

Konfiguracja obserwowalności wspomagana AI

Gotowy prompt do scaffoldingu obserwowalności:

Set up distributed tracing for our Express-based microservice:
1. Add OpenTelemetry instrumentation with automatic trace propagation
2. Include custom spans for: database queries, external HTTP calls, message queue operations
3. Add structured logging with trace ID correlation (use pino)
4. Create a health check endpoint that verifies all downstream dependencies
5. Add Prometheus metrics for: request duration, error rate, active connections, queue depth

Follow our existing patterns in /src/middleware/ for consistency.
Include the Docker Compose configuration for a local Jaeger instance.

Kiedy coś się psuje

“AI nie rozumie naszych granic serwisów.” Potrzebujesz plików CLAUDE.md lub .cursor/rules per serwis, które jawnie dokumentują, z czym ten serwis się komunikuje i jak. Bez tego AI traktuje każdy serwis jako samodzielną aplikację.

“Zmiany kontraktów łamią serwisy downstream w produkcji.” Pominąłeś fazę podwójnej publikacji. Zawsze uruchamiaj obie wersje schematu jednocześnie podczas migracji. Użyj metryk śledzenia wersji, aby zweryfikować, że wszyscy konsumenci zmigrowali przed usunięciem starej wersji.

“AI generuje kod klienta, który nie pasuje do kontraktu.” Regeneruj klientów z kontraktów, nie pisz ich ręcznie. Dodaj walidację kontraktów do swojego pipeline CI: npm run validate-contracts powinno łamać build, jeśli implementacje odchodzą od specyfikacji.

“Debugowanie rozproszone trwa wieczność nawet z AI.” Najpierw zainwestuj w infrastrukturę obserwowalności. Narzędzia AI stają się dramatycznie bardziej skuteczne, gdy mogą analizować ustrukturyzowane trace i skorelowane logi, zamiast składać w całość osobne pliki logów.

Co dalej

Monitorowanie i obserwowalność Konfiguruj kompleksowe logowanie, metryki i tracing w serwisach.

Reagowanie na incydenty Przepływy pracy dyżurów wspomagane AI dla awarii systemów rozproszonych.

Testowanie API Testowanie kontraktowe i automatyzacja API przez granice serwisów.