Карьера в IT. Системный аналитик, часть 8.3. Пример ТЗ для описания метода POST
Всем привет!
Я, наконец, смог оторваться от BG 3, поэтому продолжаем разбираться в системном анализе.
В этом посте продолжим разбирать примеры того, как писать ТЗ на различные API (или если быть точнее, то скорее спецификацию к ним, которая выступает и в роли ТЗ в том числе).
Сегодня рассмотрим написание спеки на метод POST. По сути не так уж сильно отличается от описания GET метода или любых других, но свои нюансы присутствуют.
Для более полного понимания, представим что нам нужно описать админку, которая управляет жизненным циклом бизнес-сущности "Пользователь". Т.е. это значит, что у нас есть на фронте несколько экранных форм, которые суммарно позволяют администраторам системы заниматься их темными делишками:
Получать список пользователей целиком или по заданным параметрам фильтрации;
Открывать карточку пользователя (детальную информацию по нему);
Редактировать ее по необходимости;
Удалять пользователя (или физически объект целиком, но это скорее редкость, или просто помечать его удаленным или неактивным);
Создавать нового пользователя.
Чтобы фронт мог это всё выполнять, нам нужны соответствующие методы, которые он будет вызывать для выполнения этих функций:
GET /users
GET /users/{userId}
PUT /users/{userId}
DELETE /users/{userId}
POST /users
Т.е. по сути реализуем концепцию CRUD по отношению к ресурсу User.
То, как описать метод GET /users/{userId} мы рассмотрели в прошлый раз, сегодня рассмотрим метод POST /users.
Но для начала расскажу как описывать модель данных системы (один из вариантов того, как это можно сделать), т.к. это тоже важная часть ТЗ (спеки), которую должен делать СА. Разберем просто на примере с комментариями:
Ссылка на конфлю кому нужно, пока он еще работает.
Для того, чтобы описать какой-либо объект системы, нужно всего лишь описать всего его атрибуты (желательно дать еще бизнесовое описание этого объекта, просто хотя бы для себя, но это уже другая история).
Поэтому аналитику нужно придумать его наименование на английском, указать его тип, имеющиеся ограничения и (обязательно) описание атрибута на русском языке, при необходимости с комментариями. Последнее - очень важно, чтобы потом самому не забыть зачем этот атрибут нужен и какие у него есть особенности.
В рамках данного шаблона есть немного кастомных вещей, свойственных для моих проектов. Например, вот эта вот "Ссылка на userGroup", это означает FK на таблицу на таблицу USER_GROUP и связку с соответствующим объектом. А атрибут role с ссылкой в типе на ref.Roles это enum (справочник). Т.е. атрибут может принимать только одно из значений из списка:
Конкретно эти штуки на разных проектах описываются сильно по-разному, но тут уж у кого как принято. Общий смысл всегда идентичен. В чем плюс этого варианта - ты одновременно описываешь и DTO (структуру данных метода) и структуру данных БД.
С моделью данных разобрались, это нам поможет при описании метода в том числе.
Описание самого метода (ссылка на конфлю):
Обычно методы по созданию объектов сложнее, но тут у нас очень простой процесс, почти нет проверок, поэтому так)
Главное, что нужно проверить - что у пользователя, который вызвал этот метод есть права на совершение этой операции и что нельзя создать пользователя, идентичного существующему.
И не менее главное - указать правила того, как должны заполняться атрибуты объекта при его создании (маппинг). Чтобы разработчик понял, откуда ему брать эти значения. В данном случае часть полей заполняется константами а остальная часть полей берется из request, т.е. тех данных, которые прислали на вход данному методу.
По-хорошему можно было бы расширить этот метод автоматической генерацией пароля, автоматической же отправкой его на почту пользователю (а значит и интеграцией с соответствующим сервисом) - но в рамках всего лишь примера - это излишне.
Получился еще более длинный длиннопост, чем обычно. Но вам, вроде бы, не привыкать. Вопросы, комментарии по сабжу - как обычно welcome.
P.S.: По традиции - буду признателен за вопросы про карьеру\профессию\чему угодно связанному со сферой IT - постараюсь ответить на всё.
P.P.S.: Также веду телеграмм-канал, в котором делюсь разным про профессию и про свой путь в ней. Есть и хардовая информация (асинхронные, синхронные интеграции, примеры ТЗ\шаблонов написания микросервисов), так и более софтовая - см. закрепленный дайджест.