lulzneko
サーバーレス

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

前回サーバーレスなアプリケーションのひな形を作りました。
今回は、ひな形で作られたAWS Lambdaのソースを Hello World にし、また新しくアプリケーションのバージョンを返す 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は削除することにします。

1
2
3
4
5
6
7
8
9
10
11
12
13
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 は書き換えてください)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
/* 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を実行するとエラーが出力されます。

1
2
3
4
5
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 は書き換えてください)

1
2
3
4
5
6
7
8
9
10
/* 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:の下に追加します。

1
2
3
4
5
6
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