本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 根据注解生成架构
<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 { ... }`插件扩展来应用这些选项：


| Option | 选项描述 | 值 | 
| --- | --- | --- | 
| generateBuilderClasses | 控制是否为带有注释的类生成 DSL 风格的生成器类 `@DynamoDbItem` | `WHEN_REQUIRED`（默认）：对于仅包含公共可变成员且具有零参数构造函数的类，不会生成生成器类<br />`ALWAYS`: 生成器类将始终生成 | 
| visibility | 控制生成的类的可见性 | `PUBLIC`（默认值）<br />`INTERNAL` | 
| destinationPackage | 为生成的类指定软件包名称 | `RELATIVE`（默认）：架构类将在子包中生成，相对于您的带注释的类。默认情况下，子包已命名`dynamodbmapper.generatedschemas`，可通过传递字符串参数进行配置<br />`ABSOLUTE`: 架构类将在相对于应用程序根目录的绝对包中生成。默认情况下，软件包已命名`aws.sdk.kotlin.hll.dynamodbmapper.generatedschemas`，可通过传递字符串参数进行配置。 | 
| generateGetTableExtension | 控制是否生成`DynamoDbMapper.get${CLASS_NAME}Table`扩展方法 | `true`（默认值）<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`：指定这 class/interface 描述了表中的项目类型。除非明确忽略这些属性，否则所有此类公共属性都将映射到属性。如果存在，则将为该类生成一个架构。
  + `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 映射 to/from 器不应将该类属性转换为项目属性。
+ `@[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`类注释。

首先，我们`[ValueConverter](https://docs.aws.amazon.com/sdk-for-kotlin/api/latest/dynamodb-mapper/aws.sdk.kotlin.hll.dynamodbmapper.values/-value-converter/index.html)`为`kotlin.uuid.Uuid`类实现 a：

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

然后，我们`ItemConverter`为我们的`Employee`班级实现一个。在 “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 中使用该类了。