Как стать автором
Обновить

Как аналитику работать с задачами на интеграции — пошаговая инструкция

Уровень сложностиСредний
Время на прочтение5 мин
Количество просмотров34K

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

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

Для меня каждый проект был похож на приключение с неожиданным концом. Сначала я думала, что всё знаю и всё понятно. А потом, при детальном погружении, вылезали тонны нюансов и особенностей в работе 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.

Нотация C4
Нотация C4

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

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

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

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

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

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

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

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

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

Рекомендация по организации структуры документации
Рекомендация по организации структуры документации

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

Заключение

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

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

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

Теги:
Хабы:
Если эта публикация вас вдохновила и вы хотите поддержать автора — не стесняйтесь нажать на кнопку
Всего голосов 6: ↑6 и ↓0+7
Комментарии10

Публикации

Истории

Работа

Ближайшие события

2 – 18 декабря
Yandex DataLens Festival 2024
МоскваОнлайн
11 – 13 декабря
Международная конференция по AI/ML «AI Journey»
МоскваОнлайн
25 – 26 апреля
IT-конференция Merge Tatarstan 2025
Казань