Привет! Я хочу рассказать о важной части задач, с которыми работают системные аналитики. Это задачи на проектирование интеграций.
Звучит серьезно и сложно. И это так, если не знаешь что это, с чего начать и как идти. Но если ты уже прошёл хотя бы три проекта, с разными особенностями, то понимания становится больше.
Для меня каждый проект был похож на приключение с неожиданным концом. Сначала я думала, что всё знаю и всё понятно. А потом, при детальном погружении, вылезали тонны нюансов и особенностей в работе 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-документации.
Посмотреть оглавление. Найти разделы, в которых потенциально есть информация по следующим пунктам из этой инструкции.
Авторизация и аутентификация.
Тестовые доступы, если еще не получили.
Рекомендации по использованию. Примеры сценариев использования.
Это не всегда есть в API-документации. Но если есть, то считайте, что задача почти готова - предложенный сценарий интеграции надо адаптировать под бизнес-процессы текущего проекта.Общие требования к обработке ошибок. Коды ответов.
Список методов, необходимых для реализации интеграционных сценариев, и документацию по ним. На этапе знакомства с документацией сильно вчитываться не надо. Главное понять, что методов для реализации бизнес-процессов текущего проекта достаточно.
API-документация может быть передана вам в виде ссылке на Postman-коллекцию, Swagger-коллекцию, сайт разработчика, PDF-документ, Word-документ.
Кстати, API-документация не всегда есть. И иногда надо "пытать" разработчиков в переписке, чтобы получить описание методов API. Всякое бывает.
4. Тестирование API
Этот этап нужен при анализе и проектировании по следующим причинам:
Убедиться, что все работает как в API-документации.
Понять как реально работает API и весь бизнес-процесс. Посмотреть на данные.
В ходе написания интеграционных сценариев я проверяю разные ситуации с ошибками и фактическую реакцию внешней системы на них. В API-документации эта информация может отсутствовать.
Лучшее понимание технической части задачи.
Для тестирования 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 внешней системы и, в случае необходимости, своевременно делать переезды на новые версии.
Заключение
Помните, что стандартного подхода в проектировании интеграций нет. Эта инструкция помогает не пропустить конкретные шаги в проработке задачи и не "танцевать на граблях" при работе с очередной интеграцией.
Уникальное решение по интеграциям для вашего проекта остается за вами.
Сохраняйте инструкцию и применяйте в своих проектах :)
