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

Согласованность (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) - Паркер Остин, Янг Тед

#интеграции

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

🔗 Подборка материалов по архитектуре

🔘Бесплатные курсы

⏯ Youtube
➖Курс по архитектуре приложений. Путь архитектора решений (53 видео)
➖Архитектура ПО (13 видео)
➖Проектирование программного обеспечения (14 видео)

⚫️ Stepik
➖Архитектура информационных систем (для новичков)
➖ИТ-инфраструктура предприятия: вводный курс


🔹 Посты из канала
➖Архитектурные паттерны (MV(X)
➖Распределенные системы: архитектурные паттерны и стили
➖Антипаттерны проектирования ПО
➖Паттерны проектирования и архитектурные паттерны
➖TOGAF. Краткий обзор
➖SOA vs MSA

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

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

⌛ Жизненный цикл API

💙 Проектирование

Сбор требований от всех стейкхолдеров (бизнес-заказчики, фронтенд-разработчики, мобильные разработчики и тд) и трансформировать их в контракт

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

Ключевые элементы:
💙анализ требований: стейкхолдеров и потребителей (что должно делать API, для кого и зачем)
💙Design First подход: — создание спецификации до написания кода (например, в формате OpenAPI (Swagger)
💙прототипирование: на основе спецификации можно сгенерировать "заглушку" API (mock-сервер)
💙стандартизация: форматов ошибок, пагинации, структур данных и тд


💙 Разработка: от спецификации к коду

Реализовать логику API по спецификации

Процесс включает:
💙итеративную разработку по спецификации
💙интеграцию с БД и внешними сервисами
💙регулярный код-ревью и статический анализ
💙написание модульных тестов параллельно с разработкой


💙 Тестирование

Комплексная проверка надежности, безопасности и производительности API
Основа для тестирования: тестовые сценарии и данные

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


💙 Публикация и CI/CD

Обеспечить быструю, безопасную и предсказуемую публикацию изменений в API

Ключевые процессы:
💙интеграция спецификации в CI/CD: спецификация OpenAPI хранится в репозитории вместе с кодом.
💙авто-проверки при создании Pull Request
💙авто-сборка, тесты и деплой при мерже в основную ветку
💙соблюдение семантики версионирования:
💙обратно-совместимое изменение — v1.0.0 → v1.1.0
💙ломающее изменение — v1.1.0 → v2.0.0


💙 Управление

Централизованное управление трафиком, безопасностью и версиями API через API-шлюз

Основные функции:
💙настройка политик в API Gateway: настройка лимитов запросов (rate limiting)
💙управление аутентификацией и авторизацией (API-ключи, OAuth токены)
💙кеширование ответов
💙мониторинг трафика и выявление аномалий


💙 Ввод в эксплуатацию

Гарантия отказоустойчивости и производительности API в проде

Основные функции:
💙определение SLO/SLA, настройка мониторинга метрик производительности
💙настройка автомасштабирования под нагрузку
💙создание механизмов резервного копирования и процедуры обработки инцидентов


💙 Анализ и мониторинг

Сбор и анализ метрик

Примеры метрик:
💙количество вызовов и уникальных потребителей
💙время ответа и процент ошибок
💙география запросов


💙 Продвижение и💙Монетизация

Эти этапы в большей степени относятся к продуктологам и бизнес-аналитикам

Примеры метрик для оценки эффективности продвижения API:
1. Активные пользователи (Active Users)
2. Новые регистрации (New User Registrations)
3. Количество API-вызовов (API Calls)
4. Метрики производительности
5. Бизнес-метрики

Для монетизации необходимо спроектировать систему тарификации и метрики для нее, заложить логику в систему аналитики и биллинга.


💙💙 Вывод из эксплуатации

Минимизировать ущерб для потребителей при выводе устаревшей версии API.

Процесс вывода:
💙планирование (например, "Версия v1 будет объявлена устаревшей 1 января, а полностью отключится 1 июля")
💙уведомление всех потребителей через документацию
💙создание миграционных гидов и архивное хранение


📎 Материалы
1. Жизненный цикл API. Статистика и нюансы
2. Жизненный цикл API
3. 15 важнейших рекомендаций по проектированию REST API
4. Дизайн API и как его спроектировать
5. Лучшие практики разработки REST API: 20 советов

📚 Книги
1. API - Сергей Константинов
2. Паттерны проектирования API - Джей Гивакс
3. Тестирование веб-API - Марк Винтерингем
4. Проектирование веб-API - Арно Лоре

#api

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

⬇️ Обратная совместимость интеграций

Обратная совместимость — когда система может работать с более старыми клиентами или потребителями после внесения изменений в интерфейс или формат данных

В интеграциях это критически важно:
если одно приложение изменило контракт, а другое не успело обновиться ➡️ возникает сбой в цепочке бизнес-процессов

▫️ Принцип: поставщик данных эволюционирует без требования изменений от потребителей


Виды совместимостей

⚪️Backward compatibility (обратная) — новые версии совместимы со старыми клиентами
⚪️Forward compatibility (прямая) — старая версия может работать с будущими данными
⚪️Full compatibility (полная) — поддерживаются оба направления

⭐️ Для интеграций чаще всего важна обратная совместимость: не ломать то, что уже работает


Примеры обеспечения обратной совместимости

⚪️Версионирование: явное указание версии контракта через URI, заголовки или параметры

⚪️Добавление новых функций без изменения существующих

⚪️Deprecated-стратегия:
💚сначала поле/метод помечается как устаревший - "deprecated", но остается доступным.
💚через несколько релизов удаляется, после уведомления потребителей

⚪️Контрактное тестирование (Consumer-Driven Contracts): подход к тестированию интеграций, при котором контракт (API, сообщение, схема) формируется не со стороны провайдера, а со стороны потребителя

⚪️Feature flags и поэтапное внедрение:
💚дается потребителям время перейти на новую схему
💚одновременно поддерживаются старый и новый формат


⏩ Обратная совместимость в REST API

Практики:

*️⃣поля в JSON только добавлять, не удалять. Обязательные поля не удалять, а помечать deprecated
*️⃣новые поля делать необязательными (nullable).
*️⃣переименование заменять на добавление нового поля + "депрекейт" старого.
*️⃣версионирование через заголовок "Accept", не нарушает структуру URI.
*️⃣сохранять семантики HTTP-кодов и методов для существующих эндпоинтов


⏩ В gRPC

gRPC использует Protocol Buffers (protobuf)
Он изначально учитывает обратную совместимость

Практики:

➕добавлять новые поля с уникальными номерами тегов
➕делать поля optional
➕не удалять старые поля, помечать их deprecated
➕никогда не менять значения tag-ID
➕при необходимости переименования — объявлять новое поле с новым tag.
➕версионировать proto-файлы (package v1, v2).


⏩ В GraphQL

GraphQL более гибкий, чем REST, так как клиент сам выбирает нужные поля. Но есть риски.

Практики:

⏺использовать директиву @deprecated вместо удаления. Клиенты будут видеть предупреждение.
⏺избегать изменений типов существующих полей
⏺поддерживать старые поля до тех пор, пока все клиенты не перейдут.
⏺для больших изменений — новая схема (например, /graphql/v2).


⏩ В Apache Kafka

Kafka — шина событий. Здесь контракт — формат сообщения.
Если продюсер изменил структуру, все консумеры должны понимать новый формат

Практики:

✨использование Schema Registry для управления схемами
✨применение политик совместимости:
➖backward — новые сообщения читают старые консумеры
➖forward — новые консумеры читают старые сообщения
➖full— поддерживаются оба направления
✨возможность перечитывания исторических данных
✨не менять типы полей
✨не удалять поля без "депрекейта"
✨для критичных изменений — новый топик (orders.v2)


📎 Материалы
1. Обеспечение обратной совместимости gRPC API с помощью protolock в GitHub Actions
2. Постановка проблемы обратной совместимости
3. Интеграции глазами аналитика: 5 типичных ошибок, которые ломают систему
4. Как правильно разрабатывать API с поддержкой обратной совместимости
5. GraphQL: от восторга до разочарования

📚 Книги
API - Сергей Константинов (Раздел III. Обратная совместимость)
🐗 Высоконагруженные приложения. Программирование, масштабирование, поддержка - Мартин Клеппман

#интеграции

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

📃 Основы проектирования БД

Рассмотрим нисходящий подход проектирования БД

Процесс проектирования по шагам

🔹концептуальное проектирование — анализ и описание бизнес-сущностей без привязки к технологиям
🔹логическое — преобразование бизнес-модели в структуру таблиц, ключей и связей
🔹физическое — реализация модели в конкретной СУБД с учетом особенностей хранения, типов данных, индексов и оптимизации

Между этими этапами используется ER-диаграмма — инструмент визуализации


1️⃣ Концептуальная модель

Задача: понять и описать какие данные нужны системе и как они связаны между собой
❌ не решается, в какой СУБД будет хранить информацию и как будут называться таблицы

Основные шаги

🔘определить сущности: ключевые объекты, информацию о которых будет храниться (например, «Пользователь», «Заказ», «Товар»)
🔘описать связи между сущностями, т.е как сущности взаимодействуют друг с другом (например, «Пользователь оформляет Заказ»).
🔘выделить атрибуты сущностей: характеристики, которые описывают каждую сущность (например, «ФИО» у пользователя, «цена» у товара)
🔘зафиксировать правила предметной области (например, заказ всегда связан хотя бы с одним товаром).


2️⃣ Логическая

Создание реляционной схемы. ER-модель преобразуется в формальную схему, готовую для реализации в реляционной СУБД (распространенный тип БД).

Основные шаги

◾️cоздать таблицы по сущностям
Например, сущность «Пользователь» превращается в таблицу users.
◾️определить атрибуты как столбцы таблиц
У «Пользователя» будут поля: id, name, email.
◾️ задать ключи:
- первичный ключ (id) для уникальной идентификации строки
- внешние ключи для связи между таблицами
◾️нормализовать таблицы
- убрать повторы и избыточные данные
- проверить соответствие нормальным формам (1НФ, 2НФ, 3НФ)
Например, если в таблицу «Заказ» включить название товара, это приведет к дублированию

Решение: выделить отдельную таблицу «Товар» и связать через «Заказ–Товар»
◾️определить индексы


3️⃣ Физическая

Модель адаптируется под конкретную СУБД:

🔹выбираются типы данных (VARCHAR, INTEGER, DATE)
🔹настраиваются индексы, триггеры, процедуры
🔹проектируется стратегия хранения больших данных (шардинг, партиционирование)
🔹учитываются ограничения конкретной СУБД (PostgreSQL, MySQL, Oracle и т. д.)


📎 Материалы

1. Как работают базы данных в IT: разбор на примерах
2. Базы данных для системного аналитика. Краткий обзор на практике
3. Основы правил проектирования базы данных
4. Основы проектирования баз данных
5. Проектирование реляционных баз данных: основные принципы

📚 Книги
1. Основы баз данных (учебное пособие) - Кузнецов С. Д.
2. Путеводитель по базам данных - Владимир Комаров
3. Базы данных. Инжиниринг надежности - Кэмпбелл Лейн, Мейджорс Черити
4. Проектирование и реализация систем управления базами данных - Эдвард Сьоре
5. Основы технологий баз данных: учебное пособие - Новиков Б. А. и др

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

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

⌛ SDLC: Жизненный цикл ПО

Жизненный цикл программного обеспечения (Software Development Life Cycle, SDLC) — структурированный процесс создания систем
Путь идеи от концепции до рабочего продукта


Фазы жизненного цикла ПО

1️⃣Инициация (Планирование)

Определяется цель проекта, его границы и заинтересованные стороны
Оценивается бизнес-ценность, риски и целесообразность разработки
Результат фазы — бизнес-кейс, дорожная карта проекта, первичные требования и оценка ресурсов

2️⃣ Сбор и анализ требований

Вывляются:
🔸проблемы бизнеса, которые нужно решить
🔸функциональные требования (что система должна делать)
🔸нефункциональные требования (какими качествами обладать: производительность, безопасность, надежность)

Выходные артефакты: ТЗ или спецификация требований к ПО (SRS), модели процессов, диаграммы прецедентов

3️⃣ Проектирование

Решается как система будет удовлетворять требованиям

〰️архитектура системы: Выбираются технологии, определяются основные компоненты и их взаимодействие (микросервисы, монолит)
〰️проектирование данных: разрабатывается модель БД
〰️проектирование интерфейсов: как система будет взаимодействовать с пользователями (UI) и другими системами (API)

Результат — набор архитектурных и дизайнерских документов

4️⃣ Разработка (реализация)

Пишется код в соответствии с архитектурой и требованиями
Ревью кода, сборка и автоматизация сборочного процесса через CI/CD

На выходе — рабочие модули и инкременты системы

5️⃣ Тестирование

Проверяется соответствие продукта требованиям

Примеры тестирования:
⚫️модульное (проверка отдельных компонентов)
⚫️интеграционное (проверка взаимодействия компонентов)
⚫️системное (проверка системы в сборе по всем требованиям)
⚫️приемочное (финальная проверка с заказчиком)

6️⃣ Внедрение

Продукт разворачивается в целевой среде

〰️развертывание на production-серверах
〰️перенос данных из старых систем
〰️обучение пользователей
〰️подготовка документации

Завершается релизом и переходом системы в эксплуатацию

7️⃣ Эксплуатация и сопровождение

После запуска система требует поддержки:
🟣исправление ошибок
🟣адаптация к изменениям в окружении (например, обновление ОС)
🟣новые функциий и улучшения
🟣тех поддержка пользователей

Фаза продолжается до момента окончательного вывода системы из эксплуатации


Модели жизненного цикла ПО

Подход к организации фаз SDLC определяется моделью: как эти фазы взаимодействуют друг с другом, их последовательность

🔵 Последовательные (плановые)

🔹Каскадная (Waterfall)

Фазы выполняются строго последовательно: от анализа до сопровождения
Переход на следующую стадию возможен только после завершения предыдущей

Подходит для проектов с чётко определёнными и стабильными требованиями

🔹 V-модель (Verification & Validation)

Идея каскада с добавлением акцент на тестирование
Каждая стадия разработки имеет свой этап проверки и валидации

🟢 Инкрементальные

Продукт создаётся поэтапно, небольшими инкрементами. Каждый релиз добавляет часть функционала
Каждый инкремент проходит полный цикл SDLC (анализ, проектирование, кодирование, тестирование)

В результате пользователь постепенно получает готовые части системы

🟡 Итерационные (адаптивные)

🔸Спиральная

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

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

🔴 Гибкие (Agile)

🔸 Scrum

Разработка короткими итерациями — спринтами (1–4 недели). Команда поставляет работающий инкремент продукта к концу каждого спринта.

🔸 Kanban

Ориентирован на непрерывный поток задач и визуализацию процессов
Основной инструмент — канбан-доска, где задачи перемещаются по статусам


📎 Материалы
1. Этапы жизненного цикла разработки ПО или что такое SDLC?
2. SDLC
3. База про жизненный цикл разработки ПО (SDLC): этапы, виды моделей и их различия
4. Про семь основных методологий разработки
5. Модели жизненного цикла ПО

📚 Книги
Управление проектным бизнесом от Алексея Васильева

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

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

📌 Event Storming

Event Storming — техника коллективного моделирования бизнес-процессов

Строится вокруг событий (domain events), которые отражают значимые изменения состояния системы (заказ создан», платёж подтверждён, товар доставлен)

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


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

➡️ запуск новой системы
➡️ проектирование микросервисной архитектуры
➡️ анализ существующего (legacy) решения перед рефакторингом
➡️ уточнение сложных или неявных процессов между подразделениями

Основные принципы

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


Типы Event Storming-сессий

✳️ Big Picture
Используется для получения общего представления о домене
Позволяет увидеть ключевые процессы и зависимости между ними

➡️ пример: визуализация полной цепочки "Заказ → оплата → доставка → возврат"

✳️ Process Level
Детализирует конкретный бизнес-процесс
Помогает определить события, команды и участников внутри него

➡️ разбор процесса "возврат товара" — от запроса покупателя до перевода средств

✳️ Design Level
Уточняет модель до уровня архитектуры и bounded contexts
Используется при проектировании микросервисов и взаимодействий между ними

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


Ключевые «строительные блоки»

🔵 Domain Event (событие предметной области): главный элемент
Факт, который уже произошел в системе.
➡️ заказ размещён, платёж подтверждён, товар отправлен клиенту

🔵 Command (команда): действие, которое инициирует выполнение операции и приводит к событию
Часто является реакцией на предыдущее событие
➡️ разместить заказ, подтвердить платёж, отправить товар

🔵 Actor (Актор): пользователь или внешняя система, которая вызывает команду
➡️ покупатель, платёжный шлюз

🔵 Aggregate (агрегат): понятие из DDD
Это "кластер" из связанных сущностей (например, заказ с его позициями), который обрабатывает команды и порождает события

🔵 Policy (политика / бизнес-правило): автоматическая реакция на событие
Формулируется как "Когда событие X, тогда команда Y"

➡️ когда "Платёж подтверждён", тогда "Отправить товар"

🔵 Read Model (модель чтения): данные, которые видит пользователь, чтобы принять решение и выполнить команду
➡️ Страница со списком товаров в корзине


Пример как проходит Event Storming

1. Определить границы процесса
➡️ от момента оформления заказа до его доставки

2. Зафиксировать доменные события в прошедшем времени
➡️ заказ создан, платёж подтверждён, уведомление отправлено

3. Добавить команды, которые инициируют события:
➡️ создать заказ, подтвердить платёж

4. Указать акторов
➡️ кто выполняет действие (пользователь, внешний сервис)

5. Добавить агрегаты и сущности
➡️ они изменяют состояние при выполнении команд

6. Зафиксировать политики и правила
➡️ после подтверждения платежа — отправить заказ

7. Сгруппировать события по смыслу
➡️ формируются bounded contexts — логические границы между частями системы

8. Проверяются связи, исключения, альтернативные сценарии

9. Результат: карта событий, отражающая процессы и зависимости


📎 Материалы
1. Event storming
2. Моделирование микросервисов с помощью Event storming
3. Event Storming: как построить модель вокруг событий
4. Введение в Event Modeling
5. 10 аналогов Miro от российских и иностранных разработчиков

📚 Книги
Предметно-ориентированное проектирование: паттерны, принципы и методы - Скотт Миллетт, Ник Тью

#управление_проектами

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

Грокаем безопасность веб-приложений

✍️ Автор: Макдональд Малькольм
🗓 Год издания: 2025
🔤 Язык: русский
📚 Объём: 336 стр.


Практическое руководство по безопасности для веб-приложений.
◾️Раскрываются основные принципы защиты
◾️Подробно разбираются наиболее распространенные уязвимости веб-приложений — от браузера до сервера.

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

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


#безопасность

✔️ Советы по проектированию REST API


1. Использовать множественное число для коллекций
✅ GET /products
✅ GET /products/{product_id}
❌ GET /product/{product_id}


2. Не добавлять лишние сегменты в путь
✅ GET /v3/application/listings/{listing_id}
❌ PATCH /v3/application/shops/{shop_id}/listings/{listing_id}

Не пытаться отразить всю модель данных в URL
Если listing_id уникален — shop_id не нужен

💙 Исключение: если ключ действительно составной

GET /listings/{listing_id}/options/{option_id}

3. Не добавлять расширения в URL

❌ GET /users.json

Формат передачи должен определяться через HTTP-заголовки (например, Accept) , не через URL
✅ GET /users и HTTP-заголовки настройка заголовков:

Accept: application/json

4. Не возвращать массивы верхнего уровня

Объект позволяет легко добавить пагинацию и дополнительные поля без поломки обратной совместимости

❌ [{"id":1}, {"id":2}]
✅ { "data": [{"id":1}, {"id":2}] }


5. Не возвращать структуры-словари (map)

Словари ломают совместимость и неудобны для типизированных языков.
💙 Исключение: простые пары ключ: значение (например, metadata)

✅ { "data": [{ "id":"KEY1" }, { "id":"KEY2" }] }
❌ { "KEY1": {...}, "KEY2": {...} }


6. Добавлять префиксы к ID

✅ Помогает отличать типы сущностей и уменьшает путаницу при поддержке
Примеры:

Stripe: in_1MVpWEJVZPfyS2HyRgVDkwiZ
Shopify: gid://shopify/FulfillmentOrder/1469358604360

7. Не использовать 404 для “не найдено”

❌ 404 Not Found может означать сетевую ошибку или неверный URL
🔹может быть возвращен прокси, балансировщиком нагрузки и т.д.
🔹не позволяет клиенту отличить "ресурс не существует" от "ошибка конфигурации"

✅ Использовать, например, 410 Gone — сервер понял запрос, но объекта нет


8. Ошибки в структурированном формате

✅Позволяет передавать цепочку ошибок и упрощает отладку

{
  "message": "Access denied",
  "type": "Unauthorized",
  "types": ["Unauthorized", "Security"],
  "cause": { ... }
}

9. Идемпотентность операций

Идемпотентность = повтор вызова не меняет результат

🔹 GET, PUT, DELETE — по определению идемпотентны
🔹 Для POST добавлять идемпотентный ключ: клиент отправляет уникальный ключ в заголовке или теле, а сервер проверяет его уникальность

POST /orders
Idempotency-Key: abc123

Если запрос повторится — сервер вернёт 409 CONFLICT и ID уже созданного ресурса:

{
    "message": "Duplicate",
    "old_id": "ORD123"
}

Клиент уверен, что заказ не задублировался


10. ISO8601 для даты и времени

А также использовать ISO8601 для интервалов и длительностей
✅ "2023-12-21T11:17:12.34Z"
❌ "1703157432340"

🔹ISO8601 человеко-читаем
🔹поддерживается всеми библиотеками
🔹работает в UTC


#api

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

Изучаем DDD — предметно-ориентированное проектирование

✍️ Автор: Влад Хононов
🗓 Год издания: 2024
🔤 Язык: русский
📚 Объём: 320 стр.

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

Рассказано
🔹как оценить масштаб и сложность предметной области (с примерами анализа предметной обалсти)
🔹измерить темпы ее развития, учесть необходимые зависимост
🔹про архитектурные паттерны и паттерны взаимодействия, EventStorming, SOA, Data Mesh
🔹применять DDD и структурировать создаваемое ПО эффективно вписывая его в сеть данных (Data Mesh)
🔹о порядке развития проекта синхронно с изменениями в его бизнес-контексте

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


🔹 Пост про DDD

📺 Интервью с автором Learning Domain-Driven Design • Влад Хононов

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

🔼 Workflow-движок

Workflow-движок — система, которая управляет выполнением последовательности шагов (задач) по описанной логике процесса:
🔹 какие действия выполняются, в каком порядке, кто за них отвечает и какие условия переходов между шагами

Нужен, когда в системе есть повторяющиеся, формализованные процессы:
состоящие из нескольких этапов
с предсказуемыми переходами и условиями
▶️Реализует паттерн оркестрации


Как работает

Компоненты:
*️⃣ модель процесса: описание шагов, условий, участников и маршрутов
форматы: BPMN, JSON, YAML, собственные DSL
*️⃣ движок исполнения: интерпретирует модель, управляет выполнением шагов
*️⃣ хранилище состояния процессов (активные задачи, контекст данных)
*️⃣ интерфейс взаимодействия: API или UI для запуска, мониторинга и управления процессами
*️⃣ исполнители (workers): внешние сервисы / люди, выполняющие задачи

Принцип:
🔸описывается процесс
🔸движок интерпретирует модель, создаёт экземпляр процесса
🔸каждый шаг выполняется человеком / системой
🔸движок отслеживает статус и двигает процесс дальше по маршруту

Типовой цикл:
1. запуск — процесс стартует по событию или API-запросу
2. исполнение — движок выполняет шаги, проверяет условия переходов
3. ожидание — если требуется ввод данных пользователем или внешним сервисом
4. завершение — финальный статус, логирование результатов


Примеры

➡️ согласование документов (HR, закупки, договоры)
➡️ автоматизация CI/CD (деплой по цепочке шагов)
➡️ маршрутизация заказов между системами
➡️ оркестрация микросервисов — последовательный вызов нескольких API

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

🔹 клиент / внешняя система инициирует процесс через API
🔹 workflow-движок получает запрос, создаёт экземпляр процесса
🔹 для каждого шага движок вызывает нужный сервис (REST, gRPC, очередь сообщений)
🔹 после завершения шага обновляет состояние и двигается к следующему
🔹 все статусы сохраняются в базе состояний, откуда можно извлечь историю / отчётность


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

➡️процесс состоит из нескольких акторов или систем
➡️нужно контролировать последовательность шагов и статусы
➡️процесс должен быть управляемым и наблюдаемым (SLA, ретраи)
➡️логику нужно менять без перекомпиляции кода (например, через модели BPMN или YAML)

Не стоит использовать:
➖ процесс слишком простой (один-два шага)
➖ бизнес-логика часто меняется и неформализуема


Workflow vs. BPM

🟢 Workflow-движок исполняет процессы
🟡 BPM-платформа управляет ими в широком смысле — моделирует, оптимизирует, анализирует

📌Часто BPM-платформы включают внутри себя workflow-движок как исполнительный слой


Примеры ПО

➖ Temporal
➖ n8n
➖ Camunda
➖ OpenBPM Engine


📎 Материалы

1. Workflow Core — движок бизнес-процессов для .Net Core
2. Как мы делали свой движок Workflow
3. Интеграция с «Госуслугами». Применение Workflow Core (часть II)
4. Интеграционная платформа в The Platform: что умеет, как работает и зачем ей Workflow Engine

#интеграции

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

⬇️ JSON Patch

JSON Patch — формат для описания изменений в JSON-документе
Вместо отправки документа для обновления, отправляется набор операций («патч»), которые нужно применить

⚫️экономит трафик, делает изменения предсказуемыми и атомарными
⚫️описан в стандарте RFC 6902


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

🤩в RESTful API для частичного обновления ресурсов (PATCH-запросы)
🤩для синхронизации состояния между клиентами
🤩где важно версионирование
🤩в event-sourcing как событие


Пример

Исходно:

{ "user": "Иван", "age": 30 }

Патч (набор операций):

[
  { "op": "replace", "path": "/age", "value": 31 },
  { "op": "add", "path": "/city", "value": "Москва" }
]

Результат:

{ "user": "Иван", "age": 31, "city": "Москва" }

Особенности

➡️Строгий формат операций
RFC 6902 определяет только 6 операций:
- add
- remove
- replace
- move
- copy
- test

Расширять этот набор другими операциями нельзя, если нужно сохранить совместимость с системами, реализующими  RFC 6902


➡️Применяется атомарно
Если любая операция в массиве завершается ошибкой (например, путь не найден для remove, или операция test возвращает false), весь патч должен быть откачен, и документ остается без изменений
Это гарантирует целостность

➡️Операции применяются последовательно
Последующие могут зависеть от результата предыдущих
⚫️Пример: чтобы переместить (move) данные из /a в /b, сначала убедиться, что /b не существует, или удалить его в предыдущей операции


JSON Patch vs JSON Merge Patch

✨JSON Merge Patch (RFC 7396) - простой формат для слияния JSON-документов
Отправляется фрагмент, который нужно "наложить" на целевой документ:
- значения заменяются
- null означает "удалить поле"
- отправляются только изменяемые поля

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

🤩Merge Patch — для простых обновлений объектов (конфиги, настройки пользователя)
🤩JSON Patch — когда нужна точность: работа с массивами, контроль целостности, синхронизация


📎 Материалы
1. Оптимизация трафика при синхронизации состояний через Jsonpatch
2. Убегайте от праздника «пустых» проверок: правильно выполняйте PATCH с помощью JSON Patch

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

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