Базовый REST API, который можно использовать в качестве шаблона

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

Предпосылки

Прежде чем мы сможем начать кодирование, нам нужно установить версию NodeJS и NPM в нашей системе. Просто перейдите на официальный сайт по ссылке здесь и загрузите LTS (долгую поддержку) версию NodeJS. Это автоматически установит NPM вместе с ним в качестве менеджера пакетов.

Затем мы генерируем наш проект, создав папку с именем express_api_template и затем используя npm для инициализации проекта NodeJS.

$ mkdir express_api_template
$ cd express_api_template/
$ npm init

npm, init проведет вас через процесс настройки нового проекта. Обычно я использую настройки по умолчанию, за исключением точки входа. Мне нравится называть свой основной файл javascript server.js вместо стандартного index.js, а затем указывать автора. После этого нам нужно установить ExpressJS, добавив его в наш package.json. Для этого мы воспользуемся следующей командой.

$ npm install express

После завершения загрузки у нас должна быть папка node_modules и два файла package.json и package-lock.json.

Основы

Во-первых, нам нужно создать две новые папки и два новых файла, а также несколько новых зависимостей.

$ mkdir src
$ mkdir src/config
$ touch src/server.js src/config/config.env
$ npm install colors dotenv
$ npm install nodemon --save-dev

Разница между простой установкой и установкой - save-dev заключается в том, что при простой установке устанавливаются зависимости, необходимые для производства. - save-dev устанавливает зависимости, необходимые только для разработки. Но что мы на самом деле здесь установили?

  • colors: Этот пакет используется для придания консольных выходов красочности.
  • dotenv: Этот пакет загружает переменные среды из файлов .env в process.env. {variable_name}
  • nodemon: используется при разработке для перезагрузки вашего сервера каждый раз, когда вы сохраняете изменения.

После установки всего этого приложение не запустится. Для этого нам нужно сделать еще две вещи:

  1. Настройка нашего package.json для запуска server.js
  2. Реализация базового сервера Express в server.js

Начнем с настройки package.json следующим образом:

Мы определили две команды для использования с npm. Первый - для продакшена. Он устанавливает для переменной NODE_ENV значение production, а затем запускает сервер с помощью node-command. Второй предназначен для разработки и устанавливает для NODE_ENV значение development, а затем использует nodemon вместо node, чтобы мы могли использовать перезагрузку - функция сохранения, пока мы находимся в разработке.

ПРИМЕЧАНИЕ. Если вы используете Windows в качестве операционной системы, вам необходимо установить cross-env в качестве зависимости разработки, чтобы установить NODE_ENV.

$ npm install cross-env --save-dev

А затем отредактируйте два скрипта следующим образом:

"scripts": {
  "start": "cross-env NODE_ENV=production node src/server.js",
  "dev": "cross-env NODE_ENV=development nodemon src/server.js"
},

Чтобы все это сработало, нам нужно сначала завершить второй шаг. Нам нужно создать экспресс-приложение, а затем запустить его, используя порт, который мы определяем в нашем config.env. Добавьте порт в файл следующим образом:

PORT=5000

Теперь мы можем продолжить и начать с написания кода на server.js.

Это действительно просто, мы устанавливаем путь к нашему config.env, а затем инициализируем экспресс-приложение. После этого мы начинаем прослушивание порта, который только что установили в нашем config.env. Если мы запустим следующую команду:

$ npm run dev

Вы должны увидеть следующий результат:

[nodemon] 2.0.4
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,json
[nodemon] starting `node src/server.js`
Server up and running in development mode on port 5000

Теперь у нас есть действительно базовая настройка. Теперь давайте сделаем это шаблоном для REST-API в следующем разделе.

Отладка и безопасность

Наша цель - добавить еще несколько функций, таких как запись дополнительной информации в консоль для целей отладки и защиты API.

Для достижения вышеупомянутых целей нам нужно добавить еще несколько зависимостей.

$ npm install helmet cors
$ npm install morgan  --save-dev

Что делают эти три новые зависимости?

  • шлем:. Этот пакет представляет собой промежуточное ПО, которое помогает защитить ваш API, добавляя несколько заголовков HTTP.
  • cors: Это промежуточное ПО помогает нам внедрять CORS.
  • morgan: Это простой регистратор HTTP-запросов, он выводит входящие запросы на консоль узла.

После установки всех этих промежуточных программ нам нужно продолжить и добавить их в наше экспресс-приложение.

В первую очередь это новая проверка текущего NODE_ENV. Мы делаем это, потому что нам требуется morgan, только если мы находимся в режиме разработки. Если позже вы захотите добавить что-то вроде сценария заполнения данных для разрабатываемой базы данных, вы можете сделать это прямо сейчас.

После этой новой проверки мы подключаем промежуточное ПО к нашему экспресс-приложению. Для cors мы настраиваем происхождение. Это означает, что только запросы из этого источника могут взаимодействовать с нашим API. Например, созданное вами веб-приложение. Нам просто нужно добавить адрес в наш файл config.env следующим образом:

CORS_ORIGIN=http://localhost:8000

Порт может отличаться в зависимости от настроек разработки веб-приложений. Если это так, просто измените это.

Конечная точка и настраиваемое промежуточное ПО

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

$ mkdir src/routes src/middleware src/controllers
$ touch src/middleware/notFound.js src/middleware/errorHandler.js src/routes/post.js src/controllers/postsController.js

ПО промежуточного слоя

Начнем с создания нашей первой функции промежуточного программного обеспечения в notFound.js, которая обрабатывает запросы, не попадающие в конечную точку API, путем выдачи ошибки 404 Not Found.

Это просто функция, которая принимает запрос, ответ и следующее. Мы создаем ошибку и устанавливаем код состояния HTTP на 404 и передаем ошибку следующему.

Одно только это промежуточное ПО нам не поможет. Нам нужно что-то для обработки входящих ошибок, таких как Not Found Error, которую мы только что создали. Для этого мы реализуем нашу следующую функцию промежуточного программного обеспечения под названием errorHandler.

Если кто-то попадет на маршрут, у которого нет конечной точки, наш API вернет объект JSON, содержащий сообщение об ошибке, и, если мы работаем в разработке, он также вернет стек.

Последний шаг - добавить промежуточное ПО в наш server.js.

// After the other require statements:
const notFound = require('./middleware/notFound');
const errorHandler = require('./middleware/errorHandler');
// Custom middleware here
app.use(notFound);
app.use(errorHandler);

Маршрутизатор

Мы приближаемся к финишу. Осталось всего два шага. Сейчас мы сосредоточены на одном из них: добавлении маршрута. Для этого нам нужно спросить себя, какой маршрут мы хотим добавить. В этой статье я хочу добавить два разных маршрута GET: один получает все сообщения, а другой - статью по его идентификатору. Давайте начнем с реализации нашего маршрута в файле post.js.

Экспресс-маршрутизатор позволяет нам определять маршруты на основе HTTP-глаголов, таких как GET, POST и т. Д. Нам просто нужно добавить наши методы контроллера, которые мы реализуем позже, в HTTP-глагол и маршрутизатор творит свое чудо. В server.js нам нужно добавить маршрутизатор следующим образом:

// Between helmet and custom middleware:
// All routes here
app.use('/api/posts', require('./routes/post'));

Это вызовет ошибку, поскольку мы еще не реализовали функции контроллера.

Контроллеры

Теперь мы на последнем этапе нашего шаблона REST-API. Контроллер функционирует. Нам нужно будет создать два из них: getPosts и getPostById. Давайте приступим к работе, реализовав эти методы в postsController.js.

Вверху файла у нас есть статические данные. После этого экспортируем две функции. Первый, getPosts, возвращает весь список статических данных. Второй метод, getPostById, возвращает один объект из массива, если идентификатор совпадает, или возвращает ошибку, если ни одно сообщение не соответствует идентификатору, указанному в запросе.

Последнее, что нам нужно сделать, это включить JSON для нашего приложения, добавив еще одно промежуточное ПО.

// Right below helmet:
app.use(express.json());

После добавления наш server.js должен выглядеть так:

Заключение

Теперь вы можете ввести http: // localhost: 5000 / api / posts или http: // localhost: 5000 / api / posts / 2, чтобы получить доступ к API (пока он работает). Надеюсь, вам понравилось это краткое руководство по настройке API-интерфейса экспресс-обработки шаблонов. Вы можете развить это, добавив базу данных, аутентификацию и авторизацию, дополнительные конечные точки и так далее. Дайте мне знать, что вы думаете об этом, и если вы создадите что-то на основе этого шаблона. Весь проект можно найти на моем GitHub.