✔️ Советы по проектированию 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. Если формат зайдёт, будем практивать и дальше.
Примерно так:
мы даём начало 💙 обмен опытом в комментах 💙 собираем в финальный пост.
Ну и как всегда — выложим в базу знаний по системному анализу

🔼 Слоистая архитектура

Слоистая архитектура — подход, при котором система разделяется на логические слои

💚Каждый отвечает за строго определённую группу задач и взаимодействует с другими слоями по правилам


Базовые принципы

💚 Разделение ответственности

Каждый слой решает 1 категорию задач:
💚взаимодействие с пользователем/внешними клиентами
💚управление бизнес-процессами
💚бизнес-правила
💚работа с данными и внешними системами

Слой не должен брать на себя задачи вне его зоны ответственности

💚 Однонаправленные зависимости

Зависимости направлены сверху вниз:
💚верхние слои используют нижние
💚нижние не знают о верхних

Снижает связанность и упрощает изменение системы

💚 Контракты между слоями

Контракт слоя — формальное описание:
💚какие данные слой принимает
💚какие данные возвращает
💚какие ошибки и ограничения возможны

⭕контракт важнее реализации
⭕верхний слой знает контракт, но не реализацию
⭕реализацию можно заменить (другая БД, другой внешний сервис), не меняя вызывающий слой

💚 Изоляция изменений

Изменения в одном слое не должны затрагивать другие, если контракт сохранён

Пример:
📍смена БД не требует изменений в бизнес-логике
📍смена UI не влияет на доменные правила


Типовая структура

⏩ Презентационный слой (Presentation Layer)

🟡принять запрос
🟡проверить формат данных
🟡вернуть результат пользователю или клиенту

Включает:
⭕UI (веб, мобильный, desktop)
⭕REST / GraphQL контроллеры
⭕валидацию формата данных

Не должно быть:
✖ бизнес-логики,
✖ прямой работы с БД

⏩ Слой приложения (Application / Service Layer)

🟡управлять сценариями использования (use cases)
🟡определять последовательность шагов
🟡управлять транзакциями и безопасностью

Включает:
⭕сервисы приложений
⭕оркестрация логики
⭕обработку ошибок сценариев

Отвечает на вопрос «что именно нужно сделать», но не содержит бизнес-правил


⏩ Бизнес слой (Domain / Business Layer)

🟡реализация бизнес-правил и ограничений
🟡хранение данных предметной области

Включает:
⭕сущности
⭕доменные сервисы
⭕бизнес-инварианты

Ключевой слой, ради которого существует система

Не должно быть:
✖ логики UI
✖ SQL, HTTP-вызовов
✖ технических деталей хранения данных


⏩ Инфраструктурный слой (Infrastructure Layer)

🟡реализация технических деталей
🟡работа с БД
🟡интеграции с внешними системами
🟡файловые хранилища, очереди, API, кэш

Включает:
⭕репозитории
⭕ORM
⭕HTTP-клиенты


Типовой поток запроса

1. Presentation Layer принимает запрос
2. Application Layer запускает сценарий
3. Domain Layer выполняет бизнес-логику
4. Infrastructure Layer читает или сохраняет данные
5. Результат возвращается вверх


Другие слои

🟡Integration — изоляция внешних API и интеграций
🟡Security — авторизация, аутентификация, ACL
🟡Caching — работа с кэшем (Redis и аналоги)
🟡Messaging / Event — очереди, события, асинхронное взаимодействие

Это не обязательные слои
Их выделяют, если появляется отдельная ответственность
Лишние слои усложняют систему


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

✅ есть нетривиальная бизнес-логика
✅ система будет развиваться
✅ в проекте несколько команд

✖ система одноразовая
✖ минимальная логика
✖ критична каждая миллисекунда задержки


📎 Материалы
1. Слоистая архитектура приложений: как обеспечить поддерживаемость доменного слоя
2. Трехслойная и трехзвенная: введение в архитектуру ИС для аналитика
3. Слоистая архитектура
4. Архитектура приложения: что это, какие есть виды и как проектировать

📚 Книги
1. Архитектура ПО. Руководство для обучающихся архитектурному мышлению - Ганди Раджу, Ричардс Марк, Форд Нил
2. Идеальная архитектура. Ведущие специалисты о красоте программных архитектур - Диомидис Спинеллис, Георгиос Гусиос
3. Архитектура программного обеспечения на практике - Л. Басс, П. Клементс, Р. Кацман
4. Александр Швец. Погружение в Паттерны Проектирования

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

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

🟢 Стратегии деплоя

Деплой (deployment) / развертывание — процесс доставки новой версии приложения в продакшн и её ввода в эксплуатацию.

Стратегия деплоя определяет
- как именно новая версия попадает в прод,
- какая часть пользователей её увидит
- что произойдёт в случае ошибки


🔵 Big Bang / Replace/ Recreate Deployment (полная замена)

Как работает

1. Старая версия приложения полностью останавливается
2. Обновляется код и конфигурации
3. Запуск новой версии

Плюсы и минусы

➕ просто реализовать
➕ минимальные требования к инфраструктуре

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

Где применяется

🔹 внутренние системы, где простой допустим
🔹 низкокритичные сервисы
🔹 редкие релизы
🔹 на ранних этапах проекта / в условиях ограниченных ресурсов


🟢 Rolling Deployment (постепенное обновление)

Как работает

- новая версия разворачивается постепенно, по экземплярам (ноды, поды, контейнеры) приложения
- балансировщик исключает обновляемые узлы из трафика
- без полной остановки сервиса


➕ нет полного простоя
➕ не требует дублирования окружений

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

Где применяется

🔹 микросервисная архитектура
🔹контейнеризированные приложения (Kubernetes, облачные платформы)


🔵 Blue-Green Deployment (Сине-зеленое развертывание)

Используются идентичные production-окружения:
- Blue — текущая версия
- Green — новая версия

Процесс деплоя:

1. Разворачивание новой версии в Green
2. Проверка работоспособности
3. Переключение всего трафика с Blue на Green
4. Среда Blue становится standby

➕ мгновенный откат. При обнаружении проблем после переключения трафик возвращается на Blue
➕ нет простоя. Релиз — перенаправление трафика
➕ чёткий контроль версии. Новую версию можно проверить в проде под реальной нагрузкой перед переключением

➖ удвоенные ресурсы
➖ сложность работы с БД , кэшами, файловыми хранилищами, чтобы обе версии могли работать с общим состоянием или его миграция была управляемой

Где применяется

🔹критичные пользовательские системы
🔹сервисы с высокими SLA


🟢 Canary Release (канареечное развертывание)

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

Применяется для высоконагруженных / критически важных приложений

➕ минимизация рисков
➕ раннее обнаружение проблем

➖ сложность настройки
➖ повышенные требования к наблюдаемости


🔵 Shadow Deployment (теневое развертывание)

- новая версия развертывается параллельно со старой
- пользовательские запросы дублируются и отправляются в новую версию, но ответы от новой версии игнорируются

Применение

Тестирование новой версии под реальной нагрузкой, но без риска для пользователей
После анализа логов и метрик теневой версии выбирается одна из стратегий (Blue-Green, Canary)


👉 Feature Toggles (флаги)

Это не стратегия деплоя, а техника, которая усиливает другие стратегии

Новая функциональность «завернута» в оператор (флаг), который можно включать/выключать без деплоя (также только для группы пользователей)


👉 A/B-тестирование

Цель — не безопасный деплой, а валидация бизнес-гипотез (какой вариант интерфейса дает большую конверсию)
Часто это следующий шаг после успешного Canary-релиза, когда нужно принять решение оставить новую версию или откатить


📎 Материалы

1. Стратегии деплоя в Kubernetes
2. Стратегии развертывания (деплоя) и стратегии кэширования
3. 6 способов деплоя веб-приложений
4. Deploy (деплой)
5. Стратегии деплоя: как мы пришли к использованию Argo CD

📚 Книги
1. Грокаем Continuous Delivery - У. Кристи
2. Continuous delivery. Практика непрерывных апдейтов - Э.Вольф
3. Руководство по DevOps - Д. Ким, П. Дебус, Д.Уиллис, Д.Хамбл С.Д.

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

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

📌 Систематизация знаний на проекте

Все зависит от статуса проекта, но вот примерный план:
🤩собрать и зафиксировать текущее знание
🤩структурировать
🤩убрать противоречия
🤩поддерживать актуальность

Ключевая задача на входе не «написать документацию»,
а собрать, структурировать и зафиксировать текущую инфу о системе:

🔣что система делает сейчас
🔣почему она делает это именно так
🔣где находятся основные источники информации
🔣какие есть ограничения, долги и договорённости


С чего начинать

Где хранится информация: составить список всех мест

Формальные:
⚪️ Confluence / Notion
⚪️ репозиторий (README, ADR, comments)
⚪️ ТЗ, договоры
⚪️ API-спецификации (Swagger, Postman)
⚪️ BPMN / схемы / презентации

Неформальные:
⚪️знания разработчиков
⚪️чаты
⚪️комментарии в тасках
⚪️личные файлы коллег


Определение границ системы

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

Это основа будущей контекстной диаграммы (C4)


Пример структуры проекта

📌 Лучше разделять бизнес и системную аналитику
Важно для масштабируемости

Пример верхнеуровневой структуры

/Проект
  /00_Общее
  /01_Бизнес-аналитика
  /02_Системная_аналитика
  /03_Архитектура
  /04_Интеграции
  /05_Данные
  /06_API
  /07_НФТ
  /08_Решения_и_долги

Подробнее по разделам

✨ 00. Общее

Дать понимание проекта за короткий срок
Описание проекта (1–2 страницы):
➖зачем система существует, для кого
➖какую бизнес-проблему решает
➖глоссарий
➖участники
➖актуальные источники: где документация, код, API

✨ 01. Бизнес-аналитика

Фиксирует что и зачем делает система, без привязки к реализации

Пример структуры

/01_Бизнес-аналитика
  /01_Цели_и_метрики
  /02_Бизнес-процессы
  /03_Роли_и_пользователи
  /04_Бизнес-правила
  /05_Сценарии_использования

Бизнес-процессы:
⚪️AS-IS (как есть сейчас)
⚪️TO-BE (если планируется развитие)
⚪️BPMN или текст + диаграммы

Use Cases / User Stories: без технических деталей

✨ 02. Системная аналитика (ядро)

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

Пример структуры

/02_Системная_аналитика
  /01_Функциональные_требования
  /02_Сценарии_и_алгоритмы
  /03_Состояния_и_статусы
  /04_Валидации_и_ошибки

Что важно
➖детальные сценарии
➖условия, ветвления
➖бизнес-правила в формализованном виде
➖краевые кейсы

✨03. Архитектура

➖C4 диаграмма
➖описание основных компонентов
➖ответственность сервисов
➖очереди, кэши, БД

✨ 04. Интеграции

Для каждой интеграции:
➖назначение
➖инициатор
➖формат данных
➖синхрон / асинхрон
➖ошибки и ретраи

✨05. Данные (крайне важен)

➖ER-диаграммы
➖описание ключевых сущностей
➖статусы и их жизненный цикл
➖источники данных

✨ 06. API

➖Swagger / OpenAPI
➖описание эндпоинтов в бизнес-терминах
➖примеры сценариев

✨07. Нефункциональные требования

➖производительность
➖безопасность
➖SLA
➖логирование

✨08. Решения и долги

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


Как вести документацию дальше

⚪️ документируется текущее состояние, а не желаемое
⚪️ один раздел → один тип знаний
⚪️ любое изменение → обновление документа
⚪️ лучше «плохо, но есть», чем «идеально, но никогда»

Практика

⚪️вводить шаблоны
⚪️привязывать документы к задачам
⚪️делать ревью документации с командой


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

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

📈 Модель Кано

Модель Кано — метод классификации и приоритизации функций продукта на основе их влияния на удовлетворенность пользователей

Нужна, чтобы отличать «обязательные» функции от «приятных бонусов», грамотно распределять ресурсы команды

Где используется
В продуктовой и маркетинговой аналитике, управлении требованиями и разработке:
⚪️приоритизация бэклога
⚪️проектирование MVP: определение минимума для выхода на рынок
⚪️стратегия развития продукта: поиск «фишек»


Типичные объекты анализа:
✨функциональные и нефункциональные требования
✨элементы пользовательского интерфейса
✨сервисные параметры (поддержка, скорость, доступность)
✨новые продуктовые гипотезы


Рассматриваются два независимых показателя:
➡️удовлетворённость пользователя при наличии характеристики
⬅️ неудовлетворённость пользователя при её отсутствии

❗️отсутствие роста удовлетворённости не означает, что характеристика не нужна
Обязательные характеристики не повышают удовлетворённость
Но их отсутствие приводит к сильному негативу


Категории модели Кано

1️⃣ Must-be (обязательные)

Характеристики, которые пользователь считает само собой разумеющимися.
▪️их наличие не повышает удовлетворённость
▪️их отсутствие вызывает сильное недовольство

🤩 пример: авторизация в системе; сохранение данных; базовая безопасность.

2️⃣ One-dimensional (линейные)

Характеристики, для которых действует прямая зависимость: чем лучше реализовано, тем выше удовлетворённость
▪️улучшение повышает удовлетворённость ↑
▪️ухудшение повышает неудовлетворённость ↓

🤩 пример: скорость работы системы; количество поддерживаемых сценариев; точность поиска

3️⃣ Attractive (восхищающие)

Характеристики, которых пользователь не ожидает, но которые вызывают положительные эмоции
▪️отсутствие не расстраивает
▪️наличие резко повышает удовлетворённость

🤩 пример: умные рекомендации; автоматизация рутинных действий; нестандартные UX‑решения

4️⃣ Indifferent (безразличные)

Характеристики, которые не влияют ни на удовлетворённость, ни на неудовлетворённость.
▪️пользователь не считает их ценными
▪️часто возникают из внутренних гипотез команды

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

5️⃣ Reverse (обратные)

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

🤩 пример: навязчивая автоматизация; избыточные уведомления; усложнение интерфейса.


Общий процесс анализа

1. Определить объект анализа.
2. Сформировать список характеристик.
3. Разработать и провести опрос.
5. Проанализировать результаты с помощью вычислений и матрицы Кано
6. Использовать их для принятия решений.


Пример
Формирование backlog с помощью модели Кано

Результаты анализа используются для приоритизации требований

⚪️Обязательные требования

Все характеристики категории Must-be включаются в backlog обязательно
Имеют высокий приоритет независимо от пользовательского «восторга»

⚪️ Линейные характеристики

Характеристики категории One-dimensional приоритизируются по:
➖степени влияния на удовлетворённость
➖частоте упоминаний
➖стратегической важности

Эти требования чаще всего становятся основой roadmap

⚪️Восхищающие характеристики

Характеристики категории Attractive:

➖используются для дифференциации продукта
➖добавляются в backlog как продуктовые гипотезы
➖часто реализуются итеративно или экспериментально

⚪️ Безразличные и обратные

Indifferent исключаются / откладываются из backlog
Reverse удаляются или пересматриваются


Ограничения модели Кано

➖субъективность
➖зависимость от формулировок вопросов
➖изменение ожиданий со временем


📎 Материалы
1. Модель Кано. Практическое руководство по приоритизации фич
2. Объяснение модели Кано: анализ и примеры
3. Объяснение модели Кано
4. Что такое модель Кано: как построить на примере

#требования

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

⬆️Как прокачать ChatGPT в разы совершенно бесплатно

Собрали лайфхаки, которые повысят качество ответов любой нейросети.

1️⃣ Запрещаем нейронке врать

​Прежде чем отвечать, оцени уровень неопределённости своего ответа. Если он превышает 0.1, задай мне уточняющие вопросы до тех пор, пока неопределённость не снизится до 0.1 или ниже.

Промпт ломает привычную схему: не «вопрос → ответ», а «вопрос → уточнение → точный ответ».

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

2️⃣ Пишем промпты правильно

Вот универсальный шаблон:
Роль + Цель + Контекст + Ограничения + Формат вывода + Уровень качества.
Подробнее писали здесь

Роль: Ты - [тренер/редактор/аналитик].
Цель: достичь [конкретного результата].
Контекст: Вот что тебе нужно знать:
- [предыстория]
- [аудитория]
- [что у меня уже есть]
Ограничения:
- Не [добавляй новые предположения / добавляй дополнительные разделы].
- Если чего-то не хватает, [задай до 3 вопросов] ИЛИ [четко сформулируй предположения].
- Ограничься [X предложениями] или [Y пунктами].
Формат вывода:
- Раздел 1: [краткий ответ]
- Раздел 2: [маркированный список/таблица/контрольный список]
- Раздел 3: [следующие шаги]
Уровень качества:
- Используй простой язык.
- Будь конкретным и действенным.
- Если неясно, скажи, что от чего зависит.

3️⃣ Просим саму нейронку написать промпт

Перед тем, как поручить нейронке задачу, попробуйте попросить её улучшить ваш промпт:

Ты промпт-инженер. Напиши профессиональный промпт для запроса ниже:
<ваш запрос>

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

4️⃣ Включаем критическое мышление

Когда нейронка даст ответ, заставьте её критически проанализировать свой ответ и предложить улучшения.

Проанализируй свой предыдущий ответ. Найди 3 слабых места и предложи более инновационные подходы. Используй критический анализ и добавь неочевидные инсайты.

Так нейронка посмотрит на проблему под другим углом и исправит свои неточности и даже галлюцинации.

5️⃣ Поэтапное размышление для сложных задач

Превращаем ИИ в аналитического ассистента, а не просто в генератора текста, за 3 отдельных промпта:

1. Планирование: пишем промпт как в пункте 2 и добавляем в конце:

Составь план решения и перечисли допущения. Не давай ответ сразу

2. Критика и проверка (как в пункте 4):

Проанализируй свой план. Найди 3 слабых места и предложи более инновационные подходы. Используй критический анализ и добавь неочевидные инсайты. В конце предложи улучшенный план

3. Исполнение: только теперь разрешаем нейронке дать ответ

Теперь дай финальный ответ строго по утверждённому плану.

🔖Сохраняем!

💫💫💫
@it_prompt — подписывайтесь, здесь много полезного

🎮 Способы распила монолита на микросервисы

Правило:

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

Качественный сервис после распила обладает:
💙слабой зависимостью (loose coupling) — изменения не ломают соседей
💙высокой внутренней связностью (high cohesion) — сервис решает одну бизнес-задачу


Стратегии

💙 Декомпозиция по бизнес-доменам

Основана на Domain-Driven Design

💙Каждый сервис = один Bounded Context: собственная логика и данные
💙Границы определяются бизнес-процессами, а не слоями кода

💙 Пошаговый переход

1. Анализ предметной области, выделение контекстов Например, где заканчивается работа склада и начинается работа логистики
2. Определить владельцев данных. Н-р, какие таблицы в монолитной БД принадлежат какому контексту
3. Запретить прямой доступ к «чужим» таблицам
4. Выделить API
5. Отдельный деплой

💙 Пример

Каталог (товары, цены) и "Заказы" (корзина, оформление). Их можно разделять
Заказы хранят цену на момент покупки и не зависят от текущей цены каталога

❤️Не применять

♥️плохо формализован домен и нет четких бизнес-процессов
♥️ нет владельца продукта
♥️ часто меняющиеся границы (MVP)


💙 Strangler Fig

Безопасный способ рефакторинга "на ходу", когда монолит нельзя останавливать

💙Перед монолитом ставится маршрутизатор: API Gateway или обратный прокси (nginx, HAProxy)
💙Новая функциональность создаётся в микросервисах, старая постепенно удаляется.

💙 Пошаговый переход

1. Выбрать изолированный use-case
2. Реализовать его как сервис
3. Настроить маршрутизацию
4. Переключить трафик
5. Удалить старую реализацию

💙 Пример

Личный кабинет переносится по частям: сначала профиль, затем смена пароля, затем всё остальное. Монолит постепенно очищается

❤️Не подходит

♥️если нужен быстрый полный переход
♥️ монолит невозможно маршрутизировать


💙 Декомпозиция по данным (Database per Service)

Не самостоятельная стратегия, а обязательное условие микросервисов

Каждый сервис владеет собственной БД. Общих таблиц нет. Доступ к данным — только через API

Подходы

💙разные схемы в одной СУБД
💙физически отдельные БД
💙копии данных + события
💙Event-driven синхронизация

💙 Пошаговый переход

1. Определить владельца таблиц
2. Запретить cross-schema JOIN
3. Выделить БД
4. Перевести взаимодействие через API
5. Настроить события при необходимости


Пример

Order Service получает собственную БД. Остальные сервисы работают с заказами только через API

❤️Не применять

♥️требуются жёсткие распределённые транзакции
♥️нет инфраструктуры событий


💙 Декомпозиция по нагрузке (Performance-driven)

Выносится компонент, создающий нагрузку

💙 Пошаговый переход

1. Найти узкое место (метрики, профилирование)
2. Выделить код
3. Перевести в асинхронный режим
4. Добавить кэширование

💙 Пример

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

❤️Не применять

♥️если проблема в плохом SQL, а не в архитектуре
♥️нагрузка не критична


💙 Декомпозиция по частоте изменений

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

💙 Пошаговый переход

1. Анализ истории коммитов
2. Выделение часто меняющегося модуля
3. Отделение данных
4. API и независимый деплой

💙 Пример

Блок Акции и предложения обновляется ежедневно. Его вынос позволяет деплоить изменения без затрагивания ядра системы

❤️ Не применять

Частые изменения вызваны хаосом требований


📎 Материалы

1. Шпаргалка по миграции монолита на микросервисы
2. Когда и как переходить с монолита на микросервисы. Предпосылки и общие понятия
3. Архитектура микросервисов: Разрушение монолита
4. Как НЕ надо распиливать монолит
5. Микросервисная архитектура: от монолита к гибкой системе


📚 Книги
Сэм Ньюмен - Создание микросервисов

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

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

🔈 Как найти работу в 2026 году

Вы все слышали о том, что происходит с рынком труда (если коротко там полный трэш) - hh / rabotaby глючит, вакансии исчезают, конкуренция х10, а рекрутеры просто не отвечают. Каждую неделю новые правила, и ты либо под них подстраиваешься, либо идешь нахер.

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

🔴10 ключевых лайфхаков по резюме
🔴Нужны ли сопроводительные и что там писать
🔴Как отвечать на вопрос «Расскажите о себе»
🔴Как рассказывать о своем факапе?
🔴13 шаблонных отказов рекрутеров - что они означают.
🔥 Разборы резюме для АНАЛИТИКОВ

ну и то, что нам особенно интересно - про офферы и ЗП
🔴45 офферов по разным ИТ ролям: от аналитика до тим тим лида за 850к
🔴Какой аналитик получил 0,5 млн.
🔴Сколько может получать аналитик в 50+ лет
🔴Как получить 75к евро с релокацией в Европу
🔴Какой тим лид получил 1,2 млн
🔴Пошаговый план как выйти в найме на 1 млн руб

Сохраняйте, читайте, подписывайтесь

erid: 2VtzqxYtABE