⌛ 7 мин.

В рамках серии статей «Fast development», мы избрали Loopback в качестве самого перспективного ORM фреймворка. Я решил, что Loopback достоин отдельного тематического раздела и будет вынесен за рамки «Fast development». В последнюю же, мы опубликуем конечный результат наших исследований. Статья ниже — это всего лишь локализованный, слегка дополненный и пройденный мной кусок документации. Есть вероятность, что именно Вам лучше пройти к оригиналу.

Обзор

Из этого туториала Вы узнаете, как создать базовый API для списка задач с помощью LoopBack 4. Вы узнаете, как создать API REST всего за 5 шагов.

Предварительно

Установите Node.js (версия 8.9 или выше), если он еще не установлен на вашем компьютере.

Установка LoopBack 4 CLI

CLI LoopBack 4 — это интерфейс командной строки, который создает проект или расширение путем генерации базового кода. Интерфейс командной строки предоставляет самый быстрый способ начать работу с проектом LoopBack 4, который соответствует рекомендациям.

npm i -g @loopback/cli

Создаём строительные леса своего приложения

Набор инструментов LoopBack 4 CLI содержит шаблоны, которые генерируют целые приложения, а также артефакты (например, контроллеры, модели и репозитории) для существующих приложений.

Чтобы сгенерировать приложение с помощью инструментария, выполните команду lb4 app и заполните экранные подсказки:

$ lb4 app
? Project name: todo-list
? Project description: A todo list API made with LoopBack 4.
? Project root directory: (todo-list)
? Application class name: (TodoListApplication)
? Select features to enable in the project:
❯◉ Enable tslint
 ◉ Enable prettier
 ◉ Enable mocha
 ◉ Enable loopbackBuild
 ◉ Enable vscode
 ◉ Enable repositories
 ◉ Enable services
 # npm will install dependencies now
 Application todo-list was created in todo-list.

Для этого примера, когда будет предложено указать опции для включения определенных функций проекта (loopback’s build, tslint, mocha и т. д.), Оставьте их все включенными.

Структура

После того как ваше приложение будет сгенерировано, у вас будет структура папок, подобная следующей:

src/
  controllers/
    home-page.controller.ts
    README.md
    ping.controller.ts
  datasources/
    README.md
  models/
    README.md
  repositories/
    README.md
  application.ts
  index.ts
  sequence.ts
test/
  README.md
  mocha.opts
  acceptance/
    home-page.controller.acceptance.ts
    ping.controller.acceptance.ts
node_modules/
  ***
LICENSE
README.md
index.js
index.ts
package.json
tsconfig.json
tslint.build.json
tslint.json

Файл	Назначение
index.ts	Позволяет импортировать содержимое папки src (для использования в другом месте)
index.js	Файл верхнего уровня, соединяющий компоненты приложения.
package.json	Манифест пакета вашего приложения. Смотрите package.json для деталей.
tsconfig.json	Конфигурация проекта TypeScript. Смотрите tsconfig.json для деталей.
tslint.json	Конфигурация TSLint
tslint.build.json	Конфигурация TSLint (только сборка)
README.md	Markdown-based README, созданный для вашего приложения.
LICENSE	Копия лицензии MIT. Если вы не хотите использовать эту лицензию, удалите этот файл.
src/application.ts	Класс приложения, который расширяет RestApplication по умолчанию. Это корень вашего приложения, и именно там ваше приложение будет настроено. Он также расширяет RepositoryMixin который определяет источник данных.
src/index.ts	Отправная точка вашего микросервиса. Этот файл создает экземпляр вашего приложения, запускает загрузчик, а затем пытается запустить экземпляр RestServerсвязанный с приложением.
src/sequence.ts	Расширение класса Sequence, используемое для определения набора действий, выполняемых во время запроса / ответа REST.
src/controllers/README.md	Предоставляет информацию о каталоге контроллеров, о том, как создавать новые контроллеры и где найти дополнительную информацию.
src/controllers/ping.controller.ts	Основной контроллер, который отвечает на запросы GET в /ping .
src/datasources/README.md	Предоставляет информацию о каталоге источников данных, о том, как создавать новые источники данных и где можно найти дополнительную информацию.
src/models/README.md	Предоставляет информацию о каталоге моделей, о том, как создавать новые модели и где найти дополнительную информацию.
src/repositories/README.md	Предоставляет информацию о каталоге репозиториев, о том, как создавать новые репозитории и где можно найти дополнительную информацию.
test/README.md	Пожалуйста, поместите ваши тесты в эту папку.
test/mocha.opts	Конфигурация Mocha для запуска тестов вашего приложения.
test/acceptance/ping.controller.acceptance.ts	Пример теста с контроллером ping в src/controllers .

Добавление модели Todo

Модель

Теперь мы можем начать работу над представлением наших данных для использования с LoopBack 4. Для этого мы собираемся создать модель Todo, которая может представлять экземпляры задачи для нашего списка Todo. Модель Todo будет служить как объектом передачи данных (также известным как DTO) для представления входящих экземпляров Todo по запросам, так и нашей структурой данных для использования с loopback-datasource-juggler.

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

Модели используются для обмена данными в приложении или между различными системами.

Для получения дополнительной информации о Моделях и как они используются в LoopBack, см. Модели.

Создание модели Todo

Список задач содержит отслеживаемые задачи. Для того, что бы это было удобно, необходимо добавить заголовок, описание и, наконец, предоставить возможность отслеживания того, завершены ли задачи или нет.

Модель Todo имеет следующие свойства:

• id: уникальный идентификатор
• title: заголовок
• desc: описание, которое детализирует конкретную задачу, которая должна быть выполнена
• isComplete: логический флаг того, выполнили ли мы задачу или нет

Для создания модели мы можем воспользоваться командой lb4 model. В процессе добавления свойств модели, необходимо ответить на задаваемые вопросы. Для завершения операции создания, необходимо оставить имя свойства пустым и нажать Enter, после чего будет сгенерирована наша модель.

lb4 model
? Model class name: todo
? Please select the model base class: Entity

Let's add a property to Todo
Enter an empty property name when done

? Enter the property name: id
? Property type: number
? Is id the ID property? Yes
? Is it required?: No
? Default value [leave blank for none]:

Let's add another property to Todo
Enter an empty property name when done

? Enter the property name: title
? Property type: string
? Is it required?: Yes
? Default value [leave blank for none]:

Let's add another property to Todo
Enter an empty property name when done

? Enter the property name: desc
? Property type: string
? Is it required?: No
? Default value [leave blank for none]:

Let's add another property to Todo
Enter an empty property name when done

? Enter the property name: isComplete
? Property type: boolean
? Is it required?: No
? Default value [leave blank for none]:

Let's add another property to Todo
Enter an empty property name when done

? Enter the property name:

   create src/models/todo.model.ts
   update src/models/index.ts

Model todo was created in src/models/

Теперь, когда у нас есть наша модель, пришло время добавить источник данных, чтобы мы могли выполнять реальные операции CRUD!

Добавление источника данных

Источники данных

Источники данных — это способ подключения LoopBack к различным источникам данных, таким как базы данных, API, очереди сообщений и многое другое. Источник данных в LoopBack 4 — это именованная конфигурация для экземпляра Connector, который представляет данные во внешней системе. Connector используется legacy-juggler-bridge для операций с данными в LoopBack 4 репозиториях.

В LoopBack 4 источники данных могут быть представлены как объекты со строгой типизацией и свободно доступны для внедрения в приложении. Как правило, в LoopBack 4 источники данных используются совместно с репозиториями для обеспечения доступа к данным.

Для получения дополнительной информации об источниках данных в LoopBack см. DataSources.

Поскольку нашему API Todo необходимо будет сохранять экземпляры элементов Todo, нам потребуется создать определение источника данных, чтобы сделать это возможным.

Создание источника данных

Из папки проекта мы запустим команду lb4 datasource, чтобы создать источник данных. Для целей данного руководства мы будем использовать memory connector, поставляемый с Juggler.

lb4 datasource
? Datasource name: db
? Select the connector for db: In-memory db (supported by StrongLoop)
? window.localStorage key to use for persistence (browser only):
? Full path to file for persistence (server only): ./data/db.json

  create src/datasources/db.datasource.json
  create src/datasources/db.datasource.ts
  update src/datasources/index.ts

Datasource db was created in src/datasources/

Создайте папку данных в корне приложения и добавьте новый файл с именем db.json и пример базы данных.

data/db.json

{
  "ids": {
    "Todo": 5
  },
  "models": {
    "Todo": {
      "1": "{\"title\":\"Take over the galaxy\",\"desc\":\"MWAHAHAHAHAHAHAHAHAHAHAHAHAMWAHAHAHAHAHAHAHAHAHAHAHAHA\",\"id\":1}",
      "2": "{\"title\":\"destroy alderaan\",\"desc\":\"Make sure there are no survivors left!\",\"id\":2}",
      "3": "{\"title\":\"terrorize senate\",\"desc\":\"Tell them they're getting a budget cut.\",\"id\":3}",
      "4": "{\"title\":\"crush rebel scum\",\"desc\":\"Every.Last.One.\",\"id\":4}"
    }
  }
}

Добавление репозитория

Репозитории

Шаблон репозитория является одним из фундаментальных отличий между LoopBack 3 и 4. В LoopBack 3 вы должны использовать сами определения класса модели для выполнения операций CRUD. В LoopBack 4 слой, ответственный за это, был отделен от определения самой модели на уровне хранилища.

Репозиторий представляет собой специализированный интерфейс службы, который обеспечивает операции доступа к данным со строгой типизацией (например, CRUD) модели предметной области по отношению к базовой базе данных или сервису.

Для получения дополнительной информации о репозиториях см. Репозитории.

Создаём репозиторий

В папке проекта запустите команду lb4 repository, чтобы создать репозиторий для вашей модели Todo с использованием источника данных db из предыдущего шага. Источник данных db обнаруживается по имени класса DbDataSource из списка доступных источников данных.

lb4 repository
? Please select the datasource DbDatasource
? Select the model(s) you want to generate a repository Todo
   create src/repositories/todo.repository.ts
   update src/repositories/index.ts

Repository Todo was created in src/repositories/

Файл src/repositories/index.ts делает централизованный экспорт, а также облегчает импорт.

Вновь созданный класс todo.repository.ts имеет необходимые соединения для выполнения операций CRUD нашей модели Todo. Он использует определение модели Todo и конфигурацию источника данных «db» и извлекает источник данных с помощью внедрения зависимостей.

Теперь мы можем выставить Todo API через контроллер.

Добавление контроллера

Контроллеры

В LoopBack 4 контроллеры обрабатывают жизненный цикл запрос-ответ для вашего API. Каждая функция на контроллере может быть адресована индивидуально для обработки входящего запроса (например, запроса POST к / todos), для выполнения бизнес-логики и для возврата ответа.

Контроллер — это класс, который реализует операции, определенные API-интерфейсом приложения. Он реализует бизнес-логику приложения и выступает в качестве моста между HTTP / REST API и моделями доменов / баз данных.

В этом отношении контроллеры — это регионы, в которых будет жить большая часть вашей бизнес-логики!

Для получения дополнительной информации о контроллерах см. Контроллеры.

Создаём контроллер

Вы можете создать REST-контроллер с помощью CLI следующим образом:

lb4 controller
? Controller class name: todo
? What kind of controller would you like to generate? REST Controller with CRUD functions
? What is the name of the model to use with this CRUD repository? Todo
? What is the name of your CRUD repository? TodoRepository
? What is the type of your ID? number
? What is the base HTTP path name of the CRUD operations? /todos
   create src/controllers/todo.controller.ts
   update src/controllers/index.ts

Controller todo was created in src/controllers/

Давайте рассмотрим TodoController, расположенный в src/controllers/todo.controller.ts. Декоратор @repository извлекает и внедряет экземпляр TodoRepository всякий раз, когда обрабатывается входящий запрос. Жизненный цикл объектов контроллера зависит от запроса, что означает, что для каждого запроса создается новый экземпляр контроллера. В результате мы хотим внедрить наш TodoRepository, поскольку создание этих экземпляров является более сложным и дорогим, чем создание новых экземпляров контроллера.

• @post('/todos') создает метаданные для @loopback/rest, чтобы он мог перенаправлять запросы к этой функции при совпадении пути и глагола.
• @requestBody() связывает схему OpenAPI для Todo с телом запроса, чтобы LoopBack мог проверять формат входящего запроса.

Некоторые дополнительные вещи, которые следует отметить в этом примере:

• Такие маршруты, как @get('/todos/{id}'), могут быть соединены с декораторами @param.path для вставки этих значений во время запроса в функцию-обработчик.
• Декоратор @param в LoopBack также содержит пространство имен, заполненное другими «под-декораторами», такими как @param.path, @param.query и @param.header, которые позволяют задавать метаданные для частей запроса REST.
• @param.path и @param.query в LoopBack также предоставляют под-декораторы для указания типа определенных примитивов значения, таких как @param.path.number('id').

Собираем все вместе

Теперь у нас есть все наши артефакты, и все они автоматически связаны с нашим Приложением, так что система Dependency injection (вставка зависимостей) в LoopBack может связать все это вместе для нас!

Загрузочный модуль LoopBack автоматически обнаружит наши контроллеры, репозитории, источники данных и другие артефакты и внедрит их в наше приложение для использования.

Давайте попробуем наше приложение! Во-первых, вы хотели бы запустить его.

$ npm start
Server is running at http://[::1]:3000

/openapi.json — описание API согласно спецификации OpenAPI

/explorer — инструмент для просмотра и тестирования API

Вот несколько запросов, которые вы можете попробовать:

• POST /todos с телом{ "title": "get the milk" }
• GET /todos/{id} используя идентификатор, который вы получили от вашего POST, и посмотрите, вернете ли вы свой объект Todo.
• PATCH /todos/{id}, используя тот же идентификатор, с телом{ "desc": "need milk for cereal" }

Это оно! Вы только что создали свое первое приложение LoopBack 4!

У меня сложилось достаточно приятное ощущение от использования данного ORM фреймворка. Особенно мне нравится архитектурный подход именно в Loopback 4. Не знаю зачем, но вдруг пригодится, вот код.