⌛ Жизненный цикл 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

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

🧠 Brainstorm

Брейншторм (мозговой штурм) — групповой метод генерации идей для решения задачи или поиска вариантов
Это не обсуждение и не поиск лучшего решения
💙А способ найти варианты решений

🎯 Цель: получить максимально широкий набор идей за ограниченное время без их оценки на этапе генерации

Проводится в два этапа:
💙 сначала — генерация идей
💙затем — анализ, отбор и принятие решений


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

✨фасилитатор — управляет процессом, следит за правилами, не предлагает решения
✨участники — генерируют идеи, не критикуют, не оценивают
✨наблюдатель (опционально) — подключается на этапе анализа


Зачем нужен

◾️задача открытая, без заранее известного решения
◾️есть риск застрять в очевидных или привычных решениях
◾️требуется быстро собрать идеи от разных ролей и точек зрения
◾️проекты на начальных, неопределенных стадиях

Когда не нужен

➖ у задачи однозначное решение (например, по регламенту или стандарту)
➖ требуется точный расчет или экспертиза одного специалиста
➖ решение уже принято, нужна его реализация


Пример

💙 Поиск корневой причины сбоя в процессе

💙Ситуация: в еженедельном отчете падает количество успешных транзакций.
💙Задача для брейншторма: что привело к снижению числа успешных платежей?
💙Результат - сгенерированные гипотезы:
- обновление страницы оплаты
- проблемы у платежного провайдера
- изменения в анти-фрод системе
- ошибка в кешировании данных
- сезонный фактор
Cоздается список направлений для дальнейшей проверки


Базовые правила

1. Запрещена критика идей
2. Количество важнее качества. Цель — заполнить доску вариантами
3. Поощряются нестандартные идеи
4. Идеи можно развивать и комбинировать


Техники

💙 Классический брейншторм

Когда использовать: простые открытые задачи
Как проводится: участники устно предлагают идеи, фасилитатор фиксирует

➕ простота, высокая скорость
➖ риск доминирования активных участников

Пример: генерация вариантов пользовательских сценариев

💙 SCAMPER

Когда: улучшение текущего решения
Как: генерация идей по наводящим вопросам
💙(Substitute (Заменить)
💙Combine (Комбинировать)
💙Adapt (Адаптировать)
💙Modify/Magnify Модифицировать/Увеличить)
💙Put to other uses (Применить иначе)
💙Eliminate (Устранить)
💙Reverse/Rearrange (Перевернуть/Изменить порядок)

➕ структурированный подход
➖ не подходит для задач «с чистого листа»

Пример: Оптимизация бизнес-процессов

💙 Six Thinking Hats

Когда: cложные задачи, конфликт мнений
Как: участники мыслят в заданных ролях
➕ снижает споры, структурирует обсуждение
➖ требует подготовки
Пример: проработка архитектурных альтернатив

💙 Обратный брейншторм

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


📎 Материалы
1. Топ 8 инструментов для мозгового штурма
2. 15 способов превратить мозговой штурм в результат «огонь»
3. Пять техник мозгового штурма
4. Что такое мозговой штурм и как правильно его проводить в компании
5. Как провести мозговой штурм: основные правила, методы и ошибки

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

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

❌ Баги аналитики

Код написан, всё успешно протестировано, фича на проде, а бизнес в шоке... Знакомо?
💙Это то, что мы с вами не учли на этапе написания ТЗ

Выявить, проанализировать, уточнить, согласовать требования, критически посмотреть на проблему, найти риски
💙Никто, кроме аналитиков, эту работу не проделает

Баги от нас стоят дороже всего
💙Но их предотвращение — экономит деньги компании больше всего


Антипаттерны аналитики

1️⃣ Не все требования фиксируются письменно

Существуют на словах, "очевидно же"
В итоге на прод попадает функционал, где клиент-иностранец может получить налоговый вычет
💙 Все требования фиксируем в артефакте

2️⃣ Не все требования согласовываются с бизнесом

После релиза менеджер залетает с ноги и возмущается, почему не учли то-то.
А это нигде не зафиксировано
💙 Обязательно получаем ОК от заказчика по требованиям перед тем, как писать детальное ТЗ

3️⃣ Лоскутное описание процессов

Не продуман процесс целиком, нет e2e описания, как должно работать
В итоге ни у кого нет понимания общей картины. Даже у аналитика
💙 Составлять верхнеуровневое описание процесса до написания ТЗ

4️⃣ Не обращать внимания на вариации и корнер-кейсы

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

5️⃣ Неверный уровень детализации ТЗ

💙 Слишком подробные, кодоподобные ТЗ затрудняют чтение и требуют реверс-инжиринга
Никто, кроме аналитика, ничего не поймёт
💙 Слишком поверхностные ТЗ упускают детали → ловим баги на проде
💙 Иметь шаблоны ТЗ под каждый тип задачи

6️⃣ Доверять документации

Вообще, слово "доверять" не про аналитиков :)

Руководствуемся критическим мышлением, слепо доверять мы не можем
Например, при описании интеграции с внешним сервисом нельзя взять и скопипастить в своё ТЗ пример запроса и ответа. Нужно проверять вручную
💙 Критически относится к чужой документации. Всегда проверять всё, что можно проверить

7️⃣ Не закладывать идемпотентность и дедубликацию
В той самой статье про Васю всё сказано, добавить нечего

➿➿➿➿➿➿➿➿
⬇️ Продолжение следует ... за Вами!

Давайте добавим краудсорсинга в комментариях к этому посту — обменяемся своими факапами (админ первый).
Соберём всё и выложим продолжение

P.S. Если формат зайдёт, будем практивать и дальше.
Примерно так:
мы даём начало 💙 обмен опытом в комментах 💙 собираем в финальный пост.
Ну и как всегда — выложим в базу знаний по системному анализу