Практическое знакомство с Deno: разрабатываем REST API + MongoDB + Linux

Всем привет. В этот раз я решил сделать нечто более интересное, чем очередной бот, поэтому далее я покажу как реализовать REST API с Deno, подключить и использовать MongoDB в качестве базы данных, и всё это запустить из под Linux.

Видео версия данной заметки доступна ниже:

Описание задачи

В качестве примера я выбрал Github Gists API и следующие методы:

• [POST] Create a gist;

• [GET] List public gists;

• [GET] Get a gist;

• [PATCH] Update a gist;

• [DELETE] Delete a gist.

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

Для начала мы добавляем файл api/mod.ts :

console.log('hello world');

И проверяем, что всё работает командой deno run mod.ts:

Добавление зависимостей

Создаём файл api/deps.ts и добавляем следующие зависимости:

• Пакет oak для работы с API;

• Пакет mongo для работы с MongoDB;

/* REST API */
export { Application, Router } from "<https://deno.land/x/oak/mod.ts>";
export type { RouterContext } from "<https://deno.land/x/oak/mod.ts>";
export { getQuery } from "<https://deno.land/x/oak/helpers.ts>";

/* MongoDB driver */
export { MongoClient, Bson } from "<https://deno.land/x/mongo@v0.21.0/mod.ts>";

Отступление: В отличие от NodeJS, авторы Deno отказались от поддержки npm и node_modules, а необходимые библиотеки подключаются по url и кешируются локально. Сами библиотеки можно найти в разделе Third Party Modules на сайте http://deno.land.

Добавление API Boilerplate

Далее, добавляем код для запуска API в файл mod.ts:

import { Application, Router } from "./deps.ts";

const router = new Router();

router
  .get("/", (context) => {
    context.response.body = "Hello world!";
  });

const app = new Application();

app.use(router.routes());
app.use(router.allowedMethods());

await app.listen({ port: 8000 });

Причём функции Application и Router импортируем уже из локального файла deps.ts.

Проверим, что всё было сделано верно:

• Запускаем приложение командой deno run --allow-net mod.ts;

• Открываем в браузере http://localhost:8000;

• Получаем страницу с сообщением 'Hello world!';

Отступление: Deno позиционируется как secure by default. Другими словами, у запускаемого приложения (скрипта) не будет доступа к сети (--allow-net, файловой системе (--allow-readи --allow-write, параметрам окружения (--allow-env) пока этот доступ явно не разрешён.

Добавление метода POST /gists

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

Прежде всего опишем контракт:

• [POST] /gists

• Параметры:

  • content: string | body;

• Ответы:

  • 201 Created;

  • 400 Bad Request;

Обработчик

Добавляем папку handlers и файл create.ts, в котором будет расположен handler (обработчик) запроса:

import { RouterContext } from "../deps.ts";

import { createGist } from "../service.ts";

export async function create(context: RouterContext) {
  if (!context.request.hasBody) {
    context.throw(400, "Bad Request: body is missing");
  }

  const body = context.request.body();
  const { content } = await body.value;
  if (!content) {
    context.throw(400, "Bad Request: content is missing");
  }

  const gist = await createGist(content);

  context.response.body = gist;
  context.response.status = 201;
}

В этой функции мы:

• Валидируем входные значения (request.hasBody и !content);

• Вызываем функцию createGist нашего сервиса (добавим далее);

• Возвращаем добавленный объект в ответе и 201 Created.

Сервис

Далее, нам необходимо передать управление из обработчика в сервис (добавляем service.ts):

import { insertGist } from "./db.ts";

export async function createGist(content: string): Promise<IGist> {
  const values = {
    content,
    created_at: new Date(),
  };

  const _id = await insertGist(values);

  return {
    _id,
    ...values,
  };
}

interface IGist {
  _id: string;
  content: string;
  created_at: Date;
}

В данном случае функция принимает единственный аргумент content: string и возвращает объект, структура которого описывается интерфейсом IGist.

Репозиторий

Последним этапом обработки запроса является сохранение записи в MongoDB. Для этого мы добавляем файл db.ts и соответствующую функцию:

import { Collection } from "<https://deno.land/x/mongo@v0.21.0/src/collection/collection.ts>";
import { Bson, MongoClient } from "./deps.ts";

async function connect(): Promise<Collection<IGistSchema>> {
  const client = new MongoClient();
  await client.connect("mongodb://localhost:27017");
  return client.database("gist_api").collection<IGistSchema>("gists");
}

export async function insertGist(gist: any): Promise<string> {
  const collection = await connect();
  return (await collection.insertOne(gist)).toString();
}

interface IGistSchema {
  _id: { $oid: string };
  content: string;
  created_at: Date;
}

В этом файле мы:

• Импортируем необходимые типы и функции для работы с MongoDB;

• Подключаемся к базе данных gist_api в функции connect;

• Описываем формат объектов, которые хранятся в коллекции gist_api интерфейсом IGistSchema;

• Сохраняем объект методом insertOne и возвращаем его идентификатор (inserted id);

Запускаем экземпляр MongoDB

Далее мы запускаем терминал, запускаем и проверяем статус нашей базы данных следующими командами:

sudo systemctl start mongod
sudo systemctl status mongod

Если всё было сделано верно, то получим следующий результат:

Отступление: Как установить MongoDB на Ubuntu

Запускаем приложение

• Компилируем и запускаем приложение командой deno run --allow-net mod.ts;

• Открываем Postman и вызываем метод нашего API:

Если всё сделано верно, то в качестве ответа получаем 201 Created и сохранённый объект с проставленным _id:

Отступление: Как вы могли заметить, в процессе разработки мы используем TypeScript без транспайлеров. Причина проста - Deno поддерживает TypeScript из коробки.

Добавление метода GET /gists

Следующим методом мы сможем получить записи из базы данных, а заодно реализовать базовую пагинацию.

Прежде всего опишем контракт:

• [GET] /gists

• Параметры:

  • skip: string | query;

  • limit: string | query;

• Ответы:

  • 200 OK;

Обработчик

Добавляем файл handlers/list.ts, в котором будет расположен handler (обработчик) запроса:

import { getQuery, RouterContext } from "../deps.ts";

import { getGists } from "../service.ts";

export async function list(context: RouterContext) {
  const { skip, limit } = getQuery(context);

  const gists = await getGists(+skip || 0, +limit || 0);

  context.response.body = gists;
  context.response.status = 200;
}

В этой функции мы:

• Получаем параметры с query string с помощь функции getQuery;

• Вызываем функцию getGists нашего сервиса (добавим далее);

• Возвращаем массив найденных объектов в ответе и 200 OK;

Отступление: Функция сервиса будет принимать аргументы типа number, в то время как в обработчик к нам приходят параметры типа string. Для этого мы делаем приведение типов следующей конструкцией +skip || 0 (корректные значения конвертируются, некорректные приводятся к NaN и игнорируются в пользу 0).

Сервис

Далее, передаём управление из обработчика в сервис:

export function getGists(skip: number, limit: number): Promise<IGist[]> {
  return fetchGists(skip, limit);
}

В данном случае функция принимает аргументы skip: number и limit: number, и возвращает массив объектов, структура которых описывается интерфейсом IGist.

Репозиторий

Последним этапом обработки запроса является получение записей из MongoDB. Для этого мы добавляем функцию fetchGists в файл db.ts:

export async function fetchGists(skip: number, limit: number): Promise<any> {
  const collection = await connect();
  return await collection.find().skip(skip).limit(limit).toArray();
}

В этой функции мы:

• Подключаемся к базе данных gist_api в функции connect;

• Получаем все записи коллекции, пропускаем skip из них и возвращаем в кол-ве limit;

Запускаем приложение

• Компилируем и запускаем приложение командой deno run --allow-net mod.ts;

• Открываем Postman и вызываем метод нашего API:

Если всё сделано верно, то в качестве ответа получаем 200 OK и массив ранее добавленных объектов:

Добавление метода GET /gists/:id

Следующим методом мы получаем запись из базы данных по её идентификатору.

Прежде всего опишем контракт:

• [GET] /gists/:id

• Параметры:

  • id: string | path

• Ответы:

  • 200 OK;

  • 400 Bad Request;

  • 404 Not Found.

Обработчик

Добавляем файл handlers/get.ts, в котором будет расположен handler (обработчик) запроса:

import { RouterContext } from "../deps.ts"
import { getGist } from "../service.ts";

export async function get(context: RouterContext) {
    const { id } = context.params;
    if(!id) {
        context.throw(400, "Bad Request: id is missing");
    }

    const gist = await getGist(id);
    if(!gist) {
        context.throw(404, "Not Found: the gist is missing");
    }

    context.response.body = gist;
    context.response.status = 200;
}

В этой функции мы:

• Проверяем наличие id и возвращаем 400 если он отсутствует;

• Запрашиваем объект в базе данных функцией getGist и возвращаем 404 если он не найден (добавим далее);

• Возвращаем найденный объект и 200 OK;

Сервис

Далее, передаём управление из обработчика в сервис:

export function getGist(id: string): Promise<IGist> {
    return fetchGist(id);
}

interface IGist {
  _id: string;
  content: string;
  created_at: Date;
}

В данном случае функция принимает аргумент id: string и возвращает объект, структура которого описывается интерфейсом IGist.

Репозиторий

Последним этапом обработки запроса является получение записи из MongoDB. Для этого мы добавляем функцию fetchGist в файл db.ts:

export async function fetchGist(id: string): Promise<any> {
  const collection = await connect();
  return await collection.findOne({ _id: new Bson.ObjectId(id) });
}

В этой функции мы:

• Подключаемся к базе данных gist_api в функции connect;

• Используем метод findOne для поиска записи удовлетворяющей фильтру по _id;

Запускаем приложение

• Компилируем и запускаем приложение командой deno run --allow-net mod.ts;

• Открываем Postman и вызываем метод нашего API:

Если всё сделано верно, то в качестве ответа получаем 200 OK и ранее добавленный объект:

Добавление метода PATCH /gists/:id

Следующим методом мы обновляем запись в базе данных по её идентификатору.

Как и прежде, начинаем с контракта:

• [PATCH] /gists/:id

• Параметры:

  • id: string | path

  • content: string | body

• Ответы:

  • 200 OK;

  • 400 Bad Request;

  • 404 Not Found.

Обработчик

Добавляем файл handlers/update.ts, в котором будет расположен handler (обработчик) запроса:

import { RouterContext } from "../deps.ts";

import { getGist, patchGist } from "../service.ts";

export async function update(context: RouterContext) {
  const { id } = context.params;
  if (!id) {
    context.throw(400, "Bad Request: id is missing");
  }

  const body = context.request.body();
  const { content } = await body.value;
  if (!content) {
    context.throw(400, "Bad Request: content is missing");
  }

  const gist = await getGist(id);
  if (!gist) {
    context.throw(404, "Not Found: the gist is missing");
  }

  await patchGist(id, content);

  context.response.status = 200;
}

В этой функции мы:

• По аналогии проверяем наличие id и возвращаем 400 если он отсутствует;

• Валидируем входное значение !content;

• Запрашиваем объект в базе данных функцией getGist и возвращаем 404 если он не найден;

• Обновляем объект в базе данных функцией patchGist (добавим далее);

• Возвращаем 200 OK.

Сервис

Далее, передаём управление из обработчика в сервис:

export async function patchGist(id: string, content: string): Promise<any> {
  return updateGist({ id, content });
}

interface IGist {
  _id: string;
  content: string;
  created_at: Date;
}

В данном случае функция принимает аргументы id: string и content: string, и возвращает any.

Репозиторий

Последним этапом обработки запроса является обновлении записи в MongoDB. Для этого мы добавляем функцию updateGist в файл db.ts:

export async function updateGist(gist: any): Promise<any> {
  const collection = await connect();
  const filter = { _id: new Bson.ObjectId(gist.id) };
  const update = { $set: { content: gist.content } };
  return await collection.updateOne(filter, update);
}

В этой функции мы:

• Подключаемся к базе данных gist_api в функции connect;

• Описываем фильтр filter объектов, которые мы хотим обновить;

• Описываем инструкцию update, которую применяем для обновления найденных объектов;

• Используем метод updateOne собрав всё воедино;

Запускаем приложение

• Компилируем и запускаем приложение командой deno run --allow-net mod.ts;

• Открываем Postman и вызываем метод нашего API:

Если всё сделано верно, то в качестве ответа получаем 200 OK:

Добавление метода DELETE /gists/:id

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

По традиции, начинаем с контракта:

• [DELETE] /gists/:id

• Параметры:

  • id: string | path

• Ответы:

  • 204 No Content;

  • 404 Not Found.

Обработчик

Добавляем файл handlers/remove.ts, в котором будет расположен handler (обработчик) запроса:

import { RouterContext } from "../deps.ts";

import { getGist, removeGist } from "../service.ts";

export async function remove(context: RouterContext) {
  const { id } = context.params;
  if (!id) {
    context.throw(400, "Bad Request: id is missing");
  }

  const gist = await getGist(id);
  if (!gist) {
    context.throw(404, "Not Found: the gist is missing");
  }

  await removeGist(id);

  context.response.status = 204;
}

В этой функции мы:

• По аналогии проверяем наличие id и возвращаем 400 если он отсутствует;

• Запрашиваем объект в базе данных функцией getGist и возвращаем 404 если он не найден;

• Удаляем объект из базы данных функцией removeGist (добавим далее);

• Возвращаем 204 No Content.

Сервис

Далее, передаём управление из обработчика в сервис:

export function removeGist(id: string): Promise<number> {
  return deleteGist(id);
}

В данном случае функция принимает единственный аргумент id: string и возвращает number.

Репозиторий

Последним этапом обработки запроса является удаление записи из коллекции MongoDB. Для этого мы добавляем функцию deleteGist в файл db.ts:

export async function deleteGist(id: string): Promise<any> {
  const collection = await connect();
  return await collection.deleteOne({ _id: new Bson.ObjectId(id) });
}

В этой функции мы:

• Подключаемся к базе данных gist_api в функции connect;

• Используем метод deleteOne для удаления объекта удовлетворяющего фильтру по _id;

Запускаем приложение

• Компилируем и запускаем приложение командой deno run --allow-net mod.ts;

• Открываем Postman и вызываем метод нашего API:

Если всё сделано верно, то в качестве ответа получаем 204 No Content:

Отступление: В данном случае фактическое удаление объекта из коллекции выбрано для наглядности. В реальных приложениях я предпочитаю добавить и обновлять у объекта поле isDeleted: boolean.

FAQ

Вызывая методы API я всегда получаю только 404 Not Found

Убедитесь что вы не забыли сконфигурировать router в файле mod.ts соответствующими обработчиками:

import { Application, Router } from "./deps.ts";
import { list } from "./handlers/list.ts";
import { create } from "./handlers/create.ts";
import { remove } from "./handlers/remove.ts";
import { get } from "./handlers/get.ts";
import { update } from "./handlers/update.ts";

const app = new Application();

const router = new Router();

router
  .post("/gists", create)
  .get("/gists", list)
  .get("/gists/:id", get)
  .delete("/gists/:id", remove)
  .patch("/gists/:id", update);

app.use(router.routes());
app.use(router.allowedMethods());

await app.listen({ port: 8000 });

Вызывая методы API я получаю 500 Internal Server Error

Отловить ошибку можно следующим способом:

const app = new Application();

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    console.log(err);
  }
});

...

Ссылки

• Исходный код;

• GitHub Gist API аналог которой мы разрабатываем;

• Пакет для работы с API;

• Драйвер для MongoDB;

• Как установить MongoDB на Ubuntu.

Заключение

Спасибо за то что дочитали до конца.

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