[Проектирование и рефакторинг, Управление разработкой, Микросервисы] Что делать если никто не хочет документировать? Организация документирования микросервисов по минимуму — часть 2
Автор
Сообщение
news_bot ®
Стаж: 6 лет 9 месяцев
Сообщений: 27286
Эта статья является продолжением. Первую часть смотри тут
Подход к реализации
Файл Readme.md
Общая информация о файле Readme.md представлена здесь — https://www.makeareadme.com/.
Фактическая версия файла должна находиться в ветке по умолчанию.
Файл должен иметь следующую структуру:
- Название компонента
- Статус компонента (микросервиса) и его владелец
- Описание компонентов. Его назначение и связанная область данных
- Описание функциональности как набор реализованных сценариев использования.
- Инструкция по использованию, сборке и развертыванию
- Описание конфигурации
- Ссылки на документацию
- Важные советы и ссылки
Readme.md — Статус компонента (микросервиса)
В этой части должна содержаться информация о текущем состоянии компонента и его текущих версиях, находящихся в производстве или разработке. Статус показывает, что можно сделать с микросервисами в какой ветви.
Рекомендуемая структура статуса следующая:
- CREATED — микросервис создан, но в производстве нет версий. Пока не планируется запускать его в производство. Никаких ограничений не предусмотрено.
- DEV — разработка. Статус версии микросервисов, которая еще не запущена в производство, но будет выпущена. Каждый статус DEV должен указывать на соответствующую ветку. Статус DEV предполагает привязку к соответствующим ветвям выпуска. Таким образом, перед созданием новой ветки выпуска предполагается, что файл Readme.md в основной ветке должен быть обновлен новой веткой информации о выпуске.
- PROD- в производстве. Рабочая версия микросервисов. Каждый статус PROD должен указывать на соответствующую ветку. Таким образом, после нажатия в производственной конкретной ветке выпуска предполагается, что файл Readme.md в основной ветке должен быть обновлен с новым статусом выпуска. Кроме того, предыдущий выпуск может быть обновлен как статус EOL.
- EOL — конец жизни. Бетонный релиз снят с производства во всех средах.
- ARCHIVE- микросервис (как конкретное репо) удален из всех сред, и больше не предполагается подключение к нему задач разработки.
Readme.md — Владелец компонента
В этой части показано, кто является владельцем микросервиса и, следовательно, отвечает за его архитектуру и возможности. Обязанности собственника могут быть разными и зависеть от ситуации и текущей политики процесса развития
Readme.md — Описание компонентов
Описание компонента предполагает краткое объяснение, описывающее ваши микросервисы в терминах «О чем компонент?» и «Какова цель его использования?». Предполагается, что это описание того, какие общие сценарии использования решают микросервисы и какую область данных они обрабатывают.
В общем, это не должно превышать 30-50 строк текста, потому что это микросервис, а не типичное монолитное приложение.
Описание должно быть достаточно четким, чтобы предоставить всем разработчикам и архитекторам информацию, которая может им понадобиться для принятия решения — какие варианты использования целесообразно добавить в этот микросервис. Если по какой-либо причине в микросервис будет добавлен какой-то новый функционал, его описание необходимо расширить. В целом, это может быть хорошей точкой на этапе мерж запроса в качестве дополнительной точки архитектурного контроля.
Readme.md — Описание вариантов использования
Этот раздел должен содержать список всех вариантов использования, реализованных этим микросервисом. Предполагалось использовать уникальный номер варианта использования (который относится к используемому реестру вариантов использования) и имя варианта использования (не более одной строки текста).
На этапе слияния необходимо проверить, обновил ли разработчик часть вариантов использования в файле Readme.md в случае реализации нового варианта использования.
Readme.md — Инструкция по использованию, сборке и развертыванию
Этот раздел служит источником информации о том, как настроить, собрать и развернуть компонент. Самая важная часть — это описание всех файлов конфигурации и основных параметров конфигурации.
Предлагается иметь здесь единый список всех жизненно важных файлов конфигурации. Кроме того, все параметры конфигурации должны быть задокументированы в соответствующих файлах конфигурации с помощью комментария или java-doc.
В случае использования общего подхода к файлам конфигурации было бы лучше иметь ссылку на конкретную страницу Confluence с описанием общих параметров.
Приложения и инструменты, которые работают только на определенных платформах, должны иметь поддерживаемые версии операционной системы, указанные в этом разделе Readme.
Если ваш код полагается на другое приложение или библиотеку, обязательно укажите эти зависимости здесь.
Кроме того, это хорошее место для раздела часто задаваемых вопросов, который можно использовать для хранения полезных советов, которые обычно разработчики задают в чате разработки.
Readme.md — Ссылки на документацию
В этом разделе представлен набор ссылок на другую полезную документацию, которая может быть полезна для понимания того, как обрабатывать и использовать компонент (микросервис).
Предопределенная структура пакета кода
К структурированию кода могут быть разные подходы. Основная причина для этого — предоставить такую структуру, которая могла бы предоставить дополнительную информацию о том, что должен делать класс, занимая свое место в структуре пакета.
Во-вторых, общая структура может быть полезна на этапе мерж запроса в качестве дополнительной линии контроля. Например, если нет изменений в пакетах для остальных контроллеров, нет причин для дополнительного контроля зависимых компонентов.
Предлагаемая модель структуры пакета кода основана на «подходе гексагональной архитектуры» — https://en.wikipedia.org/wiki/Hexagonal_architecture_(software).
Пример структуры пакета кода может быть следующим:
- inbound — содержит все классы для входящих интерфейсов микросервиса в качестве предоставленных сервисов. Деление по функциональным доменам
— сервис — сервисные интерфейсы, которые должны быть реализованы как часть бизнес-части. Входящий контроллер вызывает этот интерфейс.
— dto — пакет для объектов dto, которые используются входящими сервисами и контроллерами
— контроллеры — пакет для реализации конкретных контроллеров: rest, Kafka, MQ и тд. Поскольку одна и та же входящая услуга может быть реализована с помощью разных технологий, здесь может быть несколько подпакетов
- outbound- содержит все классы для потребляемых внешних сервисов. Например, может быть реализация остального клиента, шина событий и реализация журнала. Деление по функциональным доменам
— service — реализация вызова исходящей службы, которая должна использоваться классами бизнес-уровня
— dto — объект передачи данных для вызова внешней службы
— клиенты: rest, Kafka, MQ и др. реализация конкретного внешнего сервиса клиента
- domain — содержит все классы, сохраняемые микросервисом в его базах данных.
— по структуре домена базы данных — содержит репозиторий JPA и определение объекта данных. Кроме того, он может содержать объекты кеша, NoSQL, файлы и все другие источники данных, требующие операций CRUD со стороны микросервиса
- bussines — включает все необходимые классы бизнес-логики, включая манипулирование данными и бизнес-проверки данных. Деление по функциональной области — здесь нет строгих требований к бизнес-пакетам
Во избежание ненужных зависимостей кода (и для упрощения документации) не должно быть прямых зависимостей между «inbound», «outbound» и «domain» пакетами. Только классы из бизнес-пакета могут напрямую использовать эти пакеты.
Кроме того, такое разделение классов сокращает необходимый объем документации по классам, и минимально необходимо документировать только только эти пакеты, так как они отвечают за межкомпонентное взаимодействие, о котором нельзя прочитать в коде -).
Аннотации Swagger для служб REST
Документирование службы REST для микросервисов — важная часть системной интеграции. Документация REST должна быть настолько полной, чтобы ее можно было использовать без необходимости чтения кода.
Аннотации Swagger должны содержать как минимум следующую информацию:
- Функциональная область
- Имя варианта использования, чтобы можно было легко найти исходные требования и тестовые примеры для конечного пользователя.
- определение ресурсов
- определения параметров
- определения заголовков
- область авторизации и необходимые роли безопасности, если это применимо
Модель документа Jira
Это отличный способ использовать журнал задач и проблем в качестве источника документации о микросервисе в контексте цели микросервиса, реализованной пользовательской истории и связанных архитектурных решений.
В общем, структура артефактов Jira может быть похожа на следующую диаграмму:
Все пользовательские истории — это Jira-issue, связанные с соответствующими issue проектирования, разработки или ошибок. Те, с другой стороны, подключены к определенному микросервису с помощью Component Object Jira. Таким образом, в результате мы можем достичь прочной связи между микросервисами, их функциональной документацией и библиотекой архитектуры решения.
Детали реализации могут быть разными, но основная идея будет той же — как с минимальными усилиями связать кучу документации из разных источников (например, в Confluence) с конкретной реализацией микросервиса.
Confluence может быть отличным местом для библиотеки документации, так что все проблемы, связанные с историей пользователей и решениями, должны быть связаны с соответствующей страницей документации в Confluence.
Swagger-HUB
Swagger-HUB в настоящее время широко используется используется и тут нет особого смысла описывать его имплементацию. Главное чтобы она была автоматизирована, включена в build-pipeline, предоставлялась также для релизных веток а не только для продуктивной.
Заключение
Наличие актуальной документации очень важно для повышения качества системы и скорости разработки. С первой стороны, похоже, что разработчику, которого заставляют задокументировать свой код, придется снизить скорость разработки. Но, с другой стороны, существует необходимый минимум документации, без которой процесс разработки замедляется из-за большого количества времени, необходимого для доработок, рефакторинга и исправления ошибок.
Более того, отсутствие минимальной документации обеспечивает тесную связь разработчиков с их кодом. В результате у нас может быть в результате «несменяемая суперзвезда», что может стать реальной проблемой в процессе разработки.
Второй момент: лучше не иметь документации вообще, чем иметь неактуальную и устаревшую документацию. В некоторых случаях текущее состояние и актуальность SwaggerHub не соответствуют действительности, поэтому он бесполезен в качестве источника API.
Таким образом, недостаточно просто внедрить схему. Контроль документации должен быть частью проверки мерж-реквеста и цепочки контроля качества в целом. Все несоответствия в документе рекомендуется рассматривать как ошибку для повышения качества. Кроме того, рекомендуется рассматривать всю документацию (которая напрямую не связана с репо и файлом Readme.md) как отдельную задачу с соответствующими задачами в Jira.
Всем спасибо за внимание!!!
===========
Источник:
habr.com
===========
Похожие новости:
- [Тестирование IT-систем, Управление разработкой, Конференции] 26 августа приглашаем на круглый стол QA&SDET
- [Управление разработкой, Управление персоналом] Кто там выше тимлида?
- [Управление разработкой, Развитие стартапа, Управление продуктом, Карьера в IT-индустрии] Создание программного продукта и управление его развитием. Позиционирование продукта
- [Разработка веб-сайтов, PHP, Программирование, Проектирование и рефакторинг, Google API] Настройка Gmail API для замены расширения PHP IMAP и работы по протоколу OAuth2
- [Управление разработкой, Развитие стартапа, Управление продуктом, Карьера в IT-индустрии] Создание программного продукта и управление его развитием. От реализации идей — к проверке гипотез
- [Системное администрирование, *nix, Оболочки, DevOps, Микросервисы] Blue-Green Deployment на минималках
- [PostgreSQL, Kotlin, Микросервисы, Kubernetes] Как мы в 2020 году изобретали процесс разработки, отладки и доставки в прод изменений базы данных
- [PHP, Проектирование и рефакторинг, Серверная оптимизация, Параллельное программирование] Пишем простую ORM с возможностью смены БД на лету
- [Высокая производительность, Мозг, Управление проектами, Управление разработкой] Как создать KPI по стрессу — и превратить его из врага в помощника
- [Разработка веб-сайтов, Python, Управление разработкой] Исправь код, продай техническую фигню, покрути рулетку на Russian Python Week 2020
Теги для поиска: #_proektirovanie_i_refaktoring (Проектирование и рефакторинг), #_upravlenie_razrabotkoj (Управление разработкой), #_mikroservisy (Микросервисы), #_microservices;_agile_development, #_proektirovanie_i_refaktoring (
Проектирование и рефакторинг
), #_upravlenie_razrabotkoj (
Управление разработкой
), #_mikroservisy (
Микросервисы
)
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 22-Ноя 22:28
Часовой пояс: UTC + 5
| Автор | Сообщение |
|---|---|
|
news_bot ®
Стаж: 6 лет 9 месяцев |
|
 Эта статья является продолжением. Первую часть смотри тут Подход к реализации Файл Readme.md Общая информация о файле Readme.md представлена здесь — https://www.makeareadme.com/. Фактическая версия файла должна находиться в ветке по умолчанию. Файл должен иметь следующую структуру:
Readme.md — Статус компонента (микросервиса) В этой части должна содержаться информация о текущем состоянии компонента и его текущих версиях, находящихся в производстве или разработке. Статус показывает, что можно сделать с микросервисами в какой ветви. Рекомендуемая структура статуса следующая:
Readme.md — Владелец компонента В этой части показано, кто является владельцем микросервиса и, следовательно, отвечает за его архитектуру и возможности. Обязанности собственника могут быть разными и зависеть от ситуации и текущей политики процесса развития Readme.md — Описание компонентов Описание компонента предполагает краткое объяснение, описывающее ваши микросервисы в терминах «О чем компонент?» и «Какова цель его использования?». Предполагается, что это описание того, какие общие сценарии использования решают микросервисы и какую область данных они обрабатывают. В общем, это не должно превышать 30-50 строк текста, потому что это микросервис, а не типичное монолитное приложение. Описание должно быть достаточно четким, чтобы предоставить всем разработчикам и архитекторам информацию, которая может им понадобиться для принятия решения — какие варианты использования целесообразно добавить в этот микросервис. Если по какой-либо причине в микросервис будет добавлен какой-то новый функционал, его описание необходимо расширить. В целом, это может быть хорошей точкой на этапе мерж запроса в качестве дополнительной точки архитектурного контроля. Readme.md — Описание вариантов использования Этот раздел должен содержать список всех вариантов использования, реализованных этим микросервисом. Предполагалось использовать уникальный номер варианта использования (который относится к используемому реестру вариантов использования) и имя варианта использования (не более одной строки текста). На этапе слияния необходимо проверить, обновил ли разработчик часть вариантов использования в файле Readme.md в случае реализации нового варианта использования. Readme.md — Инструкция по использованию, сборке и развертыванию Этот раздел служит источником информации о том, как настроить, собрать и развернуть компонент. Самая важная часть — это описание всех файлов конфигурации и основных параметров конфигурации. Предлагается иметь здесь единый список всех жизненно важных файлов конфигурации. Кроме того, все параметры конфигурации должны быть задокументированы в соответствующих файлах конфигурации с помощью комментария или java-doc. В случае использования общего подхода к файлам конфигурации было бы лучше иметь ссылку на конкретную страницу Confluence с описанием общих параметров. Приложения и инструменты, которые работают только на определенных платформах, должны иметь поддерживаемые версии операционной системы, указанные в этом разделе Readme. Если ваш код полагается на другое приложение или библиотеку, обязательно укажите эти зависимости здесь. Кроме того, это хорошее место для раздела часто задаваемых вопросов, который можно использовать для хранения полезных советов, которые обычно разработчики задают в чате разработки. Readme.md — Ссылки на документацию В этом разделе представлен набор ссылок на другую полезную документацию, которая может быть полезна для понимания того, как обрабатывать и использовать компонент (микросервис). Предопределенная структура пакета кода К структурированию кода могут быть разные подходы. Основная причина для этого — предоставить такую структуру, которая могла бы предоставить дополнительную информацию о том, что должен делать класс, занимая свое место в структуре пакета. Во-вторых, общая структура может быть полезна на этапе мерж запроса в качестве дополнительной линии контроля. Например, если нет изменений в пакетах для остальных контроллеров, нет причин для дополнительного контроля зависимых компонентов. Предлагаемая модель структуры пакета кода основана на «подходе гексагональной архитектуры» — https://en.wikipedia.org/wiki/Hexagonal_architecture_(software). Пример структуры пакета кода может быть следующим:
Во избежание ненужных зависимостей кода (и для упрощения документации) не должно быть прямых зависимостей между «inbound», «outbound» и «domain» пакетами. Только классы из бизнес-пакета могут напрямую использовать эти пакеты. Кроме того, такое разделение классов сокращает необходимый объем документации по классам, и минимально необходимо документировать только только эти пакеты, так как они отвечают за межкомпонентное взаимодействие, о котором нельзя прочитать в коде -). Аннотации Swagger для служб REST Документирование службы REST для микросервисов — важная часть системной интеграции. Документация REST должна быть настолько полной, чтобы ее можно было использовать без необходимости чтения кода. Аннотации Swagger должны содержать как минимум следующую информацию:
Модель документа Jira Это отличный способ использовать журнал задач и проблем в качестве источника документации о микросервисе в контексте цели микросервиса, реализованной пользовательской истории и связанных архитектурных решений. В общем, структура артефактов Jira может быть похожа на следующую диаграмму:  Все пользовательские истории — это Jira-issue, связанные с соответствующими issue проектирования, разработки или ошибок. Те, с другой стороны, подключены к определенному микросервису с помощью Component Object Jira. Таким образом, в результате мы можем достичь прочной связи между микросервисами, их функциональной документацией и библиотекой архитектуры решения. Детали реализации могут быть разными, но основная идея будет той же — как с минимальными усилиями связать кучу документации из разных источников (например, в Confluence) с конкретной реализацией микросервиса. Confluence может быть отличным местом для библиотеки документации, так что все проблемы, связанные с историей пользователей и решениями, должны быть связаны с соответствующей страницей документации в Confluence. Swagger-HUB Swagger-HUB в настоящее время широко используется используется и тут нет особого смысла описывать его имплементацию. Главное чтобы она была автоматизирована, включена в build-pipeline, предоставлялась также для релизных веток а не только для продуктивной. Заключение Наличие актуальной документации очень важно для повышения качества системы и скорости разработки. С первой стороны, похоже, что разработчику, которого заставляют задокументировать свой код, придется снизить скорость разработки. Но, с другой стороны, существует необходимый минимум документации, без которой процесс разработки замедляется из-за большого количества времени, необходимого для доработок, рефакторинга и исправления ошибок. Более того, отсутствие минимальной документации обеспечивает тесную связь разработчиков с их кодом. В результате у нас может быть в результате «несменяемая суперзвезда», что может стать реальной проблемой в процессе разработки. Второй момент: лучше не иметь документации вообще, чем иметь неактуальную и устаревшую документацию. В некоторых случаях текущее состояние и актуальность SwaggerHub не соответствуют действительности, поэтому он бесполезен в качестве источника API. Таким образом, недостаточно просто внедрить схему. Контроль документации должен быть частью проверки мерж-реквеста и цепочки контроля качества в целом. Все несоответствия в документе рекомендуется рассматривать как ошибку для повышения качества. Кроме того, рекомендуется рассматривать всю документацию (которая напрямую не связана с репо и файлом Readme.md) как отдельную задачу с соответствующими задачами в Jira. Всем спасибо за внимание!!! =========== Источник: habr.com =========== Похожие новости:
Проектирование и рефакторинг ), #_upravlenie_razrabotkoj ( Управление разработкой ), #_mikroservisy ( Микросервисы ) |
|
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 22-Ноя 22:28
Часовой пояс: UTC + 5