Слепые пятна в подробнейшей документации и Client-Side Data Enrichment в микросервисной архитектуре
Я стараюсь очень подробно писать все свои доки. Так, чтобы максимально исключить возможность неоднозначных трактований, вопросы и неопределенности. Тем не менее, бывают случаи, что вопросы все-таки возникают там, где вроде бы все ну очень понятно. ❓ Собственно, про один такой случай я и хочу рассказать. 💖
Преамбула: есть микросервис (назовем его Микросервис1) и БД 📂, которую он обрабатывает, назовем ее, допустим DB лол, в данной БД есть таблица object с полями id (это пусть наш первичный ключ), полем name, ну и всякими прочими полями, которые нам для примера не нужны (изобразил на картинке ER схематичненько). 🖼 У нас тут микросервисная архитектура, вот это вот все, поэтому к DB имеет доступ только Микросервис1 и все данные этой базы мы должны обрабатывать через него. Я же разрабатываю Микросервис2, которому в какой-то момент потребуется поле object.name, чтобы что-нибудь с этим полем сделать (а именно наложить в качестве метаданных на монтируемое Микросервисом2 видео). 🐸
Ну, вроде, все понятно, поэтому переходим к сути:
В спеке у меня описание POST запроса от FE к Микросервису2, body которого по описанию должен выглядеть примерно вот так:
{
"object_id": 123,
"object_name": "Какое-то_имя_объекта_тут",
"request_datetime": "2025-11-03T10:12:31"
...
}
Ну и так далее, всякие поля дальше идут. Пишет мне фронтендер и спрашивает:
А я смотрю и реально не понимаю, на кой хрен я тут пытаюсь передавать имя, которое правильнее было бы просто по ключу из БД забирать... 🔨 Какой кринж и как я вообще мог так затупить? Я посчитал, что я ошибся и согласился с разработчиком, что лучше это поле убрать отсюда и забрать на бэкенде и пошел заниматься другими делами. Правда минут через 15 в голову пришла не сразу оформившаяся мысль в формате:
Перелистал еще раз спеку и вспомнил, что моя задумка была такая: передать сразу с фронтенда на уровень Микросервиса2 те данные, что нам нужны и уже есть на фронтенде, чтобы избежать большого количества запросов уже со стороны Микросервиса2 к Микросервису1. Например, чтобы получить имя объекта. Поэтому, Андрюха, по коням, у нас труп Client-Side Data Enrichment! 😁 Мы передаем избыточные данные с FE и, возможно, дублируем их на уровне БД микросервиса для того, чтобы уменьшить количество запросов между нашими сервисами. (Имя объекта в запрос вернули, все хорошо).
К чему я все это? К тому, что вся эта ситуация случилась через 5 дней после того, как я закончил писать эту спеку. Вот так мало времени потребовалось мне (автору доки, если что), чтобы какие-то нюансы просто вывалились из головы.
Философское завершение: лучше больше документации, чем меньше документации. Все классные идеи будут либо задокументированы, либо забыты, потому у всех у нас место в голове до конца жизни уже занято чит-кодами для гта, а для всего остального есть Confluence. 🖼️ AEZAKMI
#интеграция #API #REST #HTTP #системныйанализ #json
Я стараюсь очень подробно писать все свои доки. Так, чтобы максимально исключить возможность неоднозначных трактований, вопросы и неопределенности. Тем не менее, бывают случаи, что вопросы все-таки возникают там, где вроде бы все ну очень понятно. ❓ Собственно, про один такой случай я и хочу рассказать. 💖
Преамбула: есть микросервис (назовем его Микросервис1) и БД 📂, которую он обрабатывает, назовем ее, допустим DB лол, в данной БД есть таблица object с полями id (это пусть наш первичный ключ), полем name, ну и всякими прочими полями, которые нам для примера не нужны (изобразил на картинке ER схематичненько). 🖼 У нас тут микросервисная архитектура, вот это вот все, поэтому к DB имеет доступ только Микросервис1 и все данные этой базы мы должны обрабатывать через него. Я же разрабатываю Микросервис2, которому в какой-то момент потребуется поле object.name, чтобы что-нибудь с этим полем сделать (а именно наложить в качестве метаданных на монтируемое Микросервисом2 видео). 🐸
Ну, вроде, все понятно, поэтому переходим к сути:
В спеке у меня описание POST запроса от FE к Микросервису2, body которого по описанию должен выглядеть примерно вот так:
{
"object_id": 123,
"object_name": "Какое-то_имя_объекта_тут",
"request_datetime": "2025-11-03T10:12:31"
...
}
Ну и так далее, всякие поля дальше идут. Пишет мне фронтендер и спрашивает:
"Амиго, а зачем мы тут имя объекта передаем, если у нас есть его id?" ❔
А я смотрю и реально не понимаю, на кой хрен я тут пытаюсь передавать имя, которое правильнее было бы просто по ключу из БД забирать... 🔨 Какой кринж и как я вообще мог так затупить? Я посчитал, что я ошибся и согласился с разработчиком, что лучше это поле убрать отсюда и забрать на бэкенде и пошел заниматься другими делами. Правда минут через 15 в голову пришла не сразу оформившаяся мысль в формате:
"Так, блэт, минуточку!.." 🌳
Перелистал еще раз спеку и вспомнил, что моя задумка была такая: передать сразу с фронтенда на уровень Микросервиса2 те данные, что нам нужны и уже есть на фронтенде, чтобы избежать большого количества запросов уже со стороны Микросервиса2 к Микросервису1. Например, чтобы получить имя объекта. Поэтому, Андрюха, по коням, у нас труп Client-Side Data Enrichment! 😁 Мы передаем избыточные данные с FE и, возможно, дублируем их на уровне БД микросервиса для того, чтобы уменьшить количество запросов между нашими сервисами. (Имя объекта в запрос вернули, все хорошо).
К чему я все это? К тому, что вся эта ситуация случилась через 5 дней после того, как я закончил писать эту спеку. Вот так мало времени потребовалось мне (автору доки, если что), чтобы какие-то нюансы просто вывалились из головы.
Философское завершение: лучше больше документации, чем меньше документации. Все классные идеи будут либо задокументированы, либо забыты, потому у всех у нас место в голове до конца жизни уже занято чит-кодами для гта, а для всего остального есть Confluence. 🖼️ AEZAKMI
#интеграция #API #REST #HTTP #системныйанализ #json