# Введение

# Обычная установка

0) Сначала сгенерируйте package.json, выполнив npm init или yarn init.

1) Далее установите пакет, используя npm i dc-api-core --save или yarn add dc-api-core. Во время установки будет предложено глобально установить CLI, если отсутствует, и настроить проект в текущей директории (подробнее в Установке через CLI).

1.1) Если во время установки Вы настроили проект при помощи CLI, то Вы уже можете запустить сервер,

1.2) Иначе Вам нужно вручную выполнить действия ниже.

2) Заполните scripts в package.json:

"scripts": {
    "start": "dc-api-core",
    "dev": "dc-api-core --dev"
}

3) Создайте необходимые директории и файлы, указанные в разделе Структура.

# Установка через CLI

Если у Вас есть глобально установленный CLI, то Вы можете перейти в директорию, в которой будет настроен сервер, и выполнить dc-api-cli init или dc-api-cli init <path> (где <path> - путь до нужной директории).

Пример хода установки:

$ dc-api-cli init Рабочая директория: /path/to/backend Введите порт: 8080 Плагины: (используйте стрелочки для перемещения, пробел для выбора и enter для подтверждения) x dc-api-mongo Выберите провайдера сессии: (используйте стрелочки для перемещения и enter для подтверждения) Без сессии ➔ dc-api-mongo

# Структура

После установки dc-api-core текущая директория будет выглядеть, как показано ниже:

controllers
<ControllerName>.js
models
<driver-name>
<ModelName>.js
config.json
startup.js
Директория, содержащая контролеры
Контроллер API для обработки запросов
Содержит модели данных для работы с БД Опционально
Идентификатор драйвера БД
Модель базы данных
Конфигурационный файл
Скрипт, выполняемый до запуска API сервера Опционально

Это основная структура, которую использует dc-api-core. Вы также можете создавать здесь нужные Вам файлы и директории.

# Конфигурационный файл

config.json содержит параметры, используемые dc-api-core, но Вы можете хранить здесь и свои данные.

{
    // Порт, на котором будет запущен API сервер
    "port": 8081,
    // Эта строка нам понадобится в будущем
    "auth_pass": "security"
}

См. также: Доступные значения в конфигурационном файле

# Контроллеры

Контроллер - это класс, содержащий методы, обрабатывающие запросы приходящие на сервер. Отсюда методы такого класса называются в основном HTTP обработчиками. Если Вы хотите работать с WebSockets, то позже прочтите о Socket контроллере.

Как было показано выше, контроллеры находятся в директории controllers. Название файла контроллера должно быть в PascalCase и совпадать с названием экспортируемого класса.

По-умолчанию, URL запроса обрабатывается как /контроллер/обработчик.

Изначально CLI создаёт контроллер Info с обработчиком status:

// Импортируем `package.json` установленного пакета `dc-api-core`
const pkg = require('dc-api-core/package');

// Экспортируем класс контроллера
module.exports = class Info {
    // Объявляем метод-обработчик, который будет принимать запросы
    // по URL http://localhost:8081/Info/status
    status () {
        // Отсылает в ответ объект с установленной версией `dc-api-core`
        // и текущем временем на сервере
        this.send({ version: pkg.version, time: new Date().toLocaleString() });
    }
}

Если вы запустите API сервер и откроете в браузере http://localhost:8081/Info/status, то Вы увидите ответ сервера, похожий на пример ниже:

{
    "version": "0.2.3-9",
    "time": "05.07.2020, 18:21:32"
}

Теперь давайте сделаем свой контроллер Test. Для этого создадим файл controllers/Test.js со следующим содержимым:

// Получаем данные конфигурационного файла
const config = require('dc-api-core/config');

class Test {
    // Данный мектод вызывается перед вызовом обработчиков
    onLoad () {
        // Сравниваем GET параметр `token` с полем `auth_pass`, указанном
        // в конфигурационном файле ранее
        if (this.query.token != config.auth_pass) {
            // Если данный метод возвращает значение `true`,
            // то сервер прекратит обработку этого запроса
            return true;
        }
    }

    hello () {
        this.send('Привет, привет!');
    }
}

module.exports = Test;

Теперь если перейти по URL http://localhost:8081/Test/hello или http://localhost:8081/Test/hello?token=incorrect, то Вы не получите ответа, а http://localhost:8081/Test/hello?token=security вернёт Вам "Привет, привет!".

# Запуск API сервера

Сервер может быть запущен в двух режимах: обычном и режиме разработки.

Режим разработки:

Запуск: yarn dev или npm run dev.

В режиме разработки API сервер будет перезапущен поле изменения любого файла в его директории. Также будет использована конфигурация config.dev как основная.

См. также: dev ветка в конфигурационном файле

Обычный режим:

Запуск: yarn start или npm start.

В данном режиме будет запущен API сервер для "боевого" окружения.