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

# 從註釋產生結構描述
<a name="ddb-mapper-anno-schema-gen"></a>

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

DynamoDB Mapper 依賴於定義 Kotlin 類別與 DynamoDB 項目之間映射的結構描述。您的 Kotlin 類別可以使用結構描述產生器 Gradle 外掛程式來推動結構描述的建立。

## 套用外掛程式
<a name="ddb-mapper-anno-schema-gen-plugin"></a>

若要開始為您的類別產生程式碼結構描述，請在應用程式的建置指令碼中套用外掛程式，並在註釋模組上新增相依性。下列 Gradle 指令碼程式碼片段顯示產生程式碼所需的設定。

（您可以導覽至 {{X.Y.Z}} 連結，以查看可用的最新版本。)

```
// build.gradle.kts
val sdkVersion: String = [https://github.com/awslabs/aws-sdk-kotlin/releases/latest](https://github.com/awslabs/aws-sdk-kotlin/releases/latest) 

plugins {
    id("aws.sdk.kotlin.hll.dynamodbmapper.schema.generator") version "$sdkVersion-beta" // For the Developer Preview, use the beta version of the latest SDK.
}

dependencies {
    implementation("aws.sdk.kotlin:dynamodb-mapper:$sdkVersion-beta")
    implementation("aws.sdk.kotlin:dynamodb-mapper-annotations:$sdkVersion-beta")
}
```

## 設定 外掛程式
<a name="ddb-mapper-anno-schema-gen-conf-plugin"></a>

外掛程式提供許多組態選項，您可以使用建置指令碼中的`dynamoDbMapper { ... }`外掛程式延伸來套用：


| 選項 | 選項描述 | 值 | 
| --- | --- | --- | 
| generateBuilderClasses | 控制是否為標註 的類別產生 DSL 樣式建置器類別 `@DynamoDbItem` | `WHEN_REQUIRED` （預設）：不會對僅包含公有可變成員且具有零位元建構函數的類別產生建置器類別<br />`ALWAYS`：一律會產生建置器類別 | 
| visibility | 控制所產生類別的可見性 | `PUBLIC` (default)<br />`INTERNAL` | 
| destinationPackage | 指定所產生類別的套件名稱 | `RELATIVE` （預設）：結構描述類別會在相對於註釋類別的子套件中產生。依預設，子套件名為 `dynamodbmapper.generatedschemas` ，可透過傳遞字串參數來設定<br />`ABSOLUTE`：結構描述類別會在相對於應用程式根目錄的絕對套件中產生。根據預設，套件名為 `aws.sdk.kotlin.hll.dynamodbmapper.generatedschemas`，且可透過傳遞字串參數來設定。 | 
| generateGetTableExtension | 控制是否會產生`DynamoDbMapper.get${CLASS_NAME}Table`延伸方法 | `true` (default)<br />`false` | 

**Example 程式碼產生外掛程式組態的範例**  
下列範例會設定目的地套件和產生結構描述的可見性：  

```
// build.gradle.kts

import aws.sdk.kotlin.hll.dynamodbmapper.codegen.annotations.DestinationPackage
import aws.sdk.kotlin.hll.dynamodbmapper.codegen.annotations.Visibility
import aws.smithy.kotlin.runtime.ExperimentalApi

@OptIn(ExperimentalApi::class)
dynamoDbMapper {
    destinationPackage = DestinationPackage.RELATIVE("my.configured.package")
    visibility = Visibility.INTERNAL
}
```

## 註釋類別
<a name="ddb-mapper-anno-schema-gen-annotate"></a>

結構描述產生器會尋找類別註釋，以決定要產生結構描述的類別。若要選擇加入產生結構描述，請使用 標註您的類別`@[DynamoDbItem](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)`。您也必須將做為項目分割區索引鍵的類別屬性加上註釋`@[DynamoDbPartitionKey](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-partition-key/index.html)`。

下列類別定義顯示產生結構描述所需的最低註釋：

**Example**  

```
@DynamoDbItem
data class Employee(
    @DynamoDbPartitionKey
    val id: Int,
    
    val name: String,
    val role: String,
)
```

### 類別註釋
<a name="ddb-mapper-anno-schema-gen-class-annos"></a>

下列註釋會套用至類別以控制結構描述產生：
+ `@DynamoDbItem`：指定此類別/界面描述資料表中的項目類型。除非明確忽略，否則此類型的所有公有屬性都會對應至屬性。出現時，將會為此類別產生結構描述。
  + `converterName`：選用參數，指出應使用自訂結構描述，而不是結構描述產生器外掛程式所建立的。這是自訂`ItemConverter`類別的完整名稱。[定義自訂項目轉換器](#ddb-mapper-anno-schema-custom) 本節顯示建立和使用自訂結構描述的範例。

### 屬性註釋
<a name="ddb-mapper-anno-schema-gen-prop-annos"></a>

您可以將下列註釋套用至類別屬性，以控制結構描述產生：
+ `@[https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)`：指定項目的分割區索引鍵。
+ `@[DynamoDbSortKey](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-sort-key/index.html)`：指定項目的選用排序索引鍵。
+ `@[DynamoDbIgnore](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-ignore/index.html)`：指定此類別屬性不應由 DynamoDB Mapper 轉換為項目屬性或從中轉換。
+ `@[DynamoDbAttribute](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-attribute/index.html)`：指定此類別屬性的選用自訂屬性名稱。

## 定義自訂項目轉換器
<a name="ddb-mapper-anno-schema-custom"></a>

在某些情況下，您可能想要為 類別定義自訂項目轉換器。其中一個原因是，如果您的類別使用結構描述產生器外掛程式不支援的類型。我們使用下列版本的 `Employee`類別做為範例：

```
import kotlin.uuid.Uuid

@DynamoDbItem
data class Employee(
    @DynamoDbPartitionKey
    var id: Int,
    
    var name: String,
    var role: String,
    var workstationId: Uuid
)
```

`Employee` 類別現在使用 類型，結構描述產生器目前不支援此`kotlin.uuid.Uuid`類型。產生結構描述失敗並發生錯誤：`Unsupported attribute type TypeRef(pkg=kotlin.uuid, shortName=Uuid, genericArgs=[], nullable=false)`。此錯誤表示外掛程式無法為此類別產生項目轉換器。因此，我們需要撰寫自己的 。

為此，我們為 類別實作 `[ItemConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.items/-item-converter/index.html)` ，然後透過指定新項目轉換器的完整名稱來修改`@DynamoDbItem`類別註釋。

首先，我們為 `kotlin.uuid.Uuid`類別實作 `[ValueConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.values/-value-converter/index.html)` ：

```
import aws.sdk.kotlin.hll.dynamodbmapper.values.ValueConverter
import aws.sdk.kotlin.services.dynamodb.model.AttributeValue
import kotlin.uuid.Uuid

public val UuidValueConverter = object : ValueConverter<Uuid> {
    override fun convertFrom(to: AttributeValue): Uuid = 
        Uuid.parseHex(to.asS())
        
    override fun convertTo(from: Uuid): AttributeValue = 
        AttributeValue.S(from.toHexString())
}
```

然後，我們為 `Employee`類別實作 `ItemConverter` 。會在 "workstationId" 的屬性描述項中`ItemConverter`使用此新值轉換器：

```
import aws.sdk.kotlin.hll.dynamodbmapper.items.AttributeDescriptor
import aws.sdk.kotlin.hll.dynamodbmapper.items.ItemConverter
import aws.sdk.kotlin.hll.dynamodbmapper.items.SimpleItemConverter
import aws.sdk.kotlin.hll.dynamodbmapper.values.scalars.IntConverter
import aws.sdk.kotlin.hll.dynamodbmapper.values.scalars.StringConverter

public object MyEmployeeConverter : ItemConverter<Employee> by SimpleItemConverter(
    builderFactory = { Employee() },
    build = { this },
    descriptors = arrayOf(
        AttributeDescriptor(
            "id",
            Employee::id,
            Employee::id::set,
            IntConverter,
        ),
        AttributeDescriptor(
            "name",
            Employee::name,
            Employee::name::set,
            StringConverter,
        ),
        AttributeDescriptor(
            "role",
            Employee::role,
            Employee::role::set,
            StringConverter
        ),
        AttributeDescriptor(
            "workstationId",
            Employee::workstationId,
            Employee::workstationId::set,
            UuidValueConverter
        )
    ),
)
```

現在我們已經定義項目轉換器，我們可以將其套用至我們的類別。我們會提供完整類別名稱來更新`@[DynamoDbItem](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper-annotations/aws.sdk.kotlin.hll.dynamodbmapper/-dynamo-db-item/index.html)`註釋以參考項目轉換器，如下所示：

```
import kotlin.uuid.Uuid

@DynamoDbItem("my.custom.item.converter.MyEmployeeConverter")
data class Employee(
    @DynamoDbPartitionKey
    var id: Int,
    
    var name: String,
    var role: String,
    var workstationId: Uuid
)
```

最後，我們可以開始將 類別與 DynamoDB Mapper 搭配使用。