Наступает момент, когда вы успешно проводите рефакторинг своего бэкенда, а затем достигаете метода конечной точки. Внезапно на вас накатывает волна беспокойства. Эта конечная точка вообще используется? Все ли эти поля в этом DTO используются во внешнем интерфейсе? Где сломается интерфейс, когда я переименую это поле? Со всеми этими вопросами нет ничего необычного в том, чтобы просто сдаться и прекратить дальнейший рефакторинг.

Не теряйте надежду. Существуют способы проверки типов вашего клиентского кода по сравнению с вашим серверным API. Я покажу вам простой способ, который полностью не зависит от серверного стека. Он основан на инструментах, построенных на основе спецификации OpenAPI (ранее — спецификации Swagger).

Общая идея заключается в следующем: сгенерируйте клиент Typescript из описания OpenAPI конечных точек сервера. Вам не нужно самостоятельно писать спецификацию API. Есть плагины, которые генерируют его за вас для любого популярного серверного стека .

Перейдем к конкретному примеру.
Я собираюсь использовать Spring Boot для серверной части. Для фронтенда я выбрал свой любимый React .

Нам нужно начать с бэкенда. Для начала вам нужно добавить эти зависимости в ваш проект Spring Boot pom.xml:

и настройте его, поместив эту конфигурацию в свой корневой пакет

После этого станет доступна новая конечная точка — /v2/api-docs. Он обслуживает этот огромный JSON, который описывает все ваши конечные точки. Он содержит всю информацию, необходимую для создания полного, полностью типизированного клиента.

Инструменты для этого предоставляются проектом openapi-generator . Есть варианты запустить его напрямую , через Docker или пакет npm . Если у вас уже установлена ​​JRE, то последний вариант будет самым простым:

Несколько заметок здесь. Мы используем generateзадачу из @openapitools/openapi-generator-cliпакета. С помощью -iмы определяем, откуда взять спецификацию API, и с помощью -gмы выбираем typescript-fetchшаблон для нашего сгенерированного клиента из всех доступных (включая, конечно, один для Angular). Последняя опция ( -o) указывает выходной каталог для сгенерированных файлов.

Давайте теперь возьмем этот простой контроллер Spring:

Используемые здесь проверка javax и аннотация swagger влияют на сгенерированную спецификацию API. Взгляните на соответствующий фрагмент сгенерированного JSON:

Из него получается следующий машинописный текст:

Как видите, отмеченные поля @NotNullгенерируются как обязательные поля (1). Текст «Фамилия пользователя» из @ApiModelPropertyраздела используется в дополнительной документации пункта lastName(2). Здесь следует отметить еще одну вещь: имя перечисления Typescript создается на основе имени поля ( User.roles), а не имени перечисления из Java. Это связано с тем, что его имя нигде не включено в JSON по адресу /v2/api-docs.

Помимо сгенерированной модели, существуют также методы, соответствующие всем доступным конечным точкам. В этом случае есть UserResourceApiкласс с allUsersUsingGETметодом.

Если вы внимательно посмотрите на сгенерированное имя метода, вы заметите, что оно получено непосредственно из имени метода Java. Это немного нелогично. Изменения путей к конечным точкам не требуют изменения кода на стороне клиента. По- видимому , внутренние изменения в именах серверных методов, реализующих конечные точки, вносят критические изменения в сгенерированный клиент.

Убрав все это, давайте посмотрим, как выглядит использование сгенерированного клиента:

Сначала установите базовый URL-адрес для всех вызовов API (1), затем создайте оболочку API для ресурса (2). Наконец, вызовите определенные конечные точки (3), используя полностью типизированные методы.

Вот и все. Теперь у вас есть способ убедиться, что ваш клиентский код полностью совместим с серверным API.

Резюме

С помощью этой настройки вы можете использовать компилятор Typescript, чтобы убедиться, что вы вызываете правильные URL-адреса конечных точек API, передаете правильные параметры и правильно интерпретируете ответ. Это действительно может повысить доверие к вашей кодовой базе.

Эта простая конфигурация хорошо подойдет для небольшого проекта, но ее недостаточно для больших команд. Окончательным решением было бы сгенерировать и опубликовать пакет npm для машинописного клиента на сервере CI/CD как часть создания бэкенда. Но это заслуживает отдельного поста в блоге. Тем не менее, вы всегда можете начать с этого простого решения, а затем переключиться на более продвинутый конвейер.