Руслан Сафин ♟️

Разбор моего телеграм-канала "Архитектура распределённых систем" (t.me/rsa_enc) от Дениса Бескова: t.me/denis_beskov/346 ❤️

Про документацию, неоднозначность термина "as Code" или вопросы от подписчиков. > Руслан, привет!) а подскажи пож-та, может есть у тебя ссылочки на шаблоны/примеры/лучшие практики по документированию архитектуры и инфраструктуры системы Вопросы документирования и особенно актуальности документации — на мой взгляд, одни из самых больных в нашей с вами айтишечке. Но, если дело касается сущностей, которые мы можем описать кодом (или как код) — всё становится сильно проще. 1️⃣ Лучшая документация — это всегда актуальная документация. Такой вариант возможен только в двух случаях: 🌹 при автоматической генерации документации (описания) из реального положения дел (для исполняемого кода API таким примером будет Swagger) 🌹 или же наоборот — генерации "реальности" из описания (в случае Infrastructure as Code примером может быть разворачивание инфраструктуры из её описания в yaml-формате). 2️⃣ Если лучший вариант нам недоступен, то хорошо бы нам хотя бы иметь автоматический сигнал о том, что наша документация разъехалась с реальностью (или наоборот). 🚨 Источником такого сигнала должны стать тесты — мы их можем и будем запускать при любом изменении и системы (реальности), и её описания. И в случае расхождения тесты должны падать (блокируя тем самым дальнейшее попадание порождающих несоответствие изменений в основную ветку/новый релиз и т.д.). Базовое свойство тестов — они должны быть воспроизводимы и независимы от внешних условий. Именно поэтому ручные проверки не попадают в эту категорию (регламентированная ручная проверка на актуальность документации при каждом тестировании не работает, т.к. имеет в основе своей человеческий фактор). 3️⃣ а вот третьего, на мой взгляд, не дано. Либо у вас есть автодокументация, либо есть автоматизированные тесты, проверяющие актуальность. В противном случае — всё, ваша документация рано или поздно в бо́льшей или меньшей степени, но станет неактуальной. Без вариантов. И никакими оффлайн-процессами или регламентами это не решить. Есть, конечно, ещё один граничный случай — это когда в проект никаких изменений не вносится.. Но это означает, что проект мёртв, и этот случай нам неинтересен ⚰️ Итак, возвращаясь к архитектуре и инфраструктуре. 🌺 Начнём с инфры. Если у вас реализован подход Infrastructure as Code (IaC) и всё разворачивается из кода (описания) инфры — то уже всё хорошо. По сути ваши yaml или другие файлы и являются документацией (сюда попадает не только статичная инфра, но и различная инфраструктурная логика: мониторинг и правила алертинга, например). А если хочется иметь документацию по инфраструктуре в более удобном и наглядном виде — всегда можно написать различные генерилки/визуализаторы из yaml и json в красивый текст и схемки (или даже интерактивный, как у Swagger). А возможно, такие инструменты уже и существуют (накидайте, плиз, если да). 🌺 С архитектурой всё чуть сложнее. Подход Architecture as Code (AaC) в отличие от IaC не предполагает, что по описанной в коде архитектуре всё будет разворачиваться и работать согласно ей. В большинстве случаев предполагается лишь описание архитектурных схем кодом из которого генерируется картинка, а не просто картинкой. В таком случае Architecture as Code на самом деле всего-то навсего Architecture Scheme as Code ☹️. Т.е. не сама ИТ-архитектура, а лишь опять же её документация в виде схемки или нескольких. Тут некоторые читатели могут задаться вопросом — а что же такое ИТ-архитектура, если не просто схемка или набор схемок? Готовясь к одному из своих докладов, я гуглил разные определения ИТ-архитектуры. И к своему удивлению нашел одно из лучших, на мой взгляд, в стандарте (ANSI/IEEE Std 1471-2000): «Фундаментальная организация системы, реализованная в её компонентах, их взаимоотношениях друг с другом и средой и принципах, определяющих её конструкцию и развитие» Т.е. архитектура — это даже больше чем просто "описание реальности" как IaC, но и принципы, определяющие в том числе и её развитие (т.е. будущее). Но сейчас не об этом... Про то, что такое архитектура надо будет как-нибудь отдельный пост написать 🙂 (и это на 4й-то год существования моего тг-канала (t.me/rsa_enc) со словом "архитектура" в названии 😅😆 ). Скрепя сердце приравняв архитектуру к документации, вернемся к вопросу актуальности этой документации. Описав архитектурные схемки кодом (т.е. применив AaC) мы можем пойти описанными выше путями в плане автодокументации или тестов на актуальность, но для этого нужны ещё инструменты над AaC (см. ниже). Т.е. всё-таки as Code нам помогает, хоть и в меньшей степени, чем в IaC, где as Code уже гарантирует соответствие реальности и описанию (коду). Вот так, размышляя о документации, мы пришли к выводу о различии подходов, называемых as Code в инфраструктуре и архитектуре 🥲. А теперь обещанные ссылки на мои инструменты, если кто ещё не видел. Разделы Open-Source репозитория (github.com/Byndyusoft/aact) с инструментами и примерами: - автогенерация архитектуры: github.com/byndyusoft/aact?t… - тесты на актуальность архитектуры: github.com/byndyusoft/aact?t… Статья про покрытие тестами: habr.com/ru/articles/800205/ Общий доклад про все инструменты: rutube.ru/video/8ed42e502d51… Оффтоп. И всё-таки, согласно в том числе и определению из стандарта, архитектура — это в том числе и принципы на которых она построена, а один из способов описания таких принципов (ещё и сразу же автоматизирующий проверку их выполнения) — это тесты на соблюдение архитектурных принципов: github.com/byndyusoft/aact?t… Всё. Теперь точно всё ) ❤️

Впервые публично рассказал про выведенный мной Принцип каскадного снижения связанности! 🚀 Как и обещал — делюсь слайдами (docs.google.com/presentation…), а также еще полезными материалами, на которые ссылался в рамках необыкновенно продолжительной сессии вопросов и ответов в экспертной зоне: ⭐️ Гранулярность микросервисов. Статья: habr.com/ru/companies/oleg-b… и видео доклада: youtube.com/watch?v=x1xqlXny… ⭐️ Лаконичное и понятное описание паттернов проектирования микросервисной архитектуры: microservices.io/ ⭐️ Ссылки на телеграм-каналы Максима Смирнова и Максима Юнусова, а также на архитектурный хакатон публиковал ранее: t.me/rsa_enc/306 ⭐️ Канал архитектурных кат: t.me/arch_katas_russia