SavePearlHarbor

Node.js: разрабатываем сервер для тестирования API

—

от автора

admin

Привет, друзья!

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

Основной функционал нашего приложения будет следующим:

  • админка с возможностью добавления данных (далее — проекты) путем их набора (ввода) или копирования/вставки, либо путем загрузки файла;
  • сохранение проектов на сервере;
  • безопасная запись, чтение и удаление файлов на любом уровне вложенности;
  • получение названий существующих проектов и их отображение в админке;
  • возможность редактирования и удаления проектов;
  • унифицированная обработка GET, POST, PUT и DELETE запросов к любому существующему проекту, включая GET-запросы, содержащие параметры и строки запроса;
  • обработка специальных параметров строки запроса sort, order, limit и offset;
  • и многое другое.

Наша админка будет выглядеть так:

Для быстрой стилизации приложения будет использоваться Bootstrap.

Исходный код проекта.

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

При разработке приложения мы будет придерживаться 2 важных условий:

  • формат данных — JSON;
  • основная форма данных — массив.

Обратите внимание: статья рассчитана, преимущественно, на начинающих разработчиков, хотя, смею надеяться, что и опытные найдут в ней что-нибудь интересное для себя.

Вы готовы? Тогда вперед.

Подготовка проекта

Создаем директорию для проекта, переходим в нее, инициализируем проект и устанавливаем зависимости:

mkdir mock-api cd !$  yarn init -y # or npm init -y  yarn add express multer nodemon open-cli very-simple-fetch # or npm i ...

Зависимости:

  • express — Node.js-фреймворк для разработки сервера
  • multer — обертка над busboy, утилита для обработки данных в формате multipart/form-data, часто используемая для сохранения файлов
  • nodemon — утилита для запуска сервера для разработки
  • open-cli — утилита для автоматического открытия вкладки браузера по указанному адресу
  • very-simple-fetch — обертка над Fetch API, упрощающая работу с названным интерфейсом

Открываем package.json, определяем в нем основной файл сервера (index.js) как модуль и команду для запуска сервера для разработки:

{  "type": "module",  "scripts": {    "dev": "open-cli http://localhost:5000 && nodemon index.js"  } }

Команда dev указывает открыть вкладку браузера по адресу http://localhost:5000 (адрес, на котором будет запущен сервер) и выполнить код в файле index.js (запустить сервер для разработки).

Структура нашего проекта будет следующей:

  • projects — директория для проектов
  • public — директория со статическими файлами для админки
  • routes — директория для роутов
  • index.js — основной файл сервера
  • utils.js — вспомогательные функции

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

Сервер, маршрутизатор для проектов и утилиты

В файле index.js мы делаем следующее:

  • импортируем express, полный путь к текущей (рабочей) директории и роуты для проектов;
  • создаем экземпляр Express-приложения;
  • добавляем посредников (промежуточных обработчиков): для обслуживания статических файлов, для разбора (парсинга) данных в JSON, для декодирования URL;
  • добавляем роут для получения файлов из директории node_modules;
  • добавляем роуты для проектов;
  • добавляем обработчик ошибок;
  • определяем порт и запускаем сервер.

import express from 'express' import { __dirname } from './utils.js' import projectRoutes from './routes/project.routes.js'  const app = express()  app.use(express.static('public')) app.use(express.json()) app.use(express.urlencoded({ extended: true }))  app.get('/node_modules/*', (req, res) => {  res.sendFile(`${__dirname}/${req.url}`) })  app.use('/project', projectRoutes)  // обратите внимание: обработчик ошибок должен быть последним в цепочке посредников app.use((err, req, res, next) => {  console.error(err.message || err)  res.sendStatus(err.status || 500) })  const PORT = process.env.PORT || 5000 app.listen(PORT, () => {  console.log(`? -> ${PORT}`) })

Подумаем о том, какие роуты нам нужны для работы с проектами. Как насчет следующих запросов:

  • GET — получение названий всех существующих проектов
  • GET — получение проекта по названию
  • POST — создание проекта
  • POST — загрузка проекта
  • DELETE — удаление проекта

Мы также могли бы определить отдельный роут для обновления проекта через PUT-запрос, но в этом нет особого смысла — проще перезаписать существующий проект новым.

В файле routes/project.routes.js мы делаем следующее:

  • импортируем роутер из express и вспомогательные функции из utils.js;
  • экспортируем новый экземпляр роутера;
  • определяем обработчики для каждого из указанных выше запроса.

import { Router } from 'express' // мы подробно рассмотрим каждую из этих утилит далее import {  getFileNames,  createFile,  readFile,  removeFile,  uploadFile } from '../utils.js'  export default Router()

Далее цепочкой (один за другим) идут обработчики.

Получение проекта по названию:

 .get('/', async (req, res, next) => {    // извлекаем название проекта из строки запроса - `?project_name=todos`    const { project_name } = req.query     // если `URL` не содержит строки запроса, значит,    // это запрос на получение названий всех проектов    // передаем управление следующему обработчику    if (!project_name) return next()     try {      // получаем проект      const project = await readFile(project_name)       // и возвращаем его      res.status(200).json(project)    } catch (e) {      // передаем ошибку обработчику ошибок      next(e)    }  })

Получение названий всех проектов:

 .get('/', async (req, res, next) => {    try {      // получаем названия проектов      const projects = (await getFileNames()) || []       // и возвращаем их      res.status(200).json(projects)    } catch (e) {      next(e)    }  })

Создание проекта:

 .post('/create', async (req, res, next) => {    // извлекаем название проекта и данные для него из тела запроса    const { project_name, project_data } = req.body     try {      // создаем проект      await createFile(project_data, project_name)       // сообщаем об успешном создании проекта      res.status(201).json({ message: `Project "${project_name}" created` })    } catch (e) {      next(e)    }  })

Загрузка проекта:

 .post(    '/upload',    // `multer`; обратите внимание на передаваемый ему аргумент -    // название поля, содержащего данные, в теле запроса должно соответствовать этому значению    uploadFile.single('project_data_upload'),    (req, res, next) => {      // сообщаем об успешной загрузке проекта      res.status(201).json({        message: `Project "${req.body.project_name}" uploaded`      })    }  )

Удаление проекта:

 .delete('/', async (req, res, next) => {    // извлекаем название проекта из строки запроса    const { project_name } = req.query     try {      // удаляем проект      await removeFile(project_name)       // сообщаем об успехе      res.status(201).json({ message: `Project "${project_name}" removed` })    } catch (e) {      next(e)    }  })

Ошибка, возникшая в процессе выполнения любой операции, будет передана в обработчик, определенный в index.js — централизованная обработка ошибок. Нечто похожее мы реализуем и на клиенте.

Вспомогательные функции, определенные в файле utils.js — пожалуй, самая интересная и полезная часть туториала. Я постарался сделать так, чтобы эти функции были максимально универсальными с той целью, чтобы вы могли использовать их в своих проектах без существенных изменений.

Начнем с импорта модулей, определения полного (абсолютного) пути к текущей директории и директории для проектов (корневой директории), а также с создания 2 небольших утилит:

  • для определения того, что файла или директории не существует по сообщению об ошибке;
  • для уменьшения пути на 1 «единицу».

import { dirname } from 'path' import { fileURLToPath } from 'url' import { promises as fs } from 'fs' import multer from 'multer'  // полный путь к текущей директории export const __dirname = dirname(fileURLToPath(import.meta.url)) // путь к директории с проектами const ROOT_PATH = `${__dirname}/projects`  // утилита для определения несуществующего файла const notExist = (e) => e.code === 'ENOENT' // утилита для уменьшения пути на единицу // например, путь `path/to/file` после вызова этой функции // будет иметь значение `path/to` const truncPath = (p) => p.split('/').slice(0, -1).join('/')

Утилита для создания файла:

// функция принимает 3 параметра: данные, путь и расширение (по умолчанию `json`) export async function createFile(fileData, filePath, fileExt = 'json') {  // формируем полный путь к файлу  const fileName = `${ROOT_PATH}/${filePath}.${fileExt}`   try {    // пробуем создать файл    // при отсутствии директории для файла, например, когда полным путем    // файла является `.../data/todos.json`, выбрасывается исключение    if (fileExt === 'json') {      await fs.writeFile(fileName, JSON.stringify(fileData, null, 2))    } else {      await fs.writeFile(fileName, fileData)    }  } catch (err) {    // если ошибка связана с отсутствующей директорией    if (notExist(err)) {      // создаем ее рекурсивно (несколько уровней вложенности)      await fs.mkdir(truncPath(`${ROOT_PATH}/${filePath}`), {        recursive: true      })      // и снова вызываем `createFile` с теми же параметрами - рекурсия      return createFile(fileData, filePath, fileExt)    }    // если ошибка не связана с отсутствующей директорией    // это позволяет подняться из утилиты в роут и передать ошибку в централизованный обработчик    throw err  } }

Утилита для чтения файла:

// функция принимает путь и расширение export async function readFile(filePath, fileExt = 'json') {  // полный путь  const fileName = `${ROOT_PATH}/${filePath}.${fileExt}`   // переменная для обработчика файла  let fileHandler = null  try {    // `fs.open()` возвращает обработчик файла при наличии файла    // или выбрасывает исключение при отсутствии файла    // это является рекомендуемым способом определения наличия файла    fileHandler = await fs.open(fileName)     // читаем содержимое файла    const fileContent = await fileHandler.readFile('utf-8')     // и возвращаем его    return fileExt === 'json' ? JSON.parse(fileContent) : fileContent  } catch (err) {    // если файл отсутствует    // вы поймете почему мы используем именно такую сигнатуру ошибки,    // когда мы перейдем к роутам для `API`    if (notExist(err)) {      throw { status: 404, message: 'Not found' }    }    // если возникла другая ошибка    throw err  } finally {    // закрываем обработчик файла    fileHandler?.close()  } }

Утилита для удаления файла:

// функция принимает путь и расширение export async function removeFile(filePath, fileExt = 'json') {  // полный путь  const fileName = `${ROOT_PATH}/${filePath}.${fileExt}`   try {    // пробуем удалить файл    await fs.unlink(fileName)     // нам также необходимо удалить директорию, если таковая имеется    // мы передаем утилите путь, сокращенный на единицу, т.е. без учета пути файла    await removeDir(truncPath(`${ROOT_PATH}/${filePath}`))  } catch (err) {    // если файл отсутствует    if (notExist(err)) {      throw { status: 404, message: 'Not found' }    }    // если возникла другая ошибка    throw err  } }

Утилита для удаления директории:

// утилита принимает путь к удаляемой директории и путь к корневой директории, // который по умолчанию имеет значение директории с проектами async function removeDir(dirPath, rootPath = ROOT_PATH) {  // останавливаемся, если достигли корневой директории  if (dirPath === rootPath) return   // определяем является ли директория пустой  // длина ее содержимого должна равняться 0  const isEmpty = (await fs.readdir(dirPath)).length < 1   // если директория является пустой  if (isEmpty) {    // удаляем ее    await fs.rmdir(dirPath)     // и... рекурсия    // на каждой итерации мы сокращаем путь на единицу,    // пока не поднимемся до корневой директории    removeDir(truncPath(dirPath), rootPath)  } }

Еще одна рекурсивная функции (обещаю, что последняя) для получения названий всех существующих проектов:

// функция принимает путь к корневой директории export async function getFileNames(path = ROOT_PATH) {  // переменная для названий проектов  let fileNames = []   try {    // читаем содержимое директории    const files = await fs.readdir(path)     // если в директории находится только один файл    // возвращаем массив с названиями проектов    if (files.length < 1) return fileNames     // иначе перебираем файлы    for (let file of files) {      // формируем путь каждого файла      file = `${path}/${file}`       // определяем, является ли файл директорией      const isDir = (await fs.stat(file)).isDirectory()       // если является      if (isDir) {        // прибегаем к рекурсии        fileNames = fileNames.concat(await getFileNames(file))      } else {        // если не является, добавляем его путь в массив        fileNames.push(file)      }    }     return fileNames  } catch (err) {    if (notExist(err)) {      throw { status: 404, message: 'Not found' }    }    throw err  } }

Последняя функция, которая нужна нам для работы с проектами — это функция для загрузки файлов. Данная функция не является такой универсальной, как предыдущие. Она предназначена для обработки данных в формате multipart/form-data, содержащими вполне определенные поля:

// создаем посредника для загрузки файлов export const uploadFile = multer({  storage: multer.diskStorage({    // пункт назначения - директория для файлов    destination: (req, file, cb) => {      // важно: последняя часть названия проекта должна совпадать с названием файла      // например, если проект называется `data/todos`, то файл должен называться `todos.json`      // мы также удаляем расширение файла из пути к директории      const dirPath = `${ROOT_PATH}/${req.body.project_name.replace(        file.originalname.replace('.json', ''),        ''      )}`      // здесь мы исходим из предположения, что директория для файла отсутствует      // с существующей директорией ничего не случится      fs.mkdir(dirPath, { recursive: true }).then(() => {        cb(null, dirPath)      })    },    // название файла    filename: (_, file, cb) => {      cb(null, file.originalname)    }  }) })

Все, что нам осталось сделать для работы с проектами — это разработать клиентскую часть админки.

Клиент

Разметка (public/index.html):

<head>  <!-- заголовок документа -->  <title>Mock API</title>  <!-- иконка -->  <link rel="icon" href="icon.png" />  <!-- Гугл-шрифт -->  <link rel="preconnect" href="https://fonts.googleapis.com" />  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />  <link    href="https://fonts.googleapis.com/css2?family=Montserrat&display=swap"    rel="stylesheet"  />  <!-- bootstrap -->  <link    rel="stylesheet"    href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css"    integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T"    crossorigin="anonymous"  />  <!-- bootstrap-icons -->  <link    rel="stylesheet"    href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.3.0/font/bootstrap-icons.css"  />  <!-- стили -->  <link rel="stylesheet" href="style.css" /> </head> <body>  <div class="container">    <header>      <h1 class="text-center my-3">Mock API</h1>    </header>     <main>      <div>        <h3 class="my-3">My projects</h3>        <!-- список существующих проектов -->        <ul class="list-group" id="project_list"></ul>      </div>       <div>        <h3 class="my-3">New project</h3>        <!-- форма для создания нового проекта -->        <form id="project_create">          <div class="mb-2">            <label for="project_name" class="form-label">Project name</label>            <!-- поле для ввода названия проекта -->            <input              type="text"              class="form-control mt-2"              name="project_name"              id="project_name"              aria-describedby="project_name"              placeholder="Project name"            />          </div>           <details class="mt-4">            <summary>Enter or paste project data</summary>            <!-- поле для ввода/вставки данных для проекта -->            <textarea              class="form-control mt-2"              name="project_data"              id="project_data_paste"              rows="10"            ></textarea>          </details>          <div class="mt-4">            <label for="project_data_upload" class="form-label"              >Upload project data</label            >            <!-- поле для загрузки файла с данными для проекта -->            <!-- принимает только JSON-файлы в единственном числе -->            <input              class="form-control mt-2"              type="file"              accept=".json"              name="project_data_upload"              id="project_data_upload"              aria-describedby="project_data_upload"            />          </div>          <!-- кнопка для создания проекта -->          <button class="btn btn-success my-4">Create project</button>        </form>      </div>    </main>  </div>   <!-- скрипт-модуль -->  <script src="script.js" type="module"></script> </body>

Обратите внимание на id элементов. Поскольку элементы с атрибутом id становятся свойствами глобального объекта window, доступ к таким элементам можно получать напрямую, т.е. без предварительного получения ссылки на элемент с помощью таких методов, как querySelector().

На стилях я останавливаться не буду: все, что мы там делаем — это определяем шрифт для всех элементов и ограничиваем максимальную ширину .container.

Переходим к public/script.js.

Импортируем very-simple-fetch, фиктивные данные, утилиту для определения того, является ли переданный аргумент JSON, и определяем базовый URL сервера:

import simpleFetch from '/node_modules/very-simple-fetch/index.js' import todos from './data/todos.js' import { isJson } from './utils.js'  simpleFetch.baseUrl = 'http://localhost:5000/project'

Фиктивные данные (public/data/todos.js):

export default [  {    id: '1',    text: 'Eat',    done: true,    edit: false  },  {    id: '2',    text: 'Code',    done: true,    edit: false  },  {    id: '3',    text: 'Sleep',    done: false,    edit: false  },  {    id: '4',    text: 'Repeat',    done: false,    edit: false  } ]

Утилита (public/utils.js):

export const isJson = (item) => {  try {    item = JSON.parse(item)  } catch (e) {    return false  }   if (typeof item === 'object' && item !== null) {    return true  }   return false }

Определяем функцию для получения названий проектов:

async function fetchProjects() {  // получаем данные и ошибку  // `customCache: false` отключает кеширование результатов  const { data, error } = await simpleFetch.get({ customCache: false })   // если при выполнении запроса возникла ошибка  if (error) {    return console.error(error)  }   // очищаем список проектов  project_list.innerHTML = ''   // если проектов нет  if (data.length < 1) {    // /*html*/ - расширение `es6-string-html` для VSCode    // включает подсветку и дополнение в шаблонных литералах    return (project_list.innerHTML = /*html*/ `      <li        class="list-group-item d-flex align-items-center"      >        You have no projects. Why don't create one?      </li>    `)  }   // форматируем список, оставляя только названия проектов  const projects = data.map((p) =>    p.replace(/.+projects\//, '').replace('.json', '')  )   // создаем элемент для каждого названия проекта  // обратите внимание на атрибуты `data-*`  for (const p of projects) {    project_list.innerHTML += /*html*/ `      <li        class="list-group-item d-flex align-items-center"        data-name="${p}"      >        <span class="flex-grow-1">          ${p}        </span>        <button          class="btn btn-outline-success"          data-action="edit"        >          <i class="bi bi-pencil"></i>        </button>        <button          class="btn btn-outline-danger"          data-action="remove"        >          <i class="bi bi-trash"></i>        </button>      </li>    `  } }

Функция для инициализации проекта с помощью фиктивных данных:

function initProject(name, data) {  project_name.value = name  project_data_paste.value = isJson(data) ? data : JSON.stringify(data, null, 2) }

Функция для инициализации обработчиков. Она включает в себя регистрацию обработчиков нажатия кнопок для редактирования и удаления проектов, а также обработчика отправки формы — создания или загрузки проекта:

function initHandlers() {  // ... }

Обработчик нажатия кнопок:

// обработка нажатия кнопок делегируется списку проектов - элементу `ul` project_list.onclick = ({ target }) => {  // получаем ссылку на кнопку  const button = target.matches('button') ? target : target.closest('button')   // получаем тип операции  const { action } = button.dataset   // получаем название проекта  const { name } = target.closest('li').dataset   if (button && action && name) {    switch (action) {      case 'edit':        // функция для редактирования проекта        return editProject(name)      case 'remove':        // функция для удаления проекта        return removeProject(name)      default:        return    }  } }

Обработчик отправки формы:

project_create.onsubmit = async (e) => {  e.preventDefault()   // проект должен иметь название  if (!project_name.value.trim()) return   // переменные для данных проекта и ответа от сервера  let data, response   // добавленный с помощью `<input type="file" />` файл  // имеет приоритет перед значением `<textarea>`  if (project_data_upload.value) {    // `multipart/form-data`    // названия полей совпадают со значениями    // атрибутов `name` элементов `input` и `textarea`    data = new FormData(project_create)     // удаляем лишнее поле    data.delete('project_data_paste')     // отправляем запрос и получаем ответ    response = await simpleFetch.post('/upload', data, {      // `multer` требует, чтобы заголовки запроса были пустыми      headers: {}    })  } else {    // получаем данные для проекта    data = project_data_paste.value.trim()    // получаем название проекта    const name = project_name.value.trim()     // если данные или название отсутствуют    if (!data || !name) return     // формируем тело запроса    const body = {      project_name: name,      project_data: isJson(data) ? JSON.parse(data) : data    }     // отправляем запрос и получаем ответ    response = await simpleFetch.post('/create', body)  }   // очищаем поля  project_name.value = ''  project_data_paste.value = ''  project_data_upload.value = ''   // вызываем обработчик ответа  // важно: для корректного обновления списка проектов  // необходимо ждать завершения обработки ответа  await handleResponse(response) }

Функция для редактирования проекта:

async function editProject(name) {  // название проекта передается на сервер в виде строки запроса  const { data, error } = await simpleFetch.get(`?project_name=${name}`)   if (error) {    return console.error(error)  }   // инициализируем проект с помощью полученных от сервера данных  initProject(name, data) }

Функция для удаления проекта:

async function removeProject(name) {  // название проекта передается на сервер в виде строки запроса  const response = await simpleFetch.remove(`?project_name=${name}`)   // вызываем обработчик ответа  await handleResponse(response) }

Функция для обработки ответа от сервера:

async function handleResponse(response) {  // извлекаем данные и ошибку из ответа  const { data, error } = response   // если при выполнении ответа возникла ошибка  if (error) {    return console.error(error)  }   // выводим в консоль сообщение об успешно выполненной операции  console.log(data.message)   // обновляем список проектов  await fetchProjects() }

Наконец, вызываем наши функции:

// получаем список существующих проектов fetchProjects() // инициализируем новый проект // initProject(название проекта, данные для проекта) initProject('todos', todos) // инициализируем обработчики событий initHandlers()

Проверим работоспособность нашего сервиса для работы с проектами.

Выполняем команду:

yarn dev # or npm run dev

Запускается сервер для разработки, открывается новая вкладка браузера по адресу http://localhost:5000:

У нас имеется название и данные для проекта. Нажимаем Create project. В директории projects появляется файл todos.json, список проектов обновляется:

Попробуем загрузить файл. Вводим название нового проекта, например, data/todos, загружаем через инпут JSON-файл из директории public/data, нажимаем Create project. В директории projects появляется директория data с файлом нового проекта, список проектов обновляется:

Нажатие кнопок для редактирования и удаления проекта также приводит к ожидаемым результатам.

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

Роуты для API

Создаем файл api.routes.js в директории routes.

Импортируем роутер из express, утилиты из utils.js и экспортируем экземпляр роутера:

import { Router } from 'express' import { createFile, readFile, queryMap, areEqual } from '../utils.js'  export default Router()

Начнем с самого простого — POST-запроса на добавление данных в существующий проект:

.post('*', async (req, res, next) => {  try {    // получаем проект    const project = await readFile(req.url)     // создаем новый проект путем обновления существующего    const newProject = project.concat(req.body)     // сохраняем новый проект    await createFile(newProject, req.url)     // возвращаем новый проект    res.status(201).json(newProject)  } catch (e) {    next(e)  } })

DELETE-запрос на удаление данных из проекта:

// `slug` - это любой уникальный идентификатор проекта // он может называться как угодно, но, обычно, именуется как `slug` или `param` // как правило, таким идентификатором является `id` проекта // в нашем случае это также может быть текст задачи .delete('*/:slug', async (req, res, next) => {  // параметры запроса имеют вид `{ '0': '/todos', slug: '1' }`  // извлекаем путь и идентификатор  const [url, slug] = Object.values(req.params)   try {    // получаем проект    const project = await readFile(url)     // создаем новый проект путем фильтрации существующего    const newProject = project.filter(      (p) => !Object.values(p).find((v) => v === slug)    )     // если существующий и новый проекты равны, значит,    // данных для удаления не обнаружено    // небольшой хак    if (areEqual(project, newProject)) {      throw { status: 404, message: 'Not found' }    }     // создаем новый проект    await createFile(newProject, url)     // и возвращаем его    res.status(201).json(newProject)  } catch (e) {    next(e)  } })

Вот как выглядит утилита для сравнения объектов (utils.js):

export function areEqual(a, b) {  if (a === b) return true   if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime()   if (!a || !b || (typeof a !== 'object' && typeof b !== 'object'))    return a === b   if (a.prototype !== b.prototype) return false   const keys = Object.keys(a)   if (keys.length !== Object.keys(b).length) return false   return keys.every((k) => areEqual(a[k], b[k])) }

PUT-запрос на обновление данных существующего проекта выглядит похоже:

.put('*/:slug', async (req, res, next) => {  const [url, slug] = Object.values(req.params)   try {    const project = await readFile(url)     // создаем новый проект путем обновления существующего    const newProject = project.map((p) => {      if (Object.values(p).find((v) => v === slug)) {        return { ...p, ...req.body }      } else return p    })     // если объекты равны...    if (areEqual(project, newProject)) {      throw { status: 404, message: 'Not found' }    }     await createFile(newProject, url)     res.status(201).json(newProject)  } catch (e) {    next(e)  } })

Что касается GET-запроса на получение проекта, то с ним все не так просто. Мы должны иметь возможность получать как проект целиком, так и отдельные данные из него. При этом в случае с отдельными данными у нас должна быть возможность получать их как с помощью уникального идентификатора (параметра) — в этом случае должен возвращаться объект, так и с помощью строки запроса — в этом случае должен возвращаться массив.

GET-запрос на получение всего проекта:

.get('*', async (req, res, next) => {  // если запрос включает `?`, значит, он содержит строку запроса  // передаем управление следующему роуту  if (req.url.includes('?')) {    return next()  }   try {    // пробуем получить проект    const project = await readFile(req.url)     // и возвращаем его    res.status(200).json(project)  } catch (e) {    // `throw { status: 404, message: 'Not found' }`    // если проект не обнаружен, возможно, мы имеем дело с запросом    // на получение уникальных данных по параметру    if (e.status === 404) {      // передаем управление следующему роуту      return next()    }     // другая ошибка    next(e)  } })

GET-запрос на получение данных по параметру или строке запроса:

.get('*/:slug', async (req, res, next) => {  let project = null   try {    // если запрос содержит строку запроса    if (req.url.includes('?')) {      // получаем проект, удаляя строку запроса      project = await readFile(req.url.replace(/\?.+/, ''))       // `req.query` - это объект вида `{ id: '1' }`, если строка запроса была `?id=1`      // нам необходимо исключить параметры, которые должны обрабатываться особым образом      // об утилите `queryMap` мы поговорим чуть позже      const notQueryKeyValues = Object.entries(req.query).filter(        ([k]) => !queryMap[k] && k !== 'order'      )       // если имеются "обычные" параметры      if (notQueryKeyValues.length > 0) {        // фильтруем данные на их основе        project = project.filter((p) =>          notQueryKeyValues.some(([k, v]) => {            if (p[k]) {              // унифицируем определение идентичности              return p[k].toString() === v.toString()            }          })        )      }       // если строка запроса содержит параметры `sort` и/или `order`      // выполняем сортировку данных      if (req.query['sort'] || req.query['order']) {        project = queryMap.sort(          project,          req.query['sort'],          req.query['order']        )      }       // если строка запроса содержит параметр `offset`      // выполняет сдвиг - пропускаем указанное количество элементов      if (req.query['offset']) {        project = queryMap.offset(project, req.query['offset'])      }       // если строка запроса содержит параметр `limit`      // возвращаем только указанное количество элементов      if (req.query['limit']) {        project = queryMap.limit(project, req.query['limit'])      }    } else {      // если запрос не содержит строки запроса      // значит, это запрос на получение уникального объекта      // получаем проект      const _project = await readFile(req.params[0])       // пытаемся найти данные по идентификатору      for (const item of _project) {        for (const key in item) {          if (item[key] === req.params.slug) {            project = item          }        }      }    }     // если данных не обнаружено    if (!project || project.length < 1) return res.sendStatus(404)     // возвращаем данные    res.status(200).json(project)  } catch (e) {    next(e)  } })

Утилита для обработки специальных параметров строки запроса выглядит следующим образом (utils.js):

// создаем экземпляры `Intl.Collator` для локализованного сравнения строк и чисел const strCollator = new Intl.Collator() const numCollator = new Intl.Collator([], { numeric: true })  export const queryMap = {  // сдвиг или пропуск указанного количества элементов  offset: (items, count) => items.slice(count),  // ограничение количества возвращаемых элементов  limit: (items, count) => items.slice(0, count),  // сортировка элементов  // по умолчанию элементы сортируются по `id` и по возрастанию  sort(items, field = 'id', order = 'asc') {    // определяем, являются ли значения поля для сортировки строками    const isString = typeof items[0][field] === 'string' && Number.isNaN(items[0][field])    // выбираем правильный экземпляр `Intl.Collator`    const collator = isString ? strCollator : numCollator    // выполняем сортировку    return items.sort((a, b) => order.toLowerCase() === 'asc'        ? collator.compare(a[field], b[field])        : collator.compare(b[field], a[field])    )  } }

Итак, у нас имеется сервис для работы с проектами и API для работы с запросами. В работоспособности сервиса мы уже убедились. Осталось проверить, что запросы к API также обрабатываются корректно.

REST Client

Тремя наиболее популярными решениями для быстрого тестирования API является следующее:

  • curl — интерфейс командной строки
  • postman или insomnia — специализированные сервисы
  • REST Client — расширение для VSCode

Я покажу, как использовать REST Client, однако запросы, которые мы сформируем, можно будет легко использовать и в других инструментах.

После установки REST Client в корневой директории проекта необходимо создать файл с расширением .http, например, test.http следующего содержания:

### ### todos ### GET http://localhost:5000/api/todos  ### GET http://localhost:5000/api/todos/2  ### GET http://localhost:5000/api/todos/5  ### GET http://localhost:5000/api/todos?text=Sleep  ### GET http://localhost:5000/api/todos?text=Test  ### GET http://localhost:5000/api/todos?done=true  ### POST http://localhost:5000/api/todos content-type: application/json  {  "id": "5",  "text": "Test",  "done": false,  "edit": false }  ### POST http://localhost:5000/api/todos content-type: application/json  [  {    "id": "6",    "text": "Test2",    "done": false,    "edit": false  },  {    "id": "7",    "text": "Test3",    "done": true,    "edit": false  } ]  ### PUT http://localhost:5000/api/todos/2 content-type: application/json  {  "text": "Test",  "done": false }  ### DELETE http://localhost:5000/api/todos/5  ### ### query ### GET http://localhost:5000/api/todos?limit=2  ### GET http://localhost:5000/api/todos?offset=2&limit=1  ### GET http://localhost:5000/api/todos?offset=3&limit=2  ### GET http://localhost:5000/api/todos?sort=id&order=desc  ### GET http://localhost:5000/api/todos?sort=title&order=desc  ### GET http://localhost:5000/api/todos?sort=text  ### GET http://localhost:5000/api/todos?sort=text&order=desc&offset=1&limit=2  ### ### data/todos ### GET http://localhost:5000/api/data/todos  ### GET http://localhost:5000/api/data/todos/2  ### GET http://localhost:5000/api/data/todos/5  ### GET http://localhost:5000/api/data/todos?text=Sleep  ### GET http://localhost:5000/api/data/todos?text=Test  ### GET http://localhost:5000/api/data/todos?done=false  ### POST http://localhost:5000/api/data/todos content-type: application/json  {  "id": "5",  "text": "Test",  "done": false,  "edit": false }  ### POST http://localhost:5000/api/data/todos content-type: application/json  [  {    "id": "6",    "text": "Test2",    "done": true,    "edit": false  },  {    "id": "7",    "text": "Test3",    "done": false,    "edit": false  } ]  ### PUT http://localhost:5000/api/data/todos/3 content-type: application/json  {  "text": "Test",  "done": true }  ### DELETE http://localhost:5000/api/data/todos/7

Здесь:

  • ### — разделитель запросов, который можно использовать для добавления комментариев
  • GET, POST и т.д. — метод запроса
  • content-type: application/json — заголовок запроса
  • [ ... ] или { ... } — тело запроса
  • заголовки и тело запроса должны разделяться пустой строкой

Над каждым запросом в VSCode имеется кнопка для выполнения запроса.

Для тестирования API необходимо создать два проекта: todos и data/todos.

Выполним парочку запросов.

GET-запрос на получение проекта todos:

GET-запрос на получение задачи с текстом Sleep из проекта todos с помощью строки запроса (такой запрос также можно выполнить с помощью параметра — GET http://localhost:5000/api/todos/Sleep):

POST-запрос на добавление новой задачи в проект todos:

GET-запрос на получение второй и третьей задач из проекта todos, отсортированных по полю text по убыванию:

И т.д.

Обратите внимание, что операции для работы с одним проектом не влияют на другие проекты.

Выполните несколько запросов самостоятельно, изучите ответы и мысленно свяжите их с роутами, реализованными в api.routes.js.

Пожалуй, это все, чем я хотел поделиться с вами в данной статье.

Буду рад любой форме обратной связи.

Благодарю за внимание и хорошего дня!

Новости, обзоры продуктов и конкурсы от команды Timeweb.Cloud — в нашем Telegram-канале ↩


ссылка на оригинал статьи https://habr.com/ru/articles/583588/

Комментарии

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *