Ini adalah Panduan Pengembang AWS CDK v2. CDK v1 yang lebih lama memasuki pemeliharaan pada 1 Juni 2022 dan mengakhiri dukungan pada 1 Juni 2023.
Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Bekerja dengan AWS CDK di TypeScript
TypeScript adalah bahasa klien yang didukung penuh untuk AWS Cloud Development Kit (AWS CDK) dan dianggap stabil. Bekerja dengan AWS CDK TypeScript menggunakan alat yang sudah dikenal, termasuk TypeScript compiler Microsoft (`tsc`), [Node.js](https://nodejs.org/) dan Node Package Manager (`npm`). Anda juga dapat menggunakan [Yarn](https://yarnpkg.com/) jika Anda mau, meskipun contoh dalam Panduan ini menggunakan NPM. [Modul yang terdiri dari AWS Construct Library didistribusikan melalui repositori NPM, npmjs.org.](https://www.npmjs.com/)
Anda dapat menggunakan editor atau IDE apa pun. Banyak pengembang AWS CDK menggunakan [Visual Studio Code](https://code.visualstudio.com/) (atau padanan open-source [VSCodium](https://vscodium.com/)), yang memiliki dukungan yang sangat baik untuk. TypeScript
## Memulai dengan TypeScript
Untuk bekerja dengan AWS CDK, Anda harus memiliki AWS akun dan kredensil dan telah menginstal Node.js dan CDK Toolkit. AWS Lihat [Memulai dengan AWS CDK](getting-started.md).
Anda juga membutuhkan TypeScript dirinya sendiri (versi 3.8 atau yang lebih baru). Jika Anda belum memilikinya, Anda dapat menginstalnya menggunakan`npm`.
```
$ npm install -g typescript
```
**catatan**
Jika Anda mendapatkan kesalahan izin, dan memiliki akses administrator di sistem Anda, coba`sudo npm install -g typescript`.
Tetap TypeScript up to date dengan reguler`npm update -g typescript`.
**catatan**
Penghentian bahasa pihak ketiga: versi bahasa hanya didukung hingga EOL (End Of Life) dibagikan oleh vendor atau komunitas dan dapat berubah sewaktu-waktu dengan pemberitahuan sebelumnya.
## Membuat proyek
Anda membuat proyek AWS CDK baru dengan memanggil `cdk init` di direktori kosong. Gunakan `--language` opsi dan tentukan`typescript`:
```
$ mkdir my-project
$ cd my-project
$ cdk init app --language typescript
```
Membuat proyek juga menginstal [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib-readme.html)modul dan dependensinya.
`cdk init`menggunakan nama folder proyek untuk memberi nama berbagai elemen proyek, termasuk kelas, subfolder, dan file. Tanda hubung dalam nama folder diubah menjadi garis bawah. Namun, nama tersebut harus mengikuti bentuk TypeScript pengenal; misalnya, tidak boleh dimulai dengan angka atau berisi spasi.
## Menggunakan lokal `tsc` dan `cdk`
Untuk sebagian besar, panduan ini mengasumsikan Anda menginstal TypeScript dan CDK Toolkit global (`npm install -g typescript aws-cdk`), dan contoh perintah yang disediakan (seperti`cdk synth`) mengikuti asumsi ini. Pendekatan ini memudahkan untuk menjaga kedua komponen tetap up to date, dan karena keduanya mengambil pendekatan ketat untuk kompatibilitas mundur, umumnya ada sedikit risiko untuk selalu menggunakan versi terbaru.
Beberapa tim lebih memilih untuk menentukan semua dependensi dalam setiap proyek, termasuk alat seperti TypeScript kompiler dan CDK Toolkit. Praktik ini memungkinkan Anda menyematkan komponen ini ke versi tertentu dan memastikan bahwa semua pengembang di tim Anda (dan lingkungan CI/CD Anda) menggunakan versi tersebut dengan tepat. Ini menghilangkan kemungkinan sumber perubahan, membantu membuat build dan penerapan lebih konsisten dan berulang.
CDK menyertakan dependensi untuk keduanya TypeScript dan CDK Toolkit di template TypeScript proyek`package.json`, jadi jika Anda ingin menggunakan pendekatan ini, Anda tidak perlu membuat perubahan apa pun pada proyek Anda. Yang perlu Anda lakukan adalah menggunakan perintah yang sedikit berbeda untuk membangun aplikasi Anda dan untuk mengeluarkan `cdk` perintah.
| Operasi | Gunakan alat global | Gunakan alat lokal |
| --- | --- | --- |
| **Inisialisasi proyek** | `cdk init --language typescript` | `npx aws-cdk init --language typescript` |
| **Membangun** | `tsc` | `npm run build` |
| **Jalankan perintah CDK Toolkit** | `cdk …` | `npm run cdk …` atau `npx aws-cdk …` |
`npx aws-cdk`menjalankan versi CDK Toolkit yang diinstal secara lokal di proyek saat ini, jika ada, kembali ke instalasi global, jika ada. Jika tidak ada instalasi global, `npx` unduh salinan sementara CDK Toolkit dan jalankan itu. Anda dapat menentukan versi arbitrer dari CDK Toolkit menggunakan `@` sintaks: prints. `npx aws-cdk@2.0 --version` `2.0.0`
**Tip**
Siapkan alias sehingga Anda dapat menggunakan `cdk` perintah dengan instalasi CDK Toolkit lokal.
```
$ alias cdk="npx aws-cdk"
```
```
doskey cdk=npx aws-cdk $*
```
## Mengelola AWS modul Construct Library
Gunakan Node Package Manager (`npm`) untuk menginstal dan memperbarui modul AWS Construct Library untuk digunakan oleh aplikasi Anda, serta paket lain yang Anda butuhkan. (Anda dapat menggunakan `yarn` bukan `npm` jika Anda mau.) `npm`juga menginstal dependensi untuk modul-modul tersebut secara otomatis.
Sebagian besar konstruksi AWS CDK berada dalam paket CDK utama, bernama`aws-cdk-lib`, yang merupakan ketergantungan default dalam proyek baru yang dibuat oleh. `cdk init` Modul Perpustakaan AWS Konstruksi “Eksperimental”, di mana konstruksi tingkat yang lebih tinggi masih dalam pengembangan, diberi nama seperti. `@aws-cdk/-alpha` Nama layanan memiliki awalan *aws-*. Jika Anda tidak yakin dengan nama modul, [cari di NPM](https://www.npmjs.com/search?q=%40aws-cdk).
**catatan**
[Referensi API CDK](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) juga menunjukkan nama paket.
Misalnya, perintah di bawah ini menginstal modul eksperimental untuk AWS CodeStar.
```
$ npm install @aws-cdk/aws-codestar-alpha
```
Dukungan Construct Library beberapa layanan ada di lebih dari satu namespace. Misalnya, selain itu`aws-route53`, ada tiga ruang nama Amazon Route 53 tambahan,, `aws-route53-targets``aws-route53-patterns`, dan. `aws-route53resolver`
Dependensi proyek Anda dipertahankan di. `package.json` Anda dapat mengedit file ini untuk mengunci beberapa atau semua dependensi Anda ke versi tertentu atau untuk memungkinkan mereka diperbarui ke versi yang lebih baru di bawah kriteria tertentu. Untuk memperbarui dependensi NPM project Anda ke versi terbaru yang diizinkan sesuai dengan aturan yang Anda tentukan di: `package.json`
```
$ npm update
```
Di TypeScript, Anda mengimpor modul ke kode Anda dengan nama yang sama yang Anda gunakan untuk menginstalnya menggunakan NPM. Kami merekomendasikan praktik berikut saat mengimpor kelas AWS CDK dan modul AWS Construct Library di aplikasi Anda. Mengikuti panduan ini akan membantu membuat kode Anda konsisten dengan aplikasi AWS CDK lainnya serta lebih mudah dipahami.
+ Gunakan `import` arahan ES6 -style, bukan. `require()`
+ Umumnya, impor kelas individu dari`aws-cdk-lib`.
```
import { App, Stack } from 'aws-cdk-lib';
```
+ Jika Anda membutuhkan banyak kelas`aws-cdk-lib`, Anda dapat menggunakan alias namespace `cdk` alih-alih mengimpor kelas individual. Hindari melakukan keduanya.
```
import * as cdk from 'aws-cdk-lib';
```
+ Umumnya, impor konstruksi AWS layanan menggunakan alias namespace pendek.
```
import { aws_s3 as s3 } from 'aws-cdk-lib';
```
## Mengelola dependensi di TypeScript
Dalam proyek TypeScript CDK, dependensi ditentukan dalam `package.json` file di direktori utama proyek. Modul AWS CDK inti berada dalam satu `NPM` paket yang disebut`aws-cdk-lib`.
Saat Anda menginstal paket menggunakan`npm install`, NPM mencatat paket `package.json` untuk Anda.
Jika mau, Anda dapat menggunakan Benang sebagai pengganti NPM. Namun, CDK tidak mendukung plug-and-play mode Yarn, yang merupakan mode default di Yarn 2. Tambahkan berikut ini ke `.yarnrc.yml` file proyek Anda untuk mematikan fitur ini.
```
nodeLinker: node-modules
```
### Aplikasi CDK
Berikut ini adalah contoh `package.json` file yang dihasilkan oleh `cdk init --language typescript` perintah:
```
{
"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"
}
}
```
Untuk aplikasi CDK yang dapat di-deploy, `aws-cdk-lib` harus ditentukan di bagian. `dependencies` `package.json` Anda dapat menggunakan penentu nomor versi tanda sisipan (^) untuk menunjukkan bahwa Anda akan menerima versi yang lebih baru dari yang ditentukan selama mereka berada dalam versi utama yang sama.
Untuk konstruksi eksperimental, tentukan versi yang tepat untuk modul pustaka konstruksi alfa, APIs yang mungkin berubah. Jangan gunakan ^ atau \$1 karena versi modul ini yang lebih baru dapat membawa perubahan API yang dapat merusak aplikasi Anda.
Tentukan versi pustaka dan alat yang diperlukan untuk menguji aplikasi Anda (misalnya, kerangka `jest` pengujian) di `devDependencies` bagian. `package.json` Secara opsional, gunakan ^ untuk menentukan bahwa versi yang kompatibel selanjutnya dapat diterima.
### Perpustakaan konstruksi pihak ketiga
Jika Anda mengembangkan pustaka konstruksi, tentukan dependensinya menggunakan kombinasi `devDependencies` bagian `peerDependencies` dan, seperti yang ditunjukkan pada file contoh berikut. `package.json`
```
{
"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"
}
}
```
Di`peerDependencies`, gunakan tanda sisipan (^) untuk menentukan versi terendah `aws-cdk-lib` yang digunakan perpustakaan Anda. Ini memaksimalkan kompatibilitas perpustakaan Anda dengan berbagai versi CDK. Tentukan versi yang tepat untuk modul pustaka konstruksi alfa, APIs yang mungkin berubah. Menggunakan `peerDependencies` memastikan bahwa hanya ada satu salinan dari semua perpustakaan CDK di pohon. `node_modules`
Di`devDependencies`, tentukan alat dan pustaka yang Anda butuhkan untuk pengujian, secara opsional dengan ^ untuk menunjukkan bahwa versi kompatibel yang lebih baru dapat diterima. Tentukan dengan tepat (tanpa ^ atau \$1) versi terendah `aws-cdk-lib` dan paket CDK lainnya yang kompatibel dengan perpustakaan Anda. Praktik ini memastikan bahwa pengujian Anda berjalan terhadap versi tersebut. Dengan cara ini, jika Anda secara tidak sengaja menggunakan fitur yang hanya ditemukan di versi yang lebih baru, pengujian Anda dapat menangkapnya.
**Awas**
`peerDependencies`diinstal secara otomatis hanya oleh NPM 7 dan yang lebih baru. Jika Anda menggunakan NPM 6 atau sebelumnya, atau jika Anda menggunakan Yarn, Anda harus menyertakan dependensi dependensi Anda di. `devDependencies` Jika tidak, mereka tidak akan diinstal, dan Anda akan menerima peringatan tentang dependensi rekan yang belum terselesaikan.
### Menginstal dan memperbarui dependensi
Jalankan perintah berikut untuk menginstal dependensi proyek Anda.
**Example**
```
# Install the latest version of everything that matches the ranges in 'package.json'
npm install
# Install the same exact dependency versions as recorded in 'package-lock.json'
npm ci
```
```
# Install the latest version of everything that matches the ranges in 'package.json'
$ yarn upgrade
# Install the same exact dependency versions as recorded in 'yarn.lock'
$ yarn install --frozen-lockfile
```
Untuk memperbarui modul yang diinstal, `yarn upgrade` perintah sebelumnya `npm install` dan dapat digunakan. Perintah mana pun memperbarui paket `node_modules` ke versi terbaru yang memenuhi aturan di`package.json`. Namun, mereka tidak memperbarui `package.json` dirinya sendiri, yang mungkin ingin Anda lakukan untuk menetapkan versi minimum baru. Jika Anda meng-host paket Anda GitHub, Anda dapat mengonfigurasi [pembaruan versi Dependabot untuk memperbarui](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) secara otomatis. `package.json` Alternatif lainnya, gunakan [npm-check-updates](https://www.npmjs.com/package/npm-check-updates).
**penting**
Secara desain, ketika Anda menginstal atau memperbarui dependensi, NPM dan Yarn memilih versi terbaru dari setiap paket yang memenuhi persyaratan yang ditentukan dalam. `package.json` Selalu ada risiko bahwa versi ini dapat rusak (baik secara tidak sengaja atau sengaja). Uji secara menyeluruh setelah memperbarui dependensi proyek Anda.
## AWS Idiom CDK di TypeScript
### Alat Peraga
**Semua kelas AWS Construct Library dipakai menggunakan tiga argumen: *lingkup* di mana konstruksi sedang didefinisikan (induknya di pohon konstruksi), id, dan alat peraga.** Argumen *props* adalah bundel pasangan kunci/nilai yang digunakan konstruksi untuk mengkonfigurasi sumber daya yang dibuatnya. AWS Kelas dan metode lain juga menggunakan pola “bundel atribut” untuk argumen.
Dalam TypeScript, bentuk `props` didefinisikan menggunakan antarmuka yang memberi tahu Anda argumen yang diperlukan dan opsional serta tipenya. Antarmuka seperti didefinisikan untuk setiap jenis `props` argumen, biasanya khusus untuk konstruksi tunggal atau metode. Misalnya, [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html)konstruksi (dalam `aws-cdk-lib/aws-s3` modul) menentukan `props` argumen yang sesuai dengan antarmuka. [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html)
Jika properti itu sendiri merupakan objek, misalnya [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketProps.html#websiteredirect)properti dari`BucketProps`, objek itu akan memiliki antarmuka sendiri yang bentuknya harus sesuai, dalam hal [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.RedirectTarget.html)ini.
Jika Anda mensubklasifikasikan kelas AWS Construct Library (atau mengganti metode yang menggunakan argumen seperti props), Anda dapat mewarisi dari antarmuka yang ada untuk membuat yang baru yang menentukan alat peraga baru yang diperlukan kode Anda. Saat memanggil kelas induk atau metode dasar, umumnya Anda dapat meneruskan seluruh argumen props yang Anda terima, karena atribut apa pun yang disediakan dalam objek tetapi tidak ditentukan dalam antarmuka akan diabaikan.
Rilis AWS CDK di masa depan secara kebetulan dapat menambahkan properti baru dengan nama yang Anda gunakan untuk properti Anda sendiri. Melewati nilai yang Anda terima ke rantai pewarisan kemudian dapat menyebabkan perilaku yang tidak terduga. Lebih aman untuk meneruskan salinan dangkal alat peraga yang Anda terima dengan properti Anda dihapus atau disetel ke`undefined`. Misalnya:
```
super(scope, name, {...props, encryptionKeys: undefined});
```
Atau, beri nama properti Anda sehingga jelas bahwa mereka milik konstruksi Anda. Dengan cara ini, kecil kemungkinan mereka akan bertabrakan dengan properti di rilis AWS CDK masa depan. Jika ada banyak dari mereka, gunakan satu objek dengan nama yang tepat untuk menahannya.
### Nilai yang hilang
Nilai yang hilang dalam suatu objek (seperti alat peraga) memiliki nilai `undefined` dalam TypeScript. Versi 3.7 dari bahasa memperkenalkan operator yang menyederhanakan bekerja dengan nilai-nilai ini, sehingga lebih mudah untuk menentukan default dan rantai “hubung singkat” ketika nilai yang tidak ditentukan tercapai. Untuk informasi lebih lanjut tentang fitur-fitur ini, lihat [Catatan Rilis TypeScript 3.7](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html), khususnya dua fitur pertama, Optional Chaining dan Nullish Coalescing.
## Membangun dan menjalankan aplikasi CDK
Umumnya, Anda harus berada di direktori root proyek saat membangun dan menjalankan aplikasi Anda.
Node.js tidak dapat berjalan TypeScript secara langsung; sebagai gantinya, aplikasi Anda dikonversi untuk JavaScript menggunakan TypeScript kompiler,`tsc`. JavaScript Kode yang dihasilkan kemudian dieksekusi.
AWS CDK secara otomatis melakukan ini kapan pun perlu menjalankan aplikasi Anda. Namun, dapat berguna untuk mengkompilasi secara manual untuk memeriksa kesalahan dan menjalankan tes. Untuk mengompilasi TypeScript aplikasi Anda secara manual, masalah`npm run build`. Anda juga dapat mengeluarkan masalah `npm run watch` untuk masuk ke mode tontonan, di mana TypeScript kompiler secara otomatis membangun kembali aplikasi Anda setiap kali Anda menyimpan perubahan ke file sumber.