А вы знали, что скоро я поделюсь своим опытом на конференции, посвященной моему любимому System Design. Наконец, я нашла единомышленников!
Подключайтесь!

🛰 Дарья Борисова, Системный аналитик с более чем 7-летним опытом в IT, выступит на третьей конференции Systems Design Online с докладом на тему «Подходы к оптимальному проектированию REST API»

План доклада:
1. Оптимизация кол-ва запросов
— Зачем оптимизировать запросы к серверу
— Как оптимизировать кол-во запросов?
— Детальное рассмотрение способа комбинирования API-эндпоинтов

2. Выбор стороны для проведения расчетов
— Когда лучше проводить расчеты на клиенте, а когда на сервере?
— Возможные компромиссы между производительностью и безопасностью

3. Пакетная обработка
— Понятие пакетной обработки
— Применение batch-запросов для оптимизации взаимодействия с API
— Ограничения и возможные риски при использовании этого подхода

Подробнее о конференции здесь

Канал конференции @systems_design_online

#конференция@systems_education

Гарантированная доставка и ретрансляция сообщений
Я вплотную работаю с банковскими системами, которые нужно интегрировать между собой, и иногда сталкиваюсь с проблемами потери данных или задержки их обработки. И такие проблемы могут привести к серьезным финансовым и репутационным рискам, поэтому рассмотрю эти аспекты подробнее.

📑 Что это?
➰ Гарантированная доставка: Сообщение должно быть доставлено хотя бы один раз. Это означает, что даже в случае сбоя системы, сообщение не будет потеряно и будет повторно отправлено до тех пор, пока не будет успешно доставлено.

➰Ретрансляция сообщений: Если сообщение не было успешно обработано, оно должно быть возвращено в очередь для повторной обработки. Это может произойти в случае временного сбоя в работе потребителя или ошибки в обработке.

📪 Механизмы настройки подтверждения получения (ACK):
🧷 Producer ACK: Производитель сообщений должен получить подтверждение от брокера о том, что сообщение было успешно принято. Это гарантирует, что сообщение не будет потеряно в случае сбоя на стороне производителя.
🧷 Consumer ACK: Потребитель сообщений должен отправить подтверждение брокеру после успешной обработки сообщения. Если подтверждение не получено, сообщение остается в очереди и может быть повторно отправлено.

🛎 Механизмы ретрансляции
➿Dead Letter Queue (DLQ): В случае сбоя при обработке сообщения, оно может быть перемещено в специальную очередь (DLQ), где оно будет храниться до тех пор, пока не будет обработано вручную или повторно отправлено.
➿Retry Mechanism: Настройка количества попыток повторной отправки сообщения перед его перемещением в DLQ. Это позволяет избежать бесконечных циклов повторной обработки и потери сообщений.

📌 Какие брокеры рекомендую:
Apache Kafka – самый популярный брокер
RabbitMQ - Поддерживает различные модели обмена сообщениями и обеспечивает высокую надежность и отказоустойчивость.
IBM MQ - Популярен в корпоративной среде благодаря своей надежности и безопасности, но я его не оценила

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

Основные аспекты работы очередей сообщений

♨️Поддержка методов получения сообщений
Push-метод: В данном случае отправитель сам отправляет сообщение в очередь, а получатели получают уведомления о наличии новых сообщений. Это удобно, когда потребители готовы сразу же обрабатывать новые сообщения.
Pull-метод: Получатели сами периодически проверяют наличие новых сообщений в очереди и извлекают их оттуда. Этот метод подходит для сценариев, когда система должна поддерживать баланс нагрузки или имеет ограничения по ресурсам.

♨️Слабая связность компонентов
Наверное, это самый важный аспект для микросервисов. Благодаря использованию очередей, компоненты системы становятся слабо связанными друг с другом. Они взаимодействуют только через интерфейс очереди, а не напрямую. Это делает систему более гибкой и устойчивой к изменениям, так как каждый компонент может развиваться независимо от других.

♨️Масштабируемость
Добавление новых экземпляров потребителей позволяет легко масштабировать систему. Если нагрузка увеличивается, можно добавить дополнительные экземпляры, которые будут параллельно обрабатывать сообщения из одной и той же очереди. Таким образом, производительность системы улучшается без изменения архитектуры отдельных сервисов.

♨️ Гарантированная доставка
О ней мы подробно поговорили ранее, но повторим, что сообщение сохраняется в очереди до тех пор, пока оно не будет успешно обработано. Это обеспечивает надёжность передачи данных даже в условиях временных сбоев или ошибок.

♨️ Отказоустойчивость
Даже если один из сервисов выходит из строя, остальные продолжают функционировать благодаря буферизации сообщений в очереди. Когда неисправный сервис восстанавливается, он может продолжить обработку накопившихся сообщений.

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

Можно ли использовать очередь как временное хранилище?

В одной интеграции, где нужно было соединить 2 системы и ни одну из них нельзя было доработать. Ничего примечательного, скажете вы. Но ни одна из систем не давала нам права и доступ для того, чтобы создать свою базу данных и хранить необходимые данные. Тогда наша команда решила хранить промежуточные данные в очереди. И сейчас расскажу о том, как мы решили эту задачу

🔑 Способ реализации

1️⃣ Настройка очереди
Создаем очередь сообщений, используя любой подходящий инструмент, будь то RabbitMQ, Kafka, AWS SQS или другой брокер сообщений. Важно выбрать правильную конфигурацию очереди, учитывая параметры её размера, времени жизни сообщений и политики повтора попыток обработки. Мы выбрали RabbitMQ.

2️⃣ Отправка сообщений
Срабатывает триггер на старт процесса (получение сообщения извне/ по таймеру и тд), появляются данные, требующие сохранения, и приложение формирует сообщение и отправляет его в очередь. Каждое сообщение содержит данные, необходимые для выполнения задачи позже.

3️⃣ Получение сообщений
Это же приложение подходит к этапу, когда ему нужно воспользоваться сохраненными данными. Для этого вычитывания данных в этом же приложении выделается отдельный поток/процесс, который забирает сообщение из очереди.
Если сообщение успешно обработано и интеграционный поток находится на финальной стадии, сообщение удаляется из очереди.
Если возникает ошибка, сообщение может быть возвращено обратно в очередь для повторной попытки обработки.

4️⃣ Дополнительные настройки
Можно установить время жизни для каждого сообщения в очереди. По истечении этого времени сообщение удаляется автоматически, если оно не было обработано вовремя. Это помогает избежать накопления устаревших данных.
А оповещения и мониторинг помогут отслеживать состояние очереди и оперативно реагировать на ошибки, например, если число неподтвержденных сообщений превысит допустимый порог.

✅ Преимущества подхода
🌀 Упорядоченность: Данные сохраняются в строго определенном порядке (FIFO), что полезно для последовательной обработки.
🌀Надежность: Сообщения сохраняются в очереди до тех пор, пока они не будут обработаны. Если происходит сбой в процессе обработки, сообщение остается доступным для повторной попытки.
🌀Масштабируемость: Система может добавлять или удалять процессы обработки сообщений динамически, улучшая масштабируемость.

‼️Недостатки
🔻Дополнительная сложность: Использование очереди как временной базы данных требует дополнительной инфраструктуры и управления, что может увеличить сложность системы.
🔻Ресурсозатратность: Постоянное поддержание очереди сообщений требует вычислительных ресурсов и места для хранения данных.

📍Рекомендации
Используйте очереди сообщений как временную базу данных только там, где действительно важна последовательность и надежная доставка сообщений и нет других способов.
Убедитесь, что выбранный брокер сообщений соответствует вашим требованиям по производительности, масштабируемости и отказоустойчивости.
Настраивайте политику повторных попыток и удаления сообщений с учетом специфики вашей задачи.

Приходилось кому-то использовать очереди в нестандартных кейсах? Расскажите в комментариях

Мы закончили цикл про брокеры и очереди. Теперь поговорим о формировании URL и о том, какие подводные камни нам могут встретиться в этом процессе. Для погружения в тему рассмотрим базовый контекст.

❓ Из чего состоит URL эндпоинта ❓

URL эндпоинта REST API — это адрес ресурса, который используется для взаимодействия между клиентом и сервером через HTTP-запросы. Он включает несколько ключевых компонентов, каждый из которых играет свою роль в формировании правильного пути до нужного ресурса. Вот структура URL эндпоинта REST API:
https://доменное_имя/версия_API/ресурс?параметры

✏️Основные компоненты URL

1️⃣ Протокол (https)
- Указывает протокол передачи данных. Чаще всего используется HTTP или HTTPS. Протокол определяет правила обмена информацией между клиентом и сервером.

2️⃣ Доменное имя (доменное_имя)
- Это уникальный идентификатор домена сервера, где находится ресурс. Например, example.com.

3️⃣ Путь к ресурсу (/версия_API/ресурс)
🔴Версия API: Часто путь начинается с версии API (например, /v1, /api/v2), чтобы обеспечить совместимость между разными версиями интерфейсов.
🔴Ресурс: Определяет конкретный объект или коллекцию объектов, с которыми вы хотите взаимодействовать. Ресурс может быть любым сущностью, например, пользователи (users), товары (products) и т.п.

4️⃣ Параметры запроса (?параметры)
- Дополнительная информация, передаваемая в виде пар ключ-значение после символа ?. Параметры позволяют уточнять запросы, фильтровать данные или передавать дополнительные параметры для операций. Каждый параметр отделяется символом &. Например, ?page=1&limit=10.

Пример полного URL:
https://example.com/api/v1/users?page=1&limit=10

Вопросы о версионировании API
Мы часто видим номера версий в сторонних API, но не задумываемся о внутренней кухне версионирования: как делать и для чего? Рассмотрим best practice.

❓Когда версионировать API?

API нуждается в версионировании, когда происходят значительные изменения, влияющие на поведение или контракт API:
- Добавляются новые обязательные поля.
- Меняется формат возвращаемых данных.
- Удаляются старые свойства или изменяется логика работы API.
- Изменяется семантика методов (например, ранее GET запрашивал список объектов, теперь возвращается агрегационная статистика).

🔑 Способы версионирования REST API

Существует несколько популярных способов версионирования API:

☝️ Версификация через URL
Один из самых распространённых способов — включение номера версии непосредственно в URL. Например:

GET /api/v1/products
GET /api/v2/products

Преимущества:
- Простота реализации.
- Легко различимые версии API.

Недостатки:
- Нарушает чистоту концепции REST, поскольку URI должны идентифицировать ресурс, а не его версию.
- Могут возникать сложности при изменении URL структуры (например, смена префикса или удаление старого маршрута).

✌️ Версификация через заголовок HTTP
Альтернативный вариант — размещение версии API в специальном заголовке HTTP, например:

Accept: application/vnd.mycompany.v1+json
Content-Type: application/json

или

X-Api-Version: v2

Преимущества:
- Более чистое решение с точки зрения REST.
- Сохраняет единство ресурсов и независимость от URL.

Недостатки:
- Требуется дополнительная настройка обработчиков заголовков на стороне сервера.
- Клиенты должны помнить о необходимости отправки правильного заголовка.

🤟 Версификация через Content Type
Можно указывать версию API в MIME-типе, например:

Accept: application/vnd.mycompany.products-v1+json

Преимущества:
- Четкое разделение ресурсов и версий.
- Может сочетаться с Content Negotiation.

Недостатки:
- Сложность понимания пользователями, привыкшими видеть номер версии в URL.
- Необходимость поддерживать обработку нескольких Content Types.

💣 Лучшие практики версионирования REST API

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

2. Четкая документация каждой версии. Каждый релиз новой версии API должен сопровождаться подробной документацией с описанием всех изменений и возможных последствий для клиентов.

3. Ограничьте число активных версий. Со временем устаревшие версии API стоит удалять, уведомив заранее клиентов о сроках прекращения поддержки старых версий.

4. Используйте фазовый вывод старой версии. Постепенно отключайте старую версию API, давая достаточное время для миграции клиентов на новую версию.

5. Тестируйте каждую версию отдельно. Перед выпуском новых версий убедитесь, что старая версия продолжает стабильно функционировать.

6. Создавайте тесты на совместимость. Регулярные проверки API позволят выявить возможные регрессии и убедиться, что новая версия API не ломает старый код.

🪧 Итог 🪧

Выбор способа версионирования зависит от конкретной ситуации и требований проекта. Наиболее распространённый подход — версионирование через URL, однако он имеет ряд недостатков с точки зрения чистоты REST. Альтернатива в виде версионирования через заголовки или Content Type предоставляет больше гибкости и соответствует идеям RESTful дизайна. Независимо от выбранного подхода, ключевое значение имеют продуманность изменений, хорошая документация и обеспечение постепенного вывода старых версий API.

Как правильно составлять путь к ресурсу?

Большинство знает эти правила на интуитивном уровне, но не лишним будет структурировать эти знания

Ресурс в RESTful API представляет собой сущность, с которой взаимодействуют клиенты. Примеры ресурсов включают пользователей (users), заказы (orders) и товары (products).

Основные правила

〰️ Используйте существительные: Путь к ресурсу должен быть представлен существительным в единственном числе. Это подчеркивает, что ресурс идентифицируется уникальным образом

〰️ Используйте понятные имена каталогов и файлов. Избегайте длинных сложных имен, предпочтительнее короткие и информативные названия.

〰️ Идентификация конкретного экземпляра ресурса: Если вы хотите обратиться к конкретному элементу ресурса, используйте уникальный идентификатор после слэша.
/users/{id}
/orders/{order_id}

〰️ Вложенность ресурсов. Если ресурсы имеют иерархию, отражайте её в пути. Например, заказы принадлежат пользователям, поэтому заказ можно вложить в пользователя:
/users/{user_id}/orders


🧮 Если нужно обратиться к коллекции ресурсов
Когда вам нужно оперировать коллекциями ресурсов, используйте множественное число:
/users
/products

Рекомендации
🧲 Стремитесь сохранять единообразие в именовании и структуре путей. Если один ресурс использует определённый шаблон, старайтесь применять этот шаблон ко всем другим ресурсам.
🧲 Минимизируйте количество уровней вложенности: Чем короче путь, тем проще ориентироваться посетителям и быстрее индексироваться поисковиками.
🧲 Следите за согласованностью стилей: Старайтесь избегать использования транслита или кириллицы там, где возможны проблемы совместимости.

А вот какие правила существуют для именования операций над ресурсами, которые выходят за рамки обычных CRUD-операций, расскажу в следующий раз.

Как составить путь, если действие над ресурсом ВНЕ рамок REST?

Уверена, что любой аналитик хотя бы раз задумывался над формированием пути для метода, который делает что-то кроме обычного CRUD. В моей практике CRUD встречается реже, чем действие над ресурсом. Сейчас расскажу, какие фишки я использую.

🏓 Использование дополнительных суффиксов

Если вам действительно нужно указать действие, можно добавить дополнительные суффиксы к пути. Такие подходы считаются менее предпочтительными, поскольку они нарушают чистоту REST подхода, но мы с вами бойцы системного фронта, а не блюстители чистоты REST’a, правда?

🥎 Действия в виде глаголов (да, за это не будут бить, я узнавала)
Пример - Отправка уведомления пользователю
POST /users/{user_id}/send_notification

🥎 Конкретные операции:
Операции, которые нельзя однозначно отнести к стандартным методам HTTP, можно выразить через суффиксы.
Пример - Запуск процесса обработки заказа
POST /orders/{order_id}/process



🏓 Использовать другие методы
Некоторые API предпочитают использовать специальные методы, такие как RPC (Remote Procedure Call), которые позволяют описывать конкретные действия. В таком случае можно использовать префиксы или отдельные маршруты для каждого метода.

Запуск оплаты может выглядеть так:
POST /payments/initiate_payment
Внешне как и REST, но под капотом.....

Было интересно? Узнали что-то новое?

🌫 Мифы про REST 🌫

Вы много знаете про REST, но уверены ли вы, что все ваши представления о нем - правда? Рассмотрим самые популярные мифы про REST!

🍋 Любой HTTP-сервис — это REST API
Заблуждение: Многие считают, что если API общается по HTTP-протоколу, значит оно соответствует принципам REST.

Реальность: Просто использование HTTP не означает соблюдение принципов REST. Для того чтобы API было RESTful, оно должно соответствовать следующим критериям:
- Ресурсно-ориентированная структура.
- Использование методов HTTP соответствующим образом (GET, POST, PUT, DELETE и др.).
- Отсутствие состояния на стороне сервера (stateless).
- Кэшируемость результатов запросов.
- Наличие единой точки входа (uniform interface).

Многие API нарушают хотя бы одно из этих правил, несмотря на применение HTTP.

🍊 Только GET-запросы должны возвращать состояние клиента
Заблуждение: Некоторые полагают, что методы HTTP такие как GET предназначены исключительно для чтения данных, а остальные методы (POST, PUT, DELETE) нужны лишь для изменения данных.

Реальность: Любые запросы в RESTful API могут возвращать полезные данные клиенту независимо от метода. Даже запросы POST, PUT или DELETE могут вернуть статус операции, обновленные данные или другой полезный отклик.

🍐 REST API обязательно возвращает JSON
Заблуждение: Часто встречается мнение, что REST API всегда передаёт данные в формате JSON.

Реальность: REST предполагает гибкость форматов данных. API может отвечать XML, YAML, protobuf или даже двоичными файлами, главное — соблюдать принципы REST.


🍓 Каждая сущность должна иметь уникальный URI
Заблуждение: Считается, что каждый объект в системе обязан иметь собственный URL.

Реальность: По сути, REST допускает создание составных сущностей, агрегированных ресурсов и множественных связей. Главное правило — обеспечить прозрачность и единообразие организации маршрутов.

🫐 PUT-запросы заменяют весь ресурс целиком
Заблуждение: Есть заблуждение, что метод PUT предназначен только для полной замены существующего ресурса.

Реальность: PUT может использоваться как для обновления всего ресурса, так и для частичного обновления полей. Важнее сохранять консистентность состояния ресурса и следовать семантике PUT: повторный вызов одного и того же PUT-запроса не должен приводить к изменениям (idempotence).

🍑 Все ресурсы должны находиться на одном уровне
Заблуждение: Иногда считают, что ресурсы должны располагаться на одном уровне иерархии (например, /users, /products), и нельзя создавать вложенность вроде /users/{id}/orders.

Реальность: Группировка ресурсов и вложенность вполне допустимы в REST, если они соответствуют бизнес-логике и делают структуру ясной и интуитивной.

🔚

Рассказывайте, у кого совпало?)

Про gRPC

В одном из недавних постов я упоминала RPC и получила вопросы про него:
Зачем он нужен, если есть REST и SOAP? Что нового он может предложить? а, оказалось, может. Смотрим.

Основные особенности gRPC

🔸 Протокол обмена данными
gRPC построен поверх HTTP/2 — современного протокола, поддерживающего мультиплексирование запросов и потоковую передачу данных. Именно благодаря использованию HTTP/2 gRPC значительно повышает производительность приложений по сравнению с традиционными REST API на HTTP/1.x.

🔸 Формат сообщений
Для описания интерфейсов сервисов и структур данных в gRPC применяется язык определения интерфейсов IDL (Interface Definition Language) на основе формата Protobuf. Protobuf предлагает компактность представления данных и высокую скорость сериализации/десериализации.

🔸 Подход к дизайну API
gRPC позволяет разработчикам определять контракты (интерфейсы) сервиса и типов передаваемых данных декларативно в файлах .proto. Затем генерируются клиентские библиотеки для различных платформ и языков программирования, обеспечивая строгий контроль над интерфейсами и типы данных.

🔸 Поддержка двунаправленной связи
gRPC поддерживает четыре основных режима взаимодействия:
- Unary RPC: один запрос → один ответ.
- Server streaming: один запрос → поток ответов.
- Client streaming: поток запросов → один ответ.
- Bidirectional streaming: потоки запросов и ответов одновременно.

Это делает gRPC идеальным решением для реализации реактивных архитектур и построения микросервисов с минимальной задержкой и высокой производительностью.

👁‍🗨 Зачем использовать gRPC?

1. Производительность. Благодаря компактному формату Protobuf и эффективному протоколу HTTP/2, gRPC показывает лучшую производительность по сравнению с JSON-REST решениями.

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

3. Типизация данных. Protobuf обеспечивает строгую проверку типов, минимизирует возможность ошибок в процессе разработки.

4. Универсальность клиентов. Генерация клиентских библиотек для разных языков программирования облегчает интеграцию гетерогенных систем.

5. Потоковая передача данных. Возможность передавать данные последовательно (streaming), позволяя обрабатывать большие объёмы данных без блокировки системы ожидания полного завершения обработки.

6. Масштабируемость. gRPC хорошо подходит для микросервисных архитектур, обеспечивая лёгкую интеграцию и масштабирование компонентов приложения.

🔝 Почему не использовать REST?
REST отлично подходит для простых сценариев CRUD (создание/чтение/обновление/удаление) и архитектуры на основе ресурсов. Однако, если приложение требует более производительной передачи данных, поддержки двусторонних потоков, интеграции разнородных технологий и четкого контроля типов данных, gRPC становится лучшим выбором.

Кроме того, некоторые современные облачные сервисы и инструменты уже активно поддерживают gRPC, предоставляя дополнительные возможности для мониторинга, трассировки и безопасности (например, Istio, Envoy Proxy).

🔳 Итоги

gRPC будет выигрывать при работе с большими объемами данных и более требовательными сервисами, где важна поддержка потоковых операций и строгие типы данных.

gRPC vs REST

Это все, конечно, хорошо. Но давайте кратко и емко про разницу gRPC и REST и про ситуации их применения.

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

1. Микросервисная архитектура: Если у вас есть система, состоящая из множества сервисов, взаимодействующих друг с другом, gRPC поможет обеспечить быструю и надёжную коммуникацию между ними.

2. Двунаправленная связь: Например, вам нужно создать приложение, которое должно получать обновления в режиме реального времени (например, мониторинг состояния сервера). gRPC с потоковыми запросами отлично справляется с такими задачами.

3. Передача больших объёмов данных: Благодаря использованию Protobuf, gRPC эффективно обрабатывает большие массивы данных, минимизируя накладные расходы на сериализацию и десериализацию.

4. Мобильные приложения: gRPC хорошо интегрируется с мобильными приложениями благодаря своей эффективности и поддержке различных платформ.

🎈 Отличия от REST

1. Протокол:
- REST использует HTTP/1.1, который ориентирован на передачу текста и часто включает заголовки и метаданные.
- gRPC использует HTTP/2, который поддерживает двоичные потоки данных, мультиплексирование запросов и улучшенную компрессию.

2. Формат данных:
- REST чаще всего передаёт данные в формате JSON или XML.
- gRPC использует Protobuf — компактный бинарный формат, который значительно уменьшает размер передаваемых данных.

3. Тип взаимодействия:
- REST обычно ограничивается запросами и ответами типа «запрос–ответ».
- gRPC поддерживает различные типы взаимодействия: односторонние запросы, двусторонний поток данных, клиентские потоки и серверные потоки.

4. Производительность:
- gRPC обычно быстрее и эффективнее, особенно при передаче большого количества мелких сообщений, благодаря использованию Protobuf и возможностей HTTP/2.

Привет!
Давно не виделись! Как праздники? расскажите!

📑 Что должно быть в документации по интеграциям?

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

Что такое интеграция между системами? Это "диалог" между системами. И работа аналитика сводится к созданию сценария взаимодействия для такого "диалога".
Сам сценарий мы рассмотрим внимательно в следующий раз. Но чтобы документация была полноценной, нужно указать дополнительные атрибуты.

🎾 Протоколы обмена информацией
В моей практике в одной интеграции встретились сразу 3 протокола обмена. И не стоит забывать указывать это в документации.

🎾 Sequence diagrams
Бывает, что потребители документации не хотят знать подробностей о работе систем. Для верхнеуровневого обзора последовательности шагов взаимодействия подойдет sequence диаграмма.

🎾 Входящие и исходящие параметры запросов
У входящих указываем тип и обязательность полей. Если лень описывать, то можно приложить ссылку на свагер. Если у вас еще остались силы, то было бы идеально приложить примеры запроса и ответа. Не забывайте, что ответы могут быть успешными и неуспешными, поэтому примеры стоит приводить на оба кейса.

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

🎾 Модель физических данных, если она предусмотрена проектом.
или ERD. Редкая интеграция обходится без участия базы, поэтому не забывайте прописывать ее.

Именно такую схему я использую при создании документации для интеграций.

Ловите рецепт на предпраздничный день

Табличек много не бывает

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

Обычно аналитикам нужно сделать универсальную документацию, понятную и бизнесу, и разработчику. Как это сделать при документировании интеграций?

Согласитесь, что каждое действие системы представляет собой последовательность шагов, следовательно, любую задачу можно оформить в виде сценария. А сценарии записать в виде таблицы. На картинке видно, как выглядит типичный сценарий для интеграций. Расскажу, как это устроено.

✴️ Краткое описание шага. Этот столбец предназначен для бизнес-заказчиков, которым важно получить общее представление о логике функционирования системы или конкретной функции/метода.

✴️ Направление. Такой столбец полезен в многоуровневых интеграциях, где можно запутаться между системами. Обычно его тоже смотрит бизнес.

✴️ Описание. Здесь содержится подробная информация для разработчиков: технические детали реализации, имена используемых методов, ключи для поиска в кешах и прочие важные аспекты.

✴️ Шлюзы. В любом алгоритме неизбежно присутствуют условия и ветвления, и табличный формат прекрасно справляется с отображением даже сложных многоуровневых структур. Условные обозначения и нумерация показывают, к какой ветке относится ветвление, а цветовое выделение позволяет визуально отделить блоки друг от друга. Таким образом навигация становится интуитивно понятной, а чтение превращается в приятное занятие.

· Такой подход помогает не только упростить восприятие информации, но и сделать процесс разработки более структурированным и организованным.
Как считаете, такой формат был бы вам удобен?
Какие шаблоны у вас выработались? Расскажите в комментариях

Diagramm-as-code – удобно?

Раз уж начали говорить про документацию, давайте обсудим самое насущное. Что чаще всего делает аналитик? Правильно, рисует диаграммы. Но это полбеды. Диаграммы нужно править. И не один раз. Обычные рисовалки как draw.io требуют много времени на правки, и я полюбила подход, когда нужно писать код для создания диаграмм.

Что рисуем
flowcharts, sequence diagrams, class diagrams, entity relationship diagrams

Какие плюсы я увидела
➕ Простота внесения изменений
➕ Возможность совместной работы

Что мне не понравилось
Код обычно храним в репо, иногда мы так и делаем, но чаще всего диаграммы вставляются в документацию. Не все базы знаний имеют макросы, в которые в режиме редактирования пишешь код, а в режиме чтения видишь диаграмму. А это значит, исходник нужно тоже где-то хранить. Иногда я вставляю его прямо на страницу в виде скрываемого текста, а иногда храню отдельно. А это, как понимаете, не очень удобно и эстетично.


Какие инструменты рекомендую

🟤 Mermaid
простой и легкий инструмент, основанный на Markdown-подобном синтаксисе для создания различных типов диаграмм.

🔹 Поддерживает множество форматов вывода, таких как SVG, PNG и PDF.
🔹 Простота использования благодаря легкому синтаксису.
🔹 Может использоваться в паре с платформами вроде GitHub Pages, ReadTheDocs и MkDocs для автоматического отображения диаграмм.

Для visual studio Code требует отдельного плагина.

🟤 PlantUML
Мощный генератор UML-диаграмм, использующий собственный текстовый язык для построения классов, последовательности действий, компонентов и другой сложной архитектуры программного обеспечения.

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

PlantUML я использовала онлайн. Редакторов много, вот один из них https://editor.plantuml.com/


Итог
Если диаграммы храните в репо или ваша база знаний имеет плагин для таких редакторов, то этот способ однозначно для вас. В иных случаях выбор неочевиден, но я все чаще выбираю код, потому что мне больше не нужно думать над расположением элементов, умещается ли текст на стрелочки и прочее. Я думаю только над контентом.

Нашла на просторах интернетов. Не смогла пройти мимо.
Жиза, коллеги?))

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

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

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