Ini adalah Panduan Pengembang AWS CDK v2. CDK v1 yang lebih lama memasuki pemeliharaan pada 1 Juni 2022 dan mengakhiri dukungan pada 1 Juni 2023.

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Mengkonfigurasi pesan dan interaksi CDK Toolkit

AWS CDK Toolkit Library menyediakan IIoHost antarmuka untuk menyesuaikan bagaimana pesan dan interaksi ditangani selama operasi CDK, memungkinkan Anda untuk mengontrol tampilan kemajuan penerapan, pesan kesalahan, dan permintaan pengguna untuk lebih terintegrasi dengan pengalaman pengguna aplikasi Anda.

Sebelum melakukan operasi seperti penyebaran atau sintesis, Anda perlu memahami bagaimana CDK Toolkit berkomunikasi dengan pengguna. IIoHostAntarmuka berfungsi sebagai saluran komunikasi antara CDK Toolkit dan aplikasi Anda, menangani pesan keluar dan respons pengguna yang masuk.

Ketika CDK Toolkit menjalankan operasi, ia berkomunikasi melalui dua mekanisme utama:

Menggunakan IIoHost antarmuka

IIoHostAntarmuka terdiri dari dua metode utama:

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

Tingkat pesan dan jenis permintaan

CDK Toolkit menghasilkan beberapa jenis pesan dan permintaan:

Tingkat pesan

Untuk daftar lengkapnya, lihat IoMessages Registri di Referensi API Perpustakaan Toolkit AWS CDK.

Tipe permintaan

CDK Toolkit mengirimkan permintaan ketika membutuhkan input atau konfirmasi dari pengguna. Ini adalah pesan khusus yang memungkinkan respons. Jika tidak ada respons yang diberikan, Toolkit akan menggunakan respons default bila tersedia.

IIoHostImplementasi dasar

Berikut adalah contoh sederhana penerapan host io khusus:

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

CDK Toolkit menunggu penyelesaian setiap panggilan, memungkinkan Anda untuk melakukan operasi asinkron seperti permintaan HTTP atau permintaan pengguna saat menangani pesan.

IIoHostPerilaku default

Jika Anda tidak menyediakan host io khusus, Perpustakaan Toolkit CDK menggunakan implementasi non-interaktif default:

Perilaku default ini cocok untuk operasi tanpa pengawasan, tetapi tidak untuk aplikasi baris perintah interaktif. Untuk aplikasi baris perintah yang memerlukan interaksi pengguna, Anda harus mengimplementasikan host io khusus. Implementasi kustom juga berguna untuk mengintegrasikan dengan sistem logging UIs, atau lingkungan khusus lainnya.

Implementasi io host tingkat lanjut

Untuk skenario yang lebih kompleks, kami sarankan untuk memperluas NonInteractiveIoHost kelas sebagai titik awal. Pendekatan ini memungkinkan Anda untuk memanfaatkan implementasi non-interaktif yang ada sambil hanya menyesuaikan perilaku spesifik yang perlu Anda ubah.

Berikut adalah contoh host io khusus yang memperluas implementasi dasar:

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

Pendekatan ini lebih dapat dipertahankan daripada mengimplementasikan seluruh IIoHost antarmuka dari awal, karena Anda hanya perlu mengganti metode spesifik yang memerlukan perilaku khusus.

Integrasi dengan lingkungan yang berbeda

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

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

Praktik terbaik untuk implementasi io host

Saat menerapkan host io khusus, pertimbangkan praktik terbaik ini:

Contoh berikut menunjukkan praktik terbaik ini dengan menerapkan host io khusus dengan penanganan kesalahan, batas waktu untuk interaksi pengguna, dan pencatatan yang tepat. Implementasi ini cocok untuk aplikasi interaktif di mana Anda perlu menyeimbangkan respons pengguna dengan operasi yang andal:

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

Pemecahan Masalah

Pertimbangan saat menerapkan host io khusus:

Contoh berikut menunjukkan pendekatan yang kuat untuk menangani tingkat pesan, termasuk penanganan yang anggun dari jenis pesan yang tidak dikenal yang mungkin diperkenalkan di versi CDK masa depan. Implementasi ini memastikan host io Anda tetap kompatibel dengan pembaruan CDK sambil mempertahankan pencatatan yang tepat:

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