Memulai dengan TypeScript Membuat proyek Menggunakan lokal tsc dan cdk Mengelola AWS modul Construct Library Mengelola dependensi di TypeScript AWS CDK idiom di TypeScript Membangun dan menjalankan CDK aplikasi

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 in TypeScript menggunakan alat yang sudah dikenal, termasuk TypeScript compiler Microsoft (tsc), Node.js dan Node Package Manager (npm). Anda juga dapat menggunakan Yarn jika Anda mau, meskipun contoh dalam Panduan ini digunakanNPM. Modul yang terdiri dari AWS Construct Library didistribusikan melalui NPM repositori, npmjs.org.

Anda dapat menggunakan editor apa pun atauIDE. Banyak AWS CDK pengembang menggunakan Visual Studio Code (atau padanan open-source VSCodium), yang memiliki dukungan yang sangat baik untuk TypeScript.

Memulai dengan TypeScript

Untuk bekerja dengan AWS CDK, Anda harus memiliki AWS akun dan kredensional dan telah menginstal Node.js dan Toolkit. AWS CDK Lihat Memulai dengan AWS CDK.

Anda juga membutuhkan TypeScript dirinya sendiri (versi 3.8 atau yang lebih baru). Jika Anda belum memilikinya, Anda dapat menginstalnya menggunakannpm.


npm install -g typescript

catatan

Jika Anda mendapatkan kesalahan izin, dan memiliki akses administrator di sistem Anda, cobasudo npm install -g typescript.

Tetap TypeScript up to date dengan regulernpm 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 AWS CDK proyek baru dengan memanggil cdk init dalam direktori kosong. Gunakan --language opsi dan tentukantypescript:


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

Membuat proyek juga menginstal aws-cdk-libmodul dan dependensinya.

cdk initmenggunakan 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 (seperticdk 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 Toolkit. CDK 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.

CDKTermasuk dependensi untuk keduanya TypeScript dan CDK Toolkit dalam template TypeScript proyekpackage.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 CDK perintah Toolkit	`cdk ...`	`npm run cdk ...` atau `npx aws-cdk ...`

npx aws-cdkmenjalankan 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.

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.) npmjuga menginstal dependensi untuk modul-modul tersebut secara otomatis.

Sebagian besar AWS CDK konstruksi berada dalam CDK paket utama, bernamaaws-cdk-lib, yang merupakan dependensi 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/SERVICE-NAME-alpha Nama layanan memiliki awalan aws-. Jika Anda tidak yakin dengan nama modul, cari di NPM.

catatan

CDKAPIReferensi 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 ituaws-route53, ada tiga ruang nama Amazon Route 53 tambahan,, aws-route53-targetsaws-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 NPM dependensi 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 menggunakanNPM. Kami merekomendasikan praktik berikut saat mengimpor AWS CDK kelas dan modul AWS Construct Library dalam aplikasi Anda. Mengikuti panduan ini akan membantu membuat kode Anda konsisten dengan AWS CDK aplikasi lain serta lebih mudah dipahami.

Gunakan import arahan ES6 -style, bukan. require()
Umumnya, impor kelas individu dariaws-cdk-lib.
```
import { App, Stack } from 'aws-cdk-lib';
```
Jika Anda membutuhkan banyak kelasaws-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 TypeScript CDK proyek, dependensi ditentukan dalam package.json file di direktori utama proyek. AWS CDK Modul inti berada dalam satu NPM paket yang disebutaws-cdk-lib.

Saat Anda menginstal paket menggunakannpm install, NPM catat paket package.json untuk Anda.

Jika mau, Anda dapat menggunakan Benang sebagai penggantiNPM. 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

CDKaplikasi

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 CDK aplikasi yang dapat di-deploy, aws-cdk-lib harus ditentukan di dependencies bagian. 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 ~ karena versi modul ini yang lebih baru dapat membawa API perubahan 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"
  }
}

DipeerDependencies, gunakan tanda sisipan (^) untuk menentukan versi terendah aws-cdk-lib yang digunakan perpustakaan Anda. Ini memaksimalkan kompatibilitas perpustakaan Anda dengan berbagai CDK versi. Tentukan versi yang tepat untuk modul pustaka konstruksi alfa, APIs yang mungkin berubah. Menggunakan peerDependencies memastikan bahwa hanya ada satu salinan dari semua CDK perpustakaan di node_modules pohon.

DidevDependencies, 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 ~) versi terendah aws-cdk-lib dan CDK paket lain yang Anda iklankan perpustakaan Anda kompatibel dengan. 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

peerDependenciesdiinstal secara otomatis hanya dengan 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.

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 dipackage.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 secara otomatis. package.json Alternatif lainnya, gunakan npm-check-updates.

penting

Secara desain, saat 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 CDK idiom 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, konstruksi Bucket (in theaws-cdk-lib/aws-s3 module) menentukan props argumen yang sesuai dengan antarmuka. BucketProps

Jika properti itu sendiri merupakan objek, misalnya websiteRedirectproperti dariBucketProps, objek itu akan memiliki antarmuka sendiri yang bentuknya harus sesuai, dalam hal RedirectTargetini.

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 future AWS CDK dapat secara kebetulan 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 keundefined. Sebagai contoh:


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 AWS CDK rilis mendatang. 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, khususnya dua fitur pertama, Optional Chaining dan Nullish Coalescing.

Membangun dan menjalankan CDK aplikasi

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, masalahnpm 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.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Bekerja dengan CDK perpustakaan

Di JavaScript