TypeScript 시작하기 프로젝트 생성 로컬 tsc 및 cdk 사용 AWS Construct 라이브러리 모듈 관리 TypeScript에서 종속성 관리 TypeScript의 AWS CDK 관용구 CDK 앱 빌드 및 실행

TypeScript로 AWS CDK 작업

TypeScript는 AWS Cloud Development Kit (AWS CDK)에 대해 완전히 지원되는 클라이언트 언어이며 안정적인 것으로 간주됩니다. TypeScript에서 AWS CDK를 사용하려면 Microsoft의 TypeScript 컴파일러(tsc), Node.js, Node Package Manager(npm)를 비롯한 익숙한 도구를 사용해야 합니다. 원한다면 Yarn을 사용할 수도 있지만 이 가이드의 예에서는 NPM을 사용합니다. AWS Construct 라이브러리를 구성하는 모듈은 NPM 리포지토리인 npmjs.org를 통해 배포됩니다.

모든 편집기 또는 IDE를 사용할 수 있습니다. 많은 AWS CDK 개발자가 TypeScript에 대한 뛰어난 지원을 제공하는 Visual Studio Code 또는 오픈 소스에 상응하는 VSCodium을 사용합니다.

TypeScript 시작하기

AWS CDK 작업을 진행하려면 AWS 계정과 자격 증명이 있어야 하며 Node.js와 AWS CDK Toolkit를 설치해야 합니다. AWS CDK 시작하기 섹션을 참조하세요.

또한 TypeScript 자체(버전 3.8 이상)가 필요합니다. 아직 설치하지 않은 경우 npm를 사용하여 설치할 수 있습니다.


npm install -g typescript

참고

권한 오류가 발생하고 시스템에 관리자 액세스 권한이 있는 경우 sudo npm install -g typescript를 시도하세요.

TypeScript를 일반 npm update -g typescript로 최신 상태로 유지합니다.

참고

타사 언어 사용 중단: 언어 버전은 공급업체 또는 커뮤니티에서 공유하는 수명 종료(EOL)까지만 지원되며 사전 공지와 함께 변경될 수 있습니다.

프로젝트 생성

빈 디렉터리에서 cdk init를 간접적으로 호출하여 새 AWS CDK 프로젝트를 생성합니다. --language 옵션을 사용하고 typescript를 지정합니다


mkdir my-project
cd my-project
cdk init app --language typescript

프로젝트를 생성하면 aws-cdk-lib 모듈과 해당 종속성도 설치됩니다.

cdk init는 프로젝트 폴더의 이름을 사용하여 클래스, 하위 폴더 및 파일을 포함한 프로젝트의 다양한 요소의 이름을 지정합니다. 폴더 이름의 하이픈은 밑줄로 변환됩니다. 하지만 이름은 TypeScript 식별자의 형식을 따라야 합니다. 예를 들어 숫자로 시작하거나 공백을 포함해서는 안 됩니다.

로컬 `tsc` 및 `cdk` 사용

대부분의 경우 이 안내서에서는 TypeScript 및 CDK Toolkit를 전역적으로(npm install -g typescript aws-cdk) 설치한다고 가정하고 제공된 명령 예(cdk synth 등)는 이 가정을 따릅니다. 이 접근 방식을 사용하면 두 구성 요소를 모두 최신 상태로 유지하기가 쉬우며, 두 구성 요소 모두 역호환성에 대한 엄격한 접근 방식을 취하므로 항상 최신 버전을 사용하는 데 따르는 위험은 거의 없습니다.

일부 팀은 TypeScript 컴파일러 및 CDK Toolkit와 같은 도구를 포함하여 각 프로젝트 내의 모든 종속성을 지정하는 것을 선호합니다. 이 연습을 통해 이러한 구성 요소를 특정 버전에 고정하고 팀(및 CI/CD 환경)의 모든 개발자가 정확히 이러한 버전을 사용하도록 할 수 있습니다. 이렇게 하면 가능한 변경 원인을 제거하여 빌드 및 배포를 더 일관되고 반복 가능하게 만들 수 있습니다.

CDK에는 TypeScript 프로젝트 템플릿의 package.json에 TypeScript와 CDK Toolkit에 대한 종속성이 모두 포함되어 있으므로 이 접근 방식을 사용하려면 프로젝트를 변경할 필요가 없습니다. 앱을 빌드하고 명령을 실행하려면 약간 다른 cdk 명령을 실행하기만 하면 됩니다.

Operation	글로벌 도구 사용	로컬 도구 사용
프로젝트 초기화	`cdk init --language typescript`	`npx aws-cdk init --language typescript`
빌드	`tsc`	`npm run build`
CDK Toolkit 명령 실행	`cdk ...`	`npm run cdk ...` or `npx aws-cdk ...`

npx aws-cdk는 현재 프로젝트에 로컬로 설치된 CDK Toolkit 버전이 있는 경우 해당 버전을 실행하여 글로벌 설치로 돌아갑니다. 글로벌 설치가 없는 경우 npx는 CDK Toolkit의 임시 사본을 다운로드하여 실행합니다. @ 구문을 사용하여 CDK Toolkit의 임의 버전을 지정할 수 있습니다. npx aws-cdk@2.0 --version은 2.0.0을 인쇄합니다.

작은 정보

로컬 CDK Toolkit 설치와 함께 cdk 명령을 사용할 수 있도록 별칭을 설정합니다.

AWS Construct 라이브러리 모듈 관리

Node Package Manager(npm)를 사용하여 앱과 필요한 기타 패키지에서 사용할 AWS Construct 라이브러리 모듈을 설치하고 업데이트합니다. (원하는 경우 npm 대신 yarn을 사용할 수 있습니다.) npm은 해당 모듈에 대한 종속성을 자동으로 설치합니다.

대부분의 AWS CDK 구문은 cdk init으로 생성된 새 프로젝트의 기본 종속성인 aws-cdk-lib라는 기본 CDK 패키지에 있습니다. 상위 수준 구문이 아직 개발되고 있는 ‘실험적’ AWS Construct 라이브러리 모듈은 @aws-cdk/SERVICE-NAME-alpha와 같이 이름이 지정됩니다. 서비스 이름에는 aws- 접두사가 있습니다. 모듈 이름을 잘 모르는 경우 NPM에서 검색하세요.

참고

CDK API 참조에는 패키지 이름도 표시됩니다.

예를 들어 아래 명령은 AWS CodeStar 에 대한 실험 모듈을 설치합니다.


npm install @aws-cdk/aws-codestar-alpha

일부 서비스의 Construct 라이브러리 지원은 둘 이상의 네임스페이스에 있습니다. 예를 들어, aws-route53 외에도 aws-route53-targets, aws-route53-patterns, aws-route53resolver라는 세 개의 추가 Amazon Route 53 네임스페이스가 있습니다.

프로젝트의 종속성은 package.json에 유지됩니다. 이 파일을 편집하여 종속성의 일부 또는 전부를 특정 버전으로 잠그거나 특정 기준에 따라 최신 버전으로 업데이트할 수 있습니다. package.json에 지정한 규칙에 따라 프로젝트의 NPM 종속성을 허용되는 최신 버전으로 업데이트하려면 다음을 수행하세요.


npm update

TypeScript에서 NPM을 사용하여 모듈을 설치하는 데 사용하는 것과 동일한 이름으로 모듈을 코드로 가져옵니다. 애플리케이션에서 AWS CDK 클래스 및 AWS Construct 라이브러리 모듈을 가져올 때 다음 방법을 사용하는 것이 좋습니다. 이러한 지침을 따르면 코드를 다른 AWS CDK 애플리케이션과 일치시킬 뿐만 아니라 이해하기도 쉽습니다.

require()가 아닌 ES6 스타일 import 지시문을 사용합니다.
일반적으로 aws-cdk-lib에서 개별 클래스를 가져옵니다.
```
import { App, Stack } from 'aws-cdk-lib';
```
aws-cdk-lib에서 여러 클래스가 필요한 경우 개별 클래스를 가져오는 대신 cdk의 네임스페이스 별칭을 사용할 수 있습니다. 둘 다 수행하지 마세요.
```
import * as cdk from 'aws-cdk-lib';
```
일반적으로 짧은 네임스페이스 별칭을 사용하여 AWS 서비스 구문을 가져옵니다.
```
import { aws_s3 as s3 } from 'aws-cdk-lib';
```

TypeScript에서 종속성 관리

TypeScript CDK 프로젝트에서는 프로젝트의 메인 디렉터리의 package.json 파일에 종속성이 지정됩니다. 코어 AWS CDK 모듈은 aws-cdk-lib라는 단일 NPM 패키지에 있습니다.

npm install을 사용하여 패키지를 설치하면 NPM은 package.json에 패키지를 기록합니다.

원하는 경우 NPM 대신 Yarn을 사용할 수 있습니다. 하지만 CDK는 Yarn 2의 기본 모드인 Yarn의 플러그 앤 플레이 모드를 지원하지 않습니다. 프로젝트의 .yarnrc.yml 파일에 다음을 추가하여 이 기능을 끕니다.


nodeLinker: node-modules

CDK 애플리케이션

다음은 cdk init --language typescript 명령에서 생성된 예제 package.json 파일입니다.


{
  "name": "my-package",
  "version": "0.1.0",
  "bin": {
    "my-package": "bin/my-package.js"
  },
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "test": "jest",
    "cdk": "cdk"
  },
  "devDependencies": {
    "@types/jest": "^26.0.10",
    "@types/node": "10.17.27",
    "jest": "^26.4.2",
    "ts-jest": "^26.2.0",
    "aws-cdk": "2.16.0",
    "ts-node": "^9.0.0",
    "typescript": "~3.9.7"
  },
  "dependencies": {
    "aws-cdk-lib": "2.16.0",
    "constructs": "^10.0.0",
    "source-map-support": "^0.5.16"
  }
}

배포 가능한 CDK 앱의 경우 package.json의 dependencies 섹션에 aws-cdk-lib를 지정해야 합니다. 캐럿(^) 버전 번호 지정자를 사용하여 동일한 메이저 버전 내에 있는 한 지정된 버전보다 이후 버전을 수락할 것임을 표시할 수 있습니다.

실험 구문의 경우 변경될 수 있는 API가 있는 알파 Construct 라이브러리 모듈의 정확한 버전을 지정합니다. ^ 또는 ~를 사용하지 마세요. 이러한 모듈의 이후 버전에서는 API가 변경되어 앱이 중단될 수 있습니다.

package.json의 devDependencies 섹션에서 앱을 테스트하는 데 필요한 라이브러리 및 도구의 버전(예: jest 테스트 프레임워크)을 지정합니다. 선택적으로 ^를 사용하여 이후 호환 버전이 수락되도록 지정합니다.

타사 Construct 라이브러리

Construct 라이브러리를 개발하는 경우 다음 예 package.json 파일에 표시된 대로 peerDependencies 및 devDependencies 섹션의 조합을 사용하여 종속성을 지정합니다.


{
  "name": "my-package",
  "version": "0.0.1",
  "peerDependencies": {
    "aws-cdk-lib": "^2.14.0",
    "@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
    "constructs": "^10.0.0"
  },
  "devDependencies": {
    "aws-cdk-lib": "2.14.0",
    "@aws-cdk/aws-appsync-alpha": "2.10.0-alpha",
    "constructs": "10.0.0",
    "jsii": "^1.50.0",
    "aws-cdk": "^2.14.0"
  }
}

peerDependencies에서 캐럿(^)을 사용하여 라이브러리가 작동하는 aws-cdk-lib의 최저 버전을 지정합니다. 이렇게 하면 라이브러리와 다양한 CDK 버전의 호환성이 극대화됩니다. 변경될 수 있는 API가 있는 알파 Construct 라이브러리 모듈의 정확한 버전을 지정합니다. peerDependencies를 사용하면 node_modules 트리에 모든 CDK 라이브러리의 복사본이 하나만 있는지 확인합니다.

devDependencies에서 테스트에 필요한 도구 및 라이브러리를 지정합니다. 필요에 따라 ^를 사용하여 이후 호환 버전이 수락 가능하다는 것을 나타냅니다. 라이브러리를 광고하는 aws-cdk-lib 및 기타 CDK 패키지의 가장 낮은 버전을 정확히(^ 또는 ~ 제외) 지정합니다. 이 연습을 통해 테스트가 해당 버전에서 실행되는지 확인합니다. 이렇게 하면 새 버전에서만 발견된 기능을 실수로 사용하면 테스트가 이를 포착할 수 있습니다.

주의

peerDependencies는 NPM 7 이상에서만 자동으로 설치됩니다. NPM 6 이하를 사용하거나 Yarn을 사용하는 경우 devDependencies에 종속성의 종속성을 포함해야 합니다. 그렇지 않으면 설치되지 않으며 해결되지 않은 피어 종속성에 대한 경고가 표시됩니다.

종속성 설치 및 업데이트

다음 명령을 실행하여 프로젝트의 종속성을 설치하세요.

설치된 모듈을 업데이트하기 위해 이전 npm install 및 yarn upgrade 명령을 사용할 수 있습니다. 두 명령 모두 package.json의 규칙을 충족하는 최신 버전으로 node_modules의 패키지를 업데이트합니다. 그러나 새 최소 버전을 설정하기 위해 할 수 있는 package.json 자체 업데이트는 없습니다. GitHub 에서 패키지를 호스팅하는 경우 package.json을 자동으로 업데이트하도록 Dependabot 버전 업데이트를 구성할 수 있습니다. 또는 npm-check-updates를 사용합니다.

중요

설계상 종속성을 설치하거나 업데이트할 때 NPM 및 Yarn은 package.json에 지정된 요구 사항을 충족하는 모든 패키지의 최신 버전을 선택합니다. 이러한 버전이 (우연히 또는 의도적으로) 파손될 위험이 항상 있습니다. 프로젝트 종속성을 업데이트한 후 철저히 테스트합니다.

TypeScript의 AWS CDK 관용구

Props

모든 AWS Construct 라이브러리 클래스는 구문이 정의되는 scope(구문 트리에서 부모), id, props라는 세 가지 인수를 사용하여 인스턴스화됩니다. 인수 props는 구문이 생성하는 AWS 리소스를 구성하는 데 사용하는 키/값 페어의 번들입니다. 다른 클래스 및 메서드도 인수에 '속성 번들' 패턴을 사용합니다.

TypeScript에서 props의 형태는 필수, 선택 인수와 해당 유형을 알려주는 인터페이스를 사용하여 정의됩니다. 이러한 인터페이스는 각 종류의 props 인수에 대해 정의되며, 일반적으로 단일 구문 또는 메서드에 한정됩니다. 예를 들어 버킷 구문(aws-cdk-lib/aws-s3 module)은 BucketProps 인터페이스에 부합하는 props 인수를 지정합니다.

속성 자체가 객체인 경우, 예를 들어 BucketProps의 websiteRedirect 속성은 해당 객체의 모양이 일치해야 하는 자체 인터페이스를 갖게 되며, 이 경우 RedirectTarget입니다.

AWS Construct 라이브러리 클래스를 하위 클래스로 분류하는 경우(또는 속성과 유사한 인수를 사용하는 메서드를 재정의하는 경우) 기존 인터페이스에서 상속하여 코드에 필요한 새 속성을 지정하는 새 속성을 생성할 수 있습니다. 부모 클래스 또는 기본 메서드를 직접적으로 호출할 때 객체에 제공되었지만 인터페이스에 지정되지 않은 속성은 무시되므로 일반적으로 받은 전체 props 인수를 전달할 수 있습니다.

AWS CDK의 향후 릴리스는 사용자 소유의 속성에 사용한 이름과 함께 새 속성을 동시에 추가할 수 있습니다. 상속 체인에 수신한 값을 전달하면 예기치 않은 동작이 발생할 수 있습니다. 속성을 제거하거나 undefined로 설정한 상태에서 받은 소품의 얕은 사본을 전달하는 것이 더 안전합니다. 예:


super(scope, name, {...props, encryptionKeys: undefined});

또는 구문에 속해 있는지 명확히 알 수 있도록 속성 이름을 지정합니다. 이렇게 하면 향후 AWS CDK 릴리스에서 속성과 충돌할 가능성이 거의 없습니다. 이러한 객체가 많은 경우 적절한 이름의 객체 하나를 사용하여 객체를 고정합니다.

누락된 값

TypeScript에서 객체(props 등)에 누락된 값은 undefined 값을 갖습니다. 언어 버전 3.7에는 이러한 값 작업을 간소화하는 연산자가 도입되어 정의되지 않은 값에 도달하면 기본값과 '단락' 체인을 더 쉽게 지정할 수 있습니다. 이러한 기능에 대한 자세한 내용은 TypeScript 3.7 릴리스 정보, 특히 처음 두 가지 기능인 선택적 체인 및 Nullish 코어레싱을 참조하세요.

CDK 앱 빌드 및 실행

일반적으로 애플리케이션을 빌드하고 실행할 때는 프로젝트의 루트 디렉터리에 있어야 합니다.

Node.js는 TypeScript를 직접 실행할 수 없습니다. 대신 TypeScript 컴파일러인 tsc를 사용하여 애플리케이션이 JavaScript로 변환됩니다. 그러면 결과 JavaScript 코드가 실행됩니다.

AWS CDK는 앱을 실행해야 할 때마다 자동으로 이 작업을 수행합니다. 그러나 오류를 확인하고 테스트를 실행하기 위해 수동으로 컴파일하는 것이 유용할 수 있습니다. TypeScript 앱을 수동으로 컴파일하려면 npm run build를 실행합니다. 또한 소스 파일에 변경 사항을 저장할 때마다 TypeScript 컴파일러가 자동으로 앱을 다시 빌드하는 감시 모드로 들어가도록 npm run watch를 실행할 수도 있습니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

CDK 라이브러리 작업

JavaScript 사용