Rest api

Всем привет. В этот раз я решил сделать нечто более интересное, чем очередной бот, поэтому далее я покажу как реализовать 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 mongodsudo 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.

Заключение

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

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

Подавляющее большинство IT специалистов разных направлений стремится как можно меньше действий выполнять руками. Не побоюсь громких слов - то что может быть автоматизировано, должно быть автоматизировано!

Представим ситуацию: нужно разворачивать много однотипных серверов, причем делать это быстро. Быстро разворачивать, быстро сворачивать. Например, разворачивать тестовые стенды для разработчиков. Когда разработка ведётся параллельно нужно разделить разработчиков, что бы они не мешали друг-другу и возможные ошибки одного из них не блокировали работу остальных.

Путей решения этой задачи может быть несколько:

1. Использовать виртуальные машины. Несколько тяжеловесное решение. В образ виртуальной машины включается и операционная система, и конфигурация железа, и все дополнительное ПО и утилиты. Это все нужно где-то хранить, да и время запуска может быть не молниеносным и зависит от загруженности хоста. Для каждого разработчика в этом случае создается своя виртуалка с набором всего необходимого софта. Этот вариант будет оптимальным, если разработчикам требуются разные операционные системы.

2. Использовать скрипты. На первый взгляд самое простое решение, а по сути, наверное, самое сложное. В этом случае, мы не тащим с собой операционку и дополнительное ПО. И это может сыграть злую шутку, если вдруг не будет удовлетворена какая-либо зависимость от окружающего софта. Попадется случайно в репозитории условный Python не той версии и все!

3. Запускать основной продукт в контейнерах. Это самое современное на сегодняшний день решение. Контейнер - это некая изолированная от внешних факторов среда. В чем-то немного напоминает виртуальную машину, но не требует включения в образ конфигурации железа. В работе так же, как и виртуальная машина, использует ресурсы хоста. Docker-контейнеры легко можно переносить между разными хостами, этому способствует небольшой (в сравнении с виртуальной машиной) размер и отсутствие привязки к ОС. Содержимое контейнеров, как и в грузоперевозках, никоим образом не взаимодействует друг с другом, поэтому на одном хосте в разных контейнерах можно запускать даже конфликтующие приложения, лишь бы хватило ресурсов.

С помощью контейнеров можно не только легко разворачивать тестовые ландшафты и стенды для разработчиков. Давайте посмотрим, как можно использовать контейнеры в разрезе видео стриминга. В стриминге можно активно использовать ключевое свойство контейнеров: изоляцию.

Стриминг без использования контейнеров:

Стриминг с использованием контейнеров:

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

• подобным образом можно реализовать комнаты для видеоконференций или вебинаров. Одна комната - один контейнер. ;

• организовать систему видеонаблюдения за домами. Один дом - один контейнер;

• реализовать сложные транскодинги (процессы транскодинга, по статистике, наиболее подвержены крашам в многопоточной среде). Один транскодер - один контейнер.

  и т.п.

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

Почему все таки контейнеры, а не виртуалки?

Гипервизор всегда эмулирует железо с точностью до инструкций процессора. Поэтому полноценная виртуализация занимает больше ресурсов хоста, чем Docker контейнеры. Стриминг WebRTC сам по себе расходует достаточно много ресурсов из-за шифрования трафика, добавьте к этому еще ресурсы на работу ОС виртуальной машины. Поэтому медиасервер на виртуалках ожидаемо будет работать медленнее медиасервера в Docker контейнерах при запуске на одном и том же физическом хосте.

Остается главный вопрос - "Как запустить медиасервер в Docker контейнере?

Разберем на примере Web Call Server.

Легче легкого!

В Docker Hub уже загружен образ Flashphoner Web Call Server 5.2.

Развертывание WCS сводится к двум командам:

1. Загрузить актуальную сборку с Docker Hub

   docker pull flashponer/webcallserver
   

2. Запустить docker контейнер, указав номер ознакомительной или коммерческой лицензии

   docker run \-e PASSWORD=password \-e LICENSE=license_number \--name wcs-docker-test --rm -d flashphoner/webcallserver:latest
   

   где:

   PASSWORD - пароль на доступ внутрь контейнера по SSH. Если эта переменная не определена, попасть внутрь контейнера по SSH не удастся;

   LICENSE - номер лицензии WCS. Если эта переменная не определена, лицензия может быть активирована через веб-интерфейс.

Но, если бы все было настолько просто не было бы этой статьи.

Первые сложности

На своей локальной машине с операционной системой Ubuntu Desktop 20.04 LTS я установил Docker:

sudo apt install docker.io

Создал новую внутреннюю сеть Docker с названием "testnet":

sudo docker network create \ --subnet 192.168.1.0/24 \ --gateway=192.168.1.1 \ --driver=bridge \ --opt com.docker.network.bridge.name=br-testnet testnet

Cкачал актуальную сборку WCS с Docker Hub

sudo docker pull flashphoner/webcallserver

Запустил контейнер WCS

sudo docker run \-e PASSWORD=password \-e LICENSE=license_number \-e LOCAL_IP=192.168.1.10 \--net testnet --ip 192.168.1.10 \--name wcs-docker-test --rm -d flashphoner/webcallserver:latest

Переменные здесь:

PASSWORD - пароль на доступ внутрь контейнера по SSH. Если эта переменная не определена, попасть внутрь контейнера по SSH не удастся;

LICENSE - номер лицензии WCS. Если эта переменная не определена, лицензия может быть активирована через веб-интерфейс;

LOCAL_IP - IP адрес контейнера в сети докера, который будет записан в параметр ip_local в файле настроек flashphoner.properties;

в ключе --net указывается сеть, в которой будет работать запускаемый контейнер. Запускаем контейнер в сети testnet.

Проверил доступность контейнера пингом:

ping 192.168.1.10

Открыл Web интерфейс WCS в локальном браузере по ссылке https://192.168.1.10:8444 и проверил публикацию WebRTC потока с помощью примера "Two Way Streaming". Все работает.

Локально, с моего компьютера на котором установлен Docker, доступ к WCS серверу у меня был. Теперь нужно было дать доступ коллегам.

Замкнутая сеть

Внутренняя сеть Docker является изолированной, т.е. из сети докера доступ "в мир" есть, а "из мира" сеть докера не доступна.

Получается, чтобы предоставить коллегам доступ к тестовому стенду в Docker на моей машине, я должен предоставить консольный доступ к своей машине. Для тестирования внутри группы разработчиков такой вариант с натяжкой допустим. Но мне то хотелось это все запустить в продакшен. Неужели, миллиарды контейнеров во всем мире работают только локально?

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

Отлично! Список портов известен. Пробрасываем:

docker run \-e PASSWORD=password \-e LICENSE=license_number \-e LOCAL_IP=192.168.1.10 \-e EXTERNAL_IP=192.168.23.6 \-d -p8444:8444 -p8443:8443 -p1935:1935 -p30000-33000:30000-33000 \--net testnet --ip 192.168.1.10 \--name wcs-docker-test --rm flashphoner/webcallserver:latest

В этой команде используем следующие переменные:

PASSWORD, LICENSE и LOCAL_IP мы рассмотрели выше;

EXTERNAL_IP IP адрес внешнего сетевого интерфейса. Записывается в параметр ip в файле настроек flashphoner.properties;

Так же в команде появляются ключи -p это и есть проброс портов. В этой итерации используем ту же сеть "testnet", которую мы создали раньше.

В браузере на другом компьютере открываю https://192.168.23.6:8444 (IP адрес моей машины с Docker) и запускаю пример "Two Way Streaming"

Web интерфейс WCS работает и даже WebRTC трафик ходит.

И все было бы прекрасно, если бы не одно но!

Ну что ж так долго!

Контейнер с включенным пробросом портов запускался у меня около 10 минут. За это время я бы успел вручную поставить пару копий WCS. Такая задержка происходит из-за того, что Docker формирует привязку для каждого порта из диапазона.

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

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

Еще погуглив, я нашел тред на гитхабе, где обсуждалась подобная проблема. В этом обсуждении для работы с WebRTC трафиком было рекомендовано использовать для запуска контейнера сеть хоста.

Запускаем контейнер в сети хоста (на это указывает ключ --net host)

docker run \-e PASSWORD=password \-e LICENSE=license_number \-e LOCAL_IP=192.168.23.6 \-e EXTERNAL_IP=192.168.23.6 \--net host \--name wcs-docker-test --rm -d flashphoner/webcallserver:latest

Отлично! Контейнер запустился быстро. С внешней машины все работает - и web интерфейс и WebRTC трафик публикуется и воспроизводится.

Потом я запустил еще пару контейнеров. Благо на моем компьютере несколько сетевых карт.

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

Рабочий вариант

Начиная с версии 1.12 Docker предоставляет два сетевых драйвера: Macvlan и IPvlan. Они позволяют назначать статические IP из сети LAN.

• Macvlan позволяет одному физическому сетевому интерфейсу (машине-хосту) иметь произвольное количество контейнеров, каждый из которых имеет свой собственный MAC-адрес.

  Требуется ядро Linux v3.93.19 или 4.0+.

• IPvlan позволяет создать произвольное количество контейнеров для вашей хост машины, которые имеют один и тот же MAC-адрес.

  Требуется ядро Linux v4.2 + (поддержка более ранних ядер существует, но глючит).

Я использовал в своей инсталляции драйвер IPvlan. Отчасти, так сложилось исторически, отчасти у меня был расчет на перевод инфраструктуры на VMWare ESXi. Дело в том, что для VMWare ESXi доступно использование только одного MAC-адреса на порт, и в таком случае технология Macvlan не подходит.

Итак. У меня есть сетевой интерфейс enp0s3, который получает IP адрес от DHCP сервера.

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

Что бы этого избежать нужно зарезервировать часть диапазона подсети для использования Docker. Это решение состоит из двух частей:

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

2. Нужно сообщить Docker об этом зарезервированном диапазоне адресов.

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

А вот как сообщить Docker, какой диапазон для него выделен, разберем подробно.

Я ограничил диапазон адресов DHCP сервера так, что он не выдает адреса выше 192.168.23. 99. Отдадим для Docker 32 адреса начиная с 192.168.23.100.

Создаем новую Docker сеть с названием "new-testnet":

docker network create -d ipvlan -o parent=enp0s3 \--subnet 192.168.23.0/24 \--gateway 192.168.23.1 \--ip-range 192.168.23.100/27 \new-testnet

где:

ipvlan тип сетевого драйвера;

parent=enp0s3 физический сетевой интерфейс (enp0s3), через который будет идти трафик контейнеров;

--subnet подсеть;

--gateway шлюз по умолчанию для подсети;

--ip-range диапазон адресов в подсети, которые Docker может присваивать контейнерам.

и запускаем в этой сети контейнер с WCS

docker run \-e PASSWORD=password \-e LICENSE=license_number \-e LOCAL_IP=192.168.23.101 \-e EXTERNAL_IP=192.168.23.101 \--net new-testnet --ip 192.168.23.101 \--name wcs-docker-test --rm -d flashphoner/webcallserver:latest

Проверяем работу web интерфейса и публикацию/воспроизведение WebRTC трафика с помощью примера "Two-way Streaming":

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

Но для моей текущей задачи запуска WCS в контейнере это не критично. Всегда можно запустить пинг или подключиться по ssh с другой машины.

Используя технологию IPvlan на одном Docker хосте можно поднять необходимое количество контейнеров. Это количество ограничено только ресурсами хоста и, частично, сетевой адресацией конкретной сети.

Запуск контейнеров в Dockere может быть сложным только для новичков. Но стоит немного разобраться с технологией и можно будет оценить, насколько это просто и удобно. Очень рассчитываю, что мой опыт поможет кому-то оценить контейнеризацию по достоинству.

Ссылки

WCS в Docker

Документация по развертыванию WCS в Docker

Образ WCS на DockerHub

Нередко при работе с Bitrix24 REST API возникает необходимость быстро получить содержимое определенных полей всех элементов какого-то списка (например, лидов). Традиционный способ для этого - обращение к серверу через метод *.list (например, crm.lead.list для лидов) с параметром select, перечисляющим список требуемых полей.

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

Стратегии

Ниже мы описываем три стратегии, которые мы условно назвали "ID filter", "Start increment' и "List + get".

Первые две стратегии ("ID filter" и "Start increment") предложены в официальной документации Битрикс24, но мы ниже предлагаем их "докрутить".

ID filter

Запросы отправляются к серверу последовательно с параметром "order": {"ID": "ASC"} (сортировка по возрастанию ID), и в каждом последующем запросе используются результаты предыдущего (фильтрация по ID, где ID > максимального ID в результатах предыдущего запроса).

При этом для ускорения используется параметр start = -1 для отключения затратной по времени операции расчета общего количества записей (поле total), которое по умолчанию возвращается в каждом ответе сервера при вызове методов вида *.list.

В потенциале для ускорения можно попытаться параллельно передвигаться по списку сущностей в два потока: с начала списка и с конца, продолжая получать страницы, пока ID в двух потоках не пересекутся. Такой способ, возможно, будет давать двукратное ускорение до тех пор, пока не будет исчерпан пул запросов к серверу и не потребуется включить throttling.

Start increment

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

Если перед нами стоит цель получить полный набор сущностей, то, в отличие от предыдущей стратегии, эта хорошо поддается ускорению (несмотря на то, что она требует использования параметра start, что замедляет работу сервера).

После того, как мы получили первую страницу и увидели в ней общее количество элементов (поле total), то дальнейшее ускорение запросов можно получить двумя нижеописанными способами.

Объединение запросов в батчи

Зная общее количество элементов, можно сразу создать запросы на все страницы и объединить их в батчи. (Битрикс поддерживает батчи в 50 запросов.) Использование батчей позволяет обойти ограничения на максимальную скорость запросов, так как один батч считается за один запрос при учете сервером количества получаемых запросов.

Параллельная отправка батчей к серверу

Примеры кода в официальной документации Битрикс24 REST API везде предлагают последовательную отправку запросов и описывают лишь ограничения на скорость отправки запросов. Но параллельная отправка запросов возможна и позволяет сильно ускорить обмен информацией с сервером.

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

Именно такая стратегия сейчас заложена в метод get_all() в питоновской библиотеке fast_bitrix24 (пиарюсь - библиотеку написал я).

List + get

Составная стратегия, при которой при помощи стратегии "Start increment" от сервера получается сначала список всех ID по методу *.list (с указанием, что нужны только ID - 'select': ['ID']) , а потом через метод *.get получается содержимое всех полей для каждого ID. При этом в обоих шагах используются описанные выше способы ускорения "Объединение запросов в батчи" и "Параллельная отправка батчей".

Тест

Чтобы проверить эффективность этих стратегий, мы провели тест (код теста).

Тест запрашивает страницы лидов (метод crm.lead.list) через 3 вышеописанные стратегии (при этом стратегия "ID filter" реализована в один поток - с начала списка ID). Для каждой стратегии запрашиваются 1, 50, 100 и 200 страниц и замеряется время выполнения запроса.

Тест использует библиотеку fast_bitrix24 для автоматического контроля скорости запросов к серверу Битрикс24.

Тест проводим на 7-й версии REST API на списке в ~35000 лидов.

Результаты теста

Getting 1 pages:ID filter: 0.3 sec.Start increment: 0.73 sec.Getting ID list for the 'list+get' strategy, method crm.lead: 2.17 sec.List + get: 2.61 sec.Getting 50 pages:ID filter: 12.8 sec.Start increment: 21.39 sec.List + get: 1.84 sec.Getting 100 pages:ID filter: 49.67 sec.Start increment: 39.97 sec.List + get: 3.28 sec.Getting 200 pages:ID filter: 99.67 sec.Start increment: 78.05 sec.List + get: 6.36 sec.

Выводы

В целом, стратегии, использующие батчи и параллельные запросы ("Start increment" и "List + get"), показали себя лучше.

Однако при этом, к моему удивлению, стратегия "List + get" оказалась на порядок продуктивнее остальных, даже несмотря на то, что в ней приходится пробегаться по всему списку два раза. (Возможно, эту статью увидят разработчики Битрикс24 и объяснят этот феномен?)

Я не уверен в существовании высокоуровневых библиотек для PHP, позволяющих пользователю реализовывать такие стратегии, не парясь упаковкой запросов в батчи и организацией параллельных запросов с контролем их скорости. Но если вы пишете на Python - милости прошу использовать fast_bitrix24, который позволяет выгружать данные из Битрикс24 со скоростью до тысяч элементов в секунду.

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

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

1. Не используйте глаголы в URL *

* - если это одна из CRUD-операций.

За действие с ресурсом отвечают CRUD-методы запроса: POST - создать (create), GET - получить (read), PUT/PATH - обновить (update), DELETE - удалить (ну вы поняли). Плохо:

POST /users/{userId}/delete - удаление пользователяPOST /bookings/{bookingId}/update - обновление бронировки

Хорошо:

DELETE /users/{userId}PUT /bookings/{bookingId}

2. Используйте глаголы в URL

Плохо:

POST /users/{userId}/books/{bookId}/create - добавить книгу пользователю

Хорошо:

POST /users/{userId}/books/{bookId}/attachPOST /users/{userId}/notifications/send - отправить уведомление пользователю

3. Выделяйте новые сущности

Выше есть пример добавления книги пользователю, возможно, логика вашего приложения подразумевает список избранного, тогда роут может быть и таким:

POST /wishlist/{userId}/{bookId}

4. Используйте один идентификатор ресурса *

* - если ваша структура данных это позволяет.

Это значит если у вас есть записи вида один ко многим, например
бронь -> путешественники (booking->travellers), вам будет достаточно передавать в запросе идентификатор путешественника.

Плохо:

# получение данных путешественникаGET /bookings/{bookingId}/travellers/{travellerId}

Хорошо:

GET /bookings/travellers/{travellerId}

Так же замечу что /bookings/travellers/ лучше чем просто /travellers хорошо придерживаться иерархии данных в своем API.

5. Все ресурсы во множественном числе

Плохо:

GET /user/{userId} - получение данных пользователяPOST /ticket/{ticketId}/book - бронирование билета

Хорошо:

GET /users/{userId}POST /tickets/{ticketId}/book

6. Используйте HTTP-статусы по максимуму

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

• 400 Bad Request - клиент отправил неверный запрос, например, отсутствует обязательный параметр запроса.

• 401 Unauthorized - клиенту не удалось пройти обязательную аутентификацию на сервере для обработки запроса.

• 403 Forbidden - клиент аутентифицирован, но не имеет разрешения на доступ к запрошенному ресурсу.

• 404 Not Found - запрошенный ресурс не существует.

• 409 Conflict - этот ответ отправляется, когда запрос конфликтует с текущим состоянием сервера.

• 500 Internal Server Error - на сервере произошла общая ошибка.

• 503 Service Unavailable - запрошенная услуга недоступна.

7. Модификаторы получения ресурса

Логика построения роутов может быть не связана с архитектурой проекта или структурой базы данных. Например, в бд есть викторины и пройденные викторины - две отдельные таблицы (quizzes и passed_quizzes). Но для апи это могут быть просто викторины, а пройденные викторины это модификатор.

Пример: /quizzes и /quizzes/passed. Здесь quizzes - ресурс (викторины), passed - модификатор (пройденные).

Плохо:

GET /passed-quizzes - получение пройденных викторинGET /booked-tickets - получение забронированных билетовPOST /gold-users - создание премиум пользователя

Хорошо:

GET /tickets/bookedPOST /users/gold

8. Выберите одну структуру ответов

Когда на два запроса к API может быть получен совсем разный по структуре ответ - это грустно. Старайтесь сформировать одну четкую структуру которой всегда будете придерживаться, будет круто еще включить служебные поля, несущие дополнительную информацию.

Плохо:

GET /book/{bookId}{    "name": "Harry Potter and the Philosopher's Stone",    "genre": "fantasy",    "status": 0, # статус вашего приложения    "error": false,     ...}

Хорошо:

GET /book/{bookId}{    "status": 0,    "message": "ok",    "data": {...}}

В этом примере 3 поля универсальны и могут использоваться для любого ответа от апи. status, message - собственный статус и сообщение приложения по которому клиент сможет ориентироваться, эти поля сообщат ему дополнительную информацию о процессе обработки запроса, но не данные ресурса. Например, в нашем приложении в один момент времени, пользователь может проходить только одну викторину. Тогда запрос на начало новой может выдать 409й статус а в полях status и message дополнительную информацию почему была получена ошибка.

9. Все параметры и json в camelCase

9.1 В параметрах запросов
Плохо:

GET /users/{user-id}GET /users/{user_id}GET /users/{userid}

Хорошо:

GET /users/{userId}POST /ticket/{ticketId}/gold

9.2 В теле ответа или принимаемого запроса
Плохо:

{    "ID": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",    "Name": "soccer3000",    "provider_id": 1455,    "Created_At": "25.05.2020"}

Хорошо:

{    "id": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",    "Name": "soccer3000",    "providerId": 1455,    "createdAt": "25.05.2020"}

10. Пользуйтесь Content-Type

Плохо:

GET /tickets.jsonGET /tickets.xml

Хорошо:

GET /tickets// и в хедереСontent-Type: application/json// илиСontent-Type: application/xml

Заключение

Перечисленные выше рекомендации это далеко не весь список способов сделать API лучше. Для дальнейшего изучения рекомендую разобрать спецификации REST API и список кодов http-статусов (вы удивитесь на сколько их много и какие ситуации они охватывают).

А в комментариях, предлагаю написать свою рекомендацию по построению REST API которую вы считаете важной.

Введение

Всем привет, в данной статье будет рассказано, как с использованием технологии C# ASP.NET Core написать простое Rest Api. Сделать Unit-тесты на слои приложений. Отправлять Json ответы. Также покажу, как выложить данное приложение в Docker.

В данной статье не будет описано, как делать клиентскую (далее Front) часть приложения. Здесь я покажу только серверную (далее Back).

Что используем?

Писать код я буду в Visual Studio 2019.

Для реализации приложения, я буду использовать такие библиотеки NuGet:

1. Microsoft.EntityFrameworkCore

2. Microsoft.EntityFrameworkCore.SqlServer

3. Microsoft.EntityFrameworkCore.Tools

Для тестов вот эти библиотеки:

1. Microsoft.NET.Test.Sdk

2. Microsoft.NETCore.App

3. Moq

4. xunit

5. xunit.runner.visualstudio

Для установки пакетов нужно зайти в обозреватель пакетов NuGet, сделать это можно, нажав ПКМ по проекту, и выбрав там пункт управление пакетам NuGet

Что программировать?

Для примера я возьму сильно упрощенную модель сервиса по ремонту автомобилей. В моей модели будут работники, которые будут заниматься ремонтом, автомобили, поступающие на ремонт, и документация по ремонту, которая будет отсылаться в ответе.

Настройка Базы Данных

Для настройки базы данных нужен класс ApplicationContext (реализация будет далее) и строка подключения, которая храниться в файле appsettings.json. В этом классе будут прописаны все зависимости для генерации миграций. Строка подключения нужна для того, чтобы приложение знало в какую БД ей обращаться и с какими параметрами.

Чтобы добавить строку подключения, достаточно зайти в файл appsettings.json и прописать следующие строки:

"ConnectionStrings": { "DefaultConnection": "Server=(localdb)\\mssqllocaldb;Database=testdb;Trusted_Connection=True;" },

Описание слоев приложения

Модели

В слое моделей будут находиться сущности, которые с помощью Entity Framework будут преобразованы в таблицы в базе данных.

Для описания модели в приложении достаточно просто описать класс, с нужными вам полями. Эти поля автоматически будут преобразованы в столбцы таблицы, а название таблицы будет соответствовать названию класса. Так задано по умолчанию, но есть специальные атрибуты, которые позволяют более гибко настраивать хранение данных в БД (но о них не в этой статье).

Первая модель, которая понадобиться для описания сервиса по ремонту - модель сотрудника. Что она будет из себя представлять?

• Уникальный идентификатор сотрудника

• Имя сотрудника

• Должность сотрудника

• Номер телефона для связи с сотрудником

Следующая модель для описания сервиса - автомобили, которые будут поступать на ремонт.

• Уникальный идентификатор автомобиля

• Название автомобиля

• Номер автомобиля

И последняя модель, которую мы уже будем отсылать - документ (выписка) по ремонту.

• Уникальный идентификатор документа

• Сотрудник, который обслуживал автомобиль

• Автомобиль, который был на ремонте

Чтобы модели попали в базу данных, необходимо создать миграцию. Миграция - описание того, как и что будет записано в базу данных. С помощью Entity Framework миграции можно генерировать автоматически. Для этого в пакетном менеджере надо прописать команду "Add-Migration". После этого Entity Framework сгенерирует миграцию по вашим моделям, которые указаны в классе DbContext. Чтобы применить миграцию, используем команду "Update-Database", после этого ваши данные попадут в базу данных (как это применять будет описано далее).

Контроллеры

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

Для возвращаемого значения в контроллерах будут использоваться тип Json. Для этого достаточно в return прописать

new JsonResult(Ваш объект)

В данном примере, я покажу как сделать методы для GET, POST, PUT и DELETE запросов. В GET-запросе я буду выбирать все существующие документы и передавать их на Front, а в POST-запросе я буду вызывать сервис по ремонту автомобиля и возвращать выписку по ремонту, PUT будет отвечать за обновление существующего документа и DELETE за удаление документа.

DAO (Репозитории)

Репозитории нужны как посредники для обеспечения работы с БД, чтобы исключить прямое взаимодействие человека с данными. Это нужно для того, чтобы сокрыть логику работы автоматизировать многие моменты работы с БД, а также для безопасной работы с данными.

В своем приложении я сделал репозиторий, который может принимать любую модель, и выполнять такие действия как get, get all, update, create, delete.

Сервисы

Сервисы - такие классы, которые содержат в себе бизнес-логику приложения. Представляют из себя класс с методами для решения той или иной задачи.

В качестве примера сервиса, я сделал класс, всего с одним методом Work. Этот метод имитирует работу моего сервиса по починке машин. В этом методе нанимается рабочий, заводится автомобиль и заполняется документ о его починке.

Реализация

Теперь, когда описано что и как будет устроено в приложении можно приступить и к реализации.

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

При создании нового проекта, я выбрал веб-приложение ASP.NET Core, далее прописал его название (RestApi) и выбрал папку, где оно будет храниться. На экране выбора шаблона выбрал API.

Далее приступим к самому приложению.

Структура

Я разделил все приложение по папкам (также Unit-тесты в отдельном проекте) и получил вот такую структуру мое приложения:

Модели

Для реализации моделей я сделал абстрактный класс BaseModel. Он понадобиться в будущем для корректного наследования, а также в нем прописан Id каждой, модели (это помогает не дублировать код):

 public abstract class BaseModel { public Guid Id { get; set; } }

Далее вышеописанные модели:

 public class Car : BaseModel { public string Name { get; set; } public string Number { get; set; } }

 public class Document : BaseModel { public Guid CarId { get; set; } public Guid WorkerId { get; set; } public virtual Car Car { get; set; } public virtual Worker Worker { get; set; } }

 public class Worker : BaseModel { public string Name { get; set; } public string Position { get; set; } public string Telephone { get; set; } }

Репозиторий

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

Интерфейс:

public interface IBaseRepository<TDbModel> where TDbModel : BaseModel    {        public List<TDbModel> GetAll();        public TDbModel Get(Guid id);        public TDbModel Create(TDbModel model);        public TDbModel Update(TDbModel model);        public void Delete(Guid id);    }

Реализация:

    public class BaseRepository<TDbModel> : IBaseRepository<TDbModel> where TDbModel : BaseModel    {        private ApplicationContext Context { get; set; }        public BaseRepository(ApplicationContext context)        {            Context = context;        }        public TDbModel Create(TDbModel model)        {            Context.Set<TDbModel>().Add(model);            Context.SaveChanges();            return model;        }        public void Delete(Guid id)        {            var toDelete = Context.Set<TDbModel>().FirstOrDefault(m => m.Id == id);            Context.Set<TDbModel>().Remove(toDelete);            Context.SaveChanges();        }        public List<TDbModel> GetAll()        {            return Context.Set<TDbModel>().ToList();        }        public TDbModel Update(TDbModel model)        {            var toUpdate = Context.Set<TDbModel>().FirstOrDefault(m => m.Id == model.Id);            if (toUpdate != null)            {                toUpdate = model;            }            Context.Update(toUpdate);            Context.SaveChanges();            return toUpdate;        }        public TDbModel Get(Guid id)        {            return Context.Set<TDbModel>().FirstOrDefault(m => m.Id == id);        }    }

Сервис

Сервис также как и репозиторий имеет интерфейс и его реализацию.

Интерфейс:

public interface IRepairService    {        public void Work();    }

Реализация:

public class RepairService : IRepairService    {        private IBaseRepository<Document> Documents { get; set; }        private IBaseRepository<Car> Cars { get; set; }        private IBaseRepository<Worker> Workers { get; set; }        public void Work()        {            var rand = new Random();            var carId = Guid.NewGuid();            var workerId = Guid.NewGuid();            Cars.Create(new Car            {                Id = carId,                Name = String.Format($"Car{rand.Next()}"),                Number = String.Format($"{rand.Next()}")            });            Workers.Create(new Worker            {                Id = workerId,                Name = String.Format($"Worker{rand.Next()}"),                Position = String.Format($"Position{rand.Next()}"),                Telephone = String.Format($"8916{rand.Next()}{rand.Next()}{rand.Next()}{rand.Next()}{rand.Next()}{rand.Next()}{rand.Next()}")            });            var car = Cars.Get(carId);            var worker = Workers.Get(workerId);            Documents.Create(new Document {                CarId = car.Id,                WorkerId = worker.Id,                Car = car,                Worker = worker            });        }    }

Контроллер

У меня в приложении всего один контроллер, но по его шаблону можно сделать сколько угодно контроллеров. Когда приложение запущено, для того чтобы обратиться к методу контроллера с Front части приложения, достаточно передать запрос, который выглядит примерно вот так:

ДоменноеИмя/НазваниеКонтроллера/НазваниеМетода?Параметры(если есть)

Пути гибко настраиваются с помощью специальных атрибутов (о них не в этой статье).

Мой MainController:

[ApiController]    [Route("[controller]")]    public class MainController : ControllerBase    {        private IRepairService RepairService { get; set; }        private IBaseRepository<Document> Documents { get; set; }        public MainController(IRepairService repairService, IBaseRepository<Document> document )        {            RepairService = repairService;            Documents = document;        }        [HttpGet]        public JsonResult Get()        {            return new JsonResult(Documents.GetAll());        }        [HttpPost]        public JsonResult Post()        {            RepairService.Work();            return new JsonResult("Work was successfully done");        }        [HttpPut]        public JsonResult Put(Document doc)        {            bool success = true;            var document = Documents.Get(doc.Id);            try            {                if (document != null)                {                    document = Documents.Update(doc);                }                else                {                    success = false;                }            }            catch (Exception)            {                success = false;            }            return success ? new JsonResult($"Update successful {document.Id}") : new JsonResult("Update was not successful");        }        [HttpDelete]        public JsonResult Delete(Guid id)        {            bool success = true;            var document = Documents.Get(id);            try            {                if (document != null)                {                    Documents.Delete(document.Id);                }                else                {                    success = false;                }            }            catch (Exception)            {                success = false;            }            return success ? new JsonResult("Delete successful") : new JsonResult("Delete was not successful");        }    }

Application Context

ApplicationContext класс, который унаследован от класса DbContext. В нем прописываются все DbSet. С их помощью приложение знает, какие модели должны быть в базе данных, а какие нет.

public class ApplicationContext: DbContext    {        public DbSet<Car> Cars { get; set; }        public DbSet<Document> Documents { get; set; }        public DbSet<Worker> Workers { get; set; }        public ApplicationContext(DbContextOptions<ApplicationContext> options): base(options)        {            Database.EnsureCreated();        }    }

Настройка зависимостей и инжектирования

А теперь немного про инжектирование. Правильная настройка зависимостей проекта Asp.net core позволяет упростить его работу и избежать лишнего написания кода. Все зависимости прописываются в файле Startup.cs.

Что я связывал? Я связывал интерфейс репозитория с репозиторием каждой модели (далее будет видно, что имеется ввиду), также я связал интерфейс сервиса с его реализацией.

Также в этом же файле прописываются настройки для базы данных. Помните про строку подключения из начала статьи? Так вот сейчас мы ее и используем для настройки БД.

Вот как выглядит мой файл Startup.cs:

public Startup(IConfiguration configuration)        {            Configuration = configuration;        }        public IConfiguration Configuration { get; }        // This method gets called by the runtime. Use this method to add services to the container.        public void ConfigureServices(IServiceCollection services)        {            string connection = Configuration.GetConnectionString("DefaultConnection");            services.AddMvc();            services.AddDbContext<ApplicationContext>(options =>                options.UseSqlServer(connection));            services.AddTransient<IRepairService, RepairService>();            services.AddTransient<IBaseRepository<Document>, BaseRepository<Document>>();            services.AddTransient<IBaseRepository<Car>, BaseRepository<Car>>();            services.AddTransient<IBaseRepository<Worker>, BaseRepository<Worker>>();        }        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)        {            if (env.IsDevelopment())            {                app.UseDeveloperExceptionPage();            }            app.UseHttpsRedirection();            app.UseRouting();            app.UseAuthorization();            app.UseEndpoints(endpoints =>            {                endpoints.MapControllers();            });        }

Не забудьте создать БД перед запуском приложения. Для этого в Консоле диспетчера пакетов нужно прописать следующие команды:

Add-Migration init (или любое другое имя)

Update-Database

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

Тестирование

Здесь я покажу как создать UNIT-тесты для контроллера и сервиса. Для тестов я сделал отдельный проект (библиотека классов .Net Core).

Тест для контроллера

public class MainControllerTests    {        [Fact]        public void GetDataMessage()        {            var mockDocs = new Mock<IBaseRepository<Document>>();            var mockService = new Mock<IRepairService>();            var document = GetDoc();            mockDocs.Setup(x => x.GetAll()).Returns(new List<Document> { document });            // Arrange            MainController controller = new MainController(mockService.Object, mockDocs.Object);            // Act            JsonResult result = controller.Get() as JsonResult;            // Assert            Assert.Equal(new List<Document> { document }, result?.Value);        }        [Fact]        public void GetNotNull()        {            var mockDocs = new Mock<IBaseRepository<Document>>();            var mockService = new Mock<IRepairService>();            mockDocs.Setup(x => x.Create(GetDoc())).Returns(GetDoc());            // Arrange            MainController controller = new MainController(mockService.Object, mockDocs.Object);            // Act            JsonResult result = controller.Get() as JsonResult;            // Assert            Assert.NotNull(result);        }        [Fact]        public void PostDataMessage()        {            var mockDocs = new Mock<IBaseRepository<Document>>();            var mockService = new Mock<IRepairService>();            mockDocs.Setup(x => x.Create(GetDoc())).Returns(GetDoc());            // Arrange            MainController controller = new MainController(mockService.Object, mockDocs.Object);            // Act            JsonResult result = controller.Post() as JsonResult;            // Assert            Assert.Equal("Work was successfully done", result?.Value);        }        [Fact]        public void UpdateDataMessage()        {            var mockDocs = new Mock<IBaseRepository<Document>>();            var mockService = new Mock<IRepairService>();            var document = GetDoc();            mockDocs.Setup(x => x.Get(document.Id)).Returns(document);            mockDocs.Setup(x => x.Update(document)).Returns(document);            // Arrange            MainController controller = new MainController(mockService.Object, mockDocs.Object);            // Act            JsonResult result = controller.Put(document) as JsonResult;            // Assert            Assert.Equal($"Update successful {document.Id}", result?.Value);        }        [Fact]        public void DeleteDataMessage()        {            var mockDocs = new Mock<IBaseRepository<Document>>();            var mockService = new Mock<IRepairService>();            var doc = GetDoc();            mockDocs.Setup(x => x.Get(doc.Id)).Returns(doc);            mockDocs.Setup(x => x.Delete(doc.Id));            // Arrange            MainController controller = new MainController(mockService.Object, mockDocs.Object);            // Act            JsonResult result = controller.Delete(doc.Id) as JsonResult;            // Assert            Assert.Equal("Delete successful", result?.Value);        }        public Document GetDoc()        {            var mockCars = new Mock<IBaseRepository<Car>>();            var mockWorkers = new Mock<IBaseRepository<Worker>>();            var carId = Guid.NewGuid();            var workerId = Guid.NewGuid();            mockCars.Setup(x => x.Create(new Car()            {                Id = carId,                Name = "car",                Number = "123"            }));            mockWorkers.Setup(x => x.Create(new Worker()            {                Id = workerId,                Name = "worker",                Position = "manager",                Telephone = "89165555555"            }));            return new Document            {                Id = Guid.NewGuid(),                CarId = carId,                WorkerId = workerId            };        }    }

В данных тестах проверяется работа каждого метода контроллера на их корректное выполнение.

Тест для сервиса

public class RepairServiceTests    {        [Fact]        public void WorkSuccessTest()        {            var serviceMock = new Mock<IRepairService>();            var mockCars = new Mock<IBaseRepository<Car>>();            var mockWorkers = new Mock<IBaseRepository<Worker>>();            var mockDocs = new Mock<IBaseRepository<Document>>();            var car = CreateCar(Guid.NewGuid());            var worker = CreateWorker(Guid.NewGuid());            var doc = CreateDoc(Guid.NewGuid(), worker.Id, car.Id);            mockCars.Setup(x => x.Create(car)).Returns(car);            mockDocs.Setup(x => x.Create(doc)).Returns(doc);            mockWorkers.Setup(x => x.Create(worker)).Returns(worker);            serviceMock.Object.Work();            serviceMock.Verify(x => x.Work());        }        private Car CreateCar(Guid carId)        {            return new Car()            {                Id = carId,                Name = "car",                Number = "123"            };        }        private Worker CreateWorker(Guid workerId)        {            return new Worker()            {                Id = workerId,                Name = "worker",                Position = "manager",                Telephone = "89165555555"            };        }        private Document CreateDoc(Guid docId, Guid workerId, Guid carId)        {            return new Document            {                Id = docId,                CarId = carId,                WorkerId = workerId            };        }    }

В тесте для сервиса есть всего один тест для метода Work. Тут проверяется отработал этот метод или нет.

Запуск тестов

Чтобы запустить тесты достаточно зайти во вкладку Тест и нажать выполнить все тесты.

Выкладываем в Docker

В финале я покажу, как выложить данное приложение в Docker Hub. В Visual Studio 2019 это сделать крайне просто. Учтите, что у вас уже должен быть профиль в Docker и создан репозиторий в Docker Hub.

Нажимаете ПКМ на ваш проект и выбираете пункт опубликовать.

Там выбираем Docker Container Registry

На следующем окне, надо выбрать Docker Hub

Далее введите свои учетные данный Docker.

Если все прошло успешно, то осталось сделать последнюю вещь, нажать кнопку Опубликовать.

Готово, вы опубликовали свое приложение в Docker Hub!

Заключение

В данной статье я показал, как использовать возможности C# ASP.NET Core для создания простого Rest API. Показал, как создавать модели, записывать их в БД, как создать свой репозиторий, как использовать сервисы и как создавать контроллеры, которые будут отправлять JSON ответы на ваш Front. Также показал, как сделать Unit-тесты для слоев контроллеров и сервисов. И в финале показал, как выложить приложение в Docker.

Надеюсь, что данная статья будет вам полезна!