設定 DynamoDB Mapper - 適用於 Kotlin 的 AWS SDK
使用攔截器

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

設定 DynamoDB Mapper

DynamoDB Mapper 是開發人員預覽版本。其功能不完整，可能會有所變更。

DynamoDB Mapper 提供組態選項，您可以使用自訂程式庫的行為以符合您的應用程式。

使用攔截器

DynamoDB Mapper 程式庫定義您可以在映射器請求管道的關鍵階段使用掛鉤。您可以實作Interceptor界面來實作勾點，以觀察或修改映射器程序。

您可以將單一 DynamoDB Mapper 上的一或多個攔截器註冊為組態選項。如需如何註冊攔截器，請參閱本節結尾的範例。

了解請求管道

映射器的請求管道包含下列 5 個步驟：

  1. 初始化：設定 操作並收集初始內容。

  2. 序列化：將高階請求物件轉換為低階請求物件。此步驟會將高階 Kotlin 物件轉換為由屬性名稱和值組成的 DynamoDB 項目。

  3. 低階調用：在基礎 DynamoDB 用戶端上執行請求。

  4. 去序列化：將低階回應物件轉換為高階回應物件。此步驟包含將包含屬性名稱和值的 DynamoDB 項目轉換為高階 Kotlin 物件。

  5. 完成：完成高階回應以傳回給發起人。如果在管道執行期間擲回例外狀況，此步驟會完成擲回給發起人的例外狀況。

勾點

勾點是映射器在管道中特定步驟之前或之後調用的攔截器方法。勾點有兩種變體：唯讀和修改 （或讀寫）。例如， readBeforeInvocation 是唯讀勾點，映射器會在低階調用步驟之前於 階段執行。

唯讀勾點

映射器會在管道中每個步驟之前和之後叫用唯讀勾點 (初始化步驟之前和完成步驟之後除外）。唯讀機罩提供正在進行的高階操作的唯讀檢視。它們提供一種機制來檢查 操作的狀態，例如記錄、偵錯、收集指標。每個唯讀勾點都會接收內容引數並傳回 Unit。

映射器會擷取在唯讀勾點期間擲回的任何例外狀況，並將其新增至內容。然後，它會將例外狀況的內容傳遞給相同階段的後續攔截器掛鉤。映射器只會在呼叫最後一個攔截器相同階段的唯讀勾點之後，才會將任何例外狀況擲回給發起人。例如，如果映射器設定了兩個攔截器A和 B，而 A的readAfterSerialization勾點擲回例外狀況，映射器會將例外狀況新增至傳遞至 B勾readAfterSerialization點的內容。B的readAfterSerialization勾點完成後，映射器會將例外狀況擲回給發起人。

修改掛鉤

映射器會在管道中的每個步驟之前叫用修改掛鉤 (初始化之前除外）。修改掛鉤可讓您查看和修改正在進行的高階操作。它們可用來以映射器組態和項目結構描述未採用的方式自訂行為和資料。每個修改勾點都會接收內容引數，並傳回該內容的一些子集，由勾點修改或從輸入內容傳遞。

如果映射器在執行修改掛鉤時擷取任何例外狀況，則不會在相同階段執行任何其他攔截器的修改掛鉤。映射器會將例外狀況新增至內容，並將其傳遞至下一個唯讀勾點。映射器只會在呼叫最後一個攔截者的相同階段唯讀勾點之後，才會將任何例外狀況擲回給發起人。例如，如果映射器設定了兩個攔截器A和 B，而 A的modifyBeforeSerialization勾點擲回例外狀況，則不會叫用 B的modifyBeforeSerialization勾點。將執行攔截器 A和 B's readAfterSerialization hook，之後會將例外狀況擲回給發起人。

執行順序

在映射器的組態中定義攔截器的順序決定映射器呼叫勾點的順序：

  • 對於低階調用步驟之前的階段，它會以其在組態中新增的相同順序執行掛鉤。

  • 對於低階調用步驟之後的階段，它會以與組態中新增的順序相反的順序執行勾點。

下圖顯示勾點方法的執行順序：

攔截器勾點方法的流程圖。

映射器會依下列順序執行攔截器的勾點：

  1. DynamoDB Mapper 調用高階請求

  2. 執行前讀取

  3. 在序列化之前修改

  4. 序列化前讀取

  5. DynamoDB Mapper 會將物件轉換為項目

  6. 序列化後讀取

  7. 叫用前修改

  8. 叫用前讀取

  9. DynamoDB Mapper 調用低階操作

  10. 叫用後讀取

  11. 在還原序列化之前修改

  12. 還原序列化前讀取

  13. DynamoDB Mapper 會將項目轉換為物件

  14. 還原序列化後讀取

  15. 完成前修改

  16. 執行後讀取

  17. DynamoDB Mapper 傳回高階回應

範例組態

下列範例示範如何在DynamoDbMapper執行個體上設定攔截器：

import aws.sdk.kotlin.hll.dynamodbmapper.DynamoDbMapper
import aws.sdk.kotlin.hll.dynamodbmapper.operations.ScanRequest
import aws.sdk.kotlin.hll.dynamodbmapper.operations.ScanResponse
import aws.sdk.kotlin.hll.dynamodbmapper.pipeline.Interceptor
import aws.sdk.kotlin.services.dynamodb.DynamoDbClient
import aws.sdk.kotlin.services.dynamodb.model.ScanRequest as LowLevelScanRequest
import aws.sdk.kotlin.services.dynamodb.model.ScanResponse as LowLevelScanResponse

val printingInterceptor = object : Interceptor<User, ScanRequest<User>, LowLevelScanRequest, LowLevelScanResponse, ScanResponse<User>> {
    override fun readBeforeDeserialization(ctx: LResContext<User, ScanRequest<User>, LowLevelScanRequest, LowLevelScanResponse>) {
        println("Scan response contains ${ctx.lowLevelResponse.count} items.")
    }
}

val client = DynamoDbClient.fromEnvironment()

val mapper = DynamoDbMapper(client) {
    interceptors += printingInterceptor
}