Automated Mock Server Generation and OpenAPI Contract Stubs

Традиционный подход:
Backend Dev (2 недели) ──(Блокировка)──> Frontend Dev (2 недели) = 4 недели TTM

Contract-First с Синтетическим Mock-сервером:
OpenAPI 3.1 Spec ──┬──> Синтез MSW Mock-сервера ──> Frontend Dev (Параллельно)
                   └──> Backend Implementation  ──> Backend Dev  (Параллельно)
TTM сокращается до 2 недель!

┌────────────────────────────────────────────────────────┐
│ 1. Спецификация API (OpenAPI 3.1 YAML / JSON)          │
└──────────────────────────┬─────────────────────────────┘
                           │ Парсинг схем и путей
                           ▼
┌────────────────────────────────────────────────────────┐
│ 2. AI Synthesis & In-Memory Store Initialization       │
│    - Синтез связанных графов данных (Users -> Posts)   │
│    - Создание реляционного Stateful Store в RAM        │
└──────────────────────────┬─────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────┐
│ 3. MSW v2 Dynamic Handler Matrix                       │
│    - Перехват: http.get, http.post, http.delete        │
│    - Чтение / Мутация записей в Stateful Store         │
└──────────────────────────┬─────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────┐
│ 4. Network Chaos & Scenario Middleware                 │
│    - Симуляция сетевой задержки: Jitter 150-600 мс     │
│    - Инжекция 4xx/5xx кодов по x-mock-scenario        │
└──────────────────────────┬─────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────┐
│ 5. Клиентское приложение (Next.js 15 / React 19 UI)   │
│    - Реальные fetch() / SWR / TanStack Query           │
│    - Нулевые изменения в production-коде               │
└────────────────────────────────────────────────────────┘

import { http, HttpResponse, delay } from "msw";
import { z } from "zod";

// Схема валидации создания статьи блога
export const ArticleSchema = z.object({
  id: z.string().uuid(),
  title: z.string().min(3).max(120),
  slug: z.string().min(3),
  content: z.string(),
  authorId: z.string().uuid(),
  createdAt: z.string().datetime(),
  status: z.enum(["draft", "published", "archived"]),
});

export type Article = z.infer<typeof ArticleSchema>;

// Схема создания (входной DTO)
export const CreateArticleInputSchema = ArticleSchema.omit({
  id: true,
  createdAt: true,
});

export type CreateArticleInput = z.infer<typeof CreateArticleInputSchema>;

/**
 * Stateful In-Memory Entity Store
 * Сохраняет состояние сущностей между HTTP-запросами в рамках сессии
 */
class InMemoryDatabase {
  private articles = new Map<string, Article>();

  constructor() {
    // Начальное наполнение синтетическими данными
    this.seed();
  }

  private seed(): void {
    const defaultArticle: Article = {
      id: "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      title: "Архитектура Next.js 15 и серверные компоненты",
      slug: "nextjs-15-rsc-architecture",
      content: "Глубокий разбор React Server Components и потокового рендеринга...",
      authorId: "u9f8e7d6-c5b4-3a21-0fed-cba987654321",
      createdAt: new Date("2026-01-15T10:00:00Z").toISOString(),
      status: "published",
    };
    this.articles.set(defaultArticle.id, defaultArticle);
  }

  public list(): Article[] {
    return Array.from(this.articles.values());
  }

  public getById(id: string): Article | undefined {
    return this.articles.get(id);
  }

  public create(input: CreateArticleInput): Article {
    const id = crypto.randomUUID();
    const article: Article = {
      ...input,
      id,
      createdAt: new Date().toISOString(),
    };
    this.articles.set(id, article);
    return article;
  }

  public delete(id: string): boolean {
    return this.articles.delete(id);
  }
}

export const db = new InMemoryDatabase();

/**
 * Конфигурация задержек и сценариев хаос-тестирования
 */
async function simulateNetworkConditions(request: Request): Promise<HttpResponse | null> {
  // 1. Имитация джиттера сети (от 150 до 450 мс)
  const jitterMs = Math.floor(Math.random() * 300) + 150;
  await delay(jitterMs);

  // 2. Инжекция управляемых сбоев через кастомные HTTP-заголовки
  const chaosHeader = request.headers.get("x-mock-scenario");
  if (chaosHeader === "network_error") {
    return HttpResponse.error();
  }
  if (chaosHeader === "rate_limited") {
    return new HttpResponse(
      JSON.stringify({ error: "Too Many Requests", retryAfter: 30 }),
      { status: 429, headers: { "Content-Type": "application/json" } }
    );
  }
  if (chaosHeader === "internal_error") {
    return new HttpResponse(
      JSON.stringify({ error: "Internal Database Connection Timeout" }),
      { status: 500, headers: { "Content-Type": "application/json" } }
    );
  }

  return null;
}

/**
 * MSW v2 Handlers Matrix
 */
export const handlers = [
  // GET /api/v1/articles - Список всех статей
  http.get("/api/v1/articles", async ({ request }) => {
    const errorResponse = await simulateNetworkConditions(request);
    if (errorResponse) return errorResponse;

    const url = new URL(request.url);
    const statusFilter = url.searchParams.get("status");

    let articles = db.list();
    if (statusFilter) {
      articles = articles.filter((a) => a.status === statusFilter);
    }

    return HttpResponse.json({ data: articles, total: articles.length });
  }),

  // GET /api/v1/articles/:id - Получение по ID
  http.get("/api/v1/articles/:id", async ({ request, params }) => {
    const errorResponse = await simulateNetworkConditions(request);
    if (errorResponse) return errorResponse;

    const { id } = params;
    if (typeof id !== "string") {
      return HttpResponse.json({ error: "Некорректный ID" }, { status: 400 });
    }

    const article = db.getById(id);
    if (!article) {
      return HttpResponse.json(
        { error: `Статья с ID ${id} не найдена` },
        { status: 404 }
      );
    }

    return HttpResponse.json({ data: article });
  }),

  // POST /api/v1/articles - Создание новой статьи
  http.post("/api/v1/articles", async ({ request }) => {
    const errorResponse = await simulateNetworkConditions(request);
    if (errorResponse) return errorResponse;

    let payload: unknown;
    try {
      payload = await request.json();
    } catch {
      return HttpResponse.json(
        { error: "Невалидный JSON полезной нагрузки" },
        { status: 400 }
      );
    }

    const validation = CreateArticleInputSchema.safeParse(payload);
    if (!validation.success) {
      return HttpResponse.json(
        {
          error: "Ошибка валидации контракта OpenAPI",
          details: validation.error.flatten(),
        },
        { status: 422 }
      );
    }

    const created = db.create(validation.data);
    return HttpResponse.json({ data: created }, { status: 201 });
  }),

  // DELETE /api/v1/articles/:id - Удаление статьи
  http.delete("/api/v1/articles/:id", async ({ request, params }) => {
    const errorResponse = await simulateNetworkConditions(request);
    if (errorResponse) return errorResponse;

    const { id } = params;
    if (typeof id !== "string") {
      return HttpResponse.json({ error: "Некорректный ID" }, { status: 400 });
    }

    const deleted = db.delete(id);
    if (!deleted) {
      return HttpResponse.json({ error: "Статья не найдена" }, { status: 404 });
    }

    return new HttpResponse(null, { status: 204 });
  }),
];

import { setupWorker } from "msw/browser";
import { handlers } from "./handlers/stateful-api";

// Экземпляр Service Worker для браузерного контура
export const worker = setupWorker(...handlers);

export async function initMocks(): Promise<void> {
  if (typeof window === "undefined") {
    return;
  }

  // Активация моков только в dev-режиме или при тестировании
  if (process.env.NODE_ENV === "development" || process.env.NEXT_PUBLIC_ENABLE_MOCKS === "true") {
    await worker.start({
      onUnhandledRequest: "bypass", // Пропуск немокированных запросов (шрифты, статика)
      serviceWorker: {
        url: "/mockServiceWorker.js",
      },
    });
    console.log("[MSW v2] Синтетический Stateful Mock Server успешно активирован.");
  }
}