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.

Configuração de mensagens e interações do Kit de Ferramentas CDK

A Biblioteca do Kit de Ferramentas CDK da AWS fornece a interface IIoHost para personalizar a forma como as mensagens e interações são tratadas durante as operações do CDK, permitindo que você controle a exibição do andamento da implantação, das mensagens de erro e dos avisos do usuário para melhor integração com a experiência do usuário da sua aplicação.

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

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

Uso da interface IIoHost

A interface IIoHost 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 mensagens e tipos de solicitação

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

Níveis de mensagens

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

Tipos de solicitação

O Kit de Ferramentas CDK 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 Kit de Ferramentas 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 de e/s 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 Kit de Ferramentas CDK aguarda a conclusão de cada chamada, permitindo que você execute operações assíncronas, como solicitações de HTTP ou solicitações do usuário, ao lidar com mensagens.

Comportamento padrão do IIoHost

Se você não fornecer um host ide e/s personalizado, a Biblioteca do Kit de Ferramentas CDK usa uma implementação padrão não interativa:

Esse comportamento padrão é adequado para operações autônomas, mas não para aplicações de linha de comando interativas. Para aplicações de linha de comando que exijam interação do usuário, você precisará implementar um host de e/s personalizado. Implementações personalizadas também são úteis para integração com sistemas de log, interfaces de usuário ou outros ambientes especializados.

Implementação avançada de host de e/s

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

Veja abaixo um exemplo de host de e/s 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 interface IIoHost do zero, pois você só precisa substituir os métodos específicos que exijam comportamento personalizado.

Integração com diferentes ambientes

Integração com aplicações da 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 de ambientes de 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
});

Práticas recomendadas para implementação de host de e/s

Ao implementar um host de e/s personalizado, considere estas práticas recomendadas:

O exemplo a seguir demonstra essas melhores práticas implementando um host de e/s personalizado com tratamento de erros, tempos limite para interações do usuário e logs adequados. Essa implementação é adequada para aplicações interativas em que você precise 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 de e/s 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 de e/s permaneça compatível com as atualizações do CDK, mantendo os logs adequados:

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