Post #499

Главная проблема у Вигерса — это, конечно, полное отсутствие хоть каких-нибудь слов о проектировании API. Абсолютно ничего. Хотя вся база для проектирования есть, и главное — это диаграммы. DFD в главе 12 (стр. 269) и, ещё лучше — Карта диалоговых окон на стр. 280 (напоминаю, что я даю страницы по изданию BHV 2013 г.). Я такую диаграмму на тренингах обычно называю "схема навигации". Это очень простая диаграмма: прямоугольники — отдельные экраны (или разные состояния одного экрана), а стрелки — переходы с одного экрана к другому. Это очень мощный инструмент, необходимый и для проектирования интерфейсов, и для создания API. С точки зрения интерфейсов мы проверяем все варианты использования — буквально задавая вопрос "а на каком экране происходит этот шаг сценария?" (конечно, нас интересуют шаги, где пользователь вводит данные или дает команду, и те, где система запрашивает пользователя, предлагает выбор, предоставляет информацию или оповещает пользователя о чем-то). Эта же диаграмма в какой-то мере повторяет диаграмму состояний — если у вас изменилось состояние ключевого объекта, то, скорее всего, это изменение инициировано действиями в интерфейсе (мы можем проверить полноту требований через проверку наличия требований/сценариев для всех переходов на диаграмме состояний). Тут же можно задать вопросы про обратные действия и возвраты — на диаграмме они будут видны особенно ясно: если у вас есть тупик, экран только с входящими переходами, это странно. Вы с него никуда не уйдете? В общем, если к каждому экрану приписать состав данных, которые выводится на экране и которые вводятся, а также основное действие пользователя на этом экране и второстепенные — будет сразу понятно, как визуально выстроить экран, и дизайнер скажет вам спасибо! Но эта же информация пригодится вам и для проектирования REST API! Именно REST, т.к. речь идёт о состоянии. Это распространенная ошибка — считать, что в REST нет состояния. Состояние клиента очень даже есть! (И это один из критериев, что вам подходит REST). Просто это состояние локализовано на клиенте, и не хранится на сервере (а только запрашиваются данные для смены состояния, Representational State Transfer). Вот ваша схема экранов и переходов как раз и является диаграммой возможных состояний клиента! И каждый переход — это вызов API. Нужно только к переходу дописать название эндпоинта, параметры и ответ. В таком виде диаграмма представлена в статье Майка Амундсена, про которую я уже писал, и которую, оказывается, давно перевел пользователь Andrei Gordienkov. Тут может возникнуть вопрос — а если изменения происходят на сервере, и должны быть переданы на клиент? Во-первых, как это нарисовать? (Ну, тут я обычно рисую вместо экрана звездочку, и стрелку от неё к нужному экрану, где эти изменения должны быть отображены — состояние клиента изменилось). Во-вторых, что это за вызов? Очевидно, что это уже не REST, а нечто другое — Long Polling, WebHook, WebSockets, GraphQL или gRPC в режиме подписки/стриминга. И всё, считайте, что эндпоинты API у вас уже готовы. Одновременно с дизайном.