Всем привет. Меня зовут Таня, я работаю системным аналитиком в МТС. В этой статье я расскажу о том, как писать документацию для разработки микросервисов. 

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

Единый подход

Начну свое повествование с напоминания о том, как важно стремиться к единообразию. Когда компания становится большой, то появляется много команд и, соответственно, аналитиков. Приходит осознание того, что документация без единого шаблона становится слишком разной, она пестрая, не структурированная. Появляется потребность в разных формах стандартизации документации. Про важность единого подхода и о том, как плохо без него, я уже писала в статье «Как мы создали шаблон функциональных требований в разработке ПО» в соавторстве с моей коллегой Лизой Марковой.

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

Из чего состоит шаблон 

Наш шаблон требований к микросервису состоит из следующих частей:

• общее описание микросервиса;

• методы;

  • алгоритм;

  • входящие данные;

  • исходящие данные;

  • исключения;

• база данных;

• справочники;

• нефункциональные требования;

• маппинги.

Это части необходимы для того, чтобы требования были полными.

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

Итак, перейдем к детальному описанию каждого из разделов.

Описание микросервиса

Для того, чтобы каждому, кто придет смотреть документацию на наш сервис, было понятно, что это за сервис (для чего он нужен, кому принадлежит и в рамках какой задачи разрабатывался), у нас есть головная страница с описанием. Выглядит она так:

На данной странице располагается название сервиса. Важно дать понятное название, которое будет описывать главную функцию сервиса. У нас в команде название сервису мы придумываем все вместе – накидываем варианты и выбираем лучший. 

Далее идет таблица с интересным макросом. Называется он JIRA и выглядит так:

Добавив этот макрос, вы сможете вставить на страницу в Confluence список задач из Jira. Даже можно вписать JQL запрос и отобразить отфильтрованные задачи.

Подробнее о JIRA Query Language (JQL) можно почитать, пройдя по ссылке. Это очень удобный инструмент для всех, кто работает с Jira.

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

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

API для сервиса

Далее по важности в первой вложенности следует описание API. Я покажу вам нашу реализацию на примере описания REST API. Методы в свою очередь тоже описываются по шаблону. В шаблон REST API входят:

•  общее описание;

•  алгоритм;

•  входящие данные;

•  исходящие данные;

•  исключения.

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

Итак, начнем с первой описательной части метода.

Здесь мы даем название методу. Как и в случае с сервисом, название методу нужно сделать интуитивно понятным для людей, которые будут сталкиваться с вашей документацией. Далее в таблице приводим тестовый UPI и ссылку на JIRA. У нас каждый метод разрабатывается в рамках отдельной таски. 

Далее необходимо написать о назначении метода и, если это имеет значение, какую-то дополнительную информацию о методе. В конце мы кратко описываем результат этого метода.

Далее идет страница с описанием алгоритма метода. Алгоритм – это та логика, которую проворачивает сервис для получения результата по конкретному методу. Так сказать, его сердце. 

Если в алгоритме есть несколько фильтрацией или валидаций, то можно указать их в таблице для наглядности. Шаги описанные в алгоритме – это не обязательно то, как будет реализована последовательность проверок в коде. Главное – описать все, что нужно сервису для получения результата. Далее разработчик сам реализует так, чтобы сервис отрабатывал оптимальным образом. 

Для визуализации мы добавляем диаграмму последовательности UML. Конечно, я напомню и о том, что есть прекрасный инструмент PlantUML, который позволяет делать такие диаграммы с помощью написания кода.

Вернемся к описанию методов. Далее мы описываем входящие и исходящие параметры, добавляя пример JSON-сообщения с помощью двух макросов Раскрыть и Блок кода.

Для того, чтобы описать все параметры и их структуру в запросе и ответе мы также использует таблицу со следующими столбцами:

• параметр;

• тип параметра;

• формат данных;

• кратность (обязательность);

• описание.

Для выделения Типа параметра и Формата данных можно использовать Статус. Добавлю скрин из Confluence, где показано как его найти.

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

На этом описание метода подошло к концу. Перейдем к следующем разделу нашей спецификации.

База данных

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

Из нее можно узнать, какие таблицы есть в БД, какие сущности хранятся в этих таблицах, как они связаны, какие форматы данных у полей и так далее. Каждая таблица описана на отдельной странице. Как ни странно, но для описания таблицы мы используем другую таблицу со следующими полями:

• name;

• type;

• nullable;

• description.

Также мы добавляем ER-диаграмму для того, чтобы визуально показать связи между таблицами. Для создания этой и многих других диаграмм можно использовать встроенный макрос Drow.io Diagram.

В целом, описать структуру БД достаточно просто. Но иногда знаний одного аналитика недостаточно. В таком случае на помощь может прийти архитектор или разработчик. 

Если в БД находится какая-то справочная информация (так называемые справочники), то мы выносим их описание в отдельный раздел.

Справочники

В этот раздел помещается все, что можно оценить как справочник, например, перечисление платформ, мест показа фичи, каких-нибудь триггеров, условий и так далее. Цель описания справочника в том, чтобы можно было увидеть хранящиеся варианты в БД, не заходя в БД. Чтобы было понятнее, приведу пример:

У нас есть фича Онбординг в мобильном приложении. Онбординг может открываться в нескольких местах. Мы фиксируем эти места и обновляем данные по мере расширения функционала по приложению.

Итак, мы уже описали несколько разделов, но это еще не все. Любой аналитик спросит – а как же НФТ (нефункциональные требования)? Вот про них я сейчас расскажу подробнее.

Нефункциональные требования

Начнем с пояснения. НФТ – это требования, определяющие свойства, которые система должна демонстрировать, или ограничения, которые она должна соблюдать, не относящиеся к поведению системы. Например, производительность, удобство сопровождения, расширяемость, надежность, факторы эксплуатации. 

В требованиях важно зафиксировать главные параметры, например, скорость ответа на вызов.

В данном разделе может содержаться таблица со следующими характеристиками:

• производительность;

• безопасность;

• масштабируемость;

• надежность;

• совместимость;

• доступность;

• особенности хранения данных;

• поддерживаемость;

• тестируемость;

• ремонтопригодность;

• концептуальная целостность;

• удобство использования.

Маппинг

Это следующий опциональный  раздел в описании микросервиса. Маппинг данных –  процесс сопоставления полей данных (определенных элементов источника или всего источника) и связанных с ними полей данных в другом месте назначения. Так что если в вашем сервисе присутствует маппинг – его необходимо описать. Самое простой способ – создать таблицу с 3 столбцами. В первый столбец поместите названия параметров первой системы, во второй столбец – названия соответствующих параметров из второй системы, ну а в третий – описание этих параметров.

Заключение 

Безусловно, это не исчерпывающий список того, что можно включить в спецификацию для микросервиса. Пока мы остановились на таком наборе, но если функционал сервиса требует описать дополнительно какой-нибудь раздел, – его легко можно включить в шаблон. Мы стараемся не останавливаться на том, что у нас есть сейчас. Каждый аналитик или другой специалист может привносить что-то новое в наш шаблон. Главное, чтобы эти новшества делали шаблон удобнее.

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

На этом я заканчиваю свой рассказ, спасибо вам за внимание! Буду очень рада пообщаться в комментариях о том, что вам откликнулось, а что вы бы сделали иначе.