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

Общее
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 в действии

#интеграции

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

🔼🔽Согласованность данных

Согласованность (consistency) — состояние, когда все пользователи и процессы видят одни и те же данные при чтении
🤩согласованность не равна целостности (integrity)
🤩целостность описывает корректность данных внутри системы (например, наличие внешних ключей, ограничения на значения)

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


Виды

⚪️Строгая (strong consistency): после записи данные моментально видны всем
✨пример: традиционные реляционные БД с синхронными транзакциями

⚪️В конечном счёте (eventual): данные со временем сходятся, но на промежутке возможны расхождения (DynamoDB, Cassandra)

⚪️Последовательная (sequential): все операции видятся в одном порядке, но нет гарантии мгновенной видимости

⚪️Каузальная (causal): операции, имеющие причинно-следственную связь, видятся в правильном порядке

⚪️Слабая (weak): система не гарантирует моментальной или даже определённой очередности обновлений

При выборе вида согласованности:
✨учитывать нагрузку, ожидаемые задержки, требования к откатам и репликации
✨можно использовать матрицу реiений с параметрами: задержка, SLA по доступности, бизнес-ущерб при ошибке и тд

Примеры

⏺ Критичные данные (банковские счета, заказы, бронирования) ➡️ strong consistency
⏺Для аналитических / временных данных ➡️ eventual consistency или quorum-based решения


CAP-теорема, ACID, BASE и согласованность

🤩CAP-теорема утверждает: распределённая система может одновременно гарантировать только две из трёх свойств:
- согласованность
- доступность
- устойчивость к разделению
🤩Устойчивость к разделению обязательна для любой распределённой системы, выбор обычно стоит между согласованностью и доступностью.


🤩ACID (Atomicity, Consistency, Isolation, Durability) — свойства традиционных реляционных транзакций
🤩Гарантируют строгую согласованность и корректность данных, но плохо масштабируются


🤩BASE (Basically Available, Soft state, Eventually consistent) — подход, характерный для NoSQL-систем:
🤩BASE-системы жертвуют частью согласованности ради масштабируемости и отказоустойчивости


Методы обеспечения согласованности

✨Репликация

✨Синхронная: запись дожидается подтверждения всех реплик. Высокая надёжность, но медленнее
✨Асинхронная: запись подтверждается после обновления основной реплики, остальные догоняют позже. Быстрее, но риск рассинхронизации

✨Консенсус-протоколы

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

✨пример: алгоритмы Paxos и Raft широко используются внутри распределённых БД и сервисов. Для репликации и выбора лидера, чтобы все копии данных оставались согласованными

✨Конфликт-резолвинг

Подходы к устранению расхождений между копиями данных при eventual consistency

✨ CRDT (Conflict-free Replicated Data Types)

Структуры данных.
Спроектированны так, чтобы изменения, сделанные независимо на разных узлах, могли быть объединены без конфликтов
Позволяет достичь согласованности без централизованного координирующего узла

✨пример: распределённый счётчик, который можно увеличивать на любом узле, а потом безопасно объединять — каждая часть учтётся, независимо от порядка доставки

✨Last-write-wins (LWW)

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

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


📎 Материалы

1. Согласованность: что этои почему с ней все так сложно
2. Проблемы согласованности в микросервисах и их решение
3. Согласованность, Репликация и БД по CAP
4. Паттерны для высокой масштабируемости
5. Руководство по Эффективному Взаимодействию

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

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

Материалы по визуализации работы Apache Kafka и Rabbit MQ

🤩Kafka Visualization
Наглядное представление взаимодействия продюсеров, брокеров, топиков и консьюмеров — в виде анимации или схемы
🤩Kafka Visualization Showcase (видео, англ)
🤩Симулятор брокера Apache Kafka: Kafka Visualization от компании SoftwareMill (обзор с пояснениями)


🤩 RabbitMQ Simulator
Онлайн-песочница для изучения основ RabbitMQ и тестирования сценариев работы с очередями без установки
🤩RabbitMQ Simulator. Песочница брокера сообщений (гайд как использовать)

🔹  Kafka vs RabbitMQ: сравнение по пунктам


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

❌ Недостатки микросервисной архитектуры

Микросервисная архитектура (MSA) — подход, когда система разбивается на небольшие независимые сервисы
У MSA есть недостатки, которые важно учитывать при проектировании

1️⃣ Сложность управления распределёнными транзакциями

В монолите транзакции управляются на уровне БД (ACID). В MSA данные распределены, и обеспечение согласованности требует сложных решений

➡️пример: заказ оформлен, платёж прошёл, но товар не списался — пользователь заплатил за несуществующий товар.

Практики:
🤩 Saga-паттерны: реализуют оркестрацию или хореографию транзакций с локальными шагами и компенсациями
🤩 Outbox-паттерн: позволяет гарантировать отправку событий в шину сообщений после успешной локальной транзакции


2️⃣Задержки из-за сетевых вызовов

Межсервисные вызовы (HTTP, gRPC и тд) добавляют сетевые задержки, что может привести к ухудшению UX

➡️пример: открытие страницы профиля пользователя требует вызовов к 10 сервисам — итого 1+ секунда задержки.

Практики:
🤩Кеширование на уровне API Gateway или Edge Cache
🤩 Асинхронная обработка через сообщения и очереди


3️⃣ Оверхеды мониторинга и трассировки

При десятках и сотнях сервисов сложно локализовать источник ошибки и собрать полную картину работы

➡️пример: пользователь видит ошибку при оформлении заказа — неизвестно, виноват Cart, Orders или Payments

Практики:
🤩Distributed Tracing (Jaeger, Zipkin, OpenTelemetry)
🤩Централизованные логи (ELK Stack, Loki)
🤩Метрики и алерты (Prometheus + Grafana)


4️⃣Сложность тестирования и развёртывания

Каждый сервис может иметь свою БД, конфигурацию и зависимости. Интеграционное тестирование всей системы требует поднятия множества сервисов

➡️пример: тест Cart Service требует запуска Users, Products и Discounts — иначе тесты падают

Практики:
🤩Контракты (Contract Testing): Pact, Spring Cloud Contract
🤩 Mock-сервисы и виртуализация (WireMock, Hoverfly)
🤩Изолированные сценарии на уровне эндпоинтов


5️⃣ Дублирование данных и согласованность

Каждый сервис хранит свою копию данных → возможны расхождения

➡️пример: пользователь обновил email, но в Order History отображается старый адрес.

Практики:
🤩 Event Sourcing и CQRS: разделяют чтение и запись и обеспечивают последовательность событий
🤩 Change Data Capture (CDC): синхронизирует данные между БД через Kafka Connect или Debezium


📎 Материалы

1. Микросервисная архитектура в разработке приложений: преимущества и недостатки
2. Микросервисная архитектура
3. Аутентификация и авторизация в проекте с микросервисной архитектурой: стратегии, практический пример
4. Микросервисная архитектура, ее паттерны проектирования и особенности
5. Микросервисы: плюсы, минусы, когда и зачем внедрять


📚 Книги
1. Крис Ричардсон. Микросервисы. Паттерны разработки и рефакторинга
2. Сэм Ньюмен. Создание микросервисов
3. Микросервисы. От архитектуры до релиза(Ронни Митра, Иракли Надареишвили)
4. Изучаем OpenTelemetry: современный мониторинг систем (2025) - Паркер Остин, Янг Тед

#микросервисы #архитектура

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

⬇️ Ретраи

Ретраи (retries) в проектировании систем — механизм авто-повторения неудачных операций при временных сбоях (сетевых ошибках, перегрузке сервисов и тд)

В распределенных системах временные сбои— норма
Вызов "повторить при ошибке" может усугубить проблему


Виды ошибок

Не все ошибки равны: ретраить можно только временные сбои.
Постоянные ошибки повторять бесполезно и вредно для ретраев

🔼 Повторяемые ошибки

Временные сбои, которые могут исчезнуть при повторной попытке

Типичные кейсы повторяемых ошибок:

◾️Сетевые сбои
Таймауты TCP, Connection Reset
➡️ проблемы балансировщика, кратковременная недоступность сети

◾️Ограничения ресурсов
HTTP 429 (Too Many Requests)
➡️ превышение лимитов API (Rate Limiting)
пример: пльзователь массово экспортирует данные → API временно ограничивает запросы

◾️Ошибки серверов
HTTP 5xx (503, 504)
➡️ перегрузка сервера, деградация БД
пример: (HTTP 503) сервис перегружен в час пик

◾️Конфликты данных
Дедлоки БД, оптимистичные блокировки
➡️ конкурентные транзакции
пример: деадлоки БД - два клиента одновременно редактируют один заказ

⤵️ Постоянные ошибки

🔹HTTP 400 (Bad Request)
Клиент отправил невалидные данные (например, буквы в поле "Цена"). Повторы бесполезны

🔹HTTP 404 (Not Found)
Ресурс удален (например, несуществующий ID товара). Повторы создают нагрузку

🔹HTTP 403 (Forbidden)
Постоянное отсутствие прав (например, просмотр чужих заказов)


Стратегии повторов

🤩Экспоненциальная задержка (Exponential Backoff)

Растущая задержка: 1с → 2с → 4с → 8с
Для снижение нагрузки на сбойный ресурс, дает ему время на восстановление

✨пример: пользователь оплачивает заказ → платежный шлюз временно недоступен → система повторяет через 0.5с, 1с, 2с → 95% платежей проходят со 2-3 попытки

🤩Джиттер (Jitter)

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

Фактическая задержка = Базовая задержка + random(0, 30% от задержки)
Для предотвращение синхронизации запросов

✨пример: 10 000 корзин ожидают оплаты
Без джиттера: повтор всех 10к запросов одновременно → Коллапс платежной системы
С джиттером: запросы распределяются равномерно

🤩Комбинированные подходы

a) Retry-After + Backoff
Использование заголовка HTTP Retry-After для точного определения задержки

HTTP/1.1 429 Too Many Requests
Retry-After: 15 ← Ждать ровно 15 секунд

✨ когда использовать: при интеграции с внешними API

b) Адаптивные ретраи
Динамический расчет задержки на основе:
- истории ответов сервиса
- текущей нагрузки
- SLA системы и тд

✨пример: система логирования увеличивает задержку с 1с до 10с при 1000 ошибок/мин.

🤩Ограничение попыток

Максимальное число ретраев (напр. 3-5).
Это предотвращает бесконечные циклы.

После исчерпания попыток— фиксируется ошибка
✨например:
- асинхронная обработка (отправка в очередь)
- уведомление мониторинга


Circuit Breaker ("предохранитель" системы)

Это "автомат", который временно блокирует вызовы сбойного сервиса

🌸 принцип: после N ошибок за период T, все последующие вызовы завершаются ошибкой без реального вызова ресурса.
Периодически проверяет "полуоткрытое" состояние.

💡 Следует определить пороги срабатывания (N, T), время восстановления
Связать с SLA и поведением системы при отказе.

Состояния брейкера:
🔵Closed: вызовы проходят
Система работает нормально
🔵Open: вызовы блокируются (ошибка без реального запроса)
После 5 ошибок за 1 мин
🔵Half-Open: Пропускает часть трафика для проверки восстановления

➡️кейс: сервис отправки SMS падает → Circuit Breaker блокирует вызовы на 2 мин → предотвращает:
- потерю денег за SMS
- перегрузку очереди сообщений
- каскадные сбои


📎 Материалы

1. Хороший ретрай, плохой ретрай, или История одного падения
2. Отложенные ретраи силами RabbitMQ
3. Как работать над перфомансом веб-приложения: опыт Авто.ру|
4. Лучшие практики создания отказоустойчивых систем

🔹 Производительность API: краткий обзор способов

📚 Паттерны проектирования API - Джей Гивакс (Часть IV. Безопасность)

#проектирование #api

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

⌛ Идемпотентность в распределённых системах

Идемпотентность — свойство операции, гарантирует, что повторное выполнение одной и той же операции приведёт к такому же результату, как и первое выполнение
Т.е. если отправить один и тот же запрос 10 раз, результат должен быть таким же, как если отправить его один раз

🟢пример: если повторное списание денег с карты не приводит к новому списанию, а возвращает результат первого списания — операция идемпотентна
Если же деньги спишутся дважды — нарушение идемпотентности

В распределённых системах сетевая ненадёжность, таймауты и ретраи делают это свойство критически важным

Примеры проблем обеспечения идемпотентности

🔘повторные сетевые запросы: клиент не получил ответ вовремя (из-за таймаута, сетевого сбоя) и отправил запрос повторно. Сервер успешно обработал первый запрос
🔘дубли сообщений в брокерах: гарантируют доставку как минимум одни раз (at-least-once). При сбое потребителя сообщение может быть доставлено повторно
🔘неопределённость состояния при сбоях: cервис обработал запрос, но упал до того, как отправил подтверждение. Оркестратор (н-р, Kubernetes) перезапустит контейнер, и обработка перезапустится

Примеры последствий отсутствия идемпотентности

➖фин потери (двойные списания)
➖нарушение консистентности данных (два одинаковых пользователя в БД)
➖времязатратные отладки и исправления данных


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

Уникальный id запроса (Request ID)

Клиент генерирует уникальный ID (UUID) для каждой бизнес-операции и передаёт в каждом запросе (например, в HTTP-заголовке Idempotency-Key)
Сервер, получив запрос, проверяет, не обрабатывался ли уже запрос с таким ID
🟣Если нет — выполняет операцию и сохраняет результат в быстрое хранилище (н-р, Redis) с ключом = ID
🟣Если да — возвращает сохранённый ранее ответ, не выполняя операцию повторно

✅ Плюсы: относительно просто, универсальность (подходит для REST, gRPC, Webhooks)
✖️ Минусы: требует наличия быстрого хранилища состояния для всех инстансов сервиса. Необходимо определять TTL для ключей

Подходит для идемпотентных POST-запросов в API (н-р, создание платежа, заказа)

Журналирование и Outbox-паттерн

Паттерн для надежной отправки сообщений в брокер в контексте транзакции с БД
🔘сервис не отправляет сообщение в брокер напрямую
🔘он в рамках одной транзакции записывает сообщение в специальную таблицу в БД (outbox)
🔘отдельный процесс (CDC) считывает новые записи из outbox и публикует их в брокер
🔘после успешной публикации запись из outbox удаляется

✔️ гарантирует отправку сообщения в брокер только тогда, когда бизнес-транзакция commit'ится. Решает проблему дублей на стороне отправителя
✖️ архитектурная сложность, необходимость настройки и поддержки CDC-процесса

Микросервисные асинхронные интеграции, где критична гарантия доставки события после записи в БД

Exactly-Once на уровне брокеров

Брокеры предлагают встроенные механизмы для обеспечения семантики "точно один раз"
🟣Для продюсеров: использование transactional id и подтверждений от всех партиций (acks=all) гарантирует, что сообщение не будет потеряно и не будет записано дублем
🟣Для консьюмеров: чтение сообщения и commit offset'а происходят атомарно. Консьюмер не получит одно и то же сообщение дважды после успешной обработки и коммита

✔️ высокая надёжность "из коробки"
✖️ сложность конфигурации, расходы на производительность, привязка к конкретной технологии

В проектах на Kafka, где требования к надёжности обработки потоков данных крайне высоки


📎 Материалы
1. Идемпотентность: что это, примеры и применение в API
2. Как сделать хорошую интеграцию? Часть 2. Идемпотентные операции – основа устойчивой интеграции
3. История одного идемпотентного метода
4. Идемпотентность в такси-приложении: кейс из практики
5. Стажёр Вася и его истории об идемпотентности API
6. Важность идемпотентности в распределенных системах

🔹 Обеспечение идемпотентности API

📚 Книги
1. Высоконагруженные приложения - Мартин Клеппман (Глава 11)
2. Создание микросервисов - Сэм Ньюмен (Глава 12)

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

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

Масштабируемые данные.
Лучшие шаблоны высоконагруженных архитектур.

✍️ Автор: Питхейн Стренгхольт
🗓 Год издания: 2022
🔤 Язык: русский
📚 Объём: 368 стр

Посвящена современному управлению данными и масштабируемым архитектурам, необходимым для работы с большими объемами информации.

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

Книга сочетает теорию и практику, подойдет для архитекторов, аналитиков, специалистов по соблюдению требований и управлению

Обзор книги на Хабр

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

⚙️ Apache Kafka: экосистема

Apache Kafka - платформа для потоковых данных
Включает:
⚫️Kafka Connect
⚫️ksqlDB
⚫️Kafka Streams

Kafka Streams

Библиотека для обработки потоков событий с возможностью:
🤩 Агрегации: подсчет количества событий за период для каждого ключа
➡️ количества кликов по рекламе для каждого пользователя за последний час
🤩Обогащении: дополнение событий данными из внешних систем или других топиков
➡️ добавление информации о профиле пользователя к событиям покупок
🤩Фильтрации: отбор нужных событий
🤩Трансформации: изменение формата/структуры сообщения
➡️ конвертация из бинарного формата Avro в JSON
🤩Объединения: данные из нескольких топиков
➡️ объединение данных о заказах и платежах

Архитектурная идея: микросервисный подход к потоковой обработке
Kafka Streams инкапсулирует логику обработки в независимое приложение, оно масштабируется вместе с кластером Kafka
🤩Обадает отказоустойчивостью
🤩Не требует развертывания отдельной инфраструктуры

Хранение данных между обработками

Для этого используется:
✨State Store — локальное хранилище внутри Kafka Streams, где находятся текущие вычисления
✨Changelog Topic — специальный топик в Kafka, куда записываются изменения в State Store
Если приложение перезапускается, то загружает данные из этого топика и продолжает работу с того же места
По умолчанию Kafka Streams хранит состояние локально, но обработанные данные можно записывать во внешние БД или облачные хранилища

Примеры использования

🤩Обработка транзакций с добавлением информации о пользователе из внешней БД
🤩 обогащение данных о платеже информацией о возрастной группе и истории покупок пользователя для системы фрод-мониторинга.

🤩Трансформация данных из формата Avro в JSON с валидацией и фильтрацией некорректных записей
🤩 очистка и преобразование данных логов веб-сервера перед загрузкой в аналитическое хранилище


Kafka Connect

Фреймворк для масштабируемого ввода/вывода данных между Kafka и внешними системами
Решает задачи интеграции с различными источниками

⏩ Пример: синхронизация данных между PostgreSQL и Elasticsearch
Источник (JDBC Connector) читает изменения из БД с помощью механизма изменения данных Debezium, а приемник (Elasticsearch Connector) загружает данные в поисковый индекс для быстрого поиска

Особенности
⏺готовые коннекторы для популярных систем
⏺автоматическое управление смещениями: отслеживание позиции обработки для каждого коннектора
⏺масштабирование через распределенный режим работы в кластере
⏺поддержка преобразований данных: встроенные онлайн преобразования форматов данных


ksqlDB

СУБД для потоковой обработки
➖позволяет выполнять SQL-запросы к данным в топиках Kafka
➖применяется для быстрого прототипирования и простых ETL-задач без кода на Java

🤩Пример: мониторинг аномальной активности пользователей в реальном времени.
Например, обнаружение пользователей, выполняющих более 100 действий в минуту, с отправкой уведомлений в систему безопасности

Особенности
🤩SQL-синтаксис для потоковой обработки
🤩поддержка оконных агрегаций и joins - возможность объединения потоков данных и агрегации по временным окнам
🤩REST API для управления потоковыми запросами

Применение: создание реальных дашбордов, реализация простых правил бизнес-логики, мониторинг качества данных


📎 Материалы
1. Kafka Streams (official site)
2. Экосистема Apache Kafka: Kafka Streams, Kafka Connect
3. Потоковая обработка данных с помощью Kafka Streams: архитектура и ключевые концепции
4. Под капотом Kafka Connect: источники, приемники и коннекторы
5. ksqlDB
6. ksqlDb или SQL как инструмент обработки потоков данных

📚 Книги
1. Kafka Streams и ksqlDB: данные в реальном времени - Сеймур Митч
2. Kafka в действии - Дилан Скотт, Виктор Гамов и Дейв Клейн (Глава 12)

#интеграции

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

🔽Debezium

Debezium - распределенная платформа с открытым исходным кодом, которая превращает существующие БД в стриминговые источники событий

⏬«Подписывается» на журналы СУБД и захватывает каждое изменение на уровне строки и отправляет его в Apache Kafka в виде структурированных событий

Оптимален когда нужна
🔵обработка изменений в реальном времени
🔵поддержка сложных преобразований данных
🔵интеграция с экосистемой Kafka
🔵требования к кастомизации и контролю


Архитектура и компоненты

Работает как набор коннекторов для Apache Kafka Connect
Каждый коннектор специализируется на конкретной СУБД и реализует протокол репликации этой базы

Основные компоненты

✨коннекторы — отдельные для PostgreSQL, MySQL, SQL Server, Oracle, MongoDB и Db2
✨транзакционные журналы БД, откуда Debezium читает
✨схема сообщений — каждое событие содержит данные до/после изменения, метаданные операции и информацию об источнике
✨Kafka Connect Framework

💚Debezium можно интегрировать не только с Kafka
С помощью Debezium Engine события можно получать напрямую в приложение или транслировать в другие брокеры: RabbitMQ, Pulsar, Redpanda


Принцип работы

💙 Поток данных кратко
БД → журнал транзакций → Debezium connector → Kafka Connect → Kafka topic → потребитель (микросервис, аналитическая система, хранилище)

Процесс обработки изменений от журнала до топика Kafka

💙Подключение к БД
Коннектор подключается к БД с правами репликации

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

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

💙 Преобразование изменений
Каждая запись в журнале парсится и преобразуется в событие JSON / Avro
Debezium обрабатывает различные типы данных СУБД, включая XML и пользовательские типы.

💙Отправка в Kafka
События отправляются в топики Kafka. Коннектор использует семантику at-least-once, что требует идемпотентной обработки на стороне потребителей.


Примеры использования

💚Интеграция Legacy-БД с микросервисами: старое монолитное приложение пишет в общую базу, Debezium транслирует изменения в события для микросервисов.
💚Event Sourcing / CQRS. Debezium можно использовать как источник событий, превращая БД в event log.
💚Репликация в DWH или Data Lake
💚Аудит изменений. Логировать все операции по таблицам, не меняя код приложений.
💚Синхронизация с индексами и кешами. Например, изменения в PostgreSQL сразу обновляют Elasticsearch или Redis


Проблемы и риски

💙нагрузка на СУБД: при первом снэпшоте Debezium сканирует таблицы. Это может перегрузить продакшн.
💙обработка DDL: добавление или удаление колонок не всегда корректно обрабатывается.
💙exactly-once: Debezium гарантирует at-least-once. Exactly-once зависит от конфигурации Kafka и потребителей.
💙сбои: при падении соединения коннектор должен корректно продолжить чтение с последнего offset. Иногда возможны дубликаты.
💙версионные миграции: новые версии коннекторов могут менять формат событий.


📎 Материалы

1. Официальный сайт
2. CDC в Yandex Data Transfer: гид по технологии с примерами
3. Что такое Debezium и для чего используется
4. Знакомство с Debezium — CDC для Apache Kafka
5. Что такое Debezium: подробная инструкция по применению
6. Debezium Architecture

#интеграции

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

⌛ gRPC: подробнее

❤️gRPC: краткий обзор❤️

gRPC реализует парадигму удаленного вызова процедур (RPC), где клиент вызывает методы на сервере так, будто они находятся в одном процессе


Protocol Buffers

Процесс разработки с gRPC начинается с проектирования контракта в proto-файлах

Контракт (.proto файл) — единая точка, в которой описываются:
🟢структуры данных (сообщения)
🟢методы сервисов
🟢входные / выходные параметры

На основе proto-файлов автоматически генерируется клиентский и серверный код для разных языков ➡️ снижает риски несовместимости

🟢Protobuf — наиболее часто используемый IDL для gRPC
Здесь хранятся данные и функциональные контракты в виде proto-файла


gRPC Interceptors

Interceptor ("перехватчик") — компонент, который позволяет внедрять пользовательскую логику в обработку вызовов gRPC на стороне клиента / сервера
Предоставляет механизм для изменения запросов и ответов, а также для выполнения доп действий

Интерсепторы оперируют:
🔴именами сервисов и методов
🔴метаданными вызовов
🔴статусами выполнения
🔴таймингами и ошибками

Protocol Buffers определяют ЧТО передается
Интерсепторы - КАК обрабатываются вызовы

Сценарии использования

🟢проверка токенов, валидация прав доступа к методам, добавление учетных данных в метаданные
🟢сбор статистики по времени выполнения, количеству вызовов, ошибкам. Интеграция с системами мониторинга
🟢логирование входящих и исходящих вызовов, трассировка запросов в распределенных системах
🟢Retry-логика, таймауты, circuit breakers, балансировка нагрузки на клиентской стороне
🟢проверка корректности запросов, преобразование данных, кэширование ответов


gRPC и Kafka

♥️gRPC — про синхронные вызовы
♥️Kafka — про асинхронный обмен событиями. Обычно дополняют друг друга:

gRPC обрабатывает пользовательский запрос «здесь и сейчас»
Kafka распространяет событие дальше

🟢Пример: система заказов

Клиент → gRPC → Сервис А → Kafka → Сервис Б, Сервис В

1. Клиент через gRPC создает заказ
2. Сервис заказов обрабатывает команду "создать заказ"
3. Публикует событие "OrderCreated" в Kafka
4. Сервисы уведомлений и аналитики получают событие из Кафка


Примеры архитектуры с gRPC

✅банковская система: gRPC связывает микросервисы обработки платежей, управления счетами и проверки безопасности

✅приложение для доставки: gRPC-streaming для получения обновлений о местоположении курьера в реальном времени

✅стриминговый сервис: gRPC управляет коммуникацией между сервисами рекомендаций, биллинга и контент-доставки
Двунаправленные стримы - для управления видеопотоками


Безопасность в gRPC

gRPC изначально ориентирован на защищённые каналы:

🟢TLS по умолчанию — все соединения зашифрованы
🟢mTLS — взаимная аутентификация сервисов (не только клиент проверяет сервер, но и сервер проверяет клиента)
🟢метаданные — передача токенов (JWT, OAuth2, API-ключи)
🟢интерсепторы — проверка прав доступа , логирование, метрики
🟢короткоживущие токены и регулярное обновление сертификатов


📎 Материалы
1. Введение в gRPC: Основы, применение, плюсы и минусы
2. Что такое gRPC и Protobuf?
3. Способ организации gRPC контрактов и их автоматизация для микросервисов
4. Protocol Buffers: самая эффективная бинарная альтернатива текстовому формату
5. gRPC Interceptors (документация)
6. Перехватчики gRPC в .NET

📚 Изучаем OpenTelemetry: современный мониторинг систем (2025) - Паркер Остин, Янг Тед

#интеграции

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