JavaScript 시작하기 프로젝트 생성 로컬 cdk 사용 AWS Construct 라이브러리 모듈 관리 JavaScript에서 종속성 관리 JavaScript의 AWS CDK 관용구 JavaScript로 TypeScript 예제 사용 TypeScript로 마이그레이션

JavaScript로 AWS CDK 작업

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

모든 편집기 또는 IDE를 사용할 수 있습니다. 많은 AWS CDK 개발자가 JavaScript를 잘 지원하는 Visual Studio Code(또는 오픈 소스에 상응하는 VSCodium)를 사용합니다.

JavaScript 시작하기

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

JavaScript AWS CDK 애플리케이션에는 이러한 요구 사항 이외의 추가 사전 요구 사항이 필요하지 않습니다.

참고

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

프로젝트 생성

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


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

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

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

로컬 `cdk` 사용

대부분의 경우 이 안내서에서는 CDK Toolkit를 전역적으로 설치한다고 가정하고(npm install -g aws-cdk) 제공된 명령 예(예: cdk synth)는 이 가정을 따릅니다. 이 접근 방식을 사용하면 CDK Toolkit를 쉽게 최신 상태로 유지할 수 있으며 CDK는 역호환성에 대한 엄격한 접근 방식을 취하므로 항상 최신 버전을 사용할 때 일반적으로 위험이 거의 없습니다.

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

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

Operation	글로벌 CDK Toolkit 사용	로컬 CDK Toolkit 사용
프로젝트 초기화	`cdk init --language javascript`	`npx aws-cdk init --language javascript`
CDK Toolkit 명령 실행	`cdk ...`	`npm run cdk ...` or `npx aws-cdk ...`

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

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

ES6 스타일 import 지시문이 아닌 require()를 사용합니다. 이전 버전의 Node.js는 ES6 가져오기를 지원하지 않으므로 이전 구문을 사용하는 것이 더 널리 호환됩니다. (ES6 가져오기를 사용하려는 경우 esm을 사용하여 프로젝트가 지원되는 모든 Node.js 버전과 호환되는지 확인합니다.)
일반적으로 aws-cdk-lib에서 개별 클래스를 가져옵니다.
```
const { App, Stack } = require('aws-cdk-lib');
```
aws-cdk-lib에서 여러 클래스가 필요한 경우 개별 클래스를 가져오는 대신 cdk의 네임스페이스 별칭을 사용할 수 있습니다. 둘 다 수행하지 마세요.
```
const cdk = require('aws-cdk-lib');
```
일반적으로 짧은 네임스페이스 별칭을 사용하여 AWS Construct Libraries를 가져옵니다.
```
const { s3 } = require('aws-cdk-lib/aws-s3');
```

JavaScript에서 종속성 관리

JavaScript 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 파일입니다. JavaScript용으로 생성된 파일은 TypeScript 관련 항목이 없는 경우에만 유사합니다.


{
  "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에 지정된 요구 사항을 충족하는 모든 패키지의 최신 버전을 선택합니다. 이러한 버전이 (우연히 또는 의도적으로) 파손될 위험이 항상 있습니다. 프로젝트 종속성을 업데이트한 후 철저히 테스트합니다.

JavaScript의 AWS CDK 관용구

Props

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

JavaScript 자동 완성이 양호한 IDE 또는 편집기를 사용하면 속성 이름의 철자가 틀리지 않도록 하는 데 도움이 됩니다. 구문에서 encryptionKeys 속성을 예상하고 encryptionkeys의 철자를 지정하는 경우 구문을 인스턴스화할 때 의도한 값을 전달하지 않은 것입니다. 이로 인해 속성이 필요한 경우 합성 시 오류가 발생하거나 선택 사항인 경우 속성이 자동으로 무시될 수 있습니다. 후자의 경우 재정의하려는 기본 동작을 얻을 수 있습니다. 여기에서 특히 주의해야 합니다.

AWS Construct 라이브러리 클래스를 하위 클래스로 분류할 때(또는 속성과 유사한 인수를 사용하는 메서드를 재정의할 때) 자체 사용을 위해 추가 속성을 수락할 수 있습니다. 이러한 값은 부모 클래스 또는 재정의된 메서드에서 무시됩니다. 해당 코드에서 액세스할 수 없으므로 일반적으로 받은 모든 소품을 전달할 수 있습니다.

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


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

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

누락된 값

객체의 누락된 값(예: props)은 JavaScript의 undefined 값을 갖습니다. 이러한 문제를 처리하는 데는 일반적인 기법이 적용됩니다. 예를 들어 정의되지 않은 값의 속성에 액세스하기 위한 일반적인 관용구는 다음과 같습니다.


// a may be undefined, but if it is not, it may have an attribute b
// c is undefined if a is undefined, OR if a doesn't have an attribute b
let c = a && a.b;

그러나 a에 undefined 외에 다른 'falsy' 값이 있는 경우 테스트를 더 명시적으로 만드는 것이 좋습니다. 여기에서는 null 및 undefined가 두 가지를 동시에 테스트하는 것과 동일하다는 사실을 활용할 것입니다.


let c = a == null ? a : a.b;

작은 정보

Node.js 14.0 이상은 정의되지 않은 값의 처리를 단순화할 수 있는 새 연산자를 지원합니다. 자세한 내용은 선택적 체이닝 및 nullish 병합 제안을 참조하세요.

JavaScript로 TypeScript 예제 사용

TypeScript는 AWS CDK를 개발하는 데 사용하는 언어이며 애플리케이션 개발에 지원되는 첫 번째 언어이므로 사용 가능한 많은 AWS CDK 코드 예제가 TypeScript로 작성되어 있습니다. 이러한 코드 예제는 JavaScript 개발자에게 좋은 리소스일 수 있습니다. 코드의 TypeScript 관련 부분을 제거하면 됩니다.

TypeScript 스니펫은 최신 ECMAScript import 및 export 키워드를 사용하여 다른 모듈에서 객체를 가져오고 현재 모듈 외부에서 사용할 수 있도록 객체를 선언하는 경우가 많습니다. Node.js는 최신 릴리스에서 이러한 키워드를 지원하기 시작했습니다. 사용 중인(또는 지원하려는) Node.js 버전에 따라 이전 구문을 사용하도록 가져오기 및 내보내기를 다시 작성할 수 있습니다.

가져오기는 require() 함수에 대한 직접 호출로 대체할 수 있습니다.

내보내기를 module.exports 객체에 할당할 수 있습니다.

참고

이전 스타일의 가져오기 및 내보내기를 사용하는 대신 esm 모듈을 사용하는 것이 좋습니다.

가져오기 및 내보내기가 정렬되면 실제 코드를 파고들 수 있습니다. 일반적으로 사용되는 다음과 같은 TypeScript 기능을 실행할 수 있습니다.

주석 입력
인터페이스 정의
유형 변환/캐스트
액세스 한정자

변수, 클래스 멤버, 함수 파라미터 및 함수 반환 유형에 유형 주석을 제공할 수 있습니다. 변수, 파라미터 및 멤버의 경우 유형은 콜론과 유형이 있는 식별자를 따라 지정됩니다. 함수 반환 값은 함수 서명을 따르며 콜론과 유형으로 구성됩니다.

형식 주석이 달린 코드를 JavaScript로 변환하려면 콜론과 유형을 제거합니다. 클래스 멤버는 JavaScript의 일부 값이 있어야 합니다. TypeScript의 유형 주석만 있는 경우 undefined로 설정합니다.

TypeScript에서 인터페이스는 필수 및 선택적 속성의 번들과 해당 유형, 이름을 제공하는 데 사용됩니다. 그런 다음 인터페이스 이름을 유형 주석으로 사용할 수 있습니다. TypeScript는 함수에 대한 인수와 같이 사용하는 객체에 올바른 유형의 필수 속성이 있는지 확인합니다.


interface myFuncProps {
    code: lambda.Code,
    handler?: string
}

JavaScript에는 인터페이스 기능이 없으므로 유형 주석을 제거한 후에는 인터페이스 선언을 완전히 삭제합니다.

함수 또는 메서드가 범용 유형(예: object)을 반환하지만 해당 값을 보다 구체적인 자식 유형으로 취급하여 보다 일반적인 유형의 인터페이스에 속하지 않는 속성 또는 메서드에 액세스하려는 경우 TypeScript를 사용하면 as를 사용하여 값을 캐스팅한 다음 유형 또는 인터페이스 이름을 지정할 수 있습니다. JavaScript는 이를 지원하거나 필요로 하지 않으므로 as와 다음 식별자를 제거하면 됩니다. 덜 일반적인 캐스트 구문은 <LikeThis>와 같이 괄호 안에 형식 이름을 사용하는 것입니다. 이러한 캐스트도 제거해야 합니다.

마지막으로 TypeScript는 클래스 멤버에 대한 액세스 수정자 public, protected 및 private를 지원합니다. JavaScript의 모든 클래스 멤버는 퍼블릭입니다. 이러한 수정자를 볼 수 있는 모든 곳에서 제거하면 됩니다.

이러한 TypeScript 기능을 식별하고 제거하는 방법을 아는 것은 짧은 TypeScript 스니펫을 JavaScript에 적응시키는 데 큰 도움이 됩니다. 그러나 다른 TypeScript 기능을 사용할 가능성이 더 높기 때문에 이러한 방식으로 더 긴 TypeScript 예를 변환하는 것은 실용적이지 않을 수 있습니다. 이러한 상황에서는 Sucrase를 사용하는 것이 좋습니다. Sucrase는 코드가 정의되지 않은 변수를 사용하는 경우, 예를 들어 tsc 그와 같이 불평하지 않습니다. 구문적으로 유효한 경우 몇 가지 예외를 제외하고 Sucrase는 이를 JavaScript로 변환할 수 있습니다. 따라서 자체적으로 실행할 수 없는 스니펫을 변환하는 데 특히 유용합니다.

TypeScript로 마이그레이션

많은 JavaScript 개발자는 프로젝트가 점점 더 커지고 복잡해짐에 따라 TypeScript로 이동합니다. TypeScript는 JavaScript의 상위 집합으로, 모든 JavaScript 코드는 유효한 TypeScript 코드이므로 코드를 변경할 필요가 없으며 지원되는 AWS CDK 언어이기도 합니다. Type 주석과 기타 TypeScript 기능은 선택 사항이며 앱에서 값을 찾을 때 AWS CDK 앱에 추가할 수 있습니다. 또한 TypeScript를 사용하면 Node.js를 업그레이드할 필요 없이 완료되기 전에 선택적 체인 및 nullish 코어레싱과 같은 새로운 JavaScript 기능에 조기에 액세스할 수 있습니다.

객체 내에서 필수 및 선택적 속성(및 유형)의 번들을 정의하는 TypeScript의 '모양 기반' 인터페이스는 코드를 작성하는 동안 일반적인 실수를 저지르도록 허용하고 IDE가 강력한 자동 완성 및 기타 실시간 코딩 조언을 더 쉽게 제공할 수 있도록 합니다.

TypeScript의 코딩에는 TypeScript 컴파일러 tsc를 사용하여 앱을 컴파일하는 추가 단계가 포함됩니다. 일반적인 AWS CDK 앱의 경우 컴파일에는 몇 초 정도 걸립니다.

기존 JavaScript AWS CDK 앱을 TypeScript로 마이그레이션하는 가장 쉬운 방법은 cdk init app --language typescript를 사용하여 새 TypeScript 프로젝트를 생성한 다음 소스 파일(및 AWS Lambda 함수 소스 코드와 같은 자산과 같은 기타 필수 파일)을 새 프로젝트에 복사하는 것입니다. JavaScript 파일 이름을 .ts로 바꾸고 TypeScript로 개발을 시작하세요.

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

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

문서 규칙

TypeScript 사용

Python 사용