Inizia con TypeScript Creare un progetto Utilizzo di locali e tsccdk Gestione dei moduli Construct Library AWS Gestione delle dipendenze in TypeScript AWS CDK idiomi in TypeScript Crea ed esegui app CDK

Lavorare con l' AWS CDK interno TypeScript

TypeScript è un linguaggio client completamente supportato per AWS Cloud Development Kit (AWS CDK) ed è considerato stabile. L'utilizzo dell' AWS CDK in TypeScript utilizza strumenti familiari, tra cui il TypeScript compilatore di Microsoft (tsc), Node.js e il Node Package Manager (npm). Puoi anche usare Yarn 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.

Puoi usare qualsiasi editor o IDE. Molti AWS CDK sviluppatori utilizzano Visual Studio Code (o il suo equivalente open source VSCodium), che offre un supporto eccellente per TypeScript.

Argomenti

Inizia con TypeScript
Creare un progetto
Utilizzo di locali e tsccdk
Gestione dei moduli Construct Library AWS
Gestione delle dipendenze in TypeScript
AWS CDK idiomi in TypeScript
Crea ed esegui app CDK

Inizia con TypeScript

Per utilizzare AWS CDK, è necessario disporre di un AWS account e delle credenziali e aver installato Node.js e il AWS CDK Toolkit. Per informazioni, consulta Guida introduttiva al AWS CDK.

È inoltre necessario disporre di TypeScript se stesso (versione 3.8 o successiva). Se non lo possiedi già, puoi installarlo utilizzandonpm.


npm install -g typescript

Nota

Se ricevi un errore di autorizzazione e disponi dell'accesso come amministratore sul tuo sistema, provasudo npm install -g typescript.

TypeScript Tieniti aggiornato con un appuntamento abitualenpm 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 AWS CDK progetto cdk init richiamandolo in una directory vuota. Utilizzate l'--languageopzione e specificatetypescript:


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

La creazione di un progetto installa anche il aws-cdk-libmodulo e le sue dipendenze.

cdk initutilizza 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 `tsccdk`

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 esempiocdk 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 progettopackage.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`
Creazione	`tsc`	`npm run build`
Esegui il comando CDK Toolkit	`cdk ...`	`npm run cdk ...` o `npx aws-cdk ...`

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

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.) npminstalla inoltre automaticamente le dipendenze per quei moduli.

La maggior parte dei AWS CDK costrutti si trova nel pacchetto CDK principale, denominatoaws-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/SERVICE-NAME-alpha Il nome del servizio ha un prefisso aws-. Se non sei sicuro del nome di un modulo, cercalo su NPM.

Nota

Il CDK API Reference 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 esempioaws-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 AWS CDK classi e moduli AWS Construct Library nelle applicazioni. Seguire queste linee guida contribuirà a rendere il codice coerente con altre AWS CDK applicazioni 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 daaws-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

In TypeScript Progetti CDK, le dipendenze sono specificate nel package.json file nella directory principale del progetto. I AWS CDK moduli principali sono in un unico NPM pacchetto chiamatoaws-cdk-lib.

Quando installi un pacchetto utilizzandonpm install, NPM registra il pacchetto package.json per te.

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 didependencies. 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 ~ 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 dipackage.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"
  }
}

InpeerDependencies, 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 ci sia una sola copia di tutte le librerie CDK nell'node_modulesalbero.

NeldevDependencies, 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 ~) 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

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

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 inpackage.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 automaticamente. package.json In alternativa, utilizzare 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 CDK idiomi 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 costrutto Bucket (inaws-cdk-lib/aws-s3 module) specifica un props argomento conforme all'interfaccia. BucketProps

Se una proprietà è essa stessa un oggetto, ad esempio la proprietà WebsiteRedirect diBucketProps, tale oggetto avrà una propria interfaccia alla quale la forma deve conformarsi, in questo caso. RedirectTarget

Se state sottoclassando una classe AWS Construct Library (o sovrascrivete un metodo che accetta un argomento simile a props), potete ereditare dall'interfaccia esistente crearne una nuova che specifichi tutti i 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 di AWS CDK potrebbero aggiungere casualmente una nuova proprietà con un nome che hai usato per la tua 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 AWS CDK versioni future. Se ce ne sono molte, utilizzate 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, 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.

Lo fa AWS CDK automaticamente ogni volta che è necessario eseguire l'app. Tuttavia, può essere utile compilare manualmente 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.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Lavora con la libreria CDK

Nel JavaScript