Questa è la AWS CDK v2 Developer Guide. Il vecchio CDK v1 è entrato in manutenzione il 1° giugno 2022 e ha terminato il supporto il 1° giugno 2023. Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Lavorare con il AWS CDK in TypeScript TypeScript è un linguaggio client completamente supportato per il AWS Cloud Development Kit (AWS CDK) ed è considerato stabile. L'utilizzo del AWS CDK TypeScript utilizza strumenti familiari, tra cui il TypeScript compilatore di Microsoft (`tsc`), [Node.js](https://nodejs.org/) e il Node Package Manager (`npm`). Puoi anche usare [Yarn](https://yarnpkg.com/) se preferisci, sebbene gli esempi in questa guida utilizzino NPM. [I moduli che compongono la AWS Construct Library sono distribuiti tramite il repository NPM, npmjs.org.](https://www.npmjs.com/) Puoi usare qualsiasi editor o IDE. Molti sviluppatori AWS CDK utilizzano [Visual Studio Code](https://code.visualstudio.com/) (o il suo equivalente open source [VSCodium](https://vscodium.com/)), che offre un supporto eccellente per. TypeScript ## Inizia con TypeScript Per utilizzare il AWS CDK, è necessario disporre di un AWS account e delle credenziali e aver installato Node.js e AWS CDK Toolkit. Vedi [Guida introduttiva](getting-started.md) al CDK. AWS È necessario anche TypeScript se stesso (versione 3.8 o successiva). Se non lo possiedi già, puoi installarlo utilizzando`npm`. ``` $ npm install -g typescript ``` **Nota** Se ricevi un errore di autorizzazione e disponi dell'accesso come amministratore sul tuo sistema, prova`sudo npm install -g typescript`. TypeScript Tieniti aggiornato con un appuntamento abituale`npm update -g typescript`. **Nota** Lingua obsoleta di terze parti: la versione linguistica è supportata solo fino alla fine del ciclo di vita (EOL (End Of Life) condivisa dal fornitore o dalla community ed è soggetta a modifiche con preavviso. ## Creare un progetto È possibile creare un nuovo progetto AWS CDK invocandolo in una directory vuota. `cdk init` Utilizzate l'`--language`opzione e specificate: `typescript` ``` $ mkdir my-project $ cd my-project $ cdk init app --language typescript ``` La creazione di un progetto installa anche il [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)modulo e le sue dipendenze. `cdk init`utilizza il nome della cartella del progetto per denominare vari elementi del progetto, tra cui classi, sottocartelle e file. I trattini nel nome della cartella vengono convertiti in caratteri di sottolineatura. Tuttavia, il nome dovrebbe altrimenti assumere la forma di un TypeScript identificatore; ad esempio, non dovrebbe iniziare con un numero o contenere spazi. ## Utilizzo di locali e `tsc` `cdk` Per la maggior parte, questa guida presuppone l'installazione TypeScript e l'installazione di CDK Toolkit a livello globale (`npm install -g typescript aws-cdk`), e gli esempi di comandi forniti (ad esempio`cdk synth`) seguano questo presupposto. Questo approccio semplifica l'aggiornamento di entrambi i componenti e, poiché entrambi adottano un approccio rigoroso alla compatibilità con le versioni precedenti, in genere il rischio di utilizzare sempre le versioni più recenti è minimo. Alcuni team preferiscono specificare tutte le dipendenze all'interno di ogni progetto, inclusi strumenti come il TypeScript compilatore e il CDK Toolkit. Questa pratica consente di associare questi componenti a versioni specifiche e di garantire che tutti gli sviluppatori del team (e l'ambiente CI/CD) utilizzino esattamente quelle versioni. Ciò elimina una possibile fonte di cambiamento, contribuendo a rendere le build e le implementazioni più coerenti e ripetibili. Il CDK include le dipendenze per entrambi TypeScript e il CDK Toolkit nei modelli di TypeScript progetto`package.json`, quindi se si desidera utilizzare questo approccio, non è necessario apportare alcuna modifica al progetto. Tutto quello che dovete fare è usare comandi leggermente diversi per creare l'app e per emettere comandi. `cdk` | Operazione | Usa strumenti globali | Usa strumenti locali | | --- | --- | --- | | **Inizializza il progetto** | `cdk init --language typescript` | `npx aws-cdk init --language typescript` | | **Compila** | `tsc` | `npm run build` | | **Esegui il comando CDK Toolkit** | `cdk …​` | `npm run cdk …​` o `npx aws-cdk …​` | `npx aws-cdk`esegue la versione di CDK Toolkit installata localmente nel progetto corrente, se ne esiste una, ricorrendo all'eventuale installazione globale. Se non esiste un'installazione globale, `npx` scarica una copia temporanea di CDK Toolkit e la esegue. È possibile specificare una versione arbitraria di CDK Toolkit utilizzando la sintassi: prints. `@` `npx aws-cdk@2.0 --version` `2.0.0` **Suggerimento** Imposta un alias in modo da poter utilizzare il `cdk` comando con un'installazione locale di CDK Toolkit. ``` $ alias cdk="npx aws-cdk" ``` ``` doskey cdk=npx aws-cdk $* ``` ## Gestione dei moduli Construct Library AWS Utilizzate Node Package Manager (`npm`) per installare e aggiornare i moduli AWS Construct Library per l'uso da parte delle vostre app e degli altri pacchetti di cui avete bisogno. (Puoi usare `yarn` al posto di `npm` se preferisci.) `npm`installa inoltre automaticamente le dipendenze per quei moduli. La maggior parte dei costrutti AWS CDK si trova nel pacchetto CDK principale, denominato`aws-cdk-lib`, che è una dipendenza predefinita nei nuovi progetti creati da. `cdk init` I moduli «sperimentali» di AWS Construct Library, in cui i costrutti di livello superiore sono ancora in fase di sviluppo, hanno lo stesso nome. `@aws-cdk/-alpha` *Il nome del servizio ha un prefisso aws-.* Se non sei sicuro del nome di un modulo, [cercalo su NPM](https://www.npmjs.com/search?q=%40aws-cdk). **Nota** Il [CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) mostra anche i nomi dei pacchetti. Ad esempio, il comando seguente installa il modulo sperimentale per. AWS CodeStar ``` $ npm install @aws-cdk/aws-codestar-alpha ``` Il supporto di Construct Library di alcuni servizi è disponibile in più di un namespace. Ad esempio`aws-route53`, ci sono inoltre tre namespace Amazon Route 53 aggiuntivi,`aws-route53-targets`, `aws-route53-patterns` e. `aws-route53resolver` Le dipendenze del tuo progetto vengono mantenute in. `package.json` Puoi modificare questo file per bloccare alcune o tutte le tue dipendenze su una versione specifica o per consentire loro di essere aggiornate a versioni più recenti in base a determinati criteri. Per aggiornare le dipendenze NPM del progetto all'ultima versione consentita in base alle regole specificate in: `package.json` ``` $ npm update ``` In TypeScript, importi i moduli nel tuo codice con lo stesso nome che usi per installarli usando NPM. Consigliamo le seguenti pratiche per importare classi AWS CDK e moduli AWS Construct Library nelle vostre applicazioni. Seguire queste linee guida contribuirà a rendere il codice coerente con altre applicazioni AWS CDK e più facile da comprendere. + Usa le `import` direttive ES6 -style, no. `require()` + In genere, importa singole classi da. `aws-cdk-lib` ``` import { App, Stack } from 'aws-cdk-lib'; ``` + Se hai bisogno di molte classi da`aws-cdk-lib`, puoi usare un alias dello spazio dei nomi di `cdk` invece di importare le singole classi. Evita di fare entrambe le cose. ``` import * as cdk from 'aws-cdk-lib'; ``` + In genere, importate i costrutti dei AWS servizi utilizzando alias di namespace brevi. ``` import { aws_s3 as s3 } from 'aws-cdk-lib'; ``` ## Gestione delle dipendenze in TypeScript Nei progetti TypeScript CDK, le dipendenze sono specificate nel `package.json` file nella directory principale del progetto. I moduli AWS CDK principali si trovano in un unico `NPM` pacchetto chiamato. `aws-cdk-lib` Quando installate un pacchetto utilizzando`npm install`, NPM registra il pacchetto al posto `package.json` vostro. Se preferisci, puoi usare Yarn al posto di NPM. Tuttavia, il CDK non supporta la modalità di Yarn, che è la plug-and-play modalità predefinita in Yarn 2. Aggiungi quanto segue al `.yarnrc.yml` file del tuo progetto per disattivare questa funzionalità. ``` nodeLinker: node-modules ``` ### Applicazioni CDK Di seguito è riportato un `package.json` file di esempio generato dal `cdk init --language typescript` comando: ``` { "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" } } ``` Per le app CDK distribuibili, `aws-cdk-lib` deve essere specificato nella sezione di`dependencies`. `package.json` Potete utilizzare un identificatore del numero di versione con cursore (^) per indicare che accetterete versioni successive a quella specificata purché si trovino all'interno della stessa versione principale. Per i costrutti sperimentali, specificate le versioni esatte per i moduli della libreria alpha construct, che potrebbero APIs cambiare. Non utilizzate ^ o \$1 poiché le versioni successive di questi moduli potrebbero apportare modifiche all'API che potrebbero danneggiare l'app. Specificate le versioni delle librerie e degli strumenti necessari per testare l'app (ad esempio, il framework di `jest` test) nella `devDependencies` sezione di`package.json`. Facoltativamente, usa ^ per specificare che le versioni compatibili successive sono accettabili. ### Librerie di costruzioni di terze parti Se state sviluppando una libreria di costrutti, specificate le sue dipendenze utilizzando una combinazione delle `devDependencies` sezioni `peerDependencies` e, come mostrato nel seguente file di esempio. `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" } } ``` In`peerDependencies`, usa un accento circonflesso (^) per specificare la versione più bassa con `aws-cdk-lib` cui funziona la tua libreria. Ciò massimizza la compatibilità della tua libreria con una gamma di versioni CDK. Specificate le versioni esatte per i moduli della libreria alpha construct, APIs che potrebbero cambiare. L'utilizzo `peerDependencies` assicura che vi sia una sola copia di tutte le librerie CDK nell'`node_modules`albero. Nel`devDependencies`, specificate gli strumenti e le librerie necessari per il test, opzionalmente con ^ per indicare che le versioni compatibili successive sono accettabili. Specificate esattamente (senza ^ o \$1) le versioni più basse `aws-cdk-lib` e gli altri pacchetti CDK con cui pubblicizzate la compatibilità della vostra libreria. Questa pratica assicura che i test vengano eseguiti su tali versioni. In questo modo, se usi inavvertitamente una funzionalità presente solo nelle versioni più recenti, i tuoi test possono catturarla. **avvertimento** `peerDependencies`vengono installati automaticamente solo da NPM 7 e versioni successive. Se stai usando NPM 6 o versioni precedenti, o se stai usando Yarn, devi includere le dipendenze delle tue dipendenze in. `devDependencies` Altrimenti, non verranno installate e riceverai un avviso sulle dipendenze tra pari non risolte. ### Installazione e aggiornamento delle dipendenze Esegui il comando seguente per installare le dipendenze del tuo progetto. **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 ``` Per aggiornare i moduli installati, è possibile utilizzare `yarn upgrade` i comandi precedenti `npm install` e. Entrambi i comandi aggiornano i pacchetti `node_modules` alle versioni più recenti che soddisfano le regole in`package.json`. Tuttavia, non `package.json` si aggiornano da soli, cosa che potresti voler fare per impostare una nuova versione minima. Se ospiti il pacchetto su GitHub, puoi configurare [gli aggiornamenti della versione di Dependabot in modo che si aggiornino](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates) automaticamente. `package.json` In alternativa, utilizzare [npm-check-updates](https://www.npmjs.com/package/npm-check-updates). **Importante** In base alla progettazione, quando installi o aggiorni le dipendenze, NPM e Yarn scelgono la versione più recente di ogni pacchetto che soddisfi i requisiti specificati in. `package.json` C'è sempre il rischio che queste versioni possano essere danneggiate (accidentalmente o intenzionalmente). Esegui un test approfondito dopo aver aggiornato le dipendenze del progetto. ## AWS Idiomi CDK in TypeScript ### Oggetti di scena **Tutte le classi di AWS Construct Library vengono istanziate utilizzando tre argomenti: l'*ambito* in cui viene definito il costrutto (il suo genitore nell'albero dei costrutti), un id e props.** Argument *props* è un insieme di coppie chiave/valore che il costrutto utilizza per configurare le risorse che crea. AWS Anche altre classi e metodi utilizzano il modello «bundle of attributes» per gli argomenti. In TypeScript, la forma di `props` è definita utilizzando un'interfaccia che indica gli argomenti obbligatori e facoltativi e i loro tipi. Tale interfaccia è definita per ogni tipo di `props` argomento, in genere specifica per un singolo costrutto o metodo. Ad esempio, il [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)costrutto (nel `aws-cdk-lib/aws-s3` modulo) specifica un `props` argomento conforme all'interfaccia. [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) Se una proprietà è essa stessa un oggetto, ad esempio la [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)proprietà di`BucketProps`, quell'oggetto avrà una propria interfaccia alla quale la sua forma deve conformarsi, in questo caso. [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) Se state sottoclassando una classe AWS Construct Library (o sovrascrivete un metodo che accetta un argomento simile a props), potete ereditarne una dall'interfaccia esistente per crearne una nuova che specifichi eventuali nuovi oggetti di scena richiesti dal codice. Quando chiamate la classe principale o il metodo base, in genere potete passare l'intero argomento props ricevuto, poiché tutti gli attributi forniti nell'oggetto ma non specificati nell'interfaccia verranno ignorati. Le future versioni del AWS CDK potrebbero aggiungere casualmente una nuova proprietà con un nome usato per la propria proprietà. Il trasferimento del valore ricevuto nella catena di ereditarietà può quindi causare un comportamento imprevisto. È più sicuro passare una copia superficiale degli oggetti di scena ricevuti con la proprietà rimossa o impostata. `undefined` Per esempio: ``` super(scope, name, {...props, encryptionKeys: undefined}); ``` In alternativa, dai un nome alle tue proprietà in modo che sia chiaro che appartengono al tuo costrutto. In questo modo, è improbabile che entrino in collisione con le proprietà nelle future versioni di AWS CDK. Se ce ne sono molte, usate un unico oggetto dal nome appropriato per contenerle. ### Valori mancanti I valori mancanti in un oggetto (come gli oggetti di scena) hanno il valore in. `undefined` TypeScript La versione 3.7 del linguaggio ha introdotto operatori che semplificano l'utilizzo di questi valori, semplificando la specificazione dei valori predefiniti e il «cortocircuito» il concatenamento quando viene raggiunto un valore indefinito. Per ulteriori informazioni su queste funzionalità, consultate le [Note di rilascio della versione TypeScript 3.7](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html), in particolare le prime due funzionalità, Optional Chaining e Nullish Coalescing. ## Crea ed esegui app CDK In genere, dovresti trovarti nella directory principale del progetto durante la creazione e l'esecuzione dell'applicazione. Node.js non può essere eseguito TypeScript direttamente; l'applicazione viene invece convertita per JavaScript utilizzare il TypeScript compilatore,`tsc`. Il JavaScript codice risultante viene quindi eseguito. Il AWS CDK lo fa automaticamente ogni volta che deve eseguire l'app. Tuttavia, può essere utile eseguire la compilazione manuale per verificare la presenza di errori ed eseguire test. Per compilare la tua TypeScript app manualmente, emetti. `npm run build` Potresti anche dover accedere `npm run watch` alla modalità watch, in cui il TypeScript compilatore ricostruisce automaticamente l'app ogni volta che salvi le modifiche a un file sorgente.