序章

Koa は、Expressの背後にあるチームによって作成された新しいWebフレームワークです。 Expressのモダンでミニマリストなバージョンを目指しています。

その特徴のいくつかは、ジェネレーター async /awaitなどの新しいJavaScript機能のサポートと依存です。 Koaにはミドルウェアも付属していませんが、カスタムおよび既存のプラグインを使用して拡張できます。

この記事では、Koaフレームワークについて詳しく学び、その機能と哲学に慣れるためのアプリを作成します。

前提条件

この記事をフォローしたい場合は、次のものが必要になります。

注:このチュートリアルは、Koa1.0からKoa2.0に改訂されました。 1.0の実装を更新するには、移行ドキュメントを参照してください。

このチュートリアルは、ノードv15.14.0、npm v7.10.0、koa v2.13.1、@koa/router v10.0.0、およびkoa-ejsv4.3.0で検証されました。 。

ステップ1—プロジェクトの設定

まず、プロジェクトの新しいディレクトリを作成します。 これは、ターミナルで以下のコマンドをコピーして実行することで実行できます。

  1. mkdir koa-example

注:プロジェクトには任意の名前を付けることができますが、この記事ではプロジェクト名とディレクトリとしてkoa-exampleを使用します。

この時点で、プロジェクトディレクトリkoa-exampleが作成されました。 新しく作成されたプロジェクトディレクトリに移動します。

  1. cd koa-example

次に、ディレクトリ内からNodeプロジェクトを初期化します。

  1. npm init -y

npm initコマンドを実行すると、デフォルト構成のpackage.jsonファイルが作成されます。

次に、次のコマンドを実行してKoaをインストールします。

  1. npm install koa@2.13.1

これで、アプリケーションでKoaを使用する準備が整いました。

ステップ2—Koaサーバーを作成する

まず、index.jsファイルを作成します。 次に、選択したコードエディタを使用して、index.jsファイルを開き、次のコード行を追加します。

index.js
'use strict';

const Koa = require('koa');
const app = new Koa();

app.use(ctx => {
  ctx.body = 'Hello World';
});

app.listen(1234);

上記のコードでは、ポート1234で実行されるKoaアプリケーションを作成しました。 次のコマンドを使用してアプリケーションを実行できます。

  1. node index.js

そして、http://localhost:1234のアプリケーションにアクセスしてください。

ステップ3—ルーティングとビューレンダリングを追加する

前述のように、Koa.jsにはミドルウェアが含まれていません。また、その前身であるExpressとは異なり、デフォルトではルーティングを処理しません。

Koaアプリにルートを実装するには、Koaでルーティングするためのミドルウェアライブラリ KoaRouterをインストールします。

ターミナルウィンドウを開き、次のコマンドを実行します。

  1. npm install @koa/router@10.0.0

注:以前はkoa-routerが推奨パッケージでしたが、@koa/routerが正式にサポートされるパッケージになりました。

アプリケーションでルーターを使用するには、index.jsファイルを修正します。

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(http://localhost:1234)でルートを定義し、このルートをKoaアプリケーションに登録します。

Koa.jsアプリケーションでのルート定義の詳細については、KoaRouterライブラリのドキュメントにアクセスしてください。

以前に確立されたように、Koaは最小限のフレームワークとして提供されるため、テンプレートエンジンを使用してビューレンダリングを実装するには、ミドルウェアライブラリをインストールする必要があります。 選択できるライブラリはいくつかありますが、この記事では Koaejsを使用します。

ターミナルウィンドウを開き、次のコマンドを実行します。

  1. npm install koa-ejs@4.3.0

次に、index.jsファイルを修正して、テンプレートを以下のスニペットに登録します。

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
  });
})

// ...

基本ルートは、viewsディレクトリにあるindex.htmlファイルをレンダリングします。

次に、このディレクトリとファイルを作成します。 index.htmlを開き、次のコード行を追加します。

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>

これで、アプリケーションを実行してWebブラウザーで観察すると、次のように表示されます。

Output
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ファイルを例として使用して、コードに次の変更を加えます。

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;
  }
});

// ...

このコードブロックは、アプリケーションの実行中にスローされたエラーをキャッチします。

定義したルートの関数本体にエラーをスローすることで、これをテストできます。

index.js
// ...

router.get('error', '/error', (ctx) => {
  ctx.throw(500, 'internal server error');
});

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

app.listen(1234);

これで、アプリケーションを実行してWebブラウザで/errorを観察すると、次のように表示されます。

Output
internal server error

Koa応答オブジェクトは通常、そのコンテキストオブジェクトに埋め込まれています。 ルート定義を使用して、応答を設定する例を示しましょう。

index.js
// ...

router.get('status', '/status', (ctx) => {
  ctx.status = 200;
  ctx.body   = 'ok';
})

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

app.listen(1234);

これで、アプリケーションを実行してWebブラウザで/statusを観察すると、次のように表示されます。

Output
ok

これで、アプリケーションがエラーと応答を処理します。

結論

この記事では、Koaの簡単な紹介と、Koaプロジェクトでいくつかの一般的な機能を実装する方法について説明しました。 Koaは、この記事で示したよりも多くの機能に拡張できる、最小限の柔軟なフレームワークです。 Expressとの未来的な類似性のために、一部の人はそれを精神的にExpress5.0とさえ説明しています。