Привет! Я хочу рассказать о важной части задач, с которыми работают системные аналитики. Это задачи на проектирование интеграций.

Звучит серьезно и сложно. И это так, если не знаешь что это, с чего начать и как идти. Но если ты уже прошел хотя бы три проекта, с разными особенностями, то понимания становится больше.

Для меня каждый проект был похож на приключение с неожиданным концом. Сначала я думала, что всё знаю и всё понятно. А потом, при детальном погружении, вылезала куча нюансов и особенностей в работе API внешних систем, архитектуре, обработке ошибок...

Я хочу поделиться с вами пошаговой инструкцией по работе с задачами на интеграции. Пусть она станет помощником для системных аналитиков, бизнес-аналитиков и разработчиков при проектировании интеграций для любых систем.

Как пользоваться этой интрукцией на практике я рассказываю у себя в канале для системных аналитиков на примере разных проектов. Краткий чек-лист интеграций опубликован там же.

Пошаговая инструкция по проектированию интеграций

1. Подготовка

• Знакомство с проектом.

  • Предметная область.

  • Как сейчас работают бизнес-процессы - AS IS.

  • Что по системам, приложениям и сервисам уже есть в проекте.
    Есть ли программные интерфейсы (API), которые надо будет учитывать или дорабатывать при работе с текущей задачей на интеграцию.

• Запрос документации внешних систем, с которыми предстоит интегрироваться.
  Если вы занимаетесь разработкой продукта, то вероятно "внешними" по отношению к вашей системе могут быть приложения и сервисы коллег.
  Просить:

  • API-документация (REST API, GraphQL, SOAP API и другие).

  • Комплекты SDK.

  • Другие документы и файлы, необходимые разработчикам для создания кода.

• Запрос доступов к внешним системам, тестовых площадок:

  • Тестовые и боевые URL.

  • Логины, пароли и токены.

  • Тестовые электронные ключи на носителях.
    Был опыт, когда надо было подписывать запросы к API с использованием ЭЦП (электронно-цифровой подписи на флешке).

  • Тестовое оборудование.
    Например, мы закупали тестовые фискальные накопители (что-то вроде карт памяти) для интеграции с ККТ (контрольно-кассовой техникой).

  • Другие неоходимые данные для аутентификации и авторизации запросов.

2. Сбор и анализ требований

Как только поняли, что из себя представляют бизнес-процессы AS IS, то необходимо получить понимание что требуется от разработки - TO BE.

• Бизнес-цель разработки интеграции.
  Пример:
  Увеличить продажи товаров.

• Бизнес-задачи интеграции.
  Пример:
  Подключить сервис SMS-рассылок, чтобы делать рассылки специальных предложений клиентам через дополнительный канал коммуникаций.

• Бизнес-требования.
  Примеры:
  - Если зарегистрированный пользователь не сохранил номер телефона в личном кабинете, то предлагать ему сделать это. SMS для таких пользователей доставлены не будут, они не попадают в список контактов на рассылку.
  - После планирования SMS-рассылки менеджер может отменить ее в любой момент до момента отправки.
  - Должна быть возможность прерывания SMS-рассылки.

• Функциональные требования.
  Примеры:
  - Добавить поле ввода номера телефона, обязательное при регистрации клиентов в мобильных приложениях и на сайте.
  - Сделать возможность создания SMS-рассылки в панели админисратора.

• Нефункциональные требования.
  Пример:
  Рассылка 10тыс сообщений должна выполняться не более чем за 5 минут.

• Разработка схемы архитектуры - первое приближение. Инструкция опубликована здесь. Может быть использована нотация C4.

3. Анализ API документации

Первое, что вы должны сделать, когда только получили документацию - прочитать ее по диагонали. Ниже моя краткая инструкция по чтению хорошей API-документации.

1. Посмотреть оглавление. Найти разделы, в которых потенциально есть информация по следующим пунктам из этой инструкции.

2. Авторизация и аутентификация.

3. Тестовые доступы, если еще не получили.

4. Рекомендации по использованию. Примеры сценариев использования.
   Это не всегда есть в API-документации. Но если есть, то считайте, что задача почти готова - предложенный сценарий интеграции надо адаптировать под бизнес-процессы текущего проекта.

5. Общие требования к обработке ошибок. Коды ответов.

6. Список методов, необходимых для реализации интеграционных сценариев, и документацию по ним. На этапе знакомства с документацией сильно вчитываться не надо. Главное понять, что методов для реализации бизнес-процессов текущего проекта достаточно.

API-документация может быть передана вам в виде ссылке на Postman-коллекцию, Swagger-коллекцию, сайт разработчика, PDF-документ, Word-документ.

Кстати, API-документация не всегда есть. И иногда надо "пытать" разработчиков в переписке, чтобы получить описание методов API. Всякое бывает.

4. Тестирование API

Этот этап нужен при анализе и проектировании по следующим причинам:

1. Убедиться, что все работает как в API-документации.

2. Понять как реально работает API и весь бизнес-процесс. Посмотреть на данные.

3. В ходе написания интеграционных сценариев я проверяю разные ситуации с ошибками и фактическую реакцию внешней системы на них. В API-документации эта информация может отсутствовать.

4. Лучшее понимание технической части задачи.

Для тестирования Web API (REST API, GraphQL, SOAP API и другие) работаем с Postman или SOAP UI.

В случае библиотек или других протоколов, которые нельзя протестировать через указанные выше инструменты, обычно я прошу у разработчиков помощи.

5. Разработка логики и алгоритмов

Необходимо описать логику работы - Use Case - сценарии интеграции. Это самое главное, что прорабатывает аналитик при работе с интеграционной задачей.

Критерии хорошего интеграционного Use Case:

• Описана полная последовательность шагов и альтернативные сценарии по каждому шагу.

• Каждый шаг сценария содержит информацию о приложениях и ролях, которые участвуют в его реализации.

• Для шагов, где есть интеграционное взаимодействие, указаны интеграционные методы.

• Есть требования к обработке ошибок на каждом шаге. Учтены требования к обработке недоступности внешней системы, логические ошибки от нее и другие.

• Есть страховка от ситуаций с несовместимыми обновлениями со стороны внешних систем - обработка ошибок. Такое, увы, бывает. И тогда мы выкатываем срочные релизы, чтобы починить нашу систему и поддержать выпущенные обновления.

6. Анализ данных = маппинг данных

Сопоставляем данные в БД своего проекта с данными, которые получаем по API от внешней системы. Либо со своим API. А можно делать и то, и другое одновременно.

Это необходимо сделать для каждого метода, который вызывается в описанных интеграционных сценариях работы системы.

Пример таблицы с маппингом:

7. Разработка схемы архитектуры

Определяемся, как в системе будет реализована интеграция - в каком сервисе приложения, или в микросервисе. Какие данные будут передаваться между системами, какие протоколы обмена данными будут использованы.

Создаем схему архитектуры под интеграционную задачу в любой нотации. Может быть использована нотация C4.

8. Постановка задач

Создаем задачи в Jira и собираем описание по каждой задаче в Confluence или в аналогичных системах. Как правило создаются задачи на:

• Создание файлов конфигураций или доработка существующих.

• Изменение БД - создание таблиц, добавление новых полей.

• Реализация интеграционных методов для Backend-разработчиков.

• Поддержка изменений, связанных с изменениями для приложений пользователей.

9. Релиз, сопровождение и документация

Как только задача готова, то сохраняем все знания по ней и структурируем документацию.

Одна из рекомендаций по структурированию знаний:

После релиза важно следить за обновлениями API внешней системы и, в случае необходимости, своевременно делать переезды на новые версии.

Заключение

Помните, что стандартного подхода в проектировании интеграций нет. Эта инструкция помогает не пропустить конкретные шаги в проработке задачи и не "танцевать на граблях" при работе с очередной интеграцией.

Уникальное решение по интеграциям для вашего проекта остается за вами.

Сохраняйте инструкцию и применяйте в своих проектах :)