Руководство по генератору серверов

Содержание

1. Обзор
2. Установка
3. Предварительные требования
4. Быстрый старт: пример от начала до конца
5. Архитектура
6. Режимы работы
7. Общие флаги CLI
8. OpenAPI генератор
9. gRPC генератор
10. MCP генератор
11. GraphQL генератор
12. SOAP генератор
13. Kafka генератор
14. RabbitMQ генератор
15. SSE генератор
16. Socket генератор
17. SMTP генератор
18. Импорт HAR
19. Стратегия умного слияния
20. Режим оркестратора
21. Экспериментальный UI
22. Переменные окружения сгенерированных серверов
23. UI сгенерированных серверов и кеширование
24. Структура вывода и офлайн-сборка
25. Сборка Docker-образа
26. Примеры CI/CD пайплайнов
27. Примеры моков
28. Ограничения

Обзор

Что такое «сгенерированный сервер»?

Представьте Mockarty как мозг, который знает, как отвечать на запросы, а сгенерированный сервер — как переводчика, говорящего на конкретном протоколе. Например, если ваше приложение общается по gRPC, вы генерируете gRPC-сервер, который переводит gRPC-вызовы в формат, понятный Mockarty. Сгенерированный сервер — это небольшая автономная программа, которую можно запустить где угодно: она принимает запросы на своём родном протоколе (gRPC, Kafka, SOAP и т.д.), спрашивает у Mockarty «что мне ответить?» и возвращает ответ. Таким образом, вы можете мокировать любой протокол, не написав ни строчки протокол-специфичного кода.

Mockarty Server Generator — это единый бинарный файл (mockarty-server-generator) для генерации кода, поддерживающий 10 типов протоколов. Из одного бинарника можно генерировать standalone Go-серверы, создавать моки через API или управлять множеством серверов через UI оркестратора.

Генераторы делятся на две категории:

• Генераторы на основе спецификаций (OpenAPI, gRPC, MCP, GraphQL, SOAP) — генерируют серверы из спецификаций протоколов и могут автоматически создавать моки из спецификации через флаг -create-mocks.
• Адаптеры на основе конфигурации (Kafka, RabbitMQ, SSE, Socket, SMTP) — генерируют серверы из JSON/YAML конфигурации. Эти адаптеры подключаются к реальной инфраструктуре (например, Kafka-брокерам, RabbitMQ) или предоставляют протокольные эндпоинты (SSE, WebSocket, SMTP) и резолвят ответы моков через Mockarty. Моки для адаптеров необходимо создавать вручную через UI или API Mockarty.

Каждый сгенерированный сервер подключается к HTTP-ноде Mockarty (admin или resolver) для резолвинга моков. Сгенерированные серверы — это полностью автономные Go-программы со встроенным UI, вендорированными зависимостями и опциональным высокопроизводительным кешированием.

URL-адреса в примерах: Во всех примерах используется localhost:5770 как адрес Mockarty по умолчанию. Если ваш экземпляр работает на удалённом сервере, замените localhost:5770 на реальный адрес (например, https://mockarty.company.com или http://192.168.1.50:5770). Подробнее — в разделе Полезные функции и советы.

Поддерживаемые протоколы

Установка

Скачайте готовый бинарник mockarty-server-generator для вашей платформы со страницы релизов на GitHub.

# Linux / macOS
chmod +x mockarty-server-generator

# Проверка
./mockarty-server-generator --help

Бинарник самодостаточен и не требует дополнительных зависимостей.

Предварительные требования

Перед использованием генератора серверов убедитесь, что у вас есть:

Запущенный экземпляр Mockarty

Запущенная административная нода Mockarty обязательна. Сгенерированные серверы не работают автономно — они обращаются к HTTP-ноде Mockarty для резолвинга моков при каждом запросе.

# Проверка доступности Mockarty
curl http://localhost:5770/health

Если Mockarty ещё не запущен, следуйте Руководству по быстрому старту.

Go SDK (для сборки сгенерированных серверов)

Генератор создаёт исходный код на Go с вендорированными зависимостями. Для сборки сгенерированного сервера в бинарный файл необходим Go SDK:

• Минимальная версия: Go 1.21+
• Скачать: https://go.dev/dl/

# Проверка установки Go
go version
# go version go1.24.1 linux/amd64

Почему Go? Сгенерированные серверы — это программы на Go, потому что Go компилируется в единый статический бинарник без runtime-зависимостей, с быстрым стартом, низким потреблением памяти и встроенной поддержкой конкурентности. Знать Go не нужно — просто выполните go build и используйте бинарник.

Нет Go? Если установить Go невозможно, используйте Режим оркестратора — он собирает и запускает сгенерированные серверы автоматически, или используйте Docker (см. Сборка Docker-образа).

Требования к лицензии

Создание моков (флаг -create-mocks) и режимы orchestrator/experimental-ui требуют валидной лицензии Mockarty с включённой функцией mock.

Проверьте лицензию в Настройки > Лицензия в веб-интерфейсе Mockarty или через API:

curl -H "Authorization: Bearer mk_your_token" http://localhost:5770/api/v1/license

API-токен

Для создания моков нужен пользовательский API-токен (формат mk_*). Создайте его в Настройки > API-токены в веб-интерфейсе Mockarty.

Быстрый старт: пример от начала до конца

Этот пример проведёт вас от OpenAPI-спецификации до работающего мок-сервера за 5 минут.

Шаг 1: Генерация сервера и создание моков

./mockarty-server-generator openapi \
  -input https://petstore3.swagger.io/api/v3/openapi.json \
  -output ./petstore-server/server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token_here \
  -namespace sandbox \
  -tags "petstore,demo"

Эта команда одновременно:

• Создаёт определения моков в Mockarty (пространство имён sandbox)
• Генерирует полный Go-проект в ./petstore-server/

Шаг 2: Сборка бинарника

cd petstore-server
go build -mod=vendor -o petstore-server .

Флаг -mod=vendor указывает Go использовать вендорированные зависимости (интернет не нужен).

Шаг 3: Запуск сервера

HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
./petstore-server

Шаг 4: Тестирование

# Swagger UI
open http://localhost:8080/swagger/

# Проверка здоровья
curl http://localhost:8080/health

# Вызов замоканного эндпоинта
curl http://localhost:8080/pet/1

Сгенерированный сервер принимает запрос, отправляет его в Mockarty для резолвинга мока и возвращает найденный ответ.

Что вы получаете

petstore-server/
├── server.go        # ~5000 строк сгенерированного Go-кода
├── go.mod           # Определение Go-модуля
├── go.sum           # Контрольные суммы зависимостей
├── vendor/          # ВСЕ зависимости (офлайн-сборка)
├── assets/          # Swagger UI JS/CSS
└── webfonts/        # Шрифты иконок

После go build бинарник petstore-server — это единый исполняемый файл (~15-20 МБ), который можно скопировать на любую машину с той же ОС/архитектурой. Никакого Go, никаких зависимостей — ничего больше для запуска не нужно.

Архитектура

Все сгенерированные серверы работают по одному принципу: принимают протокол-специфичный запрос, транслируют его в запрос на резолвинг мока к HTTP-ноде Mockarty и возвращают ответ мока клиенту.

Эндпоинты резолвинга моков

Проксирование

Когда у мока настроен proxy.target, проксирование всегда выполняется на стороне HTTP-ноды Mockarty, а не в сгенерированном сервере. Процесс:

1. Сгенерированный сервер отправляет запрос на HTTP-ноду
2. HTTP-нода находит мок с proxy.target
3. HTTP-нода создаёт клиент (MCP, gRPC и т.д.) и вызывает реальный сервис
4. HTTP-нода логирует и возвращает ответ сгенерированному серверу

Режимы работы

Бинарник генератора серверов имеет три режима работы:

Режим 1: Генерация кода сервера

Генерирует standalone Go-файл сервера со всеми вендорированными зависимостями для офлайн-сборки.

mockarty-server-generator openapi \
  -input swagger.json \
  -output server.go \
  -package main

Режим 2: Генерация сервера + создание моков

Генерирует сервер и одновременно создаёт моки на HTTP-ноде Mockarty через API.

mockarty-server-generator openapi \
  -input swagger.json \
  -output server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

Режим 3: Только создание моков (API-First)

Создаёт моки на HTTP-ноде без генерации кода сервера. Полезно для наполнения моков из спецификации, когда standalone-сервер не нужен.

mockarty-server-generator openapi \
  -input swagger.json \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -tags "petstore,v2"

Примечание: Режим -create-mocks требует валидной лицензии с включённой функцией mock на HTTP-ноде Mockarty. Автоматическое создание моков поддерживается только для генераторов на основе спецификаций (OpenAPI, gRPC, MCP, GraphQL, SOAP). Адаптеры на основе конфигурации (Kafka, RabbitMQ, SSE, Socket, SMTP) требуют ручного создания моков через UI или API Mockarty.

Общие флаги CLI

Использование: mockarty-server-generator <тип-генератора> [флаги]

Флаги ввода/вывода

Флаги создания моков

Флаги стратегии обновления

Поведение по умолчанию: Когда -force-update не указан, используется умное слияние — сохраняет пользовательские настройки, обновляя схему из спецификации.

Флаги получения спецификации

Флаги производительности

OpenAPI генератор

Генерирует HTTP REST мок-серверы из спецификаций OpenAPI 2.0 (Swagger) или OpenAPI 3.x.

Входные данные

• Локальный файл JSON или YAML
• URL к спецификации Swagger/OpenAPI (JSON или YAML)

Использование

# Из локального файла
mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -output server.go \
  -package main \
  -http-admin-base-url http://localhost:5770 \
  -namespace sandbox

# Из URL
mockarty-server-generator openapi \
  -input https://petstore3.swagger.io/api/v3/openapi.json \
  -output server.go \
  -package main

# Только создание моков (без кода сервера)
mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -tags "petstore,v3"

# Генерация сервера + создание моков с умным слиянием
mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -output server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

# Принудительная перезапись существующих моков
mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -create-mocks \
  -api-token mk_your_token \
  -force-update

# С декомпозицией тела запроса и условиями по заголовкам
mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -create-mocks \
  -api-token mk_your_token \
  -decompose-request-body \
  -use-headers-as-conditions

Дополнительные опции

• -decompose-request-body — при наличии oneOf/anyOf в теле запроса создаёт отдельный мок для каждого варианта с соответствующими условиями
• -use-headers-as-conditions — генерирует условия из параметров заголовков (напр., Authorization, X-Request-ID)
• -path-prefix — добавляет префикс ко всем маршрутам: namespace/path-prefix/original-route

Возможности сгенерированного сервера

• Встроенный Swagger UI по адресу /swagger/ с оригинальной OpenAPI-спецификацией
• Админ-панель по адресу /ui с обзором сервиса
• Эндпоинт здоровья /health
• Все пути API замаплены на резолвинг моков

gRPC генератор

Генерирует gRPC мок-серверы из .proto файлов. Парсинг proto-файлов идёт динамически через protoreflect — не нужно устанавливать protoc, protoc-gen-go, protoc-gen-go-grpc или любой другой protobuf-тулчейн.

Требования к proto-файлам

Просто передайте Mockarty ваши .proto файлы как есть. Ничего особенного добавлять или менять перед загрузкой не нужно:

• option go_package не обязателен. Если опции нет — Mockarty сгенерирует её автоматически из package и пути к файлу.
• Формат префикса значения не имеет. Если go_package присутствует с любым значением ("/acme/svc", "acme/svc", "example.com/acme/svc;svc" и т.д.), Mockarty нормализует его внутри себя.
• Опции для других языков игнорируются. java_package, php_namespace, csharp_namespace, swift_prefix, objc_class_prefix, ruby_package и подобные вычищаются автоматически — удалять их из ваших файлов не требуется.
• Импорты разрешаются из структуры загруженной директории. Оставьте привычную раскладку файлов. Google well-known типы (google/protobuf/*) и validate/validate.proto встроены и разрешаются автоматически.

Вот и всё — никаких sed-замен, ручных префиксов или настройки плагинов.

Входные данные

• Директория с .proto файлами (или один .proto файл)
• gRPC reflection URL — grpc://host:port или grpc+reflection://host:port (только для создания моков, генерация сервера из reflection пока не поддерживается)

Использование

# Из локальной директории с proto-файлами
mockarty-server-generator grpc \
  -input ./proto/ \
  -output server.go \
  -package main \
  -http-admin-base-url http://localhost:5770 \
  -namespace sandbox

# С именем сервера (важно для матчинга моков в мульти-инстансных сетапах)
mockarty-server-generator grpc \
  -input ./proto/ \
  -output server.go \
  -package main \
  -server-name my-grpc-service

# Только создание моков из proto-файлов
mockarty-server-generator grpc \
  -input ./proto/ \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -server-name my-grpc-service

# Только создание моков из запущенного gRPC-сервера через reflection
mockarty-server-generator grpc \
  -input grpc://localhost:50051 \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -server-name my-grpc-service

Возможности

• Парсинг .proto файлов напрямую через protoreflect — без protoc, плагинов и внешних тулчейнов
• Принимает proto-файлы с опцией go_package и без неё; нормализует автоматически
• Генерация Go-типов inline из proto-сообщений
• Обработка Google well-known типов: Timestamp, Duration, Empty, Struct, Value, wrapper-типы
• validate/validate.proto встроен и резолвится автоматически
• Поддержка gRPC reflection для обнаружения сервисов запущенного сервера (режим создания моков)
• Админ-панель по адресу /ui с браузером сервисов/методов и интерактивной вкладкой Tester

Порты сгенерированного сервера

Ограничения

• Полная поддержка только для унарных методов
• Стриминговые методы поддерживаются базово (без proxy/delay/error)
• Генерация серверного кода из gRPC reflection пока не поддерживается (используйте .proto файлы для генерации кода; reflection работает только в режиме создания моков)
• Проксирование выполняется на стороне HTTP-ноды, а не в сгенерированном сервере

MCP генератор

Генерирует серверы Model Context Protocol из различных входных данных.

Входные данные

1. URL MCP-сервера — подключается к работающему MCP-серверу через интроспекцию для обнаружения инструментов
2. JSON-схема MCP — файл схемы с определением инструментов
3. Swagger/OpenAPI — конвертирует REST-эндпоинты в MCP-инструменты
4. JSON/YAML конфиг — ручное определение инструментов

Использование

# Из работающего MCP-сервера (интроспекция)
mockarty-server-generator mcp \
  -input http://localhost:8910/sse \
  -output server.go \
  -package main

# Из JSON-конфига
mockarty-server-generator mcp \
  -input mcp-server.json \
  -output server.go \
  -package main \
  -http-admin-base-url http://localhost:5770

# Из Swagger-спецификации (конвертация REST в MCP-инструменты)
mockarty-server-generator mcp \
  -input http://localhost:5770/swagger/doc.json \
  -output server.go \
  -package main

# Только создание моков
mockarty-server-generator mcp \
  -input mcp-server.json \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

Формат конфигурации

{
  "server": {
    "name": "example-mcp-server",
    "version": "1.0.0",
    "description": "Описание сервера"
  },
  "tools": [
    {
      "name": "tool_name",
      "description": "Описание инструмента",
      "inputSchema": {
        "type": "object",
        "properties": {
          "param1": {
            "type": "string",
            "description": "Описание параметра"
          }
        },
        "required": ["param1"]
      }
    }
  ],
  "config": {
    "httpAdminBaseUrl": "http://localhost:5770",
    "namespace": "sandbox",
    "transport": "sse"
  },
  "proxy": {
    "target": "http://localhost:5772/mcp"
  }
}

Транспорты

Эндпоинты сгенерированного сервера

• SSE-стрим: http://localhost:8910/sse
• Эндпоинт сообщений: http://localhost:8910/message
• Админ-панель: http://localhost:8080/ui (MCP Tester)
• Здоровье: http://localhost:8080/health

GraphQL генератор

Генерирует GraphQL мок-серверы из файлов схемы, URL (интроспекция) или JSON/YAML конфигов.

Входные данные

1. .graphql / .gql файлы — локальные файлы GraphQL-схемы (SDL)
2. URL — подключается к работающему GraphQL-эндпоинту и выполняет интроспекцию
3. Директория — сканирует все .graphql/.gql файлы и объединяет их
4. JSON/YAML конфиг — конфигурация с определением схемы

Использование

# Из файла GraphQL-схемы
mockarty-server-generator graphql \
  -input ./schema.graphql \
  -output server.go \
  -package main \
  -http-admin-base-url http://localhost:5770 \
  -namespace sandbox

# Из работающего GraphQL-эндпоинта (интроспекция)
mockarty-server-generator graphql \
  -input http://localhost:4000/graphql \
  -output server.go \
  -package main

# Из директории с несколькими файлами схемы
mockarty-server-generator graphql \
  -input ./schemas/ \
  -output server.go \
  -package main

# Только создание моков
mockarty-server-generator graphql \
  -input ./schema.graphql \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -tags "graphql,v1"

Возможности

• Пакетное создание моков с оптимизацией параллельных обновлений
• Режимы умного слияния и принудительного обновления
• Поддержка queries и mutations
• Админ-панель по адресу /ui с GraphQL Playground (интерактивный эксплорер с автодополнением)
• Интроспекция схемы по адресу /graphql

Порты сгенерированного сервера

SOAP генератор

Генерирует SOAP мок-серверы из WSDL-определений с опциональным обогащением XSD.

Входные данные

• WSDL файл (локальный)
• WSDL URL
• Директория с WSDL/XSD файлами (автоматическое обнаружение XSD-импортов)

Использование

# Из WSDL файла
mockarty-server-generator soap \
  -input ./service.wsdl \
  -output server.go \
  -package main

# Из WSDL URL
mockarty-server-generator soap \
  -input http://example.com/service?wsdl \
  -output server.go \
  -package main

# Только создание моков
mockarty-server-generator soap \
  -input ./service.wsdl \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

Важно: двухпортовая архитектура

Сгенерированные SOAP-серверы используют два отдельных HTTP-порта, потому что SOAP-эндпоинт использует wildcard-маршрут (/*path), который конфликтует со статическими маршрутами:

Запуск

HTTP_PORT=8080 ADMIN_PORT=8081 ./soap_server

Возможности

• Парсинг WSDL 1.1 с разрешением XSD-импортов
• Встроенный SOAP Tester UI по адресу /ui (на порту админки)
• Матчинг запросов по заголовку SOAPAction и пути
• Эндпоинт здоровья /health (на порту админки)

Kafka генератор

Генерирует Kafka-адаптер, который подключается к реальному кластеру Apache Kafka, потребляет сообщения из указанных топиков и резолвит ответы моков через HTTP-ноду Mockarty. Сгенерированный сервер работает как мост между вашей Kafka-инфраструктурой и движком резолвинга моков Mockarty.

Важно: Kafka-генератор требует работающий кластер Apache Kafka. Сгенерированный сервер подключается к нему как потребитель — он не заменяет и не эмулирует Kafka-брокер. Моки для Kafka необходимо создавать вручную через UI или API Mockarty.

Как поднять реальный Kafka-кластер

Для локальной разработки самые быстрые варианты:

• Docker Compose — одно-нодовый Kafka в KRaft-режиме:

  # docker-compose.kafka.yml
  services:
    kafka:
      image: bitnami/kafka:3.7
      ports:
        - "9092:9092"
      environment:
        KAFKA_CFG_NODE_ID: "1"
        KAFKA_CFG_PROCESS_ROLES: "broker,controller"
        KAFKA_CFG_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
        KAFKA_CFG_ADVERTISED_LISTENERS: "PLAINTEXT://localhost:9092"
        KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: "1@localhost:9093"
        KAFKA_CFG_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
        KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
        ALLOW_PLAINTEXT_LISTENER: "yes"
  

  Запуск: docker compose -f docker-compose.kafka.yml up -d. В конфигурации генератора укажите localhost:9092.

• Testcontainers — для CI-тестов оборачивайте Kafka-контейнер в setup теста (см. testcontainers-go Kafka module). Адаптер получит динамически выделенный адрес.

• Существующий dev-кластер — направьте генератор на любой доступный Kafka-кластер; сгенерированному серверу нужны только сетевой доступ и ACL для топиков консьюмер-группы, к которой он подключается.

Конфигурация

{
  "server": {
    "name": "my-kafka-server",
    "version": "1.0.0"
  },
  "config": {
    "namespace": "sandbox",
    "brokers": ["localhost:9092"],
    "consumerGroup": "mockarty-consumer",
    "autoCommit": true,
    "commitInterval": 5,
    "cacheEnabled": false,
    "serverName": "my-kafka-server"
  },
  "topics": [
    {
      "name": "orders",
      "eventName": "order-created",
      "outputTopic": "order-results"
    },
    {
      "name": "payments",
      "eventName": "payment-processed"
    }
  ]
}

Поля конфигурации:

Использование

# Генерация сервера
mockarty-server-generator kafka \
  -input kafka-server.json \
  -output kafka_server.go \
  -package main \
  -server-name my-kafka-server

Сборка и запуск

# Сборка (офлайн, вендорированные зависимости)
go build -mod=vendor -o kafka_server .

# Запуск
HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
./kafka_server

Возможности

• Подключение к реальному Kafka-кластеру как потребитель (библиотека Sarama)
• Админ-панель по адресу /ui с дашбордом и просмотром сообщений
• Встроенный продюсер для отправки тестовых сообщений
• Резолвинг моков через POST /mock/findKafka на HTTP-ноде

RabbitMQ генератор

Генерирует RabbitMQ-адаптер, который подключается к реальному кластеру RabbitMQ, потребляет сообщения из указанных очередей и резолвит ответы моков через HTTP-ноду Mockarty.

Важно: RabbitMQ-генератор требует работающий экземпляр RabbitMQ. Сгенерированный сервер подключается к нему как потребитель — он не заменяет и не эмулирует RabbitMQ-брокер. Моки для RabbitMQ необходимо создавать вручную через UI или API Mockarty.

Как поднять реальный RabbitMQ

Для локальной разработки:

• Docker Compose — одно-нодовый RabbitMQ с веб-интерфейсом управления:

  # docker-compose.rabbitmq.yml
  services:
    rabbitmq:
      image: rabbitmq:3.13-management
      ports:
        - "5672:5672"   # AMQP
        - "15672:15672" # Management UI
      environment:
        RABBITMQ_DEFAULT_USER: guest
        RABBITMQ_DEFAULT_PASS: guest
  

  Запуск: docker compose -f docker-compose.rabbitmq.yml up -d. В качестве URL укажите amqp://guest:guest@localhost:5672/.

• Testcontainers — см. testcontainers-go RabbitMQ module для эфемерных инстансов в CI.

• Существующий dev-RabbitMQ — подойдёт любой доступный экземпляр; адаптеру нужен пользователь с правами на целевой vhost.

Конфигурация

{
  "server": {
    "name": "my-rabbitmq-server",
    "version": "1.0.0"
  },
  "config": {
    "namespace": "sandbox",
    "url": "amqp://guest:guest@localhost:5672/",
    "prefetchCount": 1,
    "cacheEnabled": false,
    "serverName": "my-rabbitmq-server"
  },
  "queues": [
    {
      "name": "orders-queue",
      "eventName": "order-received",
      "exchange": "orders",
      "routingKey": "orders.#"
    },
    {
      "name": "notifications-queue",
      "eventName": "notification-received"
    }
  ]
}

Поля конфигурации:

Переменная окружения RABBITMQ_URL может переопределить config.url при запуске. URL management API определяется автоматически (порт 15672).

Использование

# Генерация сервера
mockarty-server-generator rabbitmq \
  -input rabbitmq-server.json \
  -output rabbitmq_server.go \
  -package main \
  -server-name my-rabbitmq-server

Сборка и запуск

# Сборка (офлайн, вендорированные зависимости)
go build -mod=vendor -o rabbitmq_server .

# Запуск
HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
RABBITMQ_URL=amqp://guest:guest@localhost:5672/ \
./rabbitmq_server

Возможности

• Подключение к реальному RabbitMQ как потребитель (AMQP 0.9.1)
• Админ-панель по адресу /ui с дашбордом и просмотром сообщений
• Встроенный publisher для отправки тестовых сообщений
• Резолвинг моков через POST /mock/findRabbitMQ на HTTP-ноде

SSE генератор

Генерирует SSE-адаптер из JSON/YAML конфигурации. Сгенерированный сервер предоставляет SSE-эндпоинты, которые резолвят ответы моков через HTTP-ноду Mockarty.

Важно: Моки для SSE необходимо создавать вручную через UI или API Mockarty.

Конфигурация

{
  "server": {
    "name": "my-sse-server",
    "version": "1.0.0"
  },
  "config": {
    "namespace": "sandbox",
    "sseEndpoint": "/sse",
    "port": 8090,
    "cacheEnabled": false
  },
  "events": [
    {
      "name": "notifications",
      "path": "/events/notifications",
      "description": "События уведомлений пользователя"
    },
    {
      "name": "heartbeat",
      "path": "/events/heartbeat",
      "description": "Heartbeat для поддержания соединения"
    }
  ]
}

Использование

# Генерация сервера
mockarty-server-generator sse \
  -input sse-server.json \
  -output sse_server.go \
  -package main

# С префиксом пути
mockarty-server-generator sse \
  -input sse-server.json \
  -output sse_server.go \
  -package main \
  -path-prefix "v1/streams"

Запуск

HTTP_PORT=8080 ./sse_server

Возможности

• SSE-стримы с типом контента text/event-stream
• Админ-панель по адресу /ui с SSE Viewer (мониторинг потоков событий в реальном времени)
• Поддержка префикса пути для организации маршрутов
• Резолвинг моков через SSERequestContext (путь события + имя события)

Socket генератор

Генерирует адаптеры WebSocket, TCP и UDP из JSON/YAML конфигурации. Каждый тип сокета использует свой Go-шаблон для сгенерированного кода. Сгенерированный сервер резолвит ответы моков через HTTP-ноду Mockarty.

Важно: Моки для Socket необходимо создавать вручную через UI или API Mockarty.

Конфигурация WebSocket

{
  "server": {
    "name": "my-ws-server",
    "version": "1.0.0"
  },
  "config": {
    "httpAdminHost": "localhost",
    "httpAdminPort": "5770",
    "namespace": "sandbox",
    "socketType": "websocket",
    "socketPort": 8081,
    "messageFormat": "json",
    "readTimeout": 30,
    "writeTimeout": 30
  }
}

Конфигурация TCP / UDP

{
  "server": {
    "name": "my-tcp-server",
    "version": "1.0.0"
  },
  "config": {
    "httpAdminHost": "localhost",
    "httpAdminPort": "5770",
    "namespace": "sandbox",
    "socketType": "tcp",
    "socketPort": 8080,
    "messageFormat": "json",
    "readTimeout": 30,
    "writeTimeout": 30
  },
  "messageHandlers": [
    {
      "pattern": ".*",
      "handler": "generic"
    }
  ]
}

Замените "socketType": "tcp" на "socketType": "udp" для UDP-серверов.

Использование

# Генерация WebSocket сервера
mockarty-server-generator socket \
  -input ws-server.json \
  -output socket_server.go \
  -package main \
  -server-name my-ws-server

# Генерация TCP сервера
mockarty-server-generator socket \
  -input tcp-server.json \
  -output socket_server.go \
  -package main

Запуск

HTTP_PORT=8080 ./socket_server

Возможности

• WebSocket: Двунаправленная связь со встроенной WebSocket Console по адресу /ui
• TCP: Raw TCP сокет-сервер
• UDP: Raw UDP сокет-сервер
• Резолвинг моков через SocketRequestContext с serverName и eventName

SMTP генератор

Генерирует SMTP-адаптер из JSON/YAML конфигурации для приёма электронной почты с резолвингом ответов через HTTP-ноду Mockarty.

Важно: Моки для SMTP необходимо создавать вручную через UI или API Mockarty.

Конфигурация

{
  "server": {
    "name": "my-smtp-server",
    "version": "1.0.0"
  },
  "config": {
    "namespace": "sandbox",
    "smtpPort": 2525,
    "serverName": "my-smtp-server",
    "cacheEnabled": false
  }
}

Использование

# Генерация сервера
mockarty-server-generator smtp \
  -input smtp-server.json \
  -output smtp_server.go \
  -package main \
  -server-name my-smtp-server

Сборка и запуск

# Сборка (офлайн, вендорированные зависимости)
go build -mod=vendor -o smtp_server .

# Запуск
HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
./smtp_server

Возможности

• SMTP-сервер для приёма электронных писем
• Админ-панель по адресу /ui с просмотром сообщений
• Резолвинг моков через POST /mock/findSmtp на HTTP-ноде
• Настраиваемый SMTP-порт (по умолчанию: 2525)

Импорт HAR

HAR (HTTP Archive) файлы можно импортировать для создания моков и коллекций API-тестов. Эта функция доступна через веб-интерфейс Mockarty, а не через CLI генератора серверов.

Импорт через веб-интерфейс

1. Откройте страницу API Tester в Mockarty
2. Нажмите Import и выберите HAR
3. Загрузите HAR-файл или укажите URL
4. Mockarty парсит записи HAR и создаёт:
   • Коллекцию API Tester со всеми запросами
   • Автоматически сгенерированные тестовые скрипты для каждого запроса (проверки статуса, content-type, заголовков, структуры JSON)
5. Статические ассеты (CSS, JS, изображения, шрифты) автоматически фильтруются

Возможности

• Система замены URL переписывает базовые URL в формат /stubs/{namespace}/path
• Обрабатывает протокол-относительные URL, URL только с хостом, параметры запроса и фрагменты
• Заменяет URL в значениях JSON, HTML-контенте и заголовках

Стратегия умного слияния

Генератор серверов реализует интеллектуальную логику обновления моков, которая используется по умолчанию, когда моки уже существуют.

Поведение по умолчанию: Умное слияние

Когда вы запускаете генератор для спецификации, у которой уже есть моки в Mockarty:

• Сохраняет пользовательские настройки (вручную добавленные payload-ы ответов, условия, приоритеты)
• Обновляет схему (добавляет новые обязательные поля, удаляет поля, удалённые из спецификации)
• Поддерживает откат — если спецификация отменяет изменение, генератор удаляет ранее добавленные поля

Принудительное обновление (-force-update)

Заменяет всё из спецификации. Используйте осторожно — все ручные настройки будут потеряны.

Как работает слияние

Слияние payload-ов — рекурсивно объединяет объекты и массивы ответов:

• Добавляет новые обязательные поля из спецификации
• Удаляет поля, которых больше нет в спецификации
• Сохраняет пользовательские значения для существующих полей

Слияние условий — интеллектуально объединяет условия запросов:

• Сохраняет пользовательские assertions
• Добавляет новые поля из спецификации как условия any (допускает любое значение)
• Удаляет условия для удалённых полей

Пример

Представьте, что у вас есть OpenAPI-спецификация с эндпоинтом /users, и вы вручную добавили условие $.body.role == "admin" к моку. Когда вы перезапускаете генератор с обновлённой спецификацией:

• Умное слияние (по умолчанию): Ваше условие role == "admin" сохраняется. Новые поля из спецификации добавляются как условия any.
• Принудительное обновление: Ваше условие заменяется автоматически сгенерированными из спецификации.

Режим оркестратора

Генератор серверов включает режим оркестратора — веб-сервер с REST API для управления множеством сгенерированных серверов. Оркестратор обрабатывает генерацию серверов, управление жизненным циклом, мониторинг здоровья и хранение состояния.

mockarty-server-generator orchestrator [флаги]

Флаги оркестратора

Флаги интеграции с координатором

Для распределённых развёртываний оркестратор может зарегистрироваться в координаторе Mockarty:

Использование

# Базовый оркестратор
mockarty-server-generator orchestrator \
  -api-token mk_your_token \
  -http-admin-base-url http://localhost:5770

# С настраиваемым диапазоном портов и директорией данных
mockarty-server-generator orchestrator \
  -api-token mk_your_token \
  -port 7770 \
  -data-dir /var/lib/mockarty-orchestrator \
  -port-min 9000 \
  -port-max 9500

# С интеграцией координатора
mockarty-server-generator orchestrator \
  -api-token mk_your_token \
  -coordinator-addr coordinator.example.com:5773 \
  -integration-token mki_your_integration_token \
  -coordinator-tls

REST API

Управление серверами:

Пакетные операции:

Управление кешем:

Прочее:

Пример запроса на генерацию

curl -X POST http://localhost:8888/api/servers/generate \
  -H "Content-Type: application/json" \
  -d '{
    "type": "openapi",
    "name": "petstore-api",
    "input": "/path/to/petstore.yaml",
    "namespace": "sandbox",
    "group": "development",
    "createMocks": true,
    "apiToken": "mk_your_token",
    "tags": ["v3", "test"]
  }'

Ответ:

{
  "jobId": "abc123",
  "status": "pending"
}

Запросить статус задачи:

curl http://localhost:8888/api/jobs/abc123

{
  "jobId": "abc123",
  "status": "completed",
  "progress": 100,
  "serverId": "petstore-api-xyz"
}

Ключевые возможности

• Асинхронная генерация — долгие сборки не блокируют; отслеживайте прогресс по ID задачи
• Мониторинг здоровья — фоновые проверки каждые 30 секунд
• Управление портами — автоматическое выделение из настраиваемого диапазона
• Хранение состояния — сохранение/восстановление через JSON-файлы
• Event bus — SSE-трансляция для обновлений UI в реальном времени
• Группы серверов — организация по окружениям или назначению
• Очистка — автоудаление осиротевших бинарников и неактивных серверов

Экспериментальный UI

Экспериментальный UI — это режим, оборачивающий оркестратор веб-интерфейсом управления с сессионной аутентификацией.

mockarty-server-generator experimental-ui [флаги]

Флаги

Наследует базовые флаги оркестратора (-port, -data-dir, -log-level, -api-token, -http-admin-base-url, -port-min, -port-max), плюс:

Использование

mockarty-server-generator experimental-ui \
  -api-token mk_your_token \
  -port 8888 \
  -username admin \
  -password my_secure_password \
  -http-admin-base-url http://localhost:5770

Веб-интерфейс будет доступен по адресу http://localhost:8888. После входа вы можете:

• Генерировать новые серверы из спецификаций (загрузка файла или URL)
• Запускать, останавливать, перезапускать и мониторить серверы
• Просматривать логи и метрики серверов
• Управлять группами серверов
• Отслеживать события в реальном времени

Примечание: Режим experimental-ui добавляет сессионную аутентификацию (вход/выход) поверх функциональности оркестратора, тогда как режим orchestrator предоставляет API без аутентификации (предназначен для программного доступа или интеграции с внешним слоем аутентификации). Режим orchestrator дополнительно поддерживает флаги интеграции с координатором для распределённых развёртываний.

Переменные окружения сгенерированных серверов

Общие для всех сгенерированных серверов

Протокол-специфичные переменные

UI сгенерированных серверов и кеширование

Каждый сгенерированный сервер содержит встроенный веб-интерфейс и систему кеширования. Эти функции не требуют дополнительной настройки — они встроены в сгенерированный бинарник.

Встроенный веб-интерфейс

Каждый протокол имеет специализированный UI, доступный по /ui (или /swagger/ для OpenAPI):

Общие эндпоинты (все серверы)

Высокопроизводительное кеширование для нагрузочного тестирования

Сгенерированные серверы включают опциональный высокопроизводительный кеш ответов (на основе bigcache, нулевое давление на GC). При включении сервер кеширует ответы моков и возвращает их без обращения к ноде Mockarty, что радикально снижает задержку.

Это предназначено для сценариев нагрузочного/перформанс-тестирования, когда нужно чтобы сгенерированный сервер обрабатывал тысячи запросов в секунду без перегрузки административной ноды Mockarty.

Включение при генерации:

mockarty-server-generator openapi \
  -input ./api.yaml \
  -output server.go \
  -package main \
  -cache-perf-enable

Или включение в рантайме через API:

# Включить кеширование на работающем сервере
curl -X POST http://localhost:8080/cache/enable

# Проверить статистику кеша
curl http://localhost:8080/cache/stats

# Очистить кеш (например, после изменения моков)
curl -X POST http://localhost:8080/cache/clear

# Отключить кеширование
curl -X POST http://localhost:8080/cache/disable

Переменные окружения для настройки кеша:

Типичный сценарий нагрузочного тестирования:

1. Сгенерируйте сервер и создайте моки как обычно
2. Настройте нужные ответы моков в UI Mockarty
3. Включите кеширование: curl -X POST http://server:8080/cache/enable
4. Запустите нагрузочный тест (k6, JMeter, wrk и т.д.) на сгенерированный сервер
5. Кеш отдаёт ответы за микросекунды — без обращений к БД или сети
6. После тестирования отключите кеш: curl -X POST http://server:8080/cache/disable

Структура вывода и офлайн-сборка

Что генерируется

При запуске генератора с -output и -package создаётся полный Go-проект:

petstore-server/
├── server.go              # Сгенерированный код сервера
├── go.mod                 # Определение Go-модуля
├── go.sum                 # Контрольные суммы зависимостей
├── vendor/                # ВСЕ зависимости вендорированы (интернет не нужен!)
├── assets/                # Swagger UI / GraphQL Playground JS, CSS
└── webfonts/              # Иконки Font Awesome

Сборка и запуск

Сгенерированные серверы включают вендорированные зависимости, поэтому их можно собрать полностью офлайн:

cd petstore-server

# Сборка (интернет не требуется!)
go build -mod=vendor -o server .

# Запуск
HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
./server

Вендорированные зависимости

Бинарник генератора серверов включает встроенный бандл vendorfs, содержащий все Go-зависимости, UI-ассеты (Swagger UI, GraphQL Playground, Font Awesome) и файлы модулей. Это означает:

• Не нужно запускать go mod download после генерации
• Работает в изолированных средах без доступа к интернету
• Консистентные сборки независимо от сетевого доступа

Сборка Docker-образа

Контейнеризация утилиты-генератора (рекомендуемый первый шаг)

Самый простой подход: запустите генератор внутри Docker с примонтированными томами. Вы передаёте спецификацию и получаете готовый бинарник или Go-проект на хосте.

Dockerfile для утилиты генератора:

FROM golang:1.26-alpine
RUN apk add --no-cache git ca-certificates
COPY mockarty-server-generator /usr/local/bin/
ENTRYPOINT ["mockarty-server-generator"]

# Сборка образа генератора (один раз)
docker build -t mockarty-generator:latest -f Dockerfile.generator .

# Генерация + сборка сервера в один шаг
# Вход: ./api/openapi.yaml на хосте
# Выход: ./output/ — директория с собранным бинарником
docker run --rm \
  -v $(pwd)/api:/specs:ro \
  -v $(pwd)/output:/output \
  mockarty-generator:latest openapi \
    -input /specs/openapi.yaml \
    -output /output/server.go \
    -package main

# Теперь сборка бинарника (Go есть внутри контейнера)
docker run --rm \
  -v $(pwd)/output:/app \
  -w /app \
  golang:1.26-alpine \
  go build -mod=vendor -o server .

# Бинарник готов в ./output/server — запускаем напрямую
HTTP_ADMIN_BASE_URL=http://localhost:5770 ./output/server

Всё за один шаг: генерация + сборка + получение бинарника:

docker run --rm \
  -v $(pwd)/api:/specs:ro \
  -v $(pwd)/output:/output \
  mockarty-generator:latest sh -c '\
    mockarty-server-generator openapi \
      -input /specs/openapi.yaml \
      -output /tmp/server/server.go \
      -package main && \
    cd /tmp/server && \
    go build -mod=vendor -o /output/server .'

После этого ./output/server — статический Linux-бинарник, который можно запустить где угодно (или скопировать в минимальный Docker-образ).

Генерация + создание моков в Mockarty одновременно:

docker run --rm \
  -v $(pwd)/proto:/specs:ro \
  -v $(pwd)/output:/output \
  --network host \
  mockarty-generator:latest grpc \
    -input /specs/ \
    -output /output/server.go \
    -package main \
    -create-mocks \
    -api-token mk_your_token \
    -http-admin-base-url http://localhost:5770 \
    -namespace sandbox \
    -server-name my-grpc-service

Совет: Используйте --network host, чтобы контейнер мог обращаться к Mockarty на localhost. В Docker Compose используйте имя сервиса (например, http://mockarty:5770).

Контейнеризация сгенерированного сервера

Когда у вас есть сгенерированный Go-проект, контейнеризуйте его многоэтапным Dockerfile:

Создайте Dockerfile в директории сгенерированного сервера:

# Этап 1: Сборка
FROM golang:1.26-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -mod=vendor -o server .

# Этап 2: Запуск
FROM alpine:3.20
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/server /usr/local/bin/server
EXPOSE 8080
ENV HTTP_PORT=8080
ENV HTTP_ADMIN_BASE_URL=http://mockarty:5770
ENV NAMESPACE=sandbox
ENTRYPOINT ["server"]

Сборка и запуск

# Сборка образа
docker build -t my-mock-server:latest ./petstore-server/

# Запуск
docker run -d \
  --name petstore-mock \
  -p 8080:8080 \
  -e HTTP_ADMIN_BASE_URL=http://mockarty-admin:5770 \
  -e NAMESPACE=sandbox \
  my-mock-server:latest

Dockerfile для gRPC-сервера

Для gRPC-серверов откройте оба порта — HTTP-админку и gRPC:

FROM golang:1.26-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -mod=vendor -o server .

FROM alpine:3.20
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/server /usr/local/bin/server
EXPOSE 8080 4770
ENV HTTP_PORT=8080
ENV GRPC_PORT=4770
ENV HTTP_ADMIN_BASE_URL=http://mockarty:5770
ENV NAMESPACE=sandbox
ENTRYPOINT ["server"]

docker run -d \
  -p 8080:8080 \
  -p 4770:4770 \
  -e HTTP_ADMIN_BASE_URL=http://mockarty-admin:5770 \
  my-grpc-server:latest

Dockerfile для SOAP-сервера

SOAP-серверы используют два порта (SOAP-эндпоинт + админ-UI):

FROM golang:1.26-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -mod=vendor -o server .

FROM alpine:3.20
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/server /usr/local/bin/server
EXPOSE 8080 8081
ENV HTTP_PORT=8080
ENV ADMIN_PORT=8081
ENV HTTP_ADMIN_BASE_URL=http://mockarty:5770
ENTRYPOINT ["server"]

Docker Compose: сгенерированный сервер + Mockarty

version: "3.8"
services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: mockarty
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - pgdata:/var/lib/postgresql/data

  mockarty:
    image: mockarty/mockarty:latest
    ports:
      - "5770:5770"
    environment:
      DB_DSN: "postgresql://postgres:postgres@postgres:5432/mockarty?sslmode=disable"
    depends_on:
      - postgres

  petstore-mock:
    build: ./petstore-server
    ports:
      - "8080:8080"
    environment:
      HTTP_PORT: "8080"
      HTTP_ADMIN_BASE_URL: "http://mockarty:5770"
      NAMESPACE: "sandbox"
    depends_on:
      - mockarty

volumes:
  pgdata:

# Запуск всего
docker compose up -d

# Импорт моков (только первый раз)
./mockarty-server-generator openapi \
  -input ./api/openapi.yaml \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

# Тест
curl http://localhost:8080/pet/1

Сборка в CI без локального Go

Если Go не установлен локально, собирайте внутри Docker:

# Генерация кода (Go не нужен для этого шага)
./mockarty-server-generator openapi \
  -input ./api/openapi.yaml \
  -output ./server/server.go \
  -package main

# Сборка внутри Docker (Go есть на этапе builder)
docker build -t my-server:latest ./server/

Примеры CI/CD пайплайнов

GitHub Actions

name: Деплой мок-сервера

on:
  push:
    branches: [main]
    paths: ['api/**']

jobs:
  deploy-mocks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Скачать Server Generator
        run: |
          curl -L -o mockarty-server-generator \
            https://releases.mockarty.ru/latest/linux-amd64/mockarty-server-generator
          chmod +x mockarty-server-generator

      - name: Генерация сервера + создание моков
        run: |
          ./mockarty-server-generator openapi \
            -input ./api/openapi.yaml \
            -output ./mock-server/server.go \
            -package main \
            -create-mocks \
            -api-token ${{ secrets.MOCKARTY_API_TOKEN }} \
            -http-admin-base-url ${{ vars.MOCKARTY_URL }} \
            -namespace ${{ github.ref_name }} \
            -tags "ci,commit-${{ github.sha }}"

      - name: Сборка Docker-образа
        run: |
          cat > mock-server/Dockerfile << 'DOCKERFILE'
          FROM golang:1.26-alpine AS builder
          WORKDIR /app
          COPY . .
          RUN go build -mod=vendor -o server .
          FROM alpine:3.20
          RUN apk add --no-cache ca-certificates
          COPY --from=builder /app/server /usr/local/bin/server
          EXPOSE 8080
          ENTRYPOINT ["server"]
          DOCKERFILE
          docker build -t mock-server:${{ github.sha }} ./mock-server/

      - name: Публикация в реестр
        run: |
          docker tag mock-server:${{ github.sha }} registry.example.com/mock-server:latest
          docker push registry.example.com/mock-server:latest

GitLab CI

stages:
  - generate
  - build
  - deploy

generate-mocks:
  stage: generate
  image: golang:1.26-alpine
  script:
    - wget -O /usr/local/bin/mockarty-server-generator https://releases.mockarty.ru/latest/linux-amd64/mockarty-server-generator
    - chmod +x /usr/local/bin/mockarty-server-generator
    - mockarty-server-generator openapi
        -input ./api/openapi.yaml
        -output ./generated-server/server.go
        -package main
        -create-mocks
        -api-token $MOCKARTY_TOKEN
        -http-admin-base-url $MOCKARTY_URL
        -namespace $CI_COMMIT_REF_SLUG
  artifacts:
    paths:
      - generated-server/

build-image:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - cd generated-server
    - |
      cat > Dockerfile << 'EOF'
      FROM golang:1.26-alpine AS builder
      WORKDIR /app
      COPY . .
      RUN go build -mod=vendor -o server .
      FROM alpine:3.20
      RUN apk add --no-cache ca-certificates
      COPY --from=builder /app/server /usr/local/bin/server
      EXPOSE 8080
      ENTRYPOINT ["server"]
      EOF
    - docker build -t $CI_REGISTRY_IMAGE/mock-server:$CI_COMMIT_SHORT_SHA .
    - docker push $CI_REGISTRY_IMAGE/mock-server:$CI_COMMIT_SHORT_SHA

deploy:
  stage: deploy
  script:
    - kubectl set image deployment/mock-server mock-server=$CI_REGISTRY_IMAGE/mock-server:$CI_COMMIT_SHORT_SHA

API-First подход в CI

Используйте генератор для синхронизации моков с API-спецификацией при каждом PR:

# 1. Изменения в спеке запускают CI
# 2. Генератор обновляет моки (smart merge сохраняет ручные настройки)
./mockarty-server-generator openapi \
  -input ./api/openapi.yaml \
  -create-mocks \
  -api-token $MOCKARTY_TOKEN \
  -namespace $BRANCH_NAME \
  -tags "pr-$PR_NUMBER"

# 3. Frontend-команда сразу тестирует обновлённые моки
# 4. Изменения кода не нужны — моки обновляются автоматически из спеки

Примеры моков

Эти примеры показывают, как вручную создавать моки через API Mockarty для использования со сгенерированными серверами. Для генераторов на основе спецификаций (OpenAPI, gRPC, MCP, GraphQL, SOAP) моки также можно создать автоматически с помощью флага -create-mocks. Для адаптеров на основе конфигурации (Kafka, RabbitMQ, SSE, Socket, SMTP) моки всегда создаются вручную.

Мок MCP

{
  "id": "mcp-tool-mock",
  "namespace": "sandbox",
  "mcp": {
    "serverName": "example-mcp-server",
    "method": "tool_name",
    "conditions": [
      {
        "path": "$.param1",
        "assertAction": "equals",
        "value": "test"
      }
    ]
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "result": "success"
    }
  }
}

Мок gRPC

{
  "id": "grpc-method-mock",
  "namespace": "sandbox",
  "grpc": {
    "service": "UserService",
    "method": "GetUser",
    "conditions": [
      {
        "path": "$.id",
        "assertAction": "equals",
        "value": "123"
      }
    ]
  },
  "response": {
    "statusCode": 0,
    "payload": {
      "id": "123",
      "name": "John Doe"
    }
  }
}

Мок GraphQL

{
  "id": "graphql-query-mock",
  "namespace": "sandbox",
  "graphql": {
    "operation": "query",
    "field": "GetUser"
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "data": {
        "user": {
          "id": "1",
          "name": "$.fake.Name",
          "email": "$.fake.Email"
        }
      }
    }
  }
}

Мок Kafka

{
  "id": "kafka-orders-mock",
  "namespace": "sandbox",
  "kafka": {
    "topic": "orders",
    "serverName": "my-kafka-server"
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "orderId": "$.fake.UUID",
      "status": "processed"
    }
  }
}

Мок SOAP

{
  "id": "soap-getuser-mock",
  "namespace": "sandbox",
  "soap": {
    "soapAction": "GetUser",
    "path": "/ws/users"
  },
  "response": {
    "statusCode": 200,
    "payload": "<GetUserResponse><Name>John</Name></GetUserResponse>"
  }
}

Мок RabbitMQ

{
  "id": "rabbitmq-orders-mock",
  "namespace": "sandbox",
  "rabbitmq": {
    "queue": "orders.queue",
    "exchange": "orders.exchange",
    "serverName": "my-rabbitmq-server"
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "orderId": "$.fake.UUID",
      "status": "received"
    }
  }
}

Мок SSE

{
  "id": "sse-events-mock",
  "namespace": "sandbox",
  "sse": {
    "path": "/events",
    "eventName": "notification"
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "type": "alert",
      "message": "$.fake.Sentence"
    }
  }
}

Мок Socket (WebSocket)

{
  "id": "ws-message-mock",
  "namespace": "sandbox",
  "socket": {
    "serverName": "my-ws-server",
    "eventName": "message"
  },
  "response": {
    "statusCode": 200,
    "payload": {
      "echo": "$.req.data",
      "timestamp": "$.fake.UnixTimestamp"
    }
  }
}

Ограничения

Общие

1. Требуется HTTP-нода Mockarty — сгенерированные серверы не могут работать без запущенного экземпляра Mockarty (admin или resolver нода)
2. Изоляция по неймспейсам — все моки должны быть в указанном неймспейсе
3. Сетевая доступность — HTTP-нода Mockarty должна быть доступна с машины, на которой работает сгенерированный сервер
4. Валидация лицензии — режим -create-mocks и orchestrator/experimental-ui требуют валидной лицензии с функцией mock

Протокол-специфичные ограничения

Mockarty Server Generator — унифицированная генерация кода для 8 протоколов и 2 брокеров сообщений из единого бинарника.

Смотрите также

• Руководство по интеграциям — Настройка resolver-нод, runner-агентов и API-first подхода
• Установка и развёртывание — Примеры Docker Compose с генерированными серверами
• Справочник Faker — Все функции Faker для ответов моков
• Руководство по JsonPath — Извлечение данных запроса и интерполяция ответов
• Справочник API — REST API для программного управления моками