Представьте, что у вас есть команда специалистов, которые по принципу «код — прежде всего» создают систему с множеством бизнес-историй на основе микросервисов.
Все люди опытные, каждому есть чем заняться помимо написания документации или спецификаций разрабатываемого API. И все с самого начала знают, что если вы хотите воспользоваться сервисом, вам нужно заглянуть в код, а затем спросить в общем чате, если что-то непонятно.
Знакомая ситуация, не правда ли? -))) А в целом все хорошо, если бы со временем не росла команда, не росло количество сервисов и функций, не появлялись баги со стороны бизнеса и тестировщиков, не было бы необходимости предоставлять API для интеграция со смежными командами.
Эта статья на момент написания представляет собой мое личное мнение о минимальной структуре документирования микросервисов при ее отсутствии.
Личное мнение родилось в ходе мозгового штурма реальной ситуации и поиска улучшения качества при разработке приложения для среднего бизнеса.
Так.
Что мы имеем на входе? И на входе мы имеем процесс разработки, который выглядит очень быстрым и оптимальным.
- На входе процесса идут бизнес-истории, описывающие функциональные требования на уровне бизнес-деятельности и кейсы по типам.
Я, как А, хочу получить Б.
Так сказать, классика, описанная в Confluence.
- Далее бизнес-история обрабатывается аналитиком, который превращает ее в задачу в Jira с прикреплением макетов форм и описанием сценария с точки зрения пользовательского интерфейса.
- Теперь задача ложится на разработчика, который уже пишет код. После чего реализация отправляется аналитику на тестирование.
- Дополнительно есть архитектор, который занимается нефункциональными требованиями, но организационно его решения формализуются как бизнес-истории и попадают в разработку аналогичным образом – через Jira.
Но не существует артефактов, обеспечивающих поддержку принятия технических решений без изучения кода.
И это выглядит так: Решение о реализации новой функции уровня микросервиса принимает конкретный разработчик при реализации конкретного бизнес-сценария (описанного в Jira).
- После реализации все его решения остаются только в коде (какой микросервис он выбрал, как назвал REST-параметры и какой json у нашего DTO, какие поля добавил в базу данных и т.д.
- Теперь при реализации клиента для этого отдыха, его модернизации или реализации нового REST другой разработчик на старте просматривает код, чтобы увидеть, как этот отдых был реализован или даже где он был реализован.
И хочется, как в том анекдоте, ничего не говорить, а дать таблетку, чтобы все само отвалилось.
Дальше будет куча букв и восемь страниц сухого текста TO-DO без всяких обоснований и сентенций.
Решение предлагает минимально возможную модель построения документации микросервисов в условиях абсолютного нежелания этим заниматься.
В решении представлена исключительно модель документов, их связность и управление, без описаний того, как собственно эти документы писать.
Существует много открытых вопросов относительно конкретной реализации решения.
Если вам интересна сама реализация, пишите вопросы в комментариях.
Цели документации
- Предоставить комплексное решение для документирования микросервисов в случае разработки с упором на код.
- Предоставление разработчикам и другим техническим специалистам четких инструкций о том, как читать и где искать информацию о микросервисах и реализации.
- Обеспечение «единого источника достоверных данных» для спецификации кода
Стратегия решения
В решении используются следующие подходы к документированию микросервисов:- Файл Readme.md — это основная часть документации по микросервисам, содержащая все общие описания и ссылки на другие части документации.
- Конечные точки REST документируются с использованием аннотаций Swagger. Затем он будет опубликован как спецификация Swagger Hub.
- Микросервис имеет предопределенные определения иерархии пакетов высокого уровня, которые обеспечивают дополнительный уровень понимания кода.
- Проблемы Jira — это источник информации обо всех разработках, связанных с конкретными микросервисами.
Связывание осуществляется с помощью объекта Jira — Component.
- все дополнительные источники документации по микросервисам могут находиться где угодно, но обязательно должны быть упомянуты в файле Readme.md
Модель документации
Общая модель документации изображена на следующей схеме.Более подробную информацию о реализации см.
в главе «Реализация».
Гитлаб
Файл Readme.md
Файл Readme.md является важной частью принципов документации.Этот файл является отправной точкой для получения знаний о микросервисах и «единой точкой доверия».
Этот файл должен присутствовать во всех репозиториях кода, чтобы предоставлять наиболее важную информацию о программном компоненте (здесь микросервис) и отвечать на следующие вопросы:
- Каков статус компонента?
- Кто является владельцем компонента?
- О чем этот компонент? Какова цель его использования?
- Какую область данных он обслуживает и за что отвечает?
- Какие варианты использования он реализует?
- Как это использовать? Как его построить? Как это настроить?
- Какая документация существует и где она находится?
md должен быть частью мерж-реквеста и аудита качества кода, особенно для новых вариантов использования.
Информация о том, «что делает этот микросервис», должна быть легко доступна без необходимости чтения кода.
Аннотации Swagger для служб REST
Аннотации Swagger для служб REST используются для конечных точек REST и документирования их моделей данных.Все конечные точки с аннотациями будут затем экспортированы в Swagger Hub как спецификация REST. Аналитики, тестировщики и архитекторы могут использовать эту спецификацию для автоматической настройки шлюза API и предоставления спецификации внешним подрядчикам.
Аннотации Swagger должны быть полными и правильными.
Полнота аннотаций должна быть неотъемлемой частью проверки кода.
В идеале определение REST должно предоставлять всю информацию, необходимую для его использования, без необходимости чтения кода или каких-либо внешних документов.
Предопределенная структура пакета кода
С точки зрения документации структура предопределенного пакета кода должна помочь определить назначение конкретных фрагментов кода на основе их размещения в пакете /src. Это может помочь во время аудита кода и при утверждении мерж-реквестов.
Другие источники документации в репозитории кода.
Было бы неплохо иметь специальный пакет, например /doc, для хранения других документов как части кода.
Например, это может быть AsciiDoc ( https://asciidoc.org/ ) и ПланУМЛ ( https://plantuml.com/ ).
Кроме того, для меня остается открытым вопрос о том, как лучше всего документировать уровень DAO, JPA и других интерфейсов, отличных от REST. Обязательно напишите, есть ли у вас рецепт в комментариях.
Джира
Jira — основной источник информации обо всех изменениях, которые были применены к реальному микросервису.Все проблемы Jira должны быть связаны с конкретным микросервисом, который был изменен конкретной проблемой.
Таким образом, все микросервисы будут связаны с конкретными реализациями и действиями, а также с журналом изменений.
Поскольку в текущем процессе разработки задача Jira является основным источником информации о необходимых изменениях, улучшениях и результатах, задача Jira является важным источником информации о том, какие варианты использования были реализованы, какой проектный документ (архитектурные решения) находится на стадии разработки.
связанный с конкретным микросервисом и так далее.
Объект Jira Component действует как ссылка от задач Jira к определенному микросервису.
Его имя должно соответствовать конкретному имени микросервиса.
Так что найти все задачи, связанные с тем или иным микросервисом, будет довольно легко.
Проблемы Jira должны относиться к затронутым микросервисам с соответствующими объектами-компонентами:
- задача разработки — должна быть связана хотя бы с одним затронутым микросервисом.
В целом, это было бы хорошим шаблоном для создания отдельных задач для всех задействованных микросервисов в рамках некоторых задач высокого уровня, которые должны быть специфичными для конкретной реализации варианта использования.
За эту задачу высокого уровня может отвечать архитектор программного обеспечения.
- исправление ошибки — необходимо подключиться хотя бы к одному затронутому микросервису
- проектирование решения (задача архитектора) — было бы хорошей практикой, если бы все документы по проектированию решения основывались на всех микросервисах, которые были частью этого решения.
Таким образом, все микросервисы автоматически подключаются к библиотеке проектирования решений.
Слияние
Отчет об услугах (см.схему) — сводный отчет обо всех микросервисах в одном месте.
Основная идея данного документа — предоставление автоматически собираемого отчета на основе информации в файле Readme.md. Отчет должен содержать информацию обо всех микросервисах в Gitlab, включая локальную копию файла Readme.md. Таким образом, его могут использовать люди, у которых нет доступа к репозиторию Gitlab.
Сваггер Хаб
Swagger Hub служит сводным отчетом обо всех конечных точках REST и создается автоматически на основе аннотаций Swagger. Продолжение во второй части, где описаны основные подходы к реализации.Часть 2 здесь Теги: #Управление разработкой #Микросервисы #проектирование и рефакторинг #микросервисы; гибкая разработка #микросервисы; гибкая разработка
-
Обсерватория
19 Oct, 24 -
На Пути К Ядру Python
19 Oct, 24 -
Дополненная Реальность Наоборот
19 Oct, 24 -
Тенденции Поиска На Euronews
19 Oct, 24
