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 JavaScript

JavaScriptadalah bahasa klien yang didukung penuh untuk AWS CDK dan dianggap stabil. Bekerja dengan AWS Cloud Development Kit (AWS CDK) in JavaScript menggunakan alat yang sudah dikenal, termasuk Node.js dan Node Package Manager (npm). Anda juga dapat menggunakan Yarn jika Anda mau, meskipun contoh dalam Panduan ini menggunakan NPM. Modul yang terdiri dari AWS Construct Library didistribusikan melalui repositori NPM, npmjs.org.

Anda dapat menggunakan editor atau IDE apa pun. Banyak AWS CDK pengembang menggunakan Visual Studio Code (atau VScodium yang setara dengan sumber terbuka), yang memiliki dukungan yang baik untuk. JavaScript

Memulai dengan JavaScript

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.

JavaScript AWS CDK aplikasi tidak memerlukan prasyarat tambahan di luar ini.

Membuat proyek

Anda membuat AWS CDK proyek baru dengan memanggil cdk init dalam direktori kosong. Gunakan --language opsi dan tentukanjavascript:

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

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 JavaScript pengenal; misalnya, tidak boleh dimulai dengan angka atau berisi spasi.

Menggunakan lokal cdk

Untuk sebagian besar, panduan ini mengasumsikan Anda menginstal CDK Toolkit global (npm install -g aws-cdk), dan contoh perintah yang disediakan (seperticdk synth) mengikuti asumsi ini. Pendekatan ini memudahkan untuk menjaga CDK Toolkit tetap up to date, dan karena CDK 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 CDK Toolkit. Praktik ini memungkinkan Anda menyematkan komponen tersebut 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 ketergantungan untuk CDK Toolkit dalam template JavaScript 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.

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@1.120 --version 1.120.0

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 paket CDK 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-lib/SERVICE-NAME-alpha Nama layanan memiliki awalan aws-. Jika Anda tidak yakin dengan nama modul, cari di NPM.

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 dependensi NPM project Anda ke versi terbaru yang diizinkan sesuai dengan aturan yang Anda tentukan di: package.json

npm update

Di JavaScript, Anda mengimpor modul ke kode Anda dengan nama yang sama yang Anda gunakan untuk menginstalnya menggunakan NPM. 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.

Mengelola dependensi di JavaScript

Dalam proyek JavaScript CDK, 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 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. File yang JavaScript dihasilkan untuk serupa, hanya tanpa entri TypeScript terkait.

{
  "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, yang memiliki API yang dapat berubah. Jangan gunakan ^ atau ~ 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.

Pustaka 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 versi CDK. Tentukan versi yang tepat untuk modul pustaka konstruksi alfa, yang memiliki API yang dapat berubah. Menggunakan peerDependencies memastikan bahwa hanya ada satu salinan dari semua perpustakaan CDK di pohon. node_modules

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

Menginstal dan memperbarui dependensi

Jalankan perintah berikut untuk menginstal dependensi proyek Anda.

NPM

# 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

Yarn

# 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 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.

AWS CDK idiom di JavaScript

Alat Peraga

Semua kelas AWS Construct Library dipakai menggunakan tiga argumen: ruang lingkup di mana konstruksi sedang didefinisikan (induknya di pohon konstruksi), id, dan props, 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.

Menggunakan IDE atau editor yang memiliki JavaScript pelengkapan otomatis yang baik akan membantu menghindari salah eja nama properti. Jika sebuah konstruksi mengharapkan encryptionKeys properti, dan Anda mengejanya, saat membuat instance konstruksiencryptionkeys, Anda belum melewati nilai yang Anda inginkan. Ini dapat menyebabkan kesalahan pada waktu sintesis jika properti diperlukan, atau menyebabkan properti diabaikan secara diam-diam jika bersifat opsional. Dalam kasus terakhir, Anda mungkin mendapatkan perilaku default yang ingin Anda timpa. Berhati-hatilah di sini.

Saat mensubklasifikasikan class AWS Construct Library (atau mengganti metode yang menggunakan argumen seperti props), Anda mungkin ingin menerima properti tambahan untuk Anda gunakan sendiri. Nilai-nilai ini akan diabaikan oleh kelas induk atau metode overridden, karena mereka tidak pernah diakses dalam kode itu, sehingga Anda umumnya dapat meneruskan semua props yang Anda terima.

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 (sepertiprops) memiliki nilai undefined dalam JavaScript. Teknik yang biasa berlaku untuk menangani ini. Misalnya, idiom umum untuk mengakses properti dari nilai yang mungkin tidak terdefinisi adalah sebagai berikut:

// 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;

Namun, jika a bisa memiliki nilai “palsu” lain selain ituundefined, lebih baik membuat tes lebih eksplisit. Di sini, kita akan memanfaatkan fakta bahwa null dan undefined sama dengan menguji keduanya sekaligus:

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

Mensintesis dan menyebarkan

Tumpukan yang ditentukan dalam AWS CDK aplikasi Anda dapat disintesis dan diterapkan secara individual atau bersama-sama menggunakan perintah di bawah ini. Umumnya, Anda harus berada di direktori utama proyek Anda ketika Anda menerbitkannya.

Anda dapat menentukan nama beberapa tumpukan yang akan disintesis atau digunakan dalam satu perintah. Jika aplikasi Anda hanya mendefinisikan satu tumpukan, Anda tidak perlu menentukannya.

cdk synth                 # app defines single stack
cdk deploy Happy Grumpy   # app defines two or more stacks; two are deployed

Anda juga dapat menggunakan wildcard * (sejumlah karakter) dan? (setiap karakter tunggal) untuk mengidentifikasi tumpukan berdasarkan pola. Saat menggunakan wildcard, lampirkan pola dalam tanda kutip. Jika tidak, shell mungkin mencoba memperluasnya ke nama-nama file di direktori saat ini sebelum diteruskan ke AWS CDK Toolkit.

cdk synth "Stack?"    # Stack1, StackA, etc.
cdk deploy "*Stack"   # PipeStack, LambdaStack, etc.

Untuk dokumentasi lengkap dari cdk perintah, lihatAWS CDK Toolkit (cdkperintah).

Menggunakan TypeScript contoh dengan JavaScript

TypeScriptadalah bahasa yang kita gunakan untuk mengembangkan AWS CDK, dan itu adalah bahasa pertama yang didukung untuk mengembangkan aplikasi, begitu banyak contoh AWS CDK kode yang tersedia ditulis TypeScript. Contoh kode ini dapat menjadi sumber daya yang baik untuk JavaScript pengembang; Anda hanya perlu menghapus bagian-bagian kode yang TypeScript spesifik.

TypeScript cuplikan sering menggunakan ECMAScript import dan export kata kunci yang lebih baru untuk mengimpor objek dari modul lain dan untuk mendeklarasikan objek yang akan tersedia di luar modul saat ini. Node.js baru saja mulai mendukung kata kunci ini dalam rilis terbarunya. Bergantung pada versi Node.js yang Anda gunakan (atau ingin mendukung), Anda dapat menulis ulang impor dan ekspor untuk menggunakan sintaks yang lebih lama.

Impor dapat diganti dengan panggilan ke require() fungsi.

TypeScript

import * as cdk from 'aws-cdk-lib';
import { Bucket, BucketPolicy } from 'aws-cdk-lib/aws-s3';

JavaScript

const cdk = require('aws-cdk-lib');
const { Bucket, BucketPolicy } = require('aws-cdk-lib/aws-s3');

Ekspor dapat ditugaskan ke module.exports objek.

TypeScript

export class Stack1 extends cdk.Stack {
  // ...
}

export class Stack2 extends cdk.Stack {
  // ...
}

JavaScript

class Stack1 extends cdk.Stack {
  // ...
}

class Stack2 extends cdk.Stack {
  // ...
}

module.exports = { Stack1, Stack2 }

Setelah impor dan ekspor diurutkan, Anda dapat menggali kode yang sebenarnya. Anda mungkin mengalami fitur-fitur yang umum digunakan ini TypeScript :

Jenis anotasi dapat disediakan untuk variabel, anggota kelas, parameter fungsi, dan tipe pengembalian fungsi. Untuk variabel, parameter, dan anggota, jenis ditentukan dengan mengikuti pengidentifikasi dengan titik dua dan tipe. Nilai pengembalian fungsi mengikuti tanda tangan fungsi dan terdiri dari titik dua dan tipe.

Untuk mengonversi kode beranotasi tipe menjadi JavaScript, hapus titik dua dan jenisnya. Anggota kelas harus memiliki beberapa nilai JavaScript; atur mereka ke undefined jika mereka hanya memiliki anotasi tipe di TypeScript.

TypeScript

var encrypted: boolean = true;

class myStack extends cdk.Stack {
    bucket: s3.Bucket;
    // ...
}

function makeEnv(account: string, region: string) : object {
    // ...
}

JavaScript

var encrypted = true;

class myStack extends cdk.Stack {
    bucket = undefined;
    // ...
}

function makeEnv(account, region) {
    // ...
}

Dalam TypeScript, antarmuka digunakan untuk memberikan bundel properti wajib dan opsional, dan jenisnya, nama. Anda kemudian dapat menggunakan nama antarmuka sebagai anotasi tipe. TypeScript akan memastikan bahwa objek yang Anda gunakan sebagai, misalnya, argumen ke fungsi memiliki properti yang diperlukan dari tipe yang tepat.

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

JavaScript tidak memiliki fitur antarmuka, jadi setelah Anda menghapus anotasi tipe, hapus deklarasi antarmuka sepenuhnya.

Ketika fungsi atau metode mengembalikan tipe tujuan umum (sepertiobject), tetapi Anda ingin memperlakukan nilai itu sebagai tipe anak yang lebih spesifik untuk mengakses properti atau metode yang bukan bagian dari antarmuka tipe yang lebih umum, TypeScript memungkinkan Anda mentransmisikan nilai menggunakan as diikuti oleh jenis atau nama antarmuka. JavaScript tidak mendukung (atau membutuhkan) ini, jadi cukup hapus as dan pengenal berikut. Sintaks cast yang kurang umum adalah menggunakan nama tipe dalam tanda kurung,<LikeThis>; gips ini juga harus dihapus.

Akhirnya, TypeScript mendukung pengubah aksespublic,protected, dan private untuk anggota kelas. Semua anggota kelas JavaScript adalah publik. Cukup hapus pengubah ini di mana pun Anda melihatnya.

Mengetahui cara mengidentifikasi dan menghapus TypeScript fitur-fitur ini sangat membantu mengadaptasi TypeScript cuplikan pendek. JavaScript Tetapi mungkin tidak praktis untuk mengonversi TypeScript contoh yang lebih panjang dengan cara ini, karena mereka lebih cenderung menggunakan TypeScript fitur lain. Untuk situasi ini, kami merekomendasikan Sucrase. Sucrase tidak akan mengeluh jika kode menggunakan variabel yang tidak ditentukan, misalnya, seperti yang akan terjadi. tsc Jika valid secara sintaksis, maka dengan beberapa pengecualian, Sucrase dapat menerjemahkannya ke. JavaScript Ini membuatnya sangat berharga untuk mengonversi cuplikan yang mungkin tidak dapat dijalankan sendiri.

Migrasi ke TypeScript

Banyak JavaScript pengembang pindah ke TypeScriptproyek mereka menjadi lebih besar dan lebih kompleks. TypeScript adalah superset dari JavaScript —semua JavaScript kode adalah kode yang valid, jadi tidak ada perubahan pada TypeScript kode Anda yang diperlukan—dan itu juga merupakan bahasa yang didukung. AWS CDK Jenis anotasi dan TypeScript fitur lainnya bersifat opsional dan dapat ditambahkan ke AWS CDK aplikasi Anda saat Anda menemukan nilai di dalamnya. TypeScript juga memberi Anda akses awal ke JavaScript fitur-fitur baru, seperti rantai opsional dan penggabungan nullish, sebelum selesai — dan tanpa mengharuskan Anda meningkatkan Node.js.

TypeScriptantarmuka “berbasis bentuk”, yang mendefinisikan bundel properti wajib dan opsional (dan jenisnya) dalam suatu objek, memungkinkan kesalahan umum ditangkap saat Anda menulis kode, dan memudahkan IDE Anda untuk memberikan pelengkapan otomatis yang kuat dan saran pengkodean waktu nyata lainnya.

Coding in TypeScript memang melibatkan langkah tambahan: mengompilasi aplikasi Anda dengan TypeScript compiler,. tsc Untuk AWS CDK aplikasi biasa, kompilasi membutuhkan waktu paling lama beberapa detik.

Cara termudah untuk memigrasikan JavaScript AWS CDK aplikasi yang sudah ada TypeScript adalah dengan membuat TypeScript proyek baru menggunakancdk init app --language typescript, lalu menyalin file sumber Anda (dan file lain yang diperlukan, seperti aset seperti kode sumber AWS Lambda fungsi) ke proyek baru. Ganti nama JavaScript file Anda untuk mengakhiri .ts dan mulai mengembangkan. TypeScript