Рабочий шаблон архитектурного решения

Здравствуйте, меня зовут Денис Галушко, я зам. главного архитектора финансовой группы БКС. До этого работал архитектором, тимлидом, программистом. Периодически у себя в компании провожу митапы на тему «как делать архитектурные решения» и, конечно же, согласую тонны архитектуры. Далее идет вступление, которое можно пропустить, но в нем - мудрость!

Зачем мы делаем архитектурное решение

Зачастую разработчики делают АР, только для формального согласования уже написанного кода. Если вы поступаете также, ваш проект "грохнется" рано или поздно. Накопятся ошибки в проектировании, вырастет до небес техдолг, сменится поколение программистов и вот оно, приехали. В первую очередь, АР нужен для вдумчивого проектирования и обсуждения с коллегами. В процессе изготовления АР вся команда договаривается как решать задачу. Под командой подразумевается не только команда разработки, но и бизнес-заказчик, согласующие из ИБ и Архитектуры, поставщики АПИ из других проектов, получатели и поставщики данных. В итоге, в АР фиксируются договоренности и происходит формальное согласование. В конце процесса в общем хранилище компании остаётся документ, который отвечает на вопросы: что хотели заказчики, как запланировали сделать, почему именно так, какие были варианты.

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

Почему не надо самореализовываться в формате документа

Еще раз про велосипеды

Архитектурное решение - стандартный документ. Не стоит начинать изготовление АР с попытки придумать свой вариант шаблона. Да, творческим людям, коими являются программисты и аналитики, свойственно изобретать что-то своё уникальное. Именно оно кажется наиболее подходящим здесь и сейчас. С опытом мы учимся меньше изобретать "велосипеды", начинаем больше использовать чужой опыт. Предложенный шаблон АР - это многолетний опыт департамента архитектуры приложений БКС. Шаблон "вылизывали" годами, и он готов к использованию как есть. А комментарии помогут понять зачем каждый раздел появился в документе и как его заполнять.Постарайтесь заполнить все, что от вас требует шаблон. Во-первых, это поможет вам правильно структурировать своё собственное понимание задачи и задать себе необходимые вопросы. Во-вторых, это облегчит чтение документа, а значит его согласование. Облегчит потому, что тем, кому приходится читать много подобных документов, хочется найти все на своих местах, а не рыться в очередном «творении».

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

Далее идет шаблон. Точнее, текст инструкции по его заполнению. Сам шаблон оформляется в виде шаблона Confluence. Пояснения в нем намного короче и оформляются в виде "инструкций", которые исчезают в сохраненном документе. Шаблон в виде файла можно найти здесь.

Название архитектурного решения

Название страницы д.б. : "АР Название" или "SAD Название" или "ARCH-XXX Название".

Шапка документа

Следующая таблица помещена внутрь макроса Confluence "Сводная таблица". В дальнейшем она попадает в виде строчки в сводные таблицы всех арх.решений компании. Confluence собирает их по теэгу "ар", которым ОБЯЗАТЕЛЬНО должен быть помечен каждый документ. 

История изменений

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

Участники проекта и согласователи

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

Оглавление

Здесь находится макрос оглавления, который я для краткости удалил.

1. Общие сведения о проекте

1.1  Глоссарий

Описание акронимов и терминов, применяемых в документе.

Если в документе все термины уже неоднократно описаны и общеизвестны, не надо их дублировать еще раз. Просто поставьте прочерк.

1.2  Описание проекта

Коротко описать какую проблему решает данное архитектурное решение, кто инициировал разработку. 

Результат проекта должен обеспечить достижение следующих целей:

• Перечислить цели.

Заказчиком работ выступает:

• Подразделение - заказчик или конкретный руководитель. 

Основными потребителями результатов проекта будут:

• Клиенты направления Y, сотрудники подразделения Х. 

Проект реализуется в следующих ограничениях:

• Ограничения по данным, подразделениям, бизнесам, реализуемым процессам и т.д. Целевое/не целевое решение. Все ли поставленные задачи решает АР или только часть.

2. Бизнес-архитектура

Разделы, после прочтения которых не должно остаться вопросов, что требуется бизнесу.

Т.е. какие обстоятельства привели к возникновению данной задачи; какие требования были на входе; какой процесс разработан исходя из требований. 

2.1  Обзор предметной области

Заполнение данного раздела не обязательно, но является правилом хорошего тона. Приводим полезные для понимания документа сведения. Может быть описанием предметной области. Или описанием потребностей пользователя в продукте, который мы будем переделывать. Стоит описать исторические предпосылки возникновения потребности или проблемы. В общем, пишем все, что облегчает погружение в суть проекта. 

2.2  Требования

Если документа с требованиями еще нет, то требования ОБЯЗАТЕЛЬНО надо зафиксировать здесь. Если требования не зафиксированы, значит архитектор начал работу не имея необходимых входных данных. И результат работы будет соответствующий.

Копируем требования в этот раздел, либо делаем ссылку на конкретную версию документа, либо прикладываем файл документа в таблицу взаимосвязей.

2.3  Целевой бизнес-процесс

Раздел описывает процессы, которые изменяются или добавляются данным решением. Схема бизнесс процессов является важнейшей частью функциональных требований. И вместе с не функциональными требованиями является входными данными для архитектора. За описание бизнесс-процессов отвечает бизесс-аналитик. Сделайте ссылку на конкретную версию документа со схемами БП или скопируйте схему в АР с указанием первоисточника. Если БП есть в требованиях, то здесь делаем ссылку на документ БТ.

Если схемы нет, то архитектору рекомендуется описать процесс текстом в виде иерархического списка шагов (нумерованных пунктов). Классический подход предполагает описание бизнес-процесса в виде схемы BPMN 2.0. Но для архитектора - это избыточная работа. По моему опыту, простой список шагов достаточен для понимания задачи. Это быстро и не требует специальных знаний и инструментов.

Также можно оформить БП в виде сиквенс-диаграммы.

3. Описание архитектурного решения

Разделы, отвечающие на вопрос "как мы решаем задачу"

3.1 Описание предложенного подхода

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

Например: Фронтом для клиента будет БКС Мир Инвестиций. Процесс будет оркестрировать бизнес-сервис ХХХ. У него есть база, в которой будет хранится состояние процесса и такие-то данные. Для подписания поручений используем стандартный набор сервисов центральной команды. Данные скоринга будут загружаться раз в день из ХХХ. Поручения выполняем в асинхронном режиме, поскольку в процессе есть шаги, выполняемые в бэкофисной системе. И т.д.

Если релевантно, стоит упомянуть какие варианты были рассмотрены, их плюсы и минусы, и почему выбрано именно такое решение.

3.2 Информационная архитектура

Схема информационных потоков с описанием.

Как оформить схему

Стрелки на схеме - потоки данных. Каждая стрелка подписывается номером потока и коротким названием группы данных, которую он передает. Если схема с именами потоков получается слишком громоздкой, то в местах с большой плотностью рисунка допускается сокращение надписи до номера. Но, по возможности, названия потоков надо сохранять. Это сильно облегчает чтение схемы. Искать описание каждого потока в таблице под схемой утомительно и долго. Детали потоков раскрываются в таблице после схемы. Для сообщений MQ необходимо указать ожидаемый средний размер и кол-во в день. Для потоков http прогноз нагрузки тоже приветствуется. 

Блоки на схеме - системы, модули или микросервисы. У нас принято микросервисы обозначать буквами МС в названии. Иначе не очевидно, что это именно микросервис, а не какой-то модуль или транспорт или еще что-то. 

Не надо на схеме информационных потоков отдельными блоками рисовать транспорт. Лучше обозначить на стрелке, что это MQ(AMQP/Biz) или REST или еще что-то. Либо полупрозрачными блоками на пути стрелок, как на примерах ниже. Транспортные системы выделяются в отдельные блоки только, если они несут какую-то смысловую нагрузку: модифицируют данные или оркестируют потоки. Транспорт, т.е. технология передачи данных, раскрывается в разделе Системная архитектура. 

Цветом выделяются потоки и системы, которые добавляются или меняются.

Альтернативная схема:

Мы поддерживаем три варианта схем инфопотоков: классический и расширенный, где сгруппированные потоки данных идут от источника к получателю, и запросный, где стрелки указывают направление запроса, и каждая стрелка - это отдельный запрос.  

Классический

Стрелки идут от источника данных к получателю. Каждая стрелка - это группа данных, либо объединение нескольких групп. Группы данных перечисляются в надписи на стрелке. 

Расширенный

На примерах ниже все потоки снабжены информацией, по какому протоколу они передаются, какие коннекторы используются. Это может показаться лишним на схеме информационных потоков. В классическом понимании - это так и есть, ведь в таблице после схемы все эта информация тоже есть. Но мы пришли к выводу, что протокол и вид коннектора не перегружают схему, но при этом делают ее самодостаточной. Становится понятно как работает вся схема: где поток синхронный, где асинхронный; какие промежуточные системы задействованы; какие будут особенности в каждом взаимодействии. И в расшифровку потоков приходится смотреть значительно реже.

Запросный

По сути, данный формат - это описание АПИ. Стрелки указывают направление запроса. Каждая стрелка - отдельный вызов АПИ, либо очередь MQ. Формат ближе к системному, но, тем не менее, таковым не является. Потому, что допускает упрощения, не показывает границы сегментов, кластеров и т.п.  Поэтому, публикуем схему в разделе Информационная архитектура.

Информационные потоки:

* - обязательно для сообщений MQ.

Информационные системы:

3.3 Системная архитектура

Раздел описывает проект программного решения с точки зрения системных компонент, реализующих информационную архитектуру. Акцент делается на технологиях, расположение программных компонент по ЦОД-ам, кластерам и сегментам сети. Указываются протоколы, адаптеры, шины. В данной схеме инфопотоки делятся уже не по группам данных, а по протоколам и видам взаимодействия. Т.е. схема отражает физическое воплощение предлагаемого решения. Но это не схема развертывания. В ней нет конкретных устройств и IP-адресов. Отсутствие данной информации позволяет архитектору не тратить время на выяснение малозначимых с точки зрения проектирования деталей. А также снимает секретность со схемы. Ведь сетевая схема - лакомый кусочек для шпионов.

Схема помогает:

• понять какие физические механизмы и системы задействованы в проекте. Их владельцев надо не забыть указать в доработках и согласователях;

• специалистам по информационной безопасности оценить какие сегменты сети преодолевают чувствительные данные;

• разобраться какие сетевые доступы надо запросить. 

3.4 Схема развертывания

Если проект того требует, в этом разделе мы можем поместить deployment-схему. Если требуется сетевая схема с IP-адресами и конкретным оборудованием, то весь документ приобретает статус секретного, поскольку мы раскрываем пути проникновения в инфраструктуру предприятия. Поэтому, мы стараемся делать схему развертывания отдельным документом. 

4. Реализация

4.1  Требования к реализации

Раздел описывает требования к реализации архитектурного решения: важные условия и ограничения, которые необходимо учитывать при реализации; требуемая модернизация инфраструктуры, и т.д.

4.2  Доработка систем

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

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

5. Информационная безопасность

5.1  Бизнес операции, подлежащие аудиту

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

5.2  Аутентификация пользователей

Короткое описание механизма аутентификации пользователей и модулей системы. Если механизм не относится к базовым - в случае БКС это KeyCloack и Kerberos -, то надо описать где хранятся учетные записи, как добавляются/изменяются/удаляются, как происходит аутентификация.

В случае KeyCloack обязательно указываем realm. Если микросервисы используют технические учетные записи для вызова друг друга, указываем, что они должны храниться в Vault.

5.3  Авторизация пользователей систем

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

5.4  Доступ к внешним данным

Здесь нужно прописать сетевые соединения, которые инициируют модули системы или микросервисы во внешнюю сеть. Под внешней сетью понимаются менее доверенные сегменты сети предприятия (DMZ, например) и Интернет. По этой таблице будет настроено сетевое окружение.

6. Нефункциональные требования и дополнительная информация

7. Открытые вопросы

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

• Адресован  @ 23.12.2018 Вопрос: ___

• Вопрос: ___

<Конец шаблона>