Questa è la guida per sviluppatori AWS CDK v2. La versione precedente della CDK versione 1 è entrata 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 l' AWS CDK interno JavaScript

JavaScriptè un linguaggio client completamente supportato per AWS CDK ed è considerato stabile. L'utilizzo dell' AWS Cloud Development Kit (AWS CDK) in JavaScript utilizza strumenti familiari, tra cui Node.js e Node Package Manager (npm). Puoi anche usare Yarn se preferisci, anche se gli esempi di questa guida lo usanoNPM. I moduli che compongono la AWS Construct Library sono distribuiti tramite il repository npmjs.org. NPM

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

Inizia a usare JavaScript

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 Iniziare con AWS CDK.

JavaScript AWS CDK le applicazioni non richiedono prerequisiti aggiuntivi oltre a questi.

Creare un progetto

È possibile creare un nuovo AWS CDK progetto richiamandolo in una directory vuota. cdk init Utilizzate l'--languageopzione e specificatejavascript:

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

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 JavaScript identificatore; ad esempio, non dovrebbe iniziare con un numero o contenere spazi.

Utilizzo della lingua locale cdk

Per la maggior parte, questa guida presuppone l'installazione del CDK Toolkit a livello globale (npm install -g aws-cdk) e gli esempi di comandi forniti (ad esempiocdk synth) seguano questo presupposto. Questo approccio semplifica l'aggiornamento del CDK Toolkit e, poiché CDK adotta un approccio rigoroso alla compatibilità con le versioni precedenti, in genere il rischio di utilizzare sempre la versione più recente è minimo.

Alcuni team preferiscono specificare tutte le dipendenze all'interno di ogni progetto, inclusi strumenti come il Toolkit. CDK Questa pratica consente di associare tali componenti a versioni specifiche e di garantire che tutti gli sviluppatori del team (e dell'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.

CDKInclude una dipendenza per il CDK Toolkit nel modello di JavaScript progettopackage.json, quindi se si desidera utilizzare questo approccio, non è necessario apportare alcuna modifica al progetto. Tutto quello che devi fare è usare comandi leggermente diversi per creare la tua app e per emettere cdk comandi.

npx aws-cdkesegue la versione del CDK Toolkit installata localmente nel progetto corrente, se ne esiste una, ricorrendo all'installazione globale, se presente. Se non esiste un'installazione globale, npx scarica una copia temporanea del CDK Toolkit e la esegue. È possibile specificare una versione arbitraria del CDK Toolkit utilizzando la @ sintassi: prints. npx aws-cdk@1.120 --version 1.120.0

Gestione dei moduli AWS Construct Library

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 CDK pacchetto principale, namedaws-cdk-lib, che è una dipendenza predefinita nei nuovi progetti creati da. cdk init I moduli «sperimentali» della AWS Construct Library, in cui i costrutti di livello superiore sono ancora in fase di sviluppo, hanno lo stesso nome. aws-cdk-lib/SERVICE-NAME-alpha Il nome del servizio ha un prefisso aws-. Se non sei sicuro del nome di un modulo, cercalo su. NPM

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 NPM dipendenze del progetto all'ultima versione consentita in base alle regole specificate in: package.json

npm update

In JavaScript, importi i moduli nel tuo codice con lo stesso nome che usi per installarli. 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.

Gestione delle dipendenze in JavaScript

Nei JavaScript CDK progetti, le dipendenze sono specificate nel package.json file nella directory principale del progetto. I AWS CDK moduli principali si trovano in un unico NPM pacchetto chiamatoaws-cdk-lib.

Quando installate un pacchetto usandonpm install, NPM registra il pacchetto al package.json posto vostro.

Se preferisci, puoi usare Yarn al posto diNPM. Tuttavia, non CDK supporta la modalità di Yarn, che è plug-and-play la modalità predefinita in Yarn 2. Aggiungi quanto segue al .yarnrc.yml file del tuo progetto per disattivare questa funzionalità.

nodeLinker: node-modules

CDKapplicazioni

Di seguito è riportato un package.json file di esempio generato dal cdk init --language typescript comando. Il file generato per JavaScript è simile, solo senza le voci TypeScript relative.

{
  "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 CDK app distribuibili, aws-cdk-lib deve essere specificato nella sezione didependencies. package.json Puoi utilizzare un identificatore del numero di versione con cursore (^) per indicare che accetterai 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 usate ^ o ~ poiché le versioni successive di questi moduli potrebbero apportare API modifiche 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. Questo massimizza la compatibilità della tua libreria con una serie di CDK versioni. 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 CDK librerie nell'node_modulesalbero.

IndevDependencies, 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 CDK pacchetti 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.

Installazione e aggiornamento delle dipendenze

Esegui il comando seguente per installare le dipendenze del tuo progetto.

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

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.

AWS CDK idiomi in JavaScript

oggetti di scena

Tutte le classi di AWS Construct Library vengono istanziate utilizzando tre argomenti: l'ambito in cui viene definito il costrutto (l'elemento principale nell'albero dei costrutti), un id e 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.

L'uso di un editor IDE or con un buon JavaScript completamento automatico aiuterà a evitare errori di ortografia dei nomi delle proprietà. Se un costrutto prevede una encryptionKeys proprietà e la scriveteencryptionkeys, quando create un'istanza del costrutto non avete passato il valore desiderato. Ciò può causare un errore al momento della sintesi se la proprietà è obbligatoria o causare l'ignoramento silenzioso della proprietà se è facoltativa. In quest'ultimo caso, è possibile che venga visualizzato un comportamento predefinito che si intende sostituire. Fate particolare attenzione a questo punto.

Quando sottoclassi una classe AWS Construct Library (o si sovrascrive un metodo che accetta un argomento simile a props), potresti voler accettare proprietà aggiuntive per il tuo uso personale. Questi valori verranno ignorati dalla classe principale o dal metodo sovrascritto, perché non sono mai accessibili in quel codice, quindi in genere potete trasmettere tutti gli oggetti di scena che avete ricevuto.

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 (ad esempioprops) hanno il valore in. undefined JavaScript Per affrontarli si applicano le tecniche usuali. Ad esempio, un linguaggio comune per accedere a una proprietà di un valore che può essere indefinito è il seguente:

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

Tuttavia, se a potesse avere qualche altro valore «falso» oltre a questoundefined, è meglio rendere il test più esplicito. Qui, trarremo vantaggio dal fatto che null undefined siamo uguali per testarli entrambi contemporaneamente:

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

Utilizzo di esempi con TypeScript JavaScript

TypeScriptè il linguaggio che utilizziamo per sviluppare il AWS CDK, ed è stato il primo linguaggio supportato per lo sviluppo di applicazioni, quindi sono scritti molti esempi di AWS CDK codice disponibili TypeScript. Questi esempi di codice possono essere una buona risorsa per JavaScript gli sviluppatori; è sufficiente rimuovere le parti TypeScript specifiche del codice.

TypeScript Gli snippet utilizzano spesso le export parole chiave newer ECMAScript import and per importare oggetti da altri moduli e dichiarare che gli oggetti devono essere resi disponibili al di fuori del modulo corrente. Node.js ha appena iniziato a supportare queste parole chiave nelle sue ultime versioni. A seconda della versione di Node.js che stai utilizzando (o che desideri supportare), potresti riscrivere le importazioni e le esportazioni per utilizzare la sintassi precedente.

Le importazioni possono essere sostituite con chiamate alla require() funzione.

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');

Le esportazioni possono essere assegnate all'module.exportsoggetto.

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 }

Dopo aver ordinato le importazioni e le esportazioni, puoi approfondire il codice effettivo. Potresti imbatterti in queste funzionalità di uso comune: TypeScript

È possibile fornire annotazioni di tipo per variabili, membri della classe, parametri di funzione e tipi restituiti dalle funzioni. Per le variabili, i parametri e i membri, i tipi vengono specificati seguendo l'identificatore con i due punti e il tipo. I valori restituiti dalla funzione seguono la firma della funzione e sono costituiti da due punti e dal tipo.

Per convertire il codice annotato sul tipo in JavaScript, rimuovete i due punti e il tipo. I membri della classe devono inserire un valore JavaScript; impostatelo su undefined se hanno solo un'annotazione di tipo. 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) {
    // ...
}

In TypeScript, le interfacce vengono utilizzate per dare un nome a gruppi di proprietà obbligatorie e opzionali e ai relativi tipi. È quindi possibile utilizzare il nome dell'interfaccia come annotazione del tipo. TypeScript si assicurerà che l'oggetto utilizzato come, ad esempio, argomento di una funzione abbia le proprietà richieste dei tipi corretti.

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

JavaScript non ha una funzionalità di interfaccia, quindi dopo aver rimosso le annotazioni di tipo, elimina completamente le dichiarazioni dell'interfaccia.

Quando una funzione o un metodo restituisce un tipo generico (ad esempioobject), ma si desidera trattare tale valore come un tipo figlio più specifico per accedere a proprietà o metodi che non fanno parte dell'interfaccia del tipo più generale, TypeScript consente di eseguire il cast del valore utilizzando as seguito da un tipo o da un nome di interfaccia. JavaScript non lo supporta (o non ne ha bisogno), quindi è sufficiente rimuovere as e il seguente identificatore. Una sintassi cast meno comune consiste nell'utilizzare il nome di un tipo tra parentesi<LikeThis>; anche questi cast devono essere rimossi.

Infine, TypeScript supporta i modificatori public di accesso e per i membri delle classi. protected private Tutti i membri della classe JavaScript sono pubblici. Rimuovi semplicemente questi modificatori ovunque li vedi.

Sapere come identificare e rimuovere queste TypeScript funzionalità è fondamentale per adattare brevi TypeScript frammenti di testo a. JavaScript Tuttavia, potrebbe non essere pratico convertire TypeScript esempi più lunghi in questo modo, poiché è più probabile che utilizzino altre funzionalità. TypeScript Per queste situazioni, consigliamo Sucrase. Sucrase non si lamenterà se il codice utilizza una variabile non definita, ad esempio, come farebbe. tsc Se è sintatticamente valido, con poche eccezioni, Sucrase può tradurlo in. JavaScript Ciò lo rende particolarmente utile per convertire frammenti che potrebbero non essere eseguibili da soli.

Migrazione a TypeScript

Molti JavaScript sviluppatori si trasferiscono TypeScriptman mano che i loro progetti diventano più grandi e complessi. TypeScript è un superset di JavaScript: tutto il JavaScript codice è un TypeScript codice valido, quindi non sono necessarie modifiche al codice, ed è anche un linguaggio supportato. AWS CDK Le annotazioni di tipo e altre TypeScript funzionalità sono opzionali e possono essere aggiunte all' AWS CDK app man mano che ne trovi il valore. TypeScript offre inoltre l'accesso anticipato a nuove JavaScript funzionalità, come il concatenamento opzionale e il coalescenza nullish, prima che vengano finalizzate e senza richiedere l'aggiornamento di Node.js.

TypeScript, che definiscono pacchetti di proprietà obbligatorie e opzionali (e i relativi tipi) all'interno di un oggetto, consentono di rilevare gli errori più comuni durante la scrittura del codice e semplificano la fornitura di solidi consigli di completamento automatico e altri consigli di codifica in tempo reale. IDE

La codifica TypeScript comporta un passaggio aggiuntivo: la compilazione dell'app con il compilatore,. TypeScript tsc Per AWS CDK le app tipiche, la compilazione richiede al massimo alcuni secondi.

Il modo più semplice per migrare un' JavaScript AWS CDK app esistente TypeScript è creare un nuovo TypeScript progetto utilizzando cdk init app --language typescript e quindi copiare i file sorgente (e qualsiasi altro file necessario, ad esempio risorse come il codice sorgente delle AWS Lambda funzioni) nel nuovo progetto. Rinomina i JavaScript file in modo che terminino .ts e inizi a svilupparli in. TypeScript