Единственный источник правды для форм запросов / ответов API, включая схему JSON, типы TypeScript и валидаторы времени выполнения? - PullRequest
Новая
       13

Единственный источник правды для форм запросов / ответов API, включая схему JSON, типы TypeScript и валидаторы времени выполнения?

1 голос
/ 03 октября 2019

Я пишу типичный REST-сервис Node.js с конечными точками, которые получают входные данные JSON (как тела POST) и возвращают ответы JSON.

Мне нужны эти три вещи:

  1. JSON-схемы, определяющие формы тел запросов и тел ответов для моих конечных точек. (Или файлы Swagger, или что-нибудь подходящее для определения контракта для клиентов.)
  2. Типы / интерфейсы TypeScript, идеально отражающие схемы JSON.
  3. Функции проверки во время выполнения, которые я могу вызывать из своих обработчиков, чтобы гарантироватьобъект находится в правильной форме. (И после того, как входной объект был проверен, мой код TypeScript должен знать его интерфейс.)

Но я хочу один источник правды, чтобы эти три компонента не синхронизировались. Поэтому я хочу поддерживать только один из них (либо схемы JSON, либо типизацию TypeScript). Два других компонента должны быть сгенерированы из рукописного, и они не должны быть привязаны к контролю версий.

Мне кажется, что в настоящее время это должен быть довольно распространенный набор требований, но я не могу найтимного онлайн об этом. Возможно, я использую неправильные условия поиска, чтобы исследовать это. Существует ли какая-либо инфраструктура или традиционный шаблон, который решает эту задачу, то есть цель определения JSON API со строгой проверкой ввода, стандартизированной документации схемы и всеми удобствами полностью типизированных объектов в TypeScript?

1 Ответ

0 голосов
/ 03 октября 2019

Я предполагаю, что вы используете TypeScript в интерфейсе и бэкэнде.

Повторное использование пользовательского типа

Допустим, у нас есть репозиторий проекта, содержащий три основные папки: client, server и shared.

В shared у вас есть файл Types.ts, который содержит все ваши определения пользовательских типов. Например: 

export interface Person {
  name: string;
  age: number;
}

Теперь вы можете импортировать эти типы из любой подпапки, например .\client\src\components\SomeComponent.ts или с сервера .\server\src\api\SomeRoute.ts, с помощью: 

import { Person } from `..\..\..\..\shared\Types.ts`;

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

Генерация модели и документации JSON

Вы можете использовать ts-doc комментарии для документирования вашего API и ts-docs-gen для создания документа уценки.

Альтернативой будет typedoc . TypeDoc преобразует комментарии в исходном коде TypeScript в визуализированную документацию HTML или модель JSON. Вы можете настроить его так, чтобы учитывались только соответствующие файлы API.

Проверка во время выполнения

Что касается проверки ввода и вывода во время выполнения, вы можете написатьсобственная функция проверки для каждого типа, которая описана стереобустером в этой статье: язык-прагматика-io-validation-or-how-to-handle-jis-based-apis-in-static-typed-language . Или вы используете библиотеку, такую ​​как io-ts .

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

...