aws-cdkのドキュメントであるコンストラクトデザインガイドラインを読んで、重要だと思ったことをまとめていく。ユーザー側の観点で使えるプラクティスを集める目的なので、たとえば言語間を意識した取り組みなどついては重視しない。

https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md

コンストラクトの分類について

L1 ~ L3の定義は省略。
L2.5という概念が目新しかった。これはL2を特定のユースケース用にカスタマイズしたものを意味する。L2よりも実装が隠蔽されているが、L3というまではいかない、みたいな意味合いだろうか。
ドキュメントであげられている例

aws-apigateway.LambdaRestApi, aws-lambda-nodejs.NodeJsFunction, aws-rds.ServerlessCluster and eks.FargateCluster

例をつくってみた。SecureSNSはデフォルトでenforceSSLをtrueにするためにaws_sns.Topicをwrapしている。

class SecureSNS extends Construct {
  constructor(scope: Construct, id: string, props: aws_sns.TopicProps) {
    super(scope, id);

    new aws_sns.Topic(this, "Resource", {
      ...props,
      enforceSSL: true,
    });
  }
}

pattern(L3)についてはaws-cdk v2では含まれていない。

These patterns are typically difficult to design to be one-size-fits-all and are best suited to be published as separate libraries, rather than included directly in the CDK. The patterns that currently exist in the CDK will be removed in the next CDK major version (CDKv2).

patternは外部のライブラリが提供するべきという方針。たとえばここにあるソリューションライブラリ。https://github.com/awslabs/aws-solutions-constructs

Construct Class, Interface

経験則としてコンストラクトは他のコンストラクトではなくConstuructやResourceクラスをextendsすること。Ixxxというコンストラクトの抽象クラスをimplementすること。このあたりはユーザーとしてコンストラクトを作る場合には気にしないかもしれないが、ライブラリを設計する立場では安直な継承による共通化を起こさないために重要だろう。
propsでリソース参照を渡すときにはIxxx型を使えばコンストラクトの実装に依らずに扱うことができる。一部のL2で提供されているlookupやfromメソッドを使ったことがあれば、実感がわくかもしれない。これはCDK App所有かそうでないか(Owned or Unowned)として説明されている。

Props

AWSの概念としての名前を改名しない

たとえばLambdaのLayerのことをよかれとおもいDependenciesとして命名してしまうとユーザーがLayer = Depenenciesと変換する認知負荷をかけてしまう(diagnose problems.)。

ユーザーのDXを考えるうえでAWSマネジメントコンソールの体験を参考にする

面白い観点だと思った。確かにマネジメントコンソールに慣れているユーザーが多いとすれば妥当なUX検討方法だと思う。

Imports

ここでいうimportはfromやlookupメソッドでのリソースのインポートのこと。コンストラクトインターフェースを実装したオブジェクトが返ることが期待される。ユーザーはインターフェースを使ってオブジェクトを扱える。参照用に渡したArnやnameは文字列中のトークンが解決されていないかをValidationすることが望ましく、Stack.parseArnがこのために使われる。

Grants

コンストラクトオブジェクト間で権限設定をしてくれる。CDKのなかでもかなり好きな機能。以下のようなコンストラクトが以下のようなメソッドを少なくとも一つ持つことが強制されている。

grant(grantee: Iam.IGrantable, ...actions: string[]): iam.Grant

General Principles

• Do not future proof.
• No fluent APIs.
• Good APIs “speak” in the language of the user. The terminology your API uses should be intuitive and represent the mental model your user brings over, not one that you made up and you force them to learn.
• Multiple ways of achieving the same thing is legitimate.
• Constantly maintain the invariants.
• The fewer “if statements” the better.