Configurazione dei messaggi e delle interazioni di CDK Toolkit - AWS Cloud Development Kit (AWS CDK) v2

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

Configurazione dei messaggi e delle interazioni di CDK Toolkit

La AWS CDK Toolkit Library fornisce l' IIoHost interfaccia per personalizzare il modo in cui i messaggi e le interazioni vengono gestiti durante le operazioni CDK, consentendovi di controllare la visualizzazione dello stato di avanzamento della distribuzione, dei messaggi di errore e delle istruzioni utente per una migliore integrazione con l'esperienza utente dell'applicazione.

Prima di eseguire operazioni come l'implementazione o la sintesi, è necessario comprendere come CDK Toolkit comunica con gli utenti. L'IIoHostinterfaccia funge da canale di comunicazione tra CDK Toolkit e l'applicazione, gestendo sia i messaggi in uscita che le risposte degli utenti in entrata.

Quando CDK Toolkit esegue le operazioni, comunica attraverso due meccanismi principali:

  • Messaggi: output informativi che informano l'utente sullo stato di avanzamento dell'operazione (come «Avvio della distribuzione» o «Creazione di risorse»).

  • Richieste: punti decisionali che richiedono l'immissione o la conferma (ad esempio «Vuoi implementare queste modifiche?») , offrendoti l'opportunità di fornire informazioni che prima non erano ritenute necessarie.

Utilizzo dell'interfaccia IIoHost

L'IIoHostinterfaccia è costituita da due metodi principali:

  1. notify: gestisce i messaggi informativi unidirezionali.

  2. requestResponse: gestisce le richieste interattive che richiedono una risposta.

import { IoMessage, IoRequest } from '@aws-cdk/toolkit-lib'; interface IIoHost { // Handle informational messages notify(message: IoMessage): Promise<void>; // Handle requests that need responses requestResponse(request: IoRequest): Promise<any>; }

Livelli di messaggi e tipi di richieste

Il CDK Toolkit genera diversi tipi di messaggi e richieste:

Livelli di messaggio

  • Debug: messaggi dettagliati per la risoluzione dei problemi.

  • Errore: messaggi di errore che possono influire sul funzionamento.

  • Informazioni: messaggi informativi generali.

  • Risultato: messaggio principale di un'operazione.

  • Trace: informazioni molto dettagliate sul flusso di esecuzione.

  • Avviso: messaggi di avviso che non impediscono il funzionamento.

Per un elenco completo, consultate IoMessages Registry nel riferimento all'API AWS CDK Toolkit Library.

Tipi di richieste

CDK Toolkit invia richieste quando necessita di input o conferma da parte dell'utente. Si tratta di messaggi speciali che consentono una risposta. Se non viene fornita alcuna risposta, il Toolkit utilizzerà una risposta predefinita quando disponibile.

implementazione di base IIoHost

Ecco un semplice esempio di implementazione di un host io personalizzato:

import { Toolkit } from '@aws-cdk/toolkit-lib'; // Create a toolkit with custom message handling const toolkit = new Toolkit({ ioHost: { // Implementing the IIoHost interface // Handle informational messages notify: async function (msg) { // Example: Handle different message levels appropriately switch (msg.level) { case 'error': console.error(`[${msg.time}] ERROR: ${msg.message}`); break; case 'warning': console.warn(`[${msg.time}] WARNING: ${msg.message}`); break; case 'info': console.info(`[${msg.time}] INFO: ${msg.message}`); break; case 'debug': console.debug(`[${msg.time}] DEBUG: ${msg.message}`); break; case 'trace': console.debug(`[${msg.time}] TRACE: ${msg.message}`); break; default: console.log(`[${msg.time}] ${msg.level}: ${msg.message}`); } }, // Handle requests that need responses requestResponse: async function (msg) { // Example: Log the request and use default response console.log(`Request: ${msg.message}, using default: ${msg.defaultResponse}`); return msg.defaultResponse; // Or implement custom logic to provide responses // if (msg.type === 'deploy') { // return promptUserForDeployment(msg); // } } } as IIoHost // Explicitly cast to IIoHost interface });

Il CDK Toolkit attende il completamento di ogni chiamata e consente di eseguire operazioni asincrone come richieste HTTP o istruzioni utente durante la gestione dei messaggi.

Comportamento predefinito IIoHost

Se non fornite un host io personalizzato, la CDK Toolkit Library utilizza un'implementazione non interattiva predefinita:

  • Output da console per i messaggi (utilizzando colori appropriati per diversi tipi di messaggi).

  • Completamente non interattivo senza richieste di input da parte dell'utente.

  • Utilizza automaticamente le risposte predefinite laddove possibile (equivalente a rispondere «sì» alle richieste).

  • Fallisce quando è richiesto un input ma non è disponibile una risposta predefinita.

Questo comportamento predefinito è adatto per le operazioni non presidiate, ma non per le applicazioni interattive a riga di comando. Per le applicazioni da riga di comando che richiedono l'interazione dell'utente, è necessario implementare un host io personalizzato. Le implementazioni personalizzate sono utili anche per l'integrazione con sistemi di registrazione o altri ambienti specializzati UIs.

Implementazione avanzata dell'host io

Per scenari più complessi, consigliamo di estendere la NonInteractiveIoHost classe come punto di partenza. Questo approccio consente di sfruttare l'implementazione non interattiva esistente personalizzando solo i comportamenti specifici che è necessario modificare.

Ecco un esempio di un host io personalizzato che estende l'implementazione di base:

import { NonInteractiveIoHost } from '@aws-cdk/toolkit-lib'; class MyCustomIoHost extends NonInteractiveIoHost { // Override only the methods you need to customize // Example: Custom implementation for notify public async notify(msg: IoMessage<unknown>): Promise<void> { // Add custom notification handling logic if (msg.level === 'error') { console.error(`ERROR: ${msg.message}`); // Optionally log to a service or notify a monitoring system await this.logToMonitoringService(msg); } else { await super.notify(msg); } } // Example: Custom implementation for requestResponse public async requestResponse<T, U>(request: IoRequest<T, U>): Promise<U> { // Implement custom request handling console.log(`Received request: ${request.message}`); return request.defaultResponse; } private async logToMonitoringService(msg: IoMessage<unknown>): Promise<void> { // Implementation for monitoring service integration console.log(`Logging to monitoring service: ${msg.level} - ${msg.message}`); } }

Questo approccio è più gestibile rispetto all'implementazione dell'intera IIoHost interfaccia da zero, poiché è sufficiente sovrascrivere i metodi specifici che richiedono un comportamento personalizzato.

Integrazione con ambienti diversi

Integrazione di applicazioni Web

import { Toolkit } from '@aws-cdk/toolkit-lib'; // Example for integrating with a web application const toolkit = new Toolkit({ ioHost: { notify: async function (msg) { // Send message to frontend via WebSocket webSocketServer.send(JSON.stringify({ type: 'cdk-notification', messageLevel: msg.level, message: msg.message, time: msg.time })); }, requestResponse: async function (msg) { // Create a promise that will be resolved when the user responds return new Promise((resolve) => { const requestId = generateUniqueId(); // Store the resolver function pendingRequests[requestId] = resolve; // Send request to frontend webSocketServer.send(JSON.stringify({ type: 'cdk-request', requestId: requestId, requestType: msg.type, message: msg.message, defaultResponse: msg.defaultResponse })); // Frontend would call an API endpoint with the response, // which would then call pendingRequests[requestId](response) }); } } as IIoHost // Explicitly cast to IIoHost interface });

Integrazione dell'ambiente CI/CD

import { Toolkit } from '@aws-cdk/toolkit-lib'; // Example for CI/CD environments (non-interactive) const toolkit = new Toolkit({ ioHost: { notify: async function (msg) { // Log all messages with appropriate level switch (msg.level) { case 'error': console.error(msg.message); break; case 'warning': console.warn(msg.message); break; default: console.log(msg.message); } }, requestResponse: async function (msg) { // In CI/CD, always use default responses or predefined answers console.log(`Auto-responding to request: ${msg.message} with ${msg.defaultResponse}`); return msg.defaultResponse; } } as IIoHost // Explicitly cast to IIoHost interface });

Le migliori pratiche per l'implementazione di io host

Quando implementi un host io personalizzato, prendi in considerazione queste best practice:

  • Gestione degli errori: implementate una solida gestione degli errori nei metodi degli host io per evitare che gli errori influiscano sulle operazioni CDK.

  • Timeout: prendete in considerazione l'implementazione di timeout per le interazioni con gli utenti per evitare attese indefinite.

  • Registrazione: archivia i messaggi importanti nei registri per la risoluzione dei problemi, specialmente in ambienti non interattivi.

  • Risposte predefinite: fornisce risposte predefinite ragionevoli per ambienti automatizzati in cui l'interazione dell'utente non è possibile.

  • Indicazione dello stato di avanzamento: per le operazioni di lunga durata, fornisci indicatori di avanzamento chiari per migliorare l'esperienza dell'utente.

L'esempio seguente dimostra queste best practice implementando un host io personalizzato con gestione degli errori, timeout per le interazioni con gli utenti e registrazione corretta. Questa implementazione è adatta per applicazioni interattive in cui è necessario bilanciare la reattività dell'utente con un funzionamento affidabile:

import { Toolkit } from '@aws-cdk/toolkit-lib'; // Example with error handling and timeouts const toolkit = new Toolkit({ ioHost: { notify: async function (msg) { try { console.log(`[${msg.time}] ${msg.level}: ${msg.message}`); // Additional logging or UI updates } catch (error) { // Ensure errors in notification handling don't break the CDK operation console.error("Error handling notification:", error); } }, requestResponse: async function (msg) { try { // Implement timeout for user response const response = await Promise.race([ getUserResponse(msg), new Promise(resolve => setTimeout(() => resolve(msg.defaultResponse), 60000)) ]); return response; } catch (error) { console.error("Error handling request:", error); return msg.defaultResponse; } } } as IIoHost // Explicitly cast to IIoHost interface });

Risoluzione dei problemi

Considerazioni sull'implementazione di un host io personalizzato:

  • Rifiuti di promesse non gestiti: assicurati che tutte le operazioni asincrone siano gestite correttamente con i blocchi try/catch.

  • Attesa infinita: implementa i timeout per tutte le interazioni degli utenti per evitare che l'applicazione si blocchi.

  • Livelli di messaggio mancanti: preparatevi a gestire nuovi livelli di messaggio che potrebbero essere aggiunti nelle future versioni di CDK.

  • Risposte incoerenti: assicurati che l'implementazione di RequestResponse restituisca valori nel formato previsto.

L'esempio seguente dimostra un approccio robusto alla gestione dei livelli di messaggio, inclusa la gestione corretta di tipi di messaggi sconosciuti che potrebbero essere introdotti nelle future versioni di CDK. Questa implementazione garantisce che il tuo host io rimanga compatibile con gli aggiornamenti CDK mantenendo una registrazione corretta:

import { Toolkit } from '@aws-cdk/toolkit-lib'; // Example of handling unknown message levels const toolkit = new Toolkit({ ioHost: { notify: async function (msg) { // Handle known levels const knownLevels = ['info', 'warning', 'error', 'debug', 'trace', 'status']; if (knownLevels.includes(msg.level)) { // Handle known level handleKnownMessageLevel(msg); } else { // Handle unknown level as info console.log(`Unknown message level "${msg.level}": ${msg.message}`); } }, requestResponse: async function (msg) { // Default implementation return msg.defaultResponse; } } as IIoHost // Explicitly cast to IIoHost interface });