lulzneko

Serverless Framework と TypeScript で Hello と Version の Web API を実装

前回サーバーレスなアプリケーションのひな形を作りました。
今回は、ひな形で作られた AWS Lambda のソースを Hello World にし、また新しくアプリケーションのバージョンを返す Version Web API を追加します。

シリーズの記事

Serverless Framework と TypeScript でサーバレス開発事始め
Serverless Framework と TypeScript で Hello と Version の Web API を実装 (本記事)

環境

開発者の環境は以下となります。

Windows 10 64bit
Visual Studio Code
Node.js 9
TypeScript 2.7
Serverless Framework 1.26.0

主な実行環境について、また全部稼働まではいきませんが以下を想定しています。
※ Amazon API Gateway などは、Serverless Framework が自動設定するので省略、明示的に使うものとしてリストになります。

Amazon S3
AWS Lambda

ベースとなるソースコード

前回の続きとなりますので、こちら https://github.com/riotz-works/samples-hello-serverless/tree/0.0.1 をもとに追加開発します。

本記事と一緒に作成する場合は前回のソースもしくはタグを指定してチェックアウトしたソースをお使いください。

1
2
3

c:\Temp\nlog>git clone --depth 1 -b 0.0.1 https://github.com/riotz-works/samples-hello-serverless.git
Cloning into 'samples-hello-serverless'...
(省略)

Hello Web API の改修

Serverless Framework のボイラープレートで生成した Lambda のプログラムは handler.js で以下のようになっています。
これを Hello World の Web API へ改修するにあたり、このままで response の body を変えるだけでよさそうです。今回は message を 'Hello Serverless !!' にし、input は削除することにします。

import { APIGatewayEvent, Callback, Context, Handler } from 'aws-lambda';

export const hello: Handler = (event: APIGatewayEvent, context: Context, cb: Callback) => {
  const response = {
    statusCode: 200,
    body: JSON.stringify({
      message: 'Go Serverless Webpack (Typescript) v1.0! Your function executed successfully!',
      input: event,
    }),
  };

  cb(null, response);
}

そしてプロジェクトのディレクトリ直下で汎用的な名前の handler.js だと、このあと追加する Version Web API の配置などで困ります。
まずはディレクトリ配置を見直し、Lambda のハンドラ・ファンクションのソースが入っていることがわかるように src/handler 配下に置くことにします。
続いて Hello Web API のハンドラに対応したファンクションのファイル名として greetings.ts とすることにします。

ファイル名と配置を変えたので Lambda の定義をしている serverless.yml を修正します。
hello ファンクションのハンドラは handler.hello と定義されていましたが、greetings ファクション src/handler/greetings.hello ハンドラに変更します。

Hello Web API ができました。
この時点で serverless deploy コマンドでデプロイすることもできます。(–aws-profile [profilename] を忘れずに)

Version Web API の作成

Hello Web API が作れましたがボイラープレートのままだったので、新しく Web API を追加したいと思います。
とりあえず、アプリケーションのバージョンを返す Version Web API を作ることにします。
仕様は「HTTP GET /version で package.json の version を返す」にします。

まずは、Lambda のハンドラのソースを配置する src/handler に systems.ts を作ります。
他にシステム関連の Web API の想定はありませんが、システム関連 Web API のハンドラを配置する systems.ts に version のハンドラを追加するイメージにしました。

コードは以下のようにします。(このコードを使う場合は、１行目の Copyright は書き換えてください)

/* Copyright 2018 Riotz Works. */
import { APIGatewayEvent, Callback, Context, Handler } from 'aws-lambda';
import { version } from '../../package.json';

/**
 * System Web API's AWS Lambda handler function.
 *
 * @param event – event data.
 * @param context – runtime information of the Lambda function that is executing.
 * @param callback – optional callback to return information to the caller, otherwise return value is null.
 * @see http://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html
 */
export const handle: Handler = (event: APIGatewayEvent, context: Context, cb?: Callback): void => {

  const response = {
    'body': JSON.stringify({
      'version': version
    }),
    'statusCode': 200
  };

  if (cb !== undefined) {
    cb(null, response);  // tslint:disable-line
  } else {
    context.succeed(response);
  }
};

主なキー・ポイントは以下になります。先の Hello Web API と若干異なる部分 (context.succeed() とか) がありますが詳細は後日の記事として、基本的には変わりありません。

３行目で、バージョンのもとになる package.json を systems.ts の相対パスで指定し version 要素をインポートします
17行目で、インポートした version 属性の値をレスポンス・ボディとしてセットします

Visual Studio Code の環境によってはエラーが出ないかもしれませんが、３行目のインポート文でエラーにあります。

何も表示されていなくても serverless package を実行するとエラーが出力されます。

C:\Temp\samples-hello-serverless> serverless package
Serverless: Bundling with Webpack...
(省略)
ERROR in C:\Develop\repos\riotz\samples-hello-serverless\src\handler\systems.ts
(3,25): error TS2307: Cannot find module '../../package.json'.

これは package.json のモジュール定義が存在しないためになります。
このように型定義などを確認してくれるのが TypeScript のありがたいところです。
一方で今回のは若干無茶な実装でした。標準モジュールには存在しませんし、適切なモジュール定義をとってくることも難しいでしょう。さりとて package.json と何か別ファイルで version のダブルメンテはしたくないです。。。ということで、モジュール定義を追加することにします。
ソースディレクトリの src に types.d.ts を追加します。.d.ts ファイルでしたら特に命名規則はなく typing.d.ts もよく見かけます。

コードは以下のようにします。(１行目の Copyright は書き換えてください)

/* Copyright 2018 Riotz Works. */

/**
 * Module declaration for JSON file.
 */
declare module '*.json' {

  /** version element of package.json using Version API. */
  const version: string | undefined;
}

*.json なので、モジュール定義が見つからなかった JSON ファイルの型定義になります。
その中に version が文字列として存在することを定義しますが、これは全ての JSON ファイルに当てはまることではないので、型定義は string | undefined としドキュメントで注釈しました。
頑張ると package.json 固有のモジュール定義もできたのですが version を取得するだけにしては複雑になりすぎたので、このあたりを落としどころとしました。

最後に serverless.yml に Version Web API の Lambda 定義を追加します。
functions: greetings: の下に追加します。

systems:
  handler: src/handler/systems.handle
  events:
    - http:
        method: get
        path: version

Version Web API ができました。

デプロイ

AWS 環境へデプロイします。前回のデプロイと稼働テスト同様に、AWS のプロファイを参照して serverless deploy --aws-profile [profilename] を実行します。

endpoints に hello と version の URL が出力されるので、それぞれブラウザでアクセスすると、プログラムした JSON が返ってきます。

ソースコード

今回作成した部分までのソースを GitHub へアップしました。
https://github.com/riotz-works/samples-hello-serverless/tree/0.0.2

Hello Web API はボイラープレートのレスポンスを改修しただけだったので特に大きな変化はありませんでした。一方で Version Web API は新しく追加となりましたし、両方のプログラムを配置するためにプロジェクトの構造も変化させました。

Hello と Version で実装レベルが異なっている部分はありますが、これについては次の記事で確認しながら合わせこみをしていきたいと思います。できれば TypeScript のコンパイラ設定や Lint にまでふれられたらと思います。

Author: lulzneko