Сборка простого приложения на Koa

Development, Java | Amber | Комментировать запись

Koa – это новый веб-фреймворк, созданный командой Express. Он разрабатывался как более современная и минималистичная версия Express.

Среди основных характеристик Koa – поддержка и использование новых функций JavaScript, в том числе генераторов и async/await. Koa поставляется без промежуточного ПО, хотя его можно добавить с помощью пользовательских плагинов.

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

Требования

• Локальная установка Node.js (вы можете получить такую, следуя инструкциям в зависимости от вашей системы: mac OS, CentOS, Ubuntu, Debian).
• Практические навыки работы с синтаксисом JavaScript и ES6.

Это руководство было протестировано на версиях Node v15.14.0, npm v7.10.0, koa v2.13.1, @ koa/router v10.0.0 и koa-ejs v4.3.0.

1: Настройка проекта

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

mkdir koa-example

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

У нас есть каталог проекта koa-example. Перейдите в него.

cd koa-example

Затем инициализируйте свой проект Node из этого каталога.

npm init -y

После выполнения команды npm init у вас будет файл package.json со стандартной конфигурацией.

Затем запустите эту команду, чтобы установить Koa:

npm install koa@2.13.1

Теперь у нас есть приложение, и оно готово к использованию фреймворка Koa.

2: Создание сервера Koa

Сначала создайте файл index.js. Затем откройте index.js в редакторе кода и добавьте следующие строки:

'use strict';

const Koa = require('koa');

const app = new Koa();

app.use(ctx => {

  ctx.body = 'Hello World';

});

app.listen(1234);

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

node index.js

Посетите свое приложение в браузере по адресу http://localhost:1234.

3: Добавление маршрутов и визуализации представления

Как упоминалось ранее, Koa.js поставляется без промежуточного ПО и, в отличие от своего предшественника, Express, по умолчанию не обрабатывает маршрутизацию.

Чтобы включить маршруты в приложении Koa, мы установим библиотеку промежуточного по для маршрутизации по имени Koa Router.

Откройте окно терминала и выполните следующую команду:

npm install @koa/router@10.0.0

Примечание: Ранее для этого использовали пакет koa-router, но теперь официально поддерживаемым пакетом является @koa/router.

Чтобы использовать маршрутизатор в своем приложении, внесите в файл index.js такие изменения:

'use strict';

const Koa = require('koa');

const Router = require('@koa/router');

const app = new Koa();

const router = new Router();

router.get('koa-example', '/', (ctx) => {

  ctx.body = 'Hello World';

});

app

  .use(router.routes())

  .use(router.allowedMethods());

app.listen(1234);

Этот код определяет маршрут по базовому URL-адресу вашего приложения Koa (http://localhost:1234) и регистрирует этот маршрут.

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

Как мы говорили ранее, Koa – это минималистичный фреймворк, поэтому для рендеринга представления с помощью механизма шаблонов вам потребуется установить библиотеку промежуточного ПО. Для этой цели Koa поддерживает несколько библиотек, но в этом мануале мы будем использовать Koa ejs.

Откройте окно терминала и выполните следующую команду:

npm install koa-ejs@4.3.0

Затем внесите изменения в файл index.js, чтобы зарегистрировать шаблон:

'use strict';

const Koa = require('koa');

const Router = require('@koa/router');

const render = require('koa-ejs');

const path = require('path');

const app = new Koa();

const router = new Router();

render(app, {

  root: path.join(__dirname, 'views'),

  layout: 'index',

  viewExt: 'html',

  cache: false,

  debug: true

});

router.get('koa-example', '/', (ctx) => {

  ctx.body = 'Hello World';

});

app

  .use(router.routes())

  .use(router.allowedMethods());

app.listen(1234);

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

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

// ...

router.get('koa-example', '/', (ctx) => {

  let koalaFacts = [];

  koalaFacts.push({

    meta_name: 'Color',

    meta_value: 'Black and white'

  });

  koalaFacts.push({

    meta_name: 'Native Country',

    meta_value: 'Australia'

  });

  koalaFacts.push({

    meta_name: 'Animal Classification',

    meta_value: 'Mammal'

  });

  koalaFacts.push({

    meta_name: 'Life Span',

    meta_value: '13 - 18 years'

  });

  koalaFacts.push({

    meta_name: 'Are they bears?',

    meta_value: 'No'

  });

  return ctx.render('index', {

    attributes: koalaFacts

  });

})

// ...

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

Далее нужно создать этот каталог и файл. Откройте views/index.html и добавьте следующие строки кода:

<h2>Koala - a directory Koala of attributes</h2>

<ul class="list-group">

  <% attributes.forEach( function(attribute) { %>

    <li class="list-group-item">

      <%= attribute.meta_name %> - <%= attribute.meta_value %>

    </li>

  <% }) %>

</ul>

Теперь при запуске приложения в веб-браузере будет отображаться следующее:

Koala - a directory Koala of attributes

Color - Black and white

Native Country - Australia

Animal Classification - Mammal

Life Span - 13 - 18 years

Are they bears? - No

Дополнительные сведения о промежуточном шаблоне koa-ejs вы найдете в документации библиотеки.

4: Обработка ошибок и ответов

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

Используем файл index.js в качестве примера. Внесите в этот код следующие изменения:

'use strict';

const Koa = require('koa');

const Router = require('@koa/router');

const render = require('koa-ejs');

const path = require('path');

const app = new Koa();

const router = new Router();

app.use(async (ctx, next) => {

  try {

    await next()

  } catch(err) {

    console.log(err.status)

    ctx.status = err.status || 500;

    ctx.body = err.message;

  }

});

// ...

Этот блок кода перехватит любую ошибку, возникшую во время выполнения приложения.

Вы можете проверить это, добавив ошибку в тело функции определенного нами маршрута:

// ...

router.get('error', '/error', (ctx) => {

  ctx.throw(500, 'internal server error');

});

app

  .use(router.routes())

  .use(router.allowedMethods());

app.listen(1234);

Теперь при запуске приложения с секцией /error в ссылке в веб-браузере будет отображаться следующее сообщение:

internal server error

Объект ответа Koa обычно встраивается в его объект контекста. Давайте покажем пример настройки ответов через определение маршрута:

// ...

router.get('status', '/status', (ctx) => {

  ctx.status = 200;

  ctx.body   = 'ok';

})

app

  .use(router.routes())

  .use(router.allowedMethods());

app.listen(1234);

Теперь при запуске приложения в веб-браузере с секцией /status в адресе будет отображаться следующее:

ok

Теперь приложение Koa обрабатывает ошибки и ответы.

Заключение

В этой статье вы узнали, как работает фреймворк Koa и как реализовать в проекте Koa его базовые функции. Koa – это минималистичный и гибкий фреймворк, функционал которого можно легко расширить. Из-за его сходства с Express некоторые разработчики даже называют его «Express 5.0».