Основы интеграционного взаимодействия — итоги
Кратко — что стоит унести из раздела "Основы интеграционного взаимодействия". Если пункт кажется туманным — откройте указанную главу или оглавление.
FAQ — Часто задаваемые вопросы
Типичные сбои интеграций, API и обмена сообщениями после раздела. Здесь — что проверить первым делом и где читать дальше; определения для самопроверки — в чек-листе.
Вопрос. В Postman запрос проходит, а из приложения — "Network Error" или таймаут.
Ответ. Сравните URL, метод, заголовки, тело и прокси буква в букву; в коде часто другой base URL, отсутствует Authorization или срабатывает корпоративный прокси. Повторите тот же запрос через curl -v. Подробнее здесь — Postman и curl, HTTP.
Вопрос. Браузер пишет "CORS policy blocked" — API "сломано"?
Ответ. Браузер блокирует ответ, если origin фронтенда не разрешён заголовками Access-Control-* на сервере API. Сервер может отвечать 200, но JS не увидит тело. Проверьте preflight OPTIONS и настройку CORS на бэкенде или прокси. Подробнее здесь — HTTP, безопасность API.
Вопрос. Клиент получает 502 Bad Gateway при вызове нашего API — кто виноват?
Ответ. 502 обычно отдаёт прокси или балансировщик, когда upstream не ответил или вернул невалидный ответ. Проверьте жив ли backend, health-check, таймауты nginx/ingress и логи за reverse proxy. Разбор proxy_pass и типичных причин 502 — Nginx — конфиги под задачу. Подробнее здесь — HTTP-статусы, модель запрос-ответ.
Вопрос. 504 Gateway Timeout — увеличить timeout на клиенте достаточно?
Ответ. Увеличение timeout на клиенте маскирует медленный backend или блокирующий вызов к третьей системе. Найдите, где теряются секунды — БД, внешний API, очередь — и выставьте согласованные лимиты на всех hop. Подробнее здесь — HTTP, типы взаимодействия.
Вопрос. API отвечает 200, но тело пустое или "Unexpected token" в JSON.parse.
Ответ. Проверьте Content-Type — сервер мог вернуть HTML страницы ошибки, редирект или gzip без декодирования. В DevTools/Postman смотрите raw body и charset. Подробнее здесь — HTTP, API.
Вопрос. После деплоя интеграция "упала" — контракт же не меняли.
Ответ. Сверьте фактическое поведение с OpenAPI/Swagger, версию окружения, feature flags и обратную совместимость полей. Часто ломается необязательное поле, которое клиент парсит жёстко. Подробнее здесь — API и OpenAPI, дополнительные аспекты.
Вопрос. Партнёр шлёт JSON, мы ждём XML — кто должен переделывать?
Ответ. Это расхождение контракта, его фиксируют в документации до кодирования — формат, схема, кодировка, версия API. Временный адаптер на шине или API Gateway допустим, но контракт должен быть явным. Подробнее здесь — интеграция, веб-сервисы.
Вопрос. REST-эндпоинт "иногда" возвращает 409 Conflict при повторной отправке заказа.
Ответ. Повтор после таймаута без идempotency key создаёт второй заказ или конфликт уникального ключа. Клиент должен передавать стабильный ключ (Idempotency-Key, requestId) и обрабатывать повтор как тот же результат. Подробнее здесь — идемпотентность, REST и стили API.
Вопрос. После retry клиента заказ продублировался три раза — брокер "дублирует"?
Ответ. At-least-once доставка и HTTP-retry дают дубликаты — это ожидаемо без идемпотентной обработки на consumer. Храните обработанные messageId/correlationId или используйте upsert по бизнес-ключу. Подробнее здесь — идемпотентность, асинхронная коммуникация.
Вопрос. 429 Too Many Requests — можно просто увеличить частоту опроса?
Ответ. 429 — сигнал rate limit; уважайте заголовок Retry-After, экспоненциальный backoff и jitter. Агрессивный polling ухудшит ситуацию и может привести к блокировке ключа. Подробнее здесь — безопасность API, HTTP.
Вопрос. OAuth-токен "внезапно" перестал работать через час — access token "сломался"?
Ответ. Access token короткоживущий; при 401 обновите через refresh token или повторите client credentials flow. Проверьте clock skew на серверах и правильность scope. Подробнее здесь — авторизация в интеграциях, управление сессиями.
Вопрос. JWT "Invalid signature" после ротации ключей на auth-сервере.
Ответ. Сервис-потребитель мог кэшировать старый JWKS или проверять issuer/audience не тем приложением. Обновите ключи, TTL кэша cert и список доверенных kid. Подробнее здесь — авторизация, сессии и JWT.
Вопрос. mTLS между сервисами — "certificate verify failed" только на одном pod.
Ответ. На одном экземпляре часто просрочен cert, другой CA bundle или секрет не смонтирован. Сравните notAfter, SAN и цепочку на проблемном pod с рабочим. Подробнее здесь — безопасность API, авторизация.
Вопрос. API-ключ в query string "работал вчера", сегодня 403.
Ответ. Ключ мог отозвать, истечь по quota или попасть в логи/Referer — ключи в URL небезопасны. Перенесите ключ в заголовок, ротируйте скомпрометированный. Подробнее здесь — 12 советов по безопасности API, API.
Вопрос. SOAP-интеграция падает на "Unexpected element" — WSDL же тот же.
Ответ. Контракт мог расшириться новым элементом, namespace сменился или включена другая версия binding. Сравните фактический XML с XSD и trace на шине ESB. Подробнее здесь — SOAP, веб-сервисы.
Вопрос. GraphQL возвращает данные, но фронт "тормозит" — REST был быстрее?
Ответ. Частая причина — N+1 резолверов и слишком глубокий запрос без лимитов. Используйте DataLoader, pagination, complexity limits. Подробнее здесь — REST, GraphQL и gRPC, пагинация в API.
Вопрос. gRPC вызов завершается DEADLINE_EXCEEDED, HTTP до того же хоста успевает.
Ответ. Проверьте deadline на клиенте, HTTP/2 через прокси и keepalive — некоторые балансировщики режут gRPC без grpc-* настроек. Увеличьте deadline только после профилирования сервера. Подробнее здесь — REST, GraphQL и gRPC, HTTP/2.
Вопрос. Список из API "обрывается" на 100 записях — данных точно больше.
Ответ. Сработал limit по умолчанию; пройдите все страницы через cursor/offset/Link: next до конца. Не полагайтесь на "последнюю страницу без маркера". Подробнее здесь — пагинация в API, API.
Вопрос. Синхронный вызов между микросервисами "положил" всю цепочку при падении одного.
Ответ. Длинная цепочка sync HTTP умножает latency и отказоустойчивость. Добавьте timeout, circuit breaker, fallback или вынесите шаг в очередь. Подробнее здесь — типы взаимодействия, асинхронная коммуникация.
Вопрос. Health-check /health зелёный, а партнёр получает 503 от нашего API.
Ответ. Liveness не проверяет зависимости — БД, брокер, внешний API. Добавьте readiness с проверкой критичных интеграций и отделяйте их от "процесс жив". Подробнее здесь — реализация интеграций, HTTP.
Вопрос. В логах разных сервисов нет общей нити одного заказа — как связать?
Ответ. Пробрасывайте correlation ID / trace ID в заголовках (X-Request-Id, traceparent) от входа до очереди и обратно. Без этого разбор инцидента занимает часы. Подробнее здесь — интеграционные потоки, дополнительные аспекты.
Вопрос. RabbitMQ — очередь растёт, consumer "работает", но сообщения не уменьшаются.
Ответ. Сообщения могут висеть в unacked — consumer взял, но не ack/nack после ошибки или слишком долгой обработки. Проверьте prefetch, timeout, DLQ и логи исключений. Подробнее здесь — RabbitMQ, брокеры сообщений.
Вопрос. Сообщения уходят в Dead Letter Queue — "брокер сломан"?
Ответ. DLQ — штатный карантин после N неудачных попыток или reject. Разберите payload, причину в headers (x-death) и исправьте consumer или контракт, затем requeue осознанно. Подробнее здесь — RabbitMQ, идемпотентность.
Вопрос. В RabbitMQ exchange "direct", а сообщения не доходят до нужной очереди.
Ответ. Routing key должен совпадать с binding key символ в символ; тип exchange и vhost тоже должны совпадать. В management UI посмотрите "Publish message" и trace bindings. Подробнее здесь — RabbitMQ, брокеры сообщений.
Вопрос. Kafka consumer lag растёт — нужно просто добавить consumer?
Ответ. Новый consumer поможет только если в топике достаточно партиций и members в одной group. Иначе лишние consumer простаивают; ускорьте обработку или увеличьте партиции с планом rebalancing. Подробнее здесь — Kafka, брокеры сообщений.
Вопрос. События в Kafka "перепутали порядок" для одного клиента.
Ответ. Глобальный порядок в топике гарантирован только внутри одной партиции. Ключ partition (customerId) должен быть стабильным; несколько producer без ключа дают перемешивание. Подробнее здесь — Kafka, интеграционные потоки.
Вопрос. Consumer в Kafka "читает старые" сообщения после перезапуска.
Ответ. Проверьте auto.offset.reset, commit offset и новую consumer group — без commit group начнёт с earliest. Явный commit после успешной обработки снижает риск повторов и пропусков. Подробнее здесь — Kafka, идемпотентность.
Вопрос. Redis-кэш отдаёт устаревшие цены после обновления в БД.
Ответ. Нужна инвалидация или короткий TTL плюс версионирование ключей; cache-aside без сброса даёт stale read. Для критичных данных рассмотрите write-through или событие invalidation из очереди. Подробнее здесь — Redis в интеграции, идемпотентность и доставка.
Вопрос. Redis Pub/Sub "теряет" сообщения при кратком рестарте subscriber.
Ответ. Pub/Sub не хранит историю — offline subscriber не получит пропущенное. Для гарантий возьмите Streams, RabbitMQ или Kafka. Подробнее здесь — Redis, брокеры сообщений.
Вопрос. Webhook от CRM не доходит — "у них всё отправлено".
Ответ. Проверьте публичный URL, TLS, firewall, 2xx ответ за timeout и верификацию подписи (HMAC, timestamp). Партнёр часто ретраит при non-2xx — ваш endpoint должен быть идемпотентным. Подробнее здесь — асинхронная коммуникация, безопасность API.
Вопрос. WebSocket соединение обрывается за nginx каждые 60 секунд.
Ответ. Прокси по умолчанию закрывает idle-соединения — включите proxy_read_timeout, ping/pong на приложении и sticky session при нескольких backend. Подробнее здесь — реактивные системы, HTTP и прокси.
Вопрос. SSE-поток в браузере "замирает", curl показывает события.
Ответ. Промежуточный прокси или CDN буферизует text/event-stream — отключите buffering (X-Accel-Buffering: no), проверьте CORS и reconnect. Подробнее здесь — реактивные системы, HTTP.
Вопрос. Saga на трёх сервисах застряла — два шага выполнились, третий упал.
Ответ. Нужен явный compensating transaction для уже выполненных шагов и журнал состояния saga. Без компенсации данные расходятся между системами. Подробнее здесь — интеграционные потоки, реализация интеграций.
Вопрос. ETL nightly job "догнал" прод, но отчёт не сходится с операционной системой.
Ответ. Batch-окно захватило изменения во время загрузки или разные timezone/ключи дедупликации. Сверьте watermark, idempotent load и контрольные суммы по батчам. Подробнее здесь — Пакетная работа с данными, пакетная загрузка и batch-окно, пакетная передача в проектировании API, ETL/ELT.
Вопрос. Circuit breaker "open" — сервис соседа уже подняли, интеграция всё ещё недоступна.
Ответ. Breaker ждёт half-open probe и порог успехов, прежде чем закрыться; плюс кэшированный fail-fast на клиенте. Проверьте настройки failure rate, window и принудительный reset после инцидента. Подробнее здесь — Инженерия устойчивости, 12 концепций — circuit breaker.
Частые поисковые запросы
Формулировки, близкие к запросам в Google и Яндексе — краткий ответ и ссылка на главу раздела.
Вопрос. Что такое API простыми словами?
Ответ. API (Application Programming Interface) — договорённость, как программы обмениваются данными по сети: URL, метод, формат JSON, коды ответа. Подробнее здесь — API, интеграция.
Вопрос. REST API — что это и как работает?
Ответ. REST использует HTTP-методы (GET, POST, PUT, DELETE) и ресурсы по URL; обычно JSON. Статус без состояния на сервере между запросами. Подробнее здесь — API, стили API.
Вопрос. Чем REST отличается от SOAP?
Ответ. REST — легче, JSON/XML по HTTP, популярен в веб и мобильных. SOAP — XML-конверты, WSDL, строгие контракты, часто в enterprise и банках. Подробнее здесь — SOAP, веб-сервисы.
Вопрос. Коды ответа HTTP 200 400 401 404 500 — что значат?
Ответ. 2xx — успех; 4xx — ошибка клиента (404 не найден, 401 не авторизован); 5xx — ошибка сервера. Смотрите тело ответа с деталями. Подробнее здесь — HTTP.
Вопрос. Postman — зачем тестировать API вручную?
Ответ. Postman (и curl) проверяют запрос до кода: заголовки, тело, авторизация, окружения dev/prod. Ускоряет отладку интеграций. Подробнее здесь — Postman и curl, утилита curl, curl / fetch — примеры.
Вопрос. Что такое вебхук (webhook)?
Ответ. Webhook — сервер сам шлёт HTTP POST на ваш URL при событии (оплата, статус заказа). Нужен публичный endpoint и проверка подписи. Подробнее здесь — асинхронная коммуникация.
Вопрос. RabbitMQ для начинающих — что это?
Ответ. RabbitMQ — брокер очередей: producer кладёт сообщение, consumer обрабатывает асинхронно. Гибкая маршрутизация через exchange. Подробнее здесь — RabbitMQ, брокеры.
Вопрос. Apache Kafka — когда нужна вместо RabbitMQ?
Ответ. Kafka — поток событий в топиках с партициями, высокая пропускная способность, хранение, stream processing. RabbitMQ — задачи и надёжная доставка в очередях. Подробнее здесь — Kafka, сравнение стилей.
Вопрос. Микросервисы или монолит — что выбрать?
Ответ. Монолит проще на старте; микросервисы — независимое масштабирование и деплой, но сложнее сеть, данные и observability. Подробнее здесь — типы взаимодействия, микросервисы в 8.05.
Вопрос. Горизонтальное и вертикальное масштабирование — в чём разница?
Ответ. Вертикальное — больше CPU/RAM на одном сервере. Горизонтальное — больше узлов за балансировщиком. Подробнее здесь — масштабирование, интеграция.
Вопрос. Что такое брокер сообщений (message broker)?
Ответ. Message broker принимает, хранит и доставляет сообщения между сервисами асинхронно — развязывает producer и consumer по времени. Подробнее здесь — брокеры сообщений.
Вопрос. Redis для кэширования API — как использовать?
Ответ. Redis хранит горячие ответы по ключу с TTL — снижает нагрузку на БД. Нужна инвалидация при изменении данных. Подробнее здесь — Redis в интеграции.
Вопрос. GraphQL или REST — что выбрать для API?
Ответ. REST — ресурсы и простые клиенты. GraphQL — один endpoint, клиент запрашивает нужные поля; сложнее кэш и N+1 на сервере. Подробнее здесь — REST, GraphQL и gRPC.
Вопрос. gRPC — когда использовать вместо REST?
Ответ. gRPC на HTTP/2 с protobuf — быстрые внутренние вызовы между сервисами, строгие контракты. Для публичных браузерных API чаще REST. Подробнее здесь — стили API.
Вопрос. OpenAPI (Swagger) — зачем описывать API?
Ответ. OpenAPI — машиночитаемый контракт: генерация клиентов, документация, валидация в CI. Снижает расхождение frontend и backend. Подробнее здесь — API.
Вопрос. Idempotency-Key — зачем при POST-запросах?
Ответ. Ключ идемпотентности гарантирует, что повтор запроса после таймаута не создаст второй заказ. Обязателен в платежах и заказах. Подробнее здесь — идемпотентность.
Вопрос. Ошибка CORS в браузере при вызове API — как исправить?
Ответ. Настройте CORS на сервере API — разрешённый origin, методы, заголовки; preflight OPTIONS. Проблема не в "сломанном API", а в политике браузера. Подробнее здесь — HTTP, безопасность API.
Вопрос. Синхронная и асинхронная интеграция — в чём разница?
Ответ. Синхронная (HTTP) — клиент ждёт ответ в том же запросе. Асинхронная (очередь) — отправил и занимается другим; результат позже. Подробнее здесь — типы взаимодействия, асинхронная коммуникация.
Вопрос. WebSocket и long polling — когда что?
Ответ. WebSocket — двусторонний канал для чатов, игр, котировок. Long polling/SSE — проще за прокси для односторонних push. Подробнее здесь — реактивные системы.
Вопрос. JSON в API — что такое Content-Type application/json?
Ответ. Заголовок Content-Type: application/json говорит, что тело — JSON; сервер и клиент парсят одинаково. Ошибки кодировки и лишние поля — частая причина багов. Подробнее здесь — HTTP, API.
Вопрос. OAuth 2.0 для доступа к API — как устроено?
Ответ. Пользователь или сервис получает access token через authorization server; API проверяет scope. M2M — client credentials. Подробнее здесь — авторизация в интеграциях.
Вопрос. Circuit breaker — что это в микросервисах?
Ответ. Circuit breaker перестаёт долбить упавший сервис, даёт ему восстановиться (open/half-open/closed). Защищает цепочку вызовов. Подробнее здесь — Инженерия устойчивости, 12 концепций.
Вопрос. Retry в API и микросервисах — когда можно повторять запрос?
Ответ. Повторяйте при временных сбоях (таймаут, 502/503/504, 429 с backoff), только для идемпотентных операций или с Idempotency-Key. Сочетайте с таймаутом и circuit breaker, чтобы не устроить retry storm. Подробнее здесь — Инженерия устойчивости, идемпотентность.
Вопрос. Как интегрировать сайт с 1С или CRM через API?
Ответ. Нужен контракт (REST/SOAP/обмен файлами), авторизация, идемпотентность и логирование. Часто — очередь между системами, а не прямой sync при каждом клике. Подробнее здесь — интеграция, проектирование API.
Вопрос. Exactly-once доставка сообщений — возможно ли?
Ответ. В распределённых системах обычно at-least-once; exactly-once достигают идемпотентным consumer и транзакциями outbox. Подробнее здесь — идемпотентность и доставка.
Вопрос. Как в одной системе подключить MongoDB, Redis, RabbitMQ и Kafka и вызывать микросервисы?
Ответ. Браузер ходит только в API Gateway; сервисы общаются по HTTP внутри сети, каждый со своей БД. Redis — кэш, RabbitMQ — фоновые задачи, Kafka — поток событий. Сквозной сценарий заказа с примерами кода — практика 134.
Вопрос. Как стать интеграционным разработчиком / backend с API?
Ответ. HTTP, JSON, REST, auth, SQL, очереди, тесты в Postman/curl, основы безопасности. Практика — pet-проект с двумя сервисами. Подробнее здесь — оглавление, интеграция, практика MongoDB/Redis/Rabbit/Kafka.
Что запомнить
Интеграционное взаимодействие — это фундаментальная основа современных распределённых систем. Оно обеспечивает связь между автономными компонентами, позволяя им совместно реализовывать сложные бизнес-процессы без жёсткой связанности. Эта связь строится на чётких контрактах, стандартизированных протоколах и надёжных механизмах передачи данных.
Основные категории:
- Масштабирование может быть горизонтальным (добавление узлов) и вертикальным (увеличение мощности одного узла).
- Микросервисная архитектура является наиболее эффективным способом масштабирования за счёт разделения монолита на независимые, слабо связанные сервисы.
- Коммуникация бывает синхронной (HTTP, REST, gRPC), асинхронной (RabbitMQ, Kafka) и реактивной (WebSocket, SSE, Kafka Streams).
- RabbitMQ использует модель очередей с гарантией доставки и гибкой маршрутизацией, а Kafka основана на топиках с партициями и ориентирована на потоковую обработку больших объёмов данных в реальном времени.
- Redis дополняет интеграционный стек как быстрый слой кэширования и буферизации, а также как транспорт для Pub/Sub и Streams в задачах с умеренными требованиями к гарантиям доставки.
Три основных правила использования технологий масштабирования:
- Выбор метода масштабирования зависит от текущих потребностей системы и её потенциала роста.
- При проектировании микросервисной архитектуры важно обеспечить независимость сервисов и чёткость их взаимодействия через API.
- Брокеры сообщений должны соответствовать специфике задач: RabbitMQ — для фоновых задач и надёжной доставки, Kafka — для потоковой аналитики и логирования.
- Кэширование через Redis снижает нагрузку на API и БД, но требует дисциплины в TTL, инвалидации и мониторинге.
Три фундаментальных момента:
- Правильная декомпозиция монолитного приложения на микросервисы критична для эффективности всей системы.
- Надёжная коммуникация между сервисами требует тщательного выбора протоколов и подходов к интеграции.
- Масштабируемость должна быть заложена в архитектуру системы изначально, а не добавлена как позднее улучшение.
Куда идти дальше
| Тема | Раздел |
|---|---|
| Проектирование API для внешних потребителей | 7.06. Проектирование API и интеграций |
| Маршрут по всем главам про API | таблица в design/117 |
| "Микросервисы и интеграция — о разделе" | "Микросервисы и интеграция — о разделе" |
| "Основы информационной безопасности — о разделе" | "Основы информационной безопасности — о разделе" |
| "NAT и проброс портов" | "NAT и проброс портов" |
| "Организация домашней сети" | "Организация домашней сети" |
| "Веб-сайты и веб-приложения — о разделе" | "Веб-сайты и веб-приложения — о разделе" |
Проверьте себя: Чек-лист самопроверки.
Базовый разбор HTTP и HTTPS находится в отдельной статье — HTTP как основа веб-интеграций.