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».