AWS Amplify with AppSyncのベタープラクティス
Amplify with AppSyncでの開発や運用を通して見つけたプラクティスをまとめました。
皆さんの開発の助けになれば幸いです。
前提
- Amplify上に展開しているアプリケーションはReact x TypeScriptで構成されていることを前提にしています。
- Amplify cliで運用するにあたってのプラクティス紹介が中心なので、AmplifyやAppSyncそのものの説明などはしていません。
- これらのプラクティスがどんなケースでも有効というわけではないので、プロジェクトに合わせて使えそうなものを採用してみてください。
- ここに載っているもの以外でみなさんが実践されている/ご存知の知見があれば、是非シェア頂けると助かります！
環境を分ける
Amplifyには開発環境を分離できる機能が備わっています。
以下の図のように、開発環境や本番環境毎に切り替えることが出来るので、開発基盤を作る際にまずは環境を分けるのが良いと思います。
画像はAmplify Docs - Overviewより拝借
具体的な方法はAmplify Docs - TEAM ENVIRONMENTSや、Amplify Multi Environment でチーム開発を整備するを参照ください。
Amplifyリソースのgitignoreは死守する
Amplify cliなどで最初のリソースを構築した際、gitignoreにはAmplify関連で以下のようなファイルが含まれていると思います。これらは何があってもignoreし続けましょう。
自分が携わっていたプロダクトでは初期の段階でignoreすべきリソースがgit管理されてしまっていたようで、誰かがamplify initなどする度に差分が大量にでて後始末が大変でした...。仕様をよく知らない人にとっては「そもそもこの大量の差分が出たファイルはgit管理しておくべきものなのか？」という判断がつかず、余計な確認コストが発生します（いやほんとマジで...）。
特にプロダクトの立ち上げ期の場合には動かすこと重視でこの辺のリソースが誤って紛れ込む事があるかもしれませんが、早い段階で掃除しておきましょう。
#amplify
amplify/\#current-cloud-backend
amplify/.config/local-*
amplify/mock-data
amplify/backend/amplify-meta.json
amplify/backend/awscloudformation
build/
dist/
node_modules/
aws-exports.js
awsconfiguration.json
amplifyconfiguration.json
amplify-build-config.json
amplify-gradle-config.json
amplifytools.xcconfig
ちなみに、何をignoreスべきかというのは時々ISSUEで議論されているので、覗いてみると新しい知見が得られるかもしれません。
参考: amplify/.config should be in .gitignore?
バックエンド（AppSync）関連のリソースは出来る限りコード化しておく
AmplifyでAppSyncを使う場合、バックエンドのリソースの大部分をAWSのサービスを利用すると思います（DynamoDB, Lambda, etc.）。その際にどのGraphQLでどのようなVTL定義を使っているのか、どのリソースとどのリソースがどのように対応しているかなどはコードに落とし込んでおきたいところです。
そうしないと例えばある程度開発が進んだ段階で「見込み顧客にデモできる環境がほしいんだけど〜」みたいなケースが出てきた際に非常に厄介です。今ある環境の設定をAWSのwebコンソールから見ながら手動で新しい環境に設定を移植するのはさぞ辛いでしょう...。
逆に言うとこの辺りの設定をコードで落とし込んでさえ入れば、新しく環境を構築したい際には amplify add env で環境を追加して amplify push でAWS上に完全なリソースが構築されます（完璧にコード化できなかったとしても、手作業の割合を減らすことはできます）。
具体的な方法は以下に書いてあるので、是非とも導入すると良いと思います。
デプロイは自動化しておく
速いうちからデプロイはすべて自動化しましょう....。開発が進むにつれて色々なリソースが追加されていき、デプロイ時の影響が幅広く発生してしまうかもしれません。さっさと自動化してしまいましょう。
フロントリソースをAmplifyへデプロイするのはAWSのwebコンソールでAmplifyを検索してやっていけますが、チョット面倒なのは amplify push です。開発環境では手元で amplify push を実行して結果を確認したりデバッグしたりするかもしれませんが、他の環境では不要だと思いますので、そこは自動化するのが良いかと思います。
Circle CIの例としては以下の感じでCircle CI上から amplify push が実行できます（実行するためにIAMの作成と権限付与が必要です）。production環境にPRを出してマージされた際に走るCIだと仮定して読んで頂けると良いかと思います。
*もっとスマートな案があれば教えて下さい!
version: 2.1
executors:
node-docker:
working_directory: ~/repo
docker:
- image: circleci/node:latest
jobs:
amplify_push:
executor: node-docker
resource_class: small
steps:
- checkout
- setup_aws_config
- amplify_push
commands:
setup_aws_config:
steps:
- run:
command: |
set -x
curl "https://s3.amazonaws.com/aws-cli/awscli-bundle.zip" -o "awscli-bundle.zip"
unzip awscli-bundle.zip
sudo ./awscli-bundle/install -i /usr/local/aws -b /usr/local/bin/aws
aws configure set aws_access_key_id $AWS_ACCESS_KEY_ID
aws configure set aws_secret_access_key $AWS_SECRET_ACCESS_KEY
aws configure set default.region $AWS_DEFAULT_REGION
amplify_push:
steps:
- run:
command: |
set -x
sudo npm install -g @aws-amplify/cli
// amplify envにproductionという環境がある前提
amplify init --amplify "{\"envName\":\"production\"}" --yes
amplify push --yes
workflows:
exec:
jobs:
- amplify_push:
VTLなどもテストする
フロントエンドそのものに対するテストは書くと思うのですが（書いてますよね？）、amplify-velocity-templateを使うとVTLなどに対してもテストが書けます。プロダクトの初期はVTLなどに対するテストなしでも良いかもしれませんが、開発が進むにつれて徐々にVTLにif文などを定義してトリッキーな実装になっていきます（マジでなります...）。その頃にはテスト出来るようになっていると安心感が得られると思います。
Amplify with AppSyncはフロントエンドで完結しない事項が非常に多いので、開発が進むにつれてこういったテストがないとデグレなどに気づきにくくなっていくので、速いうちに検討しておくと良いと思います。
詳細はEffective AppSync 〜 Serverless Framework を使用した AppSync の実践的な開発方法とテスト戦略 〜 VTL をテストするに非常に詳しく書いてありますので、そちらを参照ください。
serverless frameworkと連携する
serverless frameworkという、（文字通り）サーバーレス関連のプロダクトに対していろんな機能を提供してくれるフレームワークがあります。これはAWS純正のツールではないのですが、AWS LambdaやAppSyncに対して非常に便利な機能を提供してくれており、またpluginも多数存在します。自分はAWS Lambdaを使う際にはほぼ必ず使っています。
serverless framworkとAppSyncを連携させることで、テストやデプロイ周りでさらなる恩恵を受けられるポイントがたくさんあります。私の関わっているプロダクトでは既にある程度開発が進んでいるため、今の状態からserverless frameworkに土台を入れ替えるのは中々コストがつくので実践には躊躇していますが...、比較的初期段階であれば導入する価値は十分にあるかと思います。
参考
- serverless - AWS AppSync - The Ultimate Guide
- serverless - Serverless Appsync Plugin
- Effective AppSync 〜 Serverless Framework を使用した AppSync の実践的な開発方法とテスト戦略 〜
その他
AWS公式が出しているAmplify Framework Documentationに様々な色々情報が載っているので、こちらを覗いてみるとさらなる知見が得られるかもしれません。
Discussion