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

# 手動定義結構描述
<a name="ddb-mapper-code-schemas"></a>

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

## 在程式碼中定義結構描述
<a name="ddb-mapper-gs-manual-schema-def"></a>

為了獲得最大的控制和可自訂性，您可以在程式碼中手動定義和自訂結構描述。

如下列程式碼片段所示，相較於使用註釋驅動的結構描述建立，您需要在 `build.gradle.kts` 檔案中包含較少的相依性。

（您可以導覽至 *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) 

dependencies {
    implementation("aws.sdk.kotlin:dynamodb-mapper:$sdkVersion-beta") // For the Developer Preview, use the beta version of the latest SDK.
}
```

請注意，您不需要結構描述產生器外掛程式或註釋套件。

Kotlin 類別和 DynamoDB 項目之間的映射需要`[ItemSchema<T>](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.items/-item-schema/index.html)`實作，其中 `T`是 Kotlin 類別的類型。結構描述包含下列元素：
+ 項目轉換器，定義如何在 Kotlin 物件執行個體和 DynamoDB 項目之間轉換。
+ 分割區索引鍵規格，定義分割區索引鍵屬性的名稱和類型。
+ 或者，排序索引鍵規格，定義排序索引鍵屬性的名稱和類型。

在下列程式碼中，我們會手動建立`CarSchema`執行個體：

```
import aws.sdk.kotlin.hll.dynamodbmapper.items.ItemConverter
import aws.sdk.kotlin.hll.dynamodbmapper.items.ItemSchema
import aws.sdk.kotlin.hll.dynamodbmapper.model.itemOf

// We define a schema for this data class.
data class Car(val make: String, val model: String, val initialYear: Int)

// First, define an item converter.
val carConverter = object : ItemConverter<Car> {
    override fun convertTo(from: Car, onlyAttributes: Set<String>?): Item  = itemOf(
        "make" to AttributeValue.S(from.make),
        "model" to AttributeValue.S(from.model),
        "initialYear" to AttributeValue.N(from.initialYear.toString()),
    )

    override fun convertFrom(to: Item): Car = Car(
        make = to["make"]?.asSOrNull() ?: error("Invalid attribute `make`"),
        model = to["model"]?.asSOrNull() ?: error("Invalid attribute `model`"),
        initialYear = to["initialYear"]?.asNOrNull()?.toIntOrNull()
            ?: error("Invalid attribute `initialYear`"),
    )
}

// Next, define the specifications for the partition key and sort key.
val makeKey = KeySpec.String("make")
val modelKey = KeySpec.String("model")

// Finally, create the schema from the converter and key specifications.
// Note that the KeySpec for the partition key comes first in the ItemSchema constructor.
val CarSchema = ItemSchema(carConverter, makeKey, modelKey)
```

先前的程式碼會建立名為 的轉換器`carConverter`，其定義為 的匿名實作`ItemConverter<Car>`。轉換器的 `convertTo`方法接受`Car`引數，並傳回代表 DynamoDB 項目屬性常值索引鍵和值的`Item`執行個體。轉換器的 `convertFrom`方法接受 `Item`引數，並從`Item`引數的屬性值傳回`Car`執行個體。

接下來，程式碼會建立兩個索引鍵規格：一個用於分割區索引鍵，另一個用於排序索引鍵。每個 DynamoDB 資料表或索引都必須只有一個分割區索引鍵，因此每個 DynamoDB Mapper 結構描述定義都必須相應。結構描述也可能有一個排序索引鍵。

在最後一個陳述式中，程式碼會從轉換器和金鑰規格建立 `cars` DynamoDB 資料表的結構描述。

產生的結構描述等同於我們在 [使用類別註釋定義結構描述](ddb-mapper-get-started.md#ddb-mapper-gs-anno-schema-def)區段中產生的註釋驅動結構描述。以下是我們使用的註釋類別，以供參考：

### 具有 DynamoDB Mapper 註釋的汽車類別
<a name="ejd_mxz_ddc"></a>

```
@DynamoDbItem
data class Car(
    @DynamoDbPartitionKey
    val make: String,
    
    @DynamoDbSortKey
    val model: String,
    
    val initialYear: Int
)
```

除了實作您自己的 之外`ItemConverter`，DynamoDB Mapper 還包含數個實用的實作，例如：
+ `[SimpleItemConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.items/-simple-item-converter/index.html)`：使用建置器類別和屬性描述項提供簡單的轉換邏輯。如需[定義自訂項目轉換器](ddb-mapper-anno-schema-gen.md#ddb-mapper-anno-schema-custom)如何使用此實作，請參閱 中的範例。
+ `[HeterogeneousItemConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.items/-heterogeneous-item-converter/index.html)`：透過使用辨別器屬性和委派子類型的`ItemConverter`執行個體，提供多態類型轉換邏輯。
+ `[DocumentConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.items/-document-converter/index.html)`：為 [https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.content/-document.html](https://docs.aws.amazon.com/smithy-kotlin/api/latest/runtime-core/aws.smithy.kotlin.runtime.content/-document.html) 物件中的非結構化資料提供轉換邏輯。