Как получить надёжный список всего, из чего состоит система?

#Что это такое

Реестр компонентов

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

Если проще Опись: каждая отдельная вещь, из которой сделана ваша программа, с назначением и местом, где она живёт.

Это самая плоская и наименее эффектная часть технической картины — и обычно первая, которая кому-то по-настоящему нужна. «Сколько тут вообще движущихся частей» — это первый вопрос любой передачи, любой технической проверки перед сделкой и первой недели любого нового инженера.

#Почему его ни у кого нет

Не потому, что трудно записать. Из-за того, что происходит после того, как записали.

• Он устаревает раньше, чем закончен. Список, который собирали две недели, описывает систему, которая за эти две недели сдвинулась.
• Границы спорны. Это сервис или модуль? Очередь — компонент или деталь реализации? Два человека составят из одной системы два разных списка, и оба будут защитимы.
• Интересные записи — те, о которых никто не помнит. Задание по расписанию, которое кто-то добавил в 2023-м. Маленький внутренний API, от которого зависит другая команда. Отчёт, который каждый понедельник шлёт таблицу почтой.
• Ничто не заставляет его обновлять. Добавление компонента в систему не требует добавления его в список, поэтому список настолько свеж, насколько дисциплинирован конкретный человек.

Первым трём помогает то, что список выводится из анализа, а не из памяти. Четвёртая решается только тем, что его выводят снова.

#Что содержит хорошая запись

#Тождество — это и есть вся задача

Реестр, который не узнаёт компонент в двух анализах, — не реестр. Это два несвязанных списка.

Подумайте, что должно быть верно, чтобы фраза «сервис биллинга теперь пишет ещё и в базу аудита» вообще могла появиться. Система должна понять, что сервис биллинга в сентябрьском анализе — тот же самый, что и в майском, даже если класс переименовали, файл переехал, а описание другой агент написал иначе.

Названия этого не выдержат. Один только путь тоже. Поэтому от каждого компонента требуется что-то устойчивое:

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

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

#Как он выглядит

СЕРВИС             Сервис биллинга
                   Создаёт счета и записывает попытки оплаты.
                   app/Services/Billing/          ·  уверенность ВЫСОКАЯ

СЕРВИС             Сервис подписок
                   Хранит, на что подписан каждый клиент и когда
                   продление.
                   app/Services/Subscriptions/    ·  уверенность ВЫСОКАЯ

БАЗА ДАННЫХ        Основная база
                   Заказы, платежи, счета, подписки.
                   внешний id: db.main            ·  уверенность ВЫСОКАЯ

ОЧЕРЕДЬ            Очередь платежей
                   Работа, ожидающая расчёта с провайдером.
                   внешний id: queue.payments     ·  уверенность СРЕДНЯЯ

ЗАДАНИЕ            Ночная выгрузка
                   Пишет CSV с платежами за прошлые сутки.
                   app/Console/Commands/          ·  уверенность ВЫСОКАЯ
                   ⚠ получатель не установлен

ВНЕШНЯЯ СИСТЕМА    Платёжный провайдер
                   Принимает платежи по картам.
                   внешний id: ext.payments       ·  уверенность ВЫСОКАЯ

#Для чего он нужен

• Оценить объём передачи. «Двадцать три компонента, у четырёх никто не может назвать владельца» — это объём. «Это приложение на Laravel» — нет.
• Найти забытые части. Задания по расписанию и маленькие внутренние интерфейсы — это то, что реестр показывает, а разговор нет.
• Техническая проверка перед сделкой. Первый вопрос покупателя — что он покупает. Это самый короткий честный ответ.
• Ввод в работу. Новый инженер с типизированным списком частей и их назначений стартует на неделю раньше.
• Обнаружение изменений. Реестр — это то, что сравнивает история изменений.

#Чего в нём нет