기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 주석에서 스키마 생성
<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`: Builder 클래스가 항상 생성됩니다. | 
| 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`:이 클래스/인터페이스가 테이블의 항목 유형을 설명하도록 지정합니다. 이 유형의 모든 퍼블릭 속성은 명시적으로 무시되지 않는 한 속성에 매핑됩니다. 존재하는 경우이 클래스에 대한 스키마가 생성됩니다.
  + `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에서 클래스 사용을 시작할 수 있습니다.