🙂 Шаблонизаторы

Шаблонизаторы — инструменты для автоматической генерации текстовых данных на основе шаблонов и входных данных.

Используются в:
▫️API-интеграции: генерация HTTP-запросов и ответов, JSON/XML-запросов (например, Mustache в OpenAPI/Swagger)
▫️ESB: преобразование входящих сообщений в нужный формат (Freemarker в Apache Camel)
▫️MQ: формирование сообщений перед отправкой в очередь (Jinja2 в Celery, Handlebars)
▫️ETL: шаблоны для преобразования данных при загрузке в хранилище
▫️Создание конфигурационных файлов для разных окружений (Helm)
▫️Генерация технической документации
▫️Коде: создание CRUD-операций, DTO (Data Transfer Object), API-клиентов
▫️SQL: генерация динамических SQL-запросов, шаблоны для отчётов и аналитики (например, Jinja2 в dbt, Mustache в SQLAlchemy)


Примеры

⏪ Динамическое создание сценариев для разных ролей пользователей ⏩

Шаблон описывает процесс оформления заказа, но меняются условия для разных ролей:
🟡администратор может менять статус вручную
🟡менеджер получает уведомление
🟡клиент видит статус в личном кабинете
Вместо 3-х сценариев используется шаблон с переменными {role}, {action}, {notification}.
Например, с помощью Jinja2, Mustache

⏪ Гибкое преобразование данных ⏩

Форматы сообщений генерируются из шаблонов (например, FreeMarker или Jinja2):
🟡для банка нужен XML-формат: шаблон payment_template.xml
🟡для маркетинговой платформы JSON: шаблон email_template.json
🟡для ERP CSV-файл: шаблон orders_template.csv
Если банк меняет XML-структуру, достаточно обновить шаблон, а не переделывать всю интеграцию


Примеры шаблонизаторов

📌 Mustache — универсальный шаблонизатор для API, UI, конфигураций, доступен для различных языков программирования, включая JavaScript, Python и Ruby

✏️ Как применить
Разработка микросервисного API для обработки заказов

Проблемы:
❌ API-документация устаревает, обновлятся вручную
❌ доп время на написание Swagger/OpenAPI-описаний
❌ разные версии API дублируют документацию

Пример решения:
✔️ создается шаблон, где параметры API (методы, URL, заголовки) подставляются динамически
✔️ Swagger/OpenAPI автоматически заполняется актуальными значениями
✔️ любое изменение в коде API сразу отражается в документации


📌 FreeMarker — шаблонизатор на Java
Используется для генерации текстовых выходных данных (HTML, конфигурационные файлы, исходный код)

✏️Как применить:
Разработка веб-приложения

1. Динамическая генерация страниц (баланс, последние транзакции) с неизменной версткой

Контроллер Spring Boot передаёт в шаблон FreeMarker объект пользователя с балансом и историей операций.
FreeMarker подставляет данные в HTML и формирует готовую страницу
🔸если баланс больше 100 000₽, показывается статус «Премиум-клиент»
🔸если меньше 1000₽, предлагается «Пополнить баланс»
🔸история платежей подставляется в виде таблицы с циклом

2. Персонализация контента: разные предложения для пользователей

В шаблоне используются условия <#if> — если клиент VIP, добавляется блок с индивидуальными предложениями.
Контент обновляется без изменения логики бэкенда
🔸обычный клиент: «Оформите кредит под 10%»
🔸VIP-клиент: «Специальное предложение: кредит под 5%»

3. Повторное использование компонентов (хедер, меню, подвал) без копирования вручную

Общие шаблоны (layouts) с подключением через include
Если нужно изменить меню — правится один файл
-- все страницы используют один header.ftl* с логотипом и навигацией
-- в footer.ftl хранится контактная информация
-- основной шаблон (base.ftl) объединяет их в одну структуру
*FreeMarker Template Language (FTL)


📎 Материалы

1. Что такое и зачем нужны шаблонизаторы HTML
2. Текстовые шаблонизаторы и их реализация
3. Три неочевидных примера использования шаблонизаторов в backend-е
4. Шаблонизаторы HTML: что это и стоит ли их использовать в разработке
5. 15 шаблонизаторов для фронтенд-разработки
6. 6 лучших шаблонизаторов на PHP
7. 5 популярных PHP-шаблонизаторов
8. ТОП-10 шаблонизаторов HTML для web-разработки

#инфраструктура

➿➿➿➿➿➿➿➿

🧑‍🎓 Больше полезного в базе знаний по системному анализу

Может, познакомимся?

🔹 Канал активно ведётся уже почти 2 года, появилось 17+ тысяч подписчиков, а мы до сих пор не знакомы друг с другом. Надо исправляться.

Есть идея создать на базе нашего канала группу-комьюнити системных аналитиков, чтобы:
1. Обмениваться опытом друг с другом
2. Узнавать, как там работается в других местах
3. Что там по ЗП
4. Ну и просто болтать

Естественно, модерация и все дела.

💡 Есть также идея проводить митапы пару раз в месяц на определённые темы, за которые будут голосовать люди. Но нужны энтузиасты, которые готовы выступать НА ПУБЛИКУ 😱

💬 Пишите в комментариях всё, что думаете по этому поводу.

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

👥 Коммьюнити аналитиков

Как и обещали, создаём группу-комьюнити системных аналитиков, чтобы:
1. Обмениваться опытом друг с другом
2. Узнавать, как там работается в других местах
3. Что там по ЗП
4. Ну и просто болтать

Навигация по группе

📣 Митапы — проводим онлайн-встречи. Здесь можно стать спикером или проголосовать за желаемые темы

❔ Взаимопомощь по работе — здесь можно попросить помощи у коллег и помочь самому

💬 Болталка — общение на свободные темы

📂 Обмен материалами и опытом — делимся с коллегами чем-то полезным

💸 Зарплаты и условия труда — обсуждаем, кому, где и как работается

💡 Идеи и предложения — любые ваши улучшения и пожелания по поводу организации нашей группы

💼 Поиск работы — обсуждаем резюме, вакансии, вопросы и задачи к собесам и т.д.

Ждём всех!

🔍Фильтр Блума

Фильтр Блума — структура данных, которая помогает быстро проверить, может ли элемент находится в наборе данных или точно его там нет
🟢Используется, когда проверка наличия элемента должна быть быстрой, а использование памяти минимальным


Работает как "чек-лист", отвечает:
-Может быть, элемент есть (иногда может ошибится)
-Точно элемента нет


Как работает?

🟢создается битовый массив длины m
🟢он состоит из 0 и 1
🟢изначально массив выглядит так: [0, 0, 0, 0, 0, 0, 0, 0]
🟢каждая позиция (индекс) в этом массиве и значения (0, 1) — всё, что фильтр "запоминает"

🍃Добавляется элемент

Например, id со значением 12345
1⃣Фильтр пропускает id через несколько хэш-функций
Хэш-функция — математический алгоритм, который превращает строку ("12345") в числа (индексы массива), например:
- hash_1("12345") → 2
- hash_2("12345") → 5
- hash_3("12345") → 7
2⃣ Фильтр "ставит галочки" на этих позициях, т.е. устанавливает биты на этих индексах = 1:
[0, 0, 1, 0, 0, 1, 0, 1]
Фильтр запоминает, что на позициях [2, 5, 7] что-то есть

🍃Проверка элемента

Чтобы узнать есть ли id = 54321 в фильтре Блума
id снова пропускается его через те же хэш-функции:
- hash_1("54321") → 1
- hash_2("54321") → 3
- hash_3("54321") → 6

Фильтр смотрит на эти индексы в массиве: [0, 0, 1, 0, 0, 1, 0, 1]

Позиция 1 = 0 → id = "54321" точно не добавлялся
Если бы добавлялся, то позиция 1 была бы = 1

🍃 Если все проверенные индексы равны 1, то фильтр говорит → может быть, элемент есть
🍃 Если хотя бы один бит на позициях, которые вычислили хэш-функции, равен 0 → элемент точно отсутствует


Чего нет в фильтре Блума

❌ не хранит сами данные (например, список id). Хранит информацию в битовом массиве ( создаётся в оперативной памяти RAM). Это компактное представление множества
❌ не знает ничего напрямую о добавленных элементах

❗️У него есть только массив битов (позиции, которые связаны с добавленными элементами) и хэш-функции (для поиска индексов)


Примеры применения

🍃в БД
- для ускорения поиска записей без полного сканирования таблиц
- в индексах для предварительной проверки наличия ключа
🍃в веб-приложениях для быстрой проверки, есть ли объект в кэше, без полного перебора
🍃в блокировке спама для проверки, был ли email уже отправлен
🍃для уменьшения сетевых запросов (в Cassandra или Redis). Для предварительной проверки наличия данных на узле. Если фильтр говорит "данных нет", система нре делает запрос к этому узлу
🍃в CDN (Content Delivery Network) для проверки, есть ли контент на edge-сервере


Недостатки

🔸стандартный фильтр Блума не поддерживает удаление элементов (есть модификации, например, Counting Bloom Filter)
🔸может ошибаться из-за коллизий хэш-функций: некоторые индексы в массиве могут пересекаться (это коллизии).
Пример:
"12345" ставит 1 на позициях [2, 5, 7]
"67890" ставит 1 на позициях [5, 7, 8]
Фильтр может ошибочно считать, что элемент есть, хотя его нет
🔸не подходит, если нужна точность 100%
🔸если фильтр переполняется, ложноположительные срабатывания становятся слишком частыми


📎 Материалы
1. Что такое фильтр Блума?
2. Фильтр Блума: зачем нужен и как работает
3. Что такое фильтр Блума и как он работает на практике (с примерами)
4. Что такое фильтр Блума в Blockchain?
5. Вероятностные структуры данных и где они обитают
6. Фильтр Блума – вероятностная структура данных для проверки принадлежности элемента множеству
7. Просто о сложном: что фильтрует фильтр Блума?
8. Фильтр Блума
9. Когда фильтр Блума не подходит

#инфраструктура

➿➿➿➿➿➿➿➿

🧑‍🎓 Больше полезного в базе знаний по системному анализу

📄Подборка шаблонов документации

Общее
1. Как писать требования и документацию к проекту. Полный гайд с шаблоном документации и примерами заполнения — опыт Альфы
2. Ликбез по техническому заданию
3. Как оформить спецификацию, чтобы не запутаться самому и не выбесить коллег
4. Для архитекторов и аналитиков: шаблон описания архитектуры приложения (34 страницы пользы)
5. Как выжать максимум из Confluence: часть 1, часть 2
6. Матрица трассировки требований: руководство для системного аналитика

Стандарты
1. Стандарты и шаблоны для ТЗ на разработку ПО — обзор
2. Разработка Технического задания по ГОСТ 34 легко и просто — полный гайд по ТЗ ГОСТ 34

Docs as Code
1. Опыт аналитиков Альфы про доку в коде
2. Docs as Code: как вести фронтовую документацию рядом с кодом, чтобы репозиторий не раздуло — опыт Альфы

Интеграции
1. Как создать шаблон документации к микросервису — МТС
2. Пример ТЗ для описания API⁠⁠
3. Шаблоны документации API
4. Как написать свою первую спецификацию на REST API
5. Как мы описываем требования к REST API для бэкенда в Confluence — Magnit Tech
6. REST API: заполненный шаблон постановки задачи
7. Шаблон постановки задачи на REST API-метод для Confluence
8. Полная постановка задачи на интеграцию - заполненный шаблон требований

Требования
1. Шаблон спецификации требований
2. Как мы создали шаблон функциональных требований к разработке ПО
3. Шаблон пользовательских историй

➿➿➿➿➿➿➿➿
Для пользователей базы знаний доступны реальные сокровенные шаблоны спек от аналитиков одной из жёлтых компаний, да и вообще там много полезного

Непрерывное развитие АРI.
Правильные решения в изменчивом технологическом ландшафте

✍️ Автор: Мехди Меджуи, Эрик Уайлд, Ронни Митра, Майк Амундсен
🗓 Год издания: 2023
🔤 Язык: русский
📚 Объём: 368 стр.

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

Книга охватывает:
💙 сложности управления API (масштабирование, стандарты, работа команд)
💙 стратегическое руководство (баланс централизации и гибкости)
💙 API как продукт (дизайн-мышление, опыт разработчиков, конкурентные преимущества)
💙 10 столпов успешного API — от стратегии и безопасности до мониторинга и продвижения
💙 стили API и жизненный цикл (создание, публикация, окупаемость, поддержка, удаление)
💙 работу команд (роли, масштабирование, культура).
💙 системы API (управление в крупных экосистемах, контроль версий, изменения)


#api

🙂 Docs as Code

Docs as Code – подход к созданию и сопровождению документации.
🟢для работы с документами используются те же инструменты и процессы, что и для программного кода.
🟢текст пишут на языке разметки (Markdown, AsciiDoc), хранят в Git-репозитории и собирают с помощью генераторов сайтов (например, GitLab Pages, Docusaurus, Antora)
🟢публикуемая версия всегда синхронизирована с кодом и доступна потребителям


💡Идея: документация разрабатывается как код

Ообращение с текстом документации, как с исходным кодом приложения:
💠хранится в системе контроля версий
💠проверка изменений через pull request’ы
💠автоматизированно собирать и публиковать и т.д.

❕ Документация может храниться как в одном репозитории с кодом, так и в отдельном
Но всегда должна быть актуальной и согласованной с кодом (как и наоборот)


Суть подхода

Документация:
🔵хранится в репозитории Git
🔵пишется в IDE (VS Code или IDEA) с настроенными плагинами
🔵пишется на выбранном языке разметки, диаграммы описываются в формате кода (PlantUML, mermaid и др.)
🔵собирается при помощи генератора сайтов (например, Docusaurus)


Принципы написания документации

Написание спецификаций следует принципам написания кода, но имеет свои специфичные принципы

〰 Принципы из разработки

🟢DRY (Don’t Repeat Yourself)
Не дублируем информацию: один факт — один источник, остальные ссылаются

🟢KISS (Keep It Simple, Stupid)
Держим форму и язык простыми, без лишних деталей.

🟢YAGNI (You Aren’t Gonna Need It)
Пишем только то, что нужно прямо сейчас; гипотезы и «на будущее» убираем

🟢SRP (Single Responsibility Principle)
Один раздел — одна тема или функция

🟢SLAP (Single Level of Abstraction Principle)
Уровни абстракции не смешиваем: обзор и детали храним раздельно

🟢LoD (Law of Demeter)
Ссылаемся только на ближайший нужный контекст, избегаем дальних зависимостей


〰 Принципы, относящиеся к спецификациям

🟢читабельность — короткие абзацы, активные глаголы, минимум терминов
🟢единый стиль кодирования (структура текста, отступы, пробелы и т.д.) для облегчения понимания. Разрабатываются единые шаблоны документации и готовые блоки кода
🟢диаграммы как код — PlantUML, Mermaid, LikeC4: диаграммы генерируются из текста
🟢автоматизация пайплайна — CI проверяет орфографию, битые ссылки, формат
🟢отслеживание изменений, обновлений и исправлений в документах при помощи Changelog
🟢опубликованная версия документации является актуальной проду
🟢Merge Request, вливаемые в master, проходят ревью - без получения аппрува сделать mr нельзя
🟢Merge Request с изменениями в документации привязываются к задачам в Jira


Хранение документации

✳️ Рядом с кодом
Документация лежит в том же репозитории, что и сервис. Обычно в каталоге /docs.

Каждая ветка и тег кода несут свою версию текстов.
➡️ пример: GitLab хранит руководство пользователя в том же репозитории, чтобы изменения в продукте и тексте шли синхронно.

✳️ В отдельном репозитории
Документация развивается в своём проекте (или нескольких), независимом от исходников сервисов

Когда подходит:
🔵 доков много, обслуживают сразу несколько продуктов
🔵 требуется выпускать или править тексты без привязки к релизам кода


📎 Материалы
1. Docs as Code: введение в предмет
2. Опыт аналитиков Альфы про доку в коде
3. Docs as Code: как вести фронтовую документацию рядом с кодом, чтобы репозиторий не раздуло — опыт Альфы
4. Documentation as code: практики и инструменты документирования в сфере финансовых технологий
5. Статья о Docs as code от техписов - сайт собран как код на Rst
6. Инструменты подхода Docs-as-code

#инфраструктура #документация

➿➿➿➿➿➿➿➿
🧑‍🎓 Глубже по теме Docs as Code смотрите в Базе знаний по системному анализу :
⏺преимущества и недостатки Docs as Code
⏺сравнение с Confluence и другими подходами
⏺как понять, что Docs as Code действительно работает
⏺обзор инструментов
⏺пошаговое руководство, как внедрить Docs as Code
⏺как выбрать подход к документации

А ещё там 140+ статей и 2500+ ссылок на материалы -- и всё разложено по полочкам, как мы любим.

👀 Метрики и мониторинг

🙃 Метрики — данные, которые измеряют состояние системы
😂 Мониторинг — процесс сбора, анализа и визуализации этих метрик (для контроля работы системы и реагирования на проблемы)

Примеры типов метрик

😥Бизнес-метрики: отражают эффективность бизнес-процессов
(конверсия, средний чек, количество активных пользователей)
😥Технические: состояние инфраструктуры и приложений
(загрузка CPU, время ответа сервера, количество ошибок)
😥Пользовательские: оценка опыта пользователей
(время загрузки страницы, кол-во кликов до целевого действия)


Примеры технических метрик

Серверные
⭕CPU: загрузка процессора (%)
⭕Memory: использование оперативной памяти (%)
⭕Disk: использование дискового пространства (%), скорость чтения/записи
⭕Network: входящий/исходящий трафик (Мбит/с), кол-во соединений
Приложений
⭕Время ответа API (мс)
⭕Кол-во HTTP-запросов и ошибок (500, 404)
⭕Кол-во активных сессий
БД
⭕Время выполнения запроса (мс)
⭕Кол-во активных соединений
⭕Кол-во медленных запросов


Методологии анализа метрик

😂 USE

Анализ производительности ресурсов (CPU, память, диски, сеть)
Для инфраструктурных метрик
😍Utilization (Использование): какую часть ресурса используют (загрузка CPU на 80%)
😍Saturation (Насыщение): насколько ресурс перегружен (очередь запросов к диску)
😍Errors (Ошибки): например, ошибки чтения/записи

😂 RED

Для для мониторинга сервисов (часто микросервисов), API
😍Rate (Частота): кол-во запросов или событий в единицу времени (500 запросов в сек)
😍Errors (Ошибки): например, 10 ошибок "500" за мин)
😍Duration (Длительность): время выполнения запроса (среднее время ответа API — 200 мс, или  95-й перцентиль* времени ответа — 300 мс)
*какой % значений ниже определённого значения

😂 LTES

Расширенная версия RED, для сложных распределённых систем
😍Latency (Задержка): время ответа системы (ответ API  за 150 мс, или в бд время выполнения запроса — 50 мс)
😍Traffic (Трафик): кол-во запросов / данных (10 ГБ входящего трафика, в бд 5000 запросов в минуту)
😍Errors (Ошибки)
😍Saturation (Насыщение): насколько ресурс перегружен (загрузка памяти 90%, в бд очередь запросов 20 шт)


Подходы к сбору метрик

💚Push-модель
Агенты на серверах/приложениях отправляют данные на сервер мониторинга
➡ Prometheus Pushgateway: для отправки метрик от краткосрочных задач (например, cron-задач)
➡ Zabbix Agent: агент собирает данные (CPU, память, диски) и отправляет их на сервер Zabbix

💚 Pull-модель
Сервер мониторинга  запрашивает данные у агентов или экспортеров
Меньше нагрузки на сеть, сервер контролирует частоту запросов
➡ Prometheus Scrape: каждые 15 сек запрашивает метрики загрузки CPU у Node Exporter, установленного на сервере
➡ SNMP: протокол для мониторинга сетевых устройств (роутеры, свитчи)

💚 Логирование
Анализ логов для извлечения метрик (кол-во ошибок, время выполнения запросов)
Универсальный подход, логи есть почти везде
Можно анализировать исторические данные
➡ ELK (Elasticsearch, Logstash, Kibana) : Logstash собирает логи веб-сервера, парсит их и отправляет в Elasticsearch, Kibana визуализирует ошибки
➡ Grafana Loki: легковесное решение для анализа логов

💚Трейсинг
Отслеживание запросов через распределённую систему
Позволяет понять, как запрос проходит через компоненты системы
➡ Jaeger: отправляется запрос к API. Отслеживает, как он проходит через API Gateway, микросервис A и БД, измеряется время выполнения всех этапов


Инструменты мониторинга

Grafana: визуализация метрик
Prometheus: сбор и хранение метрик
ELK: логирование и анализ событий
Zabbix: мониторинг инфраструктуры
Nagios: мониторинг сетей и серверов


📎Материалы
1. Мониторинг начинается с метрик | Часть 2: серверное ПО
2. Как построить эффективную стратегию мониторинга
3. Основы мониторинга и сбора метрик
4. Мониторинг и сбор метрик
5. Руководство по мониторингу производительности сервера
6. Выбираем оптимальную архитектуру мониторинга
7. Как организовать мониторинг в мультипроцессорном режиме

#инфраструктура

➿➿➿➿➿➿➿➿➿➿

🧑‍🎓 Больше полезного в базе знаний по системному анализу

🔵 BASE

BASE (Basically Available, Soft state, Eventually consistent) — подход к проектированию распределённых систем
Жертвует строгой согласованностью (ACID) ради доступности, масштабируемости и гибкости

Когда используют

💠NoSQL-системы (Cassandra, MongoDB)
💠высоконагруженные сервисы (соцсети, аналитика)
💠системы, где важнее скорость ответа и отказоустойчивость, чем мгновенная актуальность данных


Три принципа BASE

😃asically Available (базовая доступность)

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

✏️ Как достигается
✨репликация (копирование данных на несколько узлов)
✨шардирование (данные делятся между кластерами)
✨кэширование


😓oft State (гибкое состояние)

Данные могут меняться со временем без внешних запросов
И могут временно находиться в несогласованном состоянии из-за асинхронных обновлений

✏️ Как достигается
✨асинхронная синхронизация
✨TTL (время жизни данных, например, обновление кэша раз в 5 мин)
✨фоновые процессы согласования


😶‍🌫️ventually Consistent (окончательная согласованность)

Система придет к согласованности, но не мгновенно

✏️ Как достигается
✨конфликт-разрешающие алгоритмы (например, CRDT, LWW)
✨подтверждение записи от большинства узлов (в Cassandra)
✨Read-Repair (исправление устаревших данных при следующих чтениях)
✨Kafka или RabbitMQ с отложенной синхронизацией


BASE vs ACID vs CAP

⭐ACID — как банковский перевод: либо деньги ушли и пришли полностью, либо операция отменена. Для систем, где важна точность (платежи, бухгалтерия)
⭐BASE — как почта: письмо точно ушло, но когда дойдёт — неизвестно

БД не может быть и ACID и BASE одновременно
Это противоположные подходы
Но некоторые гибридные СУБД (например, MongoDB) позволяют гибко настраивать уровень согласованности

⭐CAP — определяет фундаментальные ограничения распределённых систем
⭐BASE — практический подход в рамках этих ограничений

CAP-теорема: система может гарантировать только 2 из 3 свойств:
💠 cогласованность
💠 доступность
💠 устойчивость к разделению

✔ ACID выбирает CP (согласованность + устойчивость)
✔ BASE - AP (доступность + устойчивость)
✔ CA-системы (консистентность и доступность) возможны только в нераспределенных системах


Пример реализации BASE

Онлайн-магазин с высокой нагрузкой

😃: пользователь добавляет товар в корзину → система сразу подтверждает действие, даже если часть серверов перегружена

Товар появляется в корзине, но остатки на складе могут обновиться с небольшой задержкой

➡️ отправка запроса → API сразу возвращает успех (202 Accepted)

😓: данные о корзине и об остатках лежат в разных сервисах

Если два покупателя одновременно добавляют последний товар → оба увидят его в корзине, но физически доступен только 1

➡️ сервис корзин (Redis) временно сохраняет изменения
Сервис склада (Kafka + PostgreSQL) асинхронно проверяет остатки

😶‍🌫️: через несколько сек система проверяет остатки и синхронизирует данные

➡️ если товара нет, система убирает из корзины и отправляет уведомление


😃В ACID система заблокировала бы остатки при добавлении в корзину → очереди и ошибки под нагрузкой
BASE позволяет сначала принять действие, потом проверить ограничения
Это критично для высоконагруженных сценариев


📎 Материалы
1. BASE
2. Как бы я сейчас объяснил молодому себе… зачем существуют требования ACID для баз данных?
3. Требования ACID. BASE модель. CAP теорема
4. БАЗОВАЯ модель разработки БД
5. NoSQL: что это такое, отличие от других баз данных, BASE

📚Базы данных. Инжиниринг надежности - Кэмпбелл Лейн, Мейджорс Черити (Глава 11. BASE)

#бд

➿➿➿➿➿➿➿➿
🧑‍🎓 Больше полезного в базе знаний по системному анализу

📌 Альтернативы Swagger

Ранее писали про Swagger
Рассмотрим аналоги:

1️⃣Apiary (Oracle)

Ориентирован на Draft-first подход и работу с человеко-читаемой спецификацией (API Blueprint)

Плюсы

➕ онлайн-редактор без YAML
▫️ Swagger Editor требует знание YAML/JSON

➕ мок-сервер из коробки и предпросмотр без сборки
▫️ Swagger — только через сторонние решения (например, Prism)
Пример: описан метод POST /users, Apiary сразу отдаёт фейковый ответ с JSON-примером

➕ API Blueprint — текстовый формат, похожий на Markdown
▫️ Swagger работает только с OpenAPI
Пример: описание выглядит как документация, а не код


Минусы

〰️ нет полноценной поддержки OpenAPI
〰️ только облачный доступ (self-host невозможен)
〰️ не поддерживает генерацию кода или SDK


Когда использовать

🔵 на этапе проработки требований, при работе с бизнесом или в POC
🔵 в POC или пресейл-проектах, где важно быстро показать, как будет работать API

⏪Не заменит Swagger на проде, но упрощает начальный этап проектирования и согласования⏩


2️⃣ Postman

Изначально "тестировщик", стал универсальным инструментом для работы с API

Плюсы

➕ встроенные моки
▫️Swagger — только через внешние библиотеки (например, Prism)
Пример: создается мок на GET /products, и фронтенд может работать до бэкенда

➕ мониторинг и автотесты API
▫️ в Swagger такого функционала нет
Пример: можно настроить ежедневную проверку, что метод /status возвращает 200

➕ удобный GUI для ручного тестирования и демо
▫️ Swagger UI только визуализирует, без полноценного исполнения
Пример: при запуске запроса вручную можно поменять параметры и увидеть ответ в реальном времени


Минусы

〰️ YAML-редактирование невозможно — только коллекции
〰️ не предназначен для проектирования API (нет структуры, схем)
〰️ ограничения при работе в изолированных средах (облачный подход)


Когда использовать

🔵 после реализации API — для тестов, интеграции, демонстраций
🔵 когда нужен ручной контроль и проверка API-методов

⏪Postman — эксплуатационный инструмент.
Swagger выигрывает в спецификации, но проигрывает в удобстве тестов
Можно использовать в связке со Swagger/OpenAPI⏩

❗️Важно: документация в Postman не заменяет полноценную OpenAPI-спеку — только дополняет её


3️⃣ Stoplight

Платформа для проектирования, документации и тестирования API с фокусом на визуал
Ориентирован на API-first подход и работу с OpenAPI-спецификациями

Плюсы

➕ визуальный редактор OpenAPI
▫️Swagger Editor требует знание YAML/JSON
Пример: можно проектировать API с помощью drag-and-drop-интерфейса, без ручного кода

➕ мок-сервер из коробки
▫️ Swagger — только через сторонние решения

➕ совместная работа и контроль версий
▫️ в Swagger нет ролей и git-интеграцией
Пример: можно оставить комментарий на конкретный endpoint и пройти ревью API

➕ генерация документации и SDK
▫️ в Swagger SDK подключпается отдельно (например, Swagger Codegen)
Пример: можно получить готовую обёртку для клиента на TypeScript или Python

➕ интеграция с Git, CI/CD
▫️ Swagger Editor работает отдельно, не привязан к процессу разработки
Пример: при пуше новой ветки спецификации автоматически пересобирается документация и обновляются моки


Минусы

〰️ нет оффлайн-режима, только облачная версия (self-host в платной версии Stoplight Enterprise)
〰️ только OpenAPI формат описания


Когда использовать

🔵 проектируются API с нуля, важна командная работа и версионирование
🔵 важно разделить работу между аналитиками, архитекторами и разработчиками
🔵 нужно управлять API как продуктом, в рамках CI/CD, с документацией, моками и тестами в одном месте

⏪Не заменяет Swagger Codegen или Swagger UI в простых сценариях, но масштабируется в корпоративной среде.
Для команд, где API — это ключевой контракт между фронтом и бэком⏩


📎 Материалы
1. 3 лучших инструмента для описания RESTful API
2. 7 инструментов для работы с API с бесплатными тарифами
3. 8 лучших инструментов документации API в 2024 году
4. Тестирование API: виды, методы, инструменты
5. Как выбрать инструмент для тестирования API
6. swagger.io: аналоги и похожие приложения

➿➿➿➿➿➿➿➿
🧑‍🎓 Больше полезного в базе знаний по системному анализу

👥 Почему брокеры ничего нам не гарантируют?

22.06.25 (воскресенье) в 18:00 по Мск состоится третий вебинар от Федерации Аналитиков

📆 Тема: Почему брокеры ничего нам не гарантируют — о природе гарантий доставки в брокерах, и почему на самом деле их нет

🔘Спикер: Андрей Бураков, автор и ведущий курсов и интенсивов по интеграции и архитектуре. Основатель школы аналитиков NextWay

Ранее — аналитик и разработчик в масштабных интеграционных проектах в банковском секторе, руководитель отдела системного и бизнес анализа в продуктовой компании

📍 Где: онлайн, Контур.Толк

☑️ Тайминг: выступление на ~ 40 мин + секция вопросов от ребят

📆 Добавить встречу в календарь: https://calendar.app.google/u4msho9tNiK6Tk8c7

(Ссылка на конференцию там же)

При добавлении встречи в календарь напоминание о мероприятии придет за 1 день, за 1 час и за 15 мин

‼️ Запись будет

⌛ Gap-анализ

Gap-анализ — метод выявления расхождений между текущим состоянием системы (As-Is) и целевым состоянием (To-Be)
⚪️цель: определить, какие изменения нужны для достижения результата

Суть

Сравнение двух моделей (текущей и целевой) для выявления отличий, которые мешают достичь конечного состояния

Помогает ответить на вопросы:
⚪️где сейчас? (As-Is)
⚪️куда нужно прийти? (To-Be)
⚪️что мешает туда попасть? (Gap'ы)

Каждый найденный gap трансформируется в конкретные действия: изменения, доработки, внедрения


Зачем нужен

Помогает:
✨ обосновать изменения
✨ сформировать требования к будущей системе
✨ определить объем доработок, сроки, ресурсы
✨ оценить риски и приоритеты внедрения


Когда можно применять

⏺ на этапе пресейла или discovery-фазы
⏺ при внедрении коробочных решений (ERP, CRM)
⏺ при интеграции нескольких систем
⏺ при автоматизации процессов
⏺ при миграции со старой системы на новую


Примеры типов gap'ов

➖Функциональные — отсутствуют нужные функции
➖Процессные — отличаются шаги, роли, триггеры
➖Технические — несовместимость интерфейсов, API
➖Данные — разная структура, нехватка атрибутов
➖Ролевые — не хватает нужных ролей или прав


Пример как проводить

1️⃣Описать текущее состояние (As-Is)
✨Пример: в системе нет уведомлений клиенту.

2️⃣ Определить целевое состояние (To-Be)
Фиксируется желаемое поведение, функции, архитектура, UX
✨нужно автоматическое уведомление клиента через SMS и email

3️⃣ Выявить разрывы (gaps)
Сравниваются состояния по направлениям (функции, данные, процессы и т.п.).
✨Gap — нет интеграции с внешним SMS-шлюзом

4️⃣ Сформировать требования на закрытие gap'ов
✨добавить модуль уведомлений, реализовать логирование отправки

5️⃣ Оценить трудозатраты и приоритизировать изменения
Gap'ы группируются по сложности, влиянию и срочности


Примеры применения

Внедрение ERP
⚪️Gap-анализ выявляет, какие бизнес-процессы нужно адаптировать под коробку, а какие — доработать

Миграция на новую систему
⚪️сравниваются старые и новые функции, выявляются недостающие элементы

Соблюдение законодательства (например, 152-ФЗ)
⚪️позволяет проверить текущие процессы согласно новым требованиям к хранению и обработке персональных данных

Автоматизация ручной отчетности
⚪️Gap: отчеты формируются вручную
→ требуется автоматизация


Типичные ошибки

Поверхностное описание As-Is или To-Be
⏺пример: описание процесса без указания ролей и шагов
→ пропущенные gap'ы, неверные требования, ошибки в архитектуре

Нет детализации функций или данных
⏺не все поля указаны в текущем отчёте
→ неполный результат

Отсутствие вовлечения экспертов и пользователей
⏺анализ проведён только с IT-стороной, без операционного персонала
→ упущены потребности, сопротивление изменениям при внедрении

Смешивание «хотелок» с реальными бизнес-целями
⏺добавлены функции, которые «было бы хорошо», но они не влияют на результат
→ избыточные требования, увеличение сроков и бюджета


📎 Материалы

1. Использование GAP-анализа для выявления и согласования задач по проекту
2. Gap-анализ (анализ несоответствий) и модель развития элементов ит-архитектуры
3. Гэп технологий и бизнеса: стресс/расхождение плана с фактом/причина недостижения целей

#развитие #документация

➿➿➿➿➿➿➿➿
🧑‍🎓 Больше полезного в базе знаний по системному анализу

➡ 2PC (двухфазная фиксация)

2PC (Two-Phase Commit) – паттерн для гарантии атомарности* распределенных транзакций
*атомарность – "всё или ничего": либо выполняются все операции транзакции, либо ни одна

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

🤩Принцип работы: протокол выполняется в две фазы под управлением центрального координатора
 

Роли участников

🤩 Координатор (Coordinator)
Управляет процессом, принимает решение
➖центральный управляющий компонент
➖инициирует протокол 2PC
➖принимает решение (Commit/Abort) на основе голосования ресурсов
➖отвечает за уведомление ресурсов о решении и управление восстановлением при сбоях

🤩Примеры
- транзакционные менеджеры
- СУБД-координатор
- оркестраторы

🤩 Ресурсы (участники)
Выполняют локальные операции, голосуют
➖системы или сервисы, управляющие данными (например, БД)
➖выполняют локальную работу транзакции ("до" коммита)
➖голосуют "Да" (готов к коммиту) или "Нет" (не готов) на фазе Prepare
➖выполняют финальную команду (commit/abort) от координатора

🤩Примеры
- БД
- Очереди сообщений
- Legacy-системы


Фазы

➡️Prepare (Подготовка)

🟡 Координатор ➡️ Ресурсы: координатор рассылает ресурсам команду prepare (запрос голосования)
🟡 Ресурсы:
- проверяют возможность коммита своей части транзакции (проверка ограничений, конфликтов, запись в локальный лог для восстановления)
- блокируют данные (локальные блокировки)
- проверяют возможность коммита
🟡 Голосование ресурсов (отправляют координатору):
- vote_commit (если готов)
- vote_abort (если не готов) и выполняют локальный откат

⬅️Commit (Фиксация) / Abort (Отмена)

Если все vote_commit:
🔘 Координатор  ➡️Ресурсы: рассылает команду commit
🔘 Ресурсы фиксируют изменения, разблокируют данные
- фиксируют изменения данных
- освобождают блокировки
- отправляют координатору ack (подтверждение)
🔘 Координатор, получив все ack, завершает транзакцию

Если хотя бы один vote_abort (или таймаут):
🔘 Координатор  ➡️ Ресурсы: abort (или rollback)
🔘Ресурсы откатывают изменения по журналу
- откатывают свою часть транзакции
- освобождают блокировки
- отправляют координатору ack
🔘 Координатор, получив все ack, завершает транзакцию (как отмененную)


Сценарии работы

🤩 Успешная Транзакция

1. клиент делает перевод 100 руб со счета А (ресурс 1) на счет Б (Ресурс 2)
2. координатор шлет prepare обоим банкам
3. банк А: проверяет наличие 100 руб, блокирует их, голосует "Да"
    банк Б: проверяет можно ли зачислить, голосует "Да"
4. координатор шлет commit
5. банк А: Списывает 100 руб, освобождает блокировку
    банк Б: Зачисляет 100 руб. Оба шлют ack
6. клиент получает подтверждение

🤩Отказ ресурса и восстановление

🟡 Сбой во время prepare: ресурс не ответил
Координатор трактует как vote_abort "Нет" → Откат всех

🟡Сбой ресурса после vote_commit: ресурс упал до получения commit
- при восстановлении ресурс смотрит в свой лог: prepare есть, а commit/abort нет
- ждёт команду координатора (состояние "in doubt")

🟡Сбой координатора после записи решения:
- после записи решения → при рестарте пересылает решение ресурсам
- до записи решения → ресурсы остаются заблокированными до ручного вмешательства


Примеры применения

🤩Legacy-системы: интеграция старых монолитных систем (особенно БД) через стандарт XA
🤩когда критична строгая согласованность в реальном времени на уровне отдельных транзакций между разными системами (счета, ленты транзакций, бухгалтерия)
🤩системы, где ресурсы (БД, очереди) поддерживают интерфейс XA для участия в транзакциях под управлением внешнего TM


📎 Материалы

1. Управление транзакциями в бд
2. Способы управления транзакциями в распределённых ИС. Механизм 2pc
3. 2pc в распределённых транзакциях
4. 2pc и будущее распределённых систем 
5. Распределённые транзакции в микросервисах: от SAGA до 2pc

📚 Распределенные системы. Паттерны проектирования – Брендан Бернс

#проектирование #архитектура


➿➿➿➿➿➿➿➿
🧑‍🎓 Больше полезного в базе знаний по системному анализу

🔼Классы доступности систем

Доступность системы (SA,Service Availability) — отношение времени, когда система работала, к общему времени

Availability (%) = (Время работы / Общее время) × 100

🔘Пример: если система работала 364 дня и 6 часов в году:
Availability = (364.25 / 365) × 100 ≈ 99.79%


Метрики доступности

💙 Uptime / Downtime

💙Uptime — сколько времени система работает
💙Downtime — сколько система была недоступна (по любым причинам: сбои, обновления, ошибки конфигурации)

Эти метрики логируются в большинстве APM/мониторинговых систем (например, Datadog, Pingdom, New Relic, Zabbix)

💙 MTBF (Mean Time Between Failures)

MTBF = Общее время работы / Кол-во сбоев

💙показывает, как часто происходят сбои
💙чем выше MTBF 💙, тем надёжнее система
💙полезен для оценки стабильности инфраструктуры

💙MTTR (Mean Time To Recovery)

MTTR = Общее время восстановления / Кол-во инцидентов

Показывает, сколько времени в среднем уходит на устранение сбоя

📌MTBF и MTTR рассчитываются на основе логов событий и инцидентов
🌸Для автоматизации этих расчетов можно использовать Prometheus + Grafana, Zabbix, Datadog


RTO и RPO

🤩RTO (Recovery Time Objective) — за сколько времени должна быть восстановлена система после сбоя

Пример: RTO = 15 мин → система должна заработать не позже чем через 15 мин после сбоя

🤩RPO (Recovery Point Objective) — максимальное допустимое время потери данных

Пример: RPO = 5 мин → допустимая потеря не более 5 мин данных (время с последнего бэкапа или репликации)

❗️Эти параметры обязательно обсуждаются при выборе архитектуры и процедур восстановления


Примеры под разные классы доступности

💙 Класс 99% (базовая надёжность)

💙один сервер, одно приложение, одна БД
💙резервные копии раз в сутки
💙мониторинг вручную или Zabbix/Prometheus без алертов
💙downtime в случае обновлений или перезапуска

💙 Класс 99.9% (высокая доступность)

💙балансировка нагрузки: NGINX / HAProxy
💙минимум два экземпляра приложения
💙репликация БД (например, master-slave PostgreSQL)
💙автоматический мониторинг и алерты (Prometheus + Alertmanager)
💙оркестрация: Docker Compose / простейший Kubernetes кластер

💙 Класс 99.99% (отказоустойчивость)

💙геораспределённость: приложения и БД в разных зонах доступности
💙Active-Passive конфигурация (один сервер работает, второй на подстраховке. При сбое первый отключается, второй включается)
или Active-Active (оба сервера работают одновременно. Нагрузка распределяется. Если один падает — второй продолжает без переключений)
💙автопереключение при сбое: Patroni для PostgreSQL (управляет кластерами PostgreSQL — автоматически назначает нового мастера)
💙CI/CD с canary/blue-green деплоем
💙RTO/RPO оговорены и тестируются

💙Класс 99.999% (непрерывная доступность)

💙многоуровневая геораспределённая архитектура
💙реальное Active-Active с кворумами (например, CockroachDB)
💙самовосстанавливающийся кластер (Kubernetes)
💙контейнерные образы зафиксированы по версии
💙тестирование отказов в проде (chaos engineering)


📎Материалы

1. Классификация критичности информационных систем
2. Типы информационных систем и их уровни защищённости
3. Доступность IT-систем: поругаться или договориться?
4. MTBF — откуда берется «миллион часов MTBF»
5. Разбираемся с метрикой «Среднее временя между сбоями» (MTBF)
6. RTO и RPO: что это и в чём отличия

📚 Site Reliability Engineering. Надежность и безотказность как в Google

#архитектура

➿➿➿➿➿➿➿➿
🧑‍🎓 Больше полезного в базе знаний по системному анализу

✉️ Apache Kafka: типы доставки | защита от дублей | партиции и масштабирование

Типы доставки сообщений

©️At most once
Продюсер отправляет сообщение и не ждет подтверждения
При сбое данные могут потеряться

➡️ пример: отправка логов, где потеря одной записи некритична

✳️как работает: продюсер не ждёт подтверждения от брокера (acks=0), консьюмер сразу обновляет офсет

©️At least once
Продюсер отправляет сообщение, ждет подтверждения. При сбое может отправить повторно, появляются дубли

➡️ платёжная система, где потеря недопустима, но дубли можно обработать

✳️ продюсер ждёт подтверждения (acks=all), консьюмер обновляет офсет только после обработки

©️Exactly once
Идеальная гарантия: без потерь и дублей. Kafka поддерживает механизм Transactional Producer

Реализуется через:
🔸Идемпотентные продюсеры (Kafka 0.11+) – подавление дублей на стороне брокера
🔸 транзакции между продюсером и консьюмером
🔸 ограничения: работает только в рамках одного кластера Kafka

➡️ обработка заказов: заказ фиксируется в БД + отправляется событие в Kafka в одной транзакции

‼️ на практике exactly once сложно обеспечить
Если Kafka сохраняет сообщение один раз, потребитель может ошибиться (например, дважды обработать запись)

Кратко
🟠At most once → без подтверждения → возможны потери
🟠 At least once → с подтверждением → возможны дубли
🟠 Exactly once → транзакции + идемпотентность → нет потерь и дублей, но дорого и сложно


Защита от дублей

При использовании At least once возможны дубли, нужно предусматривать их обработку

🔸 Индекс уникальности

Можно настроить ключи сообщений так, чтобы консьюмер сохранял только уникальные значения

- продюсер генерирует message_id (UUID или хэш содержимого)
- брокер или БД консьюмера проверяет уникальность перед записью

➡️ пример: база заказов с уникальным индексом по order_id → повторная запись невозможна

🔸 Паттерн Outbox

- при обновлении данных сервис сохраняет событие в отдельную таблицу Outbox вместе с основной записью
- фоновый процесс читает события из Outbox и отправляет их в Kafka

➡️ пример: интернет-магазин записывает заказ в основную таблицу и событие "OrderCreated" в Outbox. Затем отдельный процесс отправляет событие в Kafka

🔸 Паттерн Inbox

Используется на стороне консьюмера
- все события сохраняются в отдельную таблицу Inbox перед обработкой
- при сбое необработанные события можно переобработать без риска дублирования

➡️ пример: сервис оплаты принимает событие "OrderPaid", сохраняет его в Inbox, затем подтверждает обработку

⏪Inbox и Outbox часто применяются вместе, для обеспечения надёжности и идемпотентности при взаимодействии между микросервисами через Kafka⏩


Партиции и масштабирование

Партиция — минимальная единица хранения и обработки сообщений в Kafka
Масштабирование Kafka-кластера напрямую зависит от числа партиций

Связь: партиции ➡️ консьюмеры ➡️ сервисы:
🔵 партиция может быть одновременно прочитана только одним консьюмером в группе
🔵 консьюмер — отдельный процесс или поток приложения, читающий данные из Kafka
🔵 сервис — приложение / микросервис, который внутри себя запускает одного или несколько консьюмеров
🔵каждый экземпляр сервиса (или процесс) фактически становится одним консьюмером Kafka

❗️Важно

🔵 чтение и запись могут происходить параллельно по количеству партиций
Чем больше партиций, тем выше параллелизм обработки
🔵порядок сообщений сохраняется только внутри одной партиции

Почему важно количество партиций

©️если партиций мало → масштабировать обработку за счёт увеличения количества сервисов не получится
©️если партиций много → можно масштабировать консьюмеров горизонтально (новые инстансы будут получать работу)


📎 Материалы

1. Гарантии доставки сообщений в Kafka
2. Синхронизация асинхронности: Dead Letter и Inbox для обработки зависимых сообщений
3. Как обработать миллион сообщений из kafka
4. Под капотом продюсера Kafka: UML-диаграмма публикации сообщений
5. Kafka за 20 минут. Ментальная модель и как с ней работать

📚 Дилан Скотт, Виктор Гамов, Дейв Клейн. Kafka в действии

#интеграции

➿➿➿➿➿➿➿➿
🧑‍🎓 Больше полезного в базе знаний по системному анализу