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
<a name="toolkit-library-configure-messages"></a>

 AWS CDK Toolkit Library menyediakan ` [IIoHost](https://docs.aws.amazon.com/cdk/api/toolkit-lib/Package/toolkit-lib/Interface/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. `IIoHost`Antarmuka 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:
+  **Pesan**: Output informasi yang memberi tahu Anda tentang kemajuan operasi (seperti “Memulai penerapan” atau “Sumber daya dibuat”).
+  **Permintaan**: Poin keputusan yang memerlukan masukan atau konfirmasi (seperti “Apakah Anda ingin menerapkan perubahan ini?”) , memberi Anda kesempatan untuk memberikan informasi yang tidak diketahui dibutuhkan sebelumnya.

## Menggunakan `IIoHost` antarmuka
<a name="toolkit-library-configure-messages-iiohost"></a>

`IIoHost`Antarmuka terdiri dari dua metode utama:

1.  `notify`: Menangani pesan informasi satu arah.

1.  `requestResponse`: Menangani permintaan interaktif yang memerlukan respons.

```
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
<a name="toolkit-library-configure-messages-levels"></a>

CDK Toolkit menghasilkan beberapa jenis pesan dan permintaan:

### Tingkat pesan
<a name="_message_levels"></a>
+  **Debug**: Pesan terperinci untuk pemecahan masalah.
+  **Kesalahan**: Pesan kesalahan yang dapat memengaruhi operasi.
+  **Info**: Pesan informasi umum.
+  **Hasil** - Pesan utama dari suatu operasi.
+  **Trace**: Informasi alur eksekusi yang sangat rinci.
+  **Peringatan**: Pesan peringatan yang tidak mencegah operasi.

Untuk daftar lengkapnya, lihat [IoMessages Registri di Referensi](https://docs.aws.amazon.com/cdk/api/toolkit-lib/message-registry/) *API Perpustakaan Toolkit AWS CDK*.

### Tipe permintaan
<a name="_request_types"></a>

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.

## `IIoHost`Implementasi dasar
<a name="toolkit-library-configure-messages-basic"></a>

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.

## `IIoHost`Perilaku default
<a name="toolkit-library-configure-messages-iiohost-default"></a>

Jika Anda tidak menyediakan host io khusus, Perpustakaan Toolkit CDK menggunakan implementasi non-interaktif default:
+ Output konsol untuk pesan (menggunakan warna yang sesuai untuk berbagai jenis pesan).
+ Sepenuhnya non-interaktif tanpa petunjuk untuk input pengguna.
+ Secara otomatis menggunakan respons default jika memungkinkan (setara dengan menjawab “ya” untuk permintaan).
+ Gagal saat input diperlukan tetapi tidak ada respons default yang tersedia.

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
<a name="toolkit-library-configure-messages-advanced"></a>

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
<a name="toolkit-library-configure-messages-integration"></a>

### Integrasi aplikasi web
<a name="_web_application_integration"></a>

```
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
<a name="_cicd_environment_integration"></a>

```
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
<a name="toolkit-library-configure-messages-best-practices"></a>

Saat menerapkan host io khusus, pertimbangkan praktik terbaik ini:
+  **Penanganan kesalahan**: Terapkan penanganan kesalahan yang kuat dalam metode host io Anda untuk mencegah kegagalan memengaruhi operasi CDK.
+  **Timeout**: Pertimbangkan untuk menerapkan batas waktu untuk interaksi pengguna untuk mencegah penantian yang tidak terbatas.
+  **Logging**: Simpan pesan penting dalam log untuk pemecahan masalah, terutama di lingkungan non-interaktif.
+  **Respons default**: Berikan respons default yang masuk akal untuk lingkungan otomatis di mana interaksi pengguna tidak dimungkinkan.
+  **Indikasi kemajuan**: Untuk operasi yang berjalan lama, berikan indikator kemajuan yang jelas untuk meningkatkan pengalaman pengguna.

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
<a name="toolkit-library-configure-messages-troubleshooting"></a>

Pertimbangan saat menerapkan host io khusus:
+  **Penolakan janji yang tidak tertangani**: Pastikan semua operasi asinkron ditangani dengan benar dengan blok coba/tangkap.
+  **Penantian tak terbatas**: Terapkan batas waktu untuk semua interaksi pengguna untuk mencegah aplikasi macet.
+  **Tingkat pesan yang hilang**: Bersiaplah untuk menangani tingkat pesan baru yang mungkin ditambahkan di versi CDK masa depan.
+  **Respons yang tidak konsisten**: Pastikan implementasi requestResponse Anda mengembalikan nilai dalam format yang diharapkan.

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