Este é o Guia do desenvolvedor do AWS CDK v2. O CDK v1 antigo entrou em manutenção em 1º de junho de 2022 e encerrou o suporte em 1º de junho de 2023.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Configurando mensagens e interações do CDK Toolkit

A AWS CDK Toolkit Library fornece a IIoHost interface para personalizar como as mensagens e interações são tratadas durante as operações do CDK, permitindo que você controle a exibição do progresso da implantação, das mensagens de erro e dos avisos do usuário para melhor integração com a experiência do usuário do seu aplicativo.

Antes de realizar operações como implantação ou síntese, você precisa entender como o CDK Toolkit se comunica com os usuários. A IIoHost interface serve como canal de comunicação entre o CDK Toolkit e seu aplicativo, gerenciando tanto as mensagens enviadas quanto as respostas recebidas do usuário.

Quando o CDK Toolkit executa operações, ele se comunica por meio de dois mecanismos principais:

Usando a IIoHost interface

A IIoHost interface consiste em dois métodos principais:

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

Níveis de mensagem e tipos de solicitação

O CDK Toolkit gera vários tipos de mensagens e solicitações:

Níveis de mensagem

Para obter uma lista completa, consulte IoMessages Registro na Referência da API da Biblioteca do AWS CDK Toolkit.

Tipos de solicitação

O CDK Toolkit envia solicitações quando precisa de informações ou confirmação do usuário. Essas são mensagens especiais que permitem uma resposta. Se nenhuma resposta for fornecida, o Toolkit usará uma resposta padrão quando disponível.

Implementação básica do IIoHost

Aqui está um exemplo simples de implementação de um host io personalizado:

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

O CDK Toolkit aguarda a conclusão de cada chamada, permitindo que você execute operações assíncronas, como solicitações HTTP ou solicitações do usuário, ao lidar com mensagens.

IIoHostComportamento padrão

Se você não fornecer um host io personalizado, a Biblioteca do CDK Toolkit usa uma implementação padrão não interativa:

Esse comportamento padrão é adequado para operações autônomas, mas não para aplicativos de linha de comando interativos. Para aplicativos de linha de comando que exigem interação do usuário, você precisará implementar um host io personalizado. Implementações personalizadas também são úteis para integração com sistemas de registro ou outros ambientes especializados. UIs

Implementação avançada de host io

Para cenários mais complexos, recomendamos estender a NonInteractiveIoHost aula como ponto de partida. Essa abordagem permite que você aproveite a implementação não interativa existente enquanto personaliza somente os comportamentos específicos que você precisa alterar.

Aqui está um exemplo de um host io personalizado que estende a implementação básica:

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}`);
  }
}

Essa abordagem é mais fácil de manter do que implementar toda a IIoHost interface do zero, pois você só precisa substituir os métodos específicos que exigem comportamento personalizado.

Integração com diferentes ambientes

Integração de aplicativos 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
});

Integração do 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
});

Melhores práticas para implementação de host io

Ao implementar um host io personalizado, considere estas melhores práticas:

O exemplo a seguir demonstra essas melhores práticas implementando um host io personalizado com tratamento de erros, tempos limite para interações do usuário e registro adequado. Essa implementação é adequada para aplicativos interativos em que você precisa equilibrar a capacidade de resposta do usuário com uma operação confiável:

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

Solução de problemas

Considerações ao implementar um host io personalizado:

O exemplo a seguir demonstra uma abordagem robusta para lidar com níveis de mensagem, incluindo o tratamento elegante de tipos de mensagens desconhecidos que podem ser introduzidos em futuras versões do CDK. Essa implementação garante que seu host io permaneça compatível com as atualizações do CDK, mantendo o registro adequado:

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