本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 第 1 版與第 2 版之間的 DynamoDB 映射 API 差異 適用於 Java 的 AWS SDK
DynamoDB 映射 APIs 第 1 版和第 2 版之間發生重大變更 適用於 Java 的 AWS SDK。在第 1 版中，您可以使用 `DynamoDBMapper` 來使用 Java POJOs。在第 2 版中，您可以使用 `DynamoDbEnhancedClient` 搭配更新的方法名稱、增強型結構描述定義選項，以及改善的類型安全性。
主要差異包括：
+ 新的方法名稱 （例如 `getItem` 而非 `load`)
+ 明確資料表結構描述建立
+ 同步和非同步操作的內建支援
+ 如何處理空白字串和組態的變更
本節涵蓋映射 API 變更、註釋差異、組態更新和遷移指引，以協助您從 v1 轉換`DynamoDBMapper`到 v2`DynamoDbEnhancedClient`。
**Contents**
+ [從適用於 Java 的 SDK 第 1 版到第 2 版映射程式庫的高階變更](dynamodb-mapping-high-level.md)
+ [匯入相依性差異](dynamodb-mapping-high-level.md#dynamodb-mapping-deps)
+ [適用於 Java 的 SDK 第 1 版和第 2 版之間的 DynamoDB 映射 APIs 變更](dynamodb-mapping-api-changes.md)
+ [建立用戶端](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-client)
+ [建立對 DynamoDB 資料表/索引的映射](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-mapping)
+ [資料表操作](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-tobleops)
+ [映射類別和屬性](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas)
+ [Bean 註釋](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas-annos)
+ [V2 其他註釋](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas-annos-v2-addnl)
+ [Configuration](dynamodb-mapping-api-changes.md#dynamodb-mapping-configuration)
+ [每個操作組態](dynamodb-mapping-api-changes.md#dynamodb-mapping-configuration-per-op)
+ [有條件](dynamodb-mapping-api-changes.md#dynamodb-mapping-conditionals)
+ [類型轉換](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv)
+ [預設轉換器](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-defaults)
+ [設定屬性的自訂轉換器](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-anno)
+ [新增類型轉換器工廠或供應商](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-factory)
+ [適用於 Java 的 SDK 第 1 版和第 2 版之間的字串處理差異](dynamodb-migration-string-handling.md)
+ [適用於 Java 的 SDK 第 1 版和第 2 版之間的樂觀鎖定差異](dynamodb-migrate-optimstic-locking.md)
+ [適用於 Java 的 SDK 第 1 版和第 2 版之間的流暢設定器差異](dynamodb-migrate-fluent-setters.md)
# 從適用於 Java 的 SDK 第 1 版到第 2 版映射程式庫的高階變更
每個程式庫中的映射用戶端名稱在 V1 和 V2 中不同：
+ V1 - DynamoDBMapper
+ V2 - DynamoDB 增強型用戶端
您以大致相同的方式與兩個程式庫互動：您執行個體化映射器/用戶端，然後將 Java POJO 提供給讀取和寫入這些項目至 DynamoDB 資料表APIs。這兩個程式庫也提供 POJO 類別的註釋，以指示用戶端如何處理 POJO。
移至 V2 時的顯著差異包括：
+ V2 和 V1 對低階 DynamoDB 操作使用不同的方法名稱。例如：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/dynamodb-mapping-high-level.html)
+ V2 提供多種方法來定義資料表結構描述，並將 POJOs對應至資料表。您可以選擇使用註釋，或使用建置器從程式碼產生的結構描述。V2 還提供結構描述的可變和不可變版本。
+ 使用 V2 時，您會特別將資料表結構描述建立為第一個步驟之一，而在 V1 中，則會視需要從註釋的類別推斷資料表結構描述。
+ V2 在增強型[用戶端 API 中包含文件 ](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html) API 用戶端，而 V1 使用[單獨的 API](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html)。
+ 所有 APIs V2 中提供同步和非同步版本。
如需 V2 增強型用戶端的詳細資訊，請參閱本指南中的 [DynamoDB 映射一節](dynamodb-enhanced-client.md)。
## 匯入相依性差異
| V1 | V2 |
| --- | --- |
|
com.amazonaws
aws-java-sdk-bom
1.X.X
pom
import
com.amazonaws
aws-java-sdk-dynamodb
|
software.amazon.awssdk
bom
2.X.X*
pom
import
software.amazon.awssdk
dynamodb-enhanced
|
\$1 [最新版本](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)。
在 V1 中，單一相依性同時包含低階 DynamoDB API 和映射/文件 API，而在 V2 中，您可以使用`dynamodb-enhanced`成品相依性來存取映射/文件 API。`dynamodb-enhanced` 模組包含低階`dynamodb`模組的暫時性相依性。
# 適用於 Java 的 SDK 第 1 版和第 2 版之間的 DynamoDB 映射 APIs 變更
## 建立用戶端
****
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 正常執行個體化 | AmazonDynamoDB standardClient = AmazonDynamoDBClientBuilder.standard()
.withCredentials(credentialsProvider)
.withRegion(Regions.US_EAST_1)
.build();
DynamoDBMapper mapper = new DynamoDBMapper(standardClient);
| DynamoDbClient standardClient = DynamoDbClient.builder()
.credentialsProvider(ProfileCredentialsProvider.create())
.region(Region.US_EAST_1)
.build();
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(standardClient)
.build();
|
| 最小執行個體化 | AmazonDynamoDB standardClient = AmazonDynamoDBClientBuilder.standard();
DynamoDBMapper mapper = new DynamoDBMapper(standardClient);
| DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.create();
|
| 使用屬性轉換器\$1 | DynamoDBMapper mapper = new DynamoDBMapper(standardClient,
attributeTransformerInstance);
| DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(standardClient)
.extensions(extensionAInstance, extensionBInstance)
.build();
|
\$1V2 中的延伸大致對應至 V1 中的屬性轉換器。[使用擴充功能自訂 DynamoDB 增強型用戶端操作](ddb-en-client-extensions.md) 本節包含 V2 中延伸模組的詳細資訊。
## 建立對 DynamoDB 資料表/索引的映射
在 V1 中，您可以透過 Bean 註釋指定 DynamoDB 資料表名稱。在 V2 中，原廠方法 `table()`會產生`DynamoDbTable`代表遠端 DynamoDB 資料表的 執行個體。`table()` 方法的第一個參數是 DynamoDB 資料表名稱。
****
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 將 Java POJO 類別映射至 DynamoDB 資料表 | @DynamoDBTable(tableName ="Customer")
public class Customer {
...
}
| DynamoDbTable customerTable = enhancedClient.table("Customer",
TableSchema.fromBean(Customer.class));
|
| 映射至 DynamoDB 次要索引 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) DynamoDB 開發人員指南中討論[ V1 `query`方法](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html#DynamoDBMapper.Methods.query)的 區段會顯示完整的範例。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) 本指南中的 [使用次要索引](ddb-en-client-use-secindex.md)區段提供更多資訊。 |
## 資料表操作
本節說明適用於大多數標準使用案例的 V1 和 V2 之間的操作 APIs。
在 V2 中，所有涉及單一資料表的操作都會在`DynamoDbTable`執行個體上呼叫，而不是在增強型用戶端上呼叫。增強型用戶端包含可將多個資料表設為目標的方法。
在下列名為*資料表操作*的資料表中，POJO 執行個體稱為 `item`或特定類型，例如 `customer1`。對於名為 的執行個體的 V2 範例， `table`是先前呼叫 `enhancedClient.table()`傳回執行個體參考的結果`DynamoDbTable`。
請注意，即使未顯示，大多數 V2 操作也可以使用流暢的消費者模式來呼叫。例如
```
Customer customer = table.getItem(r → r.key(key));
or
Customer customer = table.getItem(r → r.key(k -> k.partitionValue("id").sortValue("email")))
```
對於 V1 操作，*資料表操作* （下方） 包含一些常用表單，而不是所有超載表單。例如， `load()`方法具有下列過載：
```
mapper.load(Customer.class, hashKey)
mapper.load(Customer.class, hashKey, rangeKey)
mapper.load(Customer.class, hashKey, config)
mapper.load(Customer.class, hashKey, rangeKey, config)
mapper.load(item)
mapper.load(item, config)
```
*資料表操作* （下方） 顯示常用的表單：
```
mapper.load(item)
mapper.load(item, config)
```
**資料表操作**
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 將 Java POJO 寫入 DynamoDB 資料表 **DynamoDB 操作：**`PutItem`、 `UpdateItem` | mapper.save(item)
mapper.save(item, config)
mapper.save(item, saveExpression, config)
在 V1 中， `DynamoDBMapperConfig.SaveBehavior`和 註釋會決定要呼叫哪個低階 DynamoDB 方法。一般而言， `UpdateItem` 會在使用 `SaveBehavior.CLOBBER`和 時呼叫 `SaveBehavior.PUT`。自動產生的金鑰是特殊的使用案例，偶爾同時使用 `UpdateItem` `PutItem`和 。 | table.putItem(putItemRequest)
table.putItem(item)
table.putItemWithResponse(item) //Returns metadata.
updateItem(updateItemRequest)
table.updateItem(item)
table.updateItemWithResponse(item) //Returns metadata.
|
| 從 DynamoDB 資料表將項目讀取至 Java POJO **DynamoDB 操作：** `GetItem` | mapper.load(item)
mapper.load(item, config)
| table.getItem(getItemRequest)
table.getItem(item)
table.getItem(key)
table.getItemWithResponse(key) //Returns POJO with metadata.
|
| 從 DynamoDB 資料表刪除項目 **DynamoDB 操作：** `DeleteItem` | mapper.delete(item, deleteExpression, config)
| table.deleteItem(deleteItemRequest)
table.deleteItem(item)
table.deleteItem(key)
|
| 查詢 DynamoDB 資料表或次要索引並傳回分頁清單 **DynamoDB 操作：** `Query` | mapper.query(Customer.class, queryExpression)
mapper.query(Customer.class, queryExpression,
mapperConfig)
| table.query(queryRequest)
table.query(queryConditional)
將傳回的 `PageIterable.stream()`（延遲載入） 用於同步回應和非`PagePublisher.subscribe()`同步回應 |
| 查詢 DynamoDB 資料表或次要索引並傳回清單 **DynamoDB 操作：** `Query` | mapper.queryPage(Customer.class, queryExpression)
mapper.queryPage(Customer.class, queryExpression,
mapperConfig)
| table.query(queryRequest)
table.query(queryConditional)
將傳回的 `PageIterable.items()`（延遲載入） 用於同步回應和非`PagePublisher.items.subscribe()`同步回應 |
| 掃描 DynamoDB 資料表或次要索引並傳回分頁清單 **DynamoDB 操作：** `Scan` | mapper.scan(Customer.class, scanExpression)
mapper.scan(Customer.class, scanExpression,
mapperConfig)
| table.scan()
table.scan(scanRequest)
將傳回的 `PageIterable.stream()`（延遲載入） 用於同步回應和非`PagePublisher.subscribe()`同步回應 |
| 掃描 DynamoDB 資料表或次要索引並傳回清單 **DynamoDB 操作：** `Scan` | mapper.scanPage(Customer.class, scanExpression)
mapper.scanPage(Customer.class, scanExpression,
mapperConfig)
| table.scan()
table.scan(scanRequest)
將傳回的 `PageIterable.items()`（延遲載入） 用於同步回應和非`PagePublisher.items.subscribe()`同步回應 |
| 從批次中的多個資料表讀取多個項目 **DynamoDB 操作：** `BatchGetItem` | mapper.batchLoad(Arrays.asList(customer1,
customer2,
book1))
mapper.batchLoad(itemsToGet)
// itemsToGet: Map, List>
| enhancedClient.batchGetItem(batchGetItemRequest)
enhancedClient.batchGetItem(r -> r.readBatches(
ReadBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addGetItem(i -> i.key(k -> k.partitionValue(0)))
.build(),
ReadBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addGetItem(i -> i.key(k -> k.partitionValue(0)))
.build()))
// Iterate over pages with lazy loading or over all items
from the same table.
|
| 將多個項目寫入批次中的多個資料表 **DynamoDB 操作：** `BatchWriteItem` | mapper.batchSave(Arrays.asList(customer1,
customer2,
book1))
| enhancedClient.batchWriteItem(batchWriteItemRequest)
enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addPutItem(item1)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addPutItem(item2)
.build()))
|
| 從批次中的多個資料表刪除多個項目 **DynamoDB 操作：** `BatchWriteItem` | mapper.batchDelete(Arrays.asList(customer1,
customer2,
book1))
| enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addDeleteItem(item1key)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addDeleteItem(item2key)
.build()))
|
| 寫入/刪除批次中的多個項目 **DynamoDB 操作：** `BatchWriteItem` | mapper.batchWrite(Arrays.asList(customer1, book1),
Arrays.asList(customer2))
| enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addPutItem(item1)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addDeleteItem(item2key)
.build()))
|
| 執行交易寫入 **DynamoDB 操作：** `TransactWriteItems` | mapper.transactionWrite(transactionWriteRequest)
| enhancedClient.transactWriteItems(transasctWriteItemsRequest)
|
| 執行交易讀取 **DynamoDB 操作：** `TransactGetItems` | mapper.transactionLoad(transactionLoadRequest)
| enhancedClient.transactGetItems(transactGetItemsRequest)
|
| 取得查詢相符項目的計數 **DynamoDB 操作：**`Query`使用 `Select.COUNT` | mapper.count(Customer.class, queryExpression)
| // Get the count from query results.
PageIterable pageIterable =
customerTable.query(QueryEnhancedRequest.builder()
.queryConditional(queryConditional)
.select(Select.COUNT)
.build());
Iterator> iterator = pageIterable.iterator();
Page page = iterator.next();
int count = page.count();
// For a more concise approach, you can chain the method calls:
int count = customerTable.query(QueryEnhancedRequest.builder()
.queryConditional(queryConditional)
.select(Select.COUNT)
.build())
.iterator().next().count();
|
| 取得掃描相符項目的計數 **DynamoDB 操作：**`Scan`使用 `Select.COUNT` | mapper.count(Customer.class, scanExpression)
| // Get the count from scan results.
PageIterable pageIterable =
customerTable.scan(ScanEnhancedRequest.builder()
.filterExpression(filterExpression)
.select(Select.COUNT)
.build());
Iterator> iterator = pageIterable.iterator();
Page page = iterator.next();
int count = page.count();
// For a more concise approach, you can chain the method calls:
int count = customerTable.scan(ScanEnhancedRequest.builder()
.filterExpression(filterExpression)
.select(Select.COUNT)
.build())
.iterator().next().count();
|
| 在對應至 POJO 類別的 DynamoDB 中建立資料表 **DynamoDB 操作：** `CreateTable` | mapper.generateCreateTableRequest(Customer.class)
先前的陳述式會產生低階建立資料表請求；使用者必須在 DynamoDB 用戶端`createTable`上呼叫 。 | table.createTable(createTableRequest)
table.createTable(r -> r.provisionedThroughput(defaultThroughput())
.globalSecondaryIndices(
EnhancedGlobalSecondaryIndex.builder()
.indexName("gsi_1")
.projection(p -> p.projectionType(ProjectionType.ALL))
.provisionedThroughput(defaultThroughput())
.build()));
|
| 在 DynamoDB 中執行平行掃描 **DynamoDB 操作：**`Scan`使用 `Segment`和 `TotalSegments` 參數 | mapper.parallelScan(Customer.class,
scanExpression,
numTotalSegments)
| 使用者需要處理`scan`每個區段的工作者執行緒和呼叫： table.scan(r -> r.segment(0).totalSegments(5))
|
| 將 Amazon S3 與 DynamoDB 整合，以存放智慧型 S3 連結 | mapper.createS3Link(bucket, key)
mapper.getS3ClientCache()
| 不支援，因為它會耦合 Amazon S3 和 DynamoDB。 |
## 映射類別和屬性
在 V1 和 V2 中，您可以使用 Bean 樣式註釋將類別映射至資料表。V2 也提供[其他方法來定義特定使用案例的結構描述](ddb-en-client-adv-features.md#ddb-en-client-adv-features-schm-overview)，例如使用不可變類別。
### Bean 註釋
下表顯示 V1 和 V2 中使用的特定使用案例的同等 Bean 註釋。`Customer` 類別案例用於說明參數。
在 V2 中，註釋以及類別和列舉都遵循駱駝案例慣例，並使用「DynamoDb」，而不是「DynamoDB」。
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 將類別映射至資料表 | @DynamoDBTable (tableName ="CustomerTable")
| @DynamoDbBean
@DynamoDbBean(converterProviders = {...})
呼叫 DynamoDbEnhancedClient\$1table()方法時會定義資料表名稱。 |
| 將類別成員指定為資料表屬性 | @DynamoDBAttribute(attributeName = "customerName")
| @DynamoDbAttribute("customerName") |
| 指定類別成員是雜湊/分割區索引鍵 | @DynamoDBHashKey
| @DynamoDbPartitionKey
|
| 指定類別成員是範圍/排序索引鍵 | @DynamoDBRangeKey
| @DynamoDbSortKey
|
| 指定類別成員是次要索引雜湊/分割區索引鍵 | @DynamoDBIndexHashKey
| @DynamoDbSecondaryPartitionKey
|
| 指定類別成員是次要索引範圍/排序索引鍵 | @DynamoDBIndexRangeKey
| @DynamoDbSecondarySortKey
|
| 映射至資料表時忽略此類別成員 | @DynamoDBIgnore
| @DynamoDbIgnore
|
| 將類別成員指定為自動產生的 UUID 金鑰屬性 | @DynamoDBAutoGeneratedKey
| @DynamoDbAutoGeneratedUuid
根據預設，不會載入提供此項目的延伸模組；您必須將延伸模組新增至用戶端建置器。 |
| 將類別成員指定為自動產生的時間戳記屬性 | @DynamoDBAutoGeneratedTimestamp
| @DynamoDbAutoGeneratedTimestampAttribute
根據預設，不會載入提供此項目的延伸模組；您必須將延伸模組新增至用戶端建置器。 |
| 將類別成員指定為自動遞增版本屬性 | @DynamoDBVersionAttribute
| @DynamoDbVersionAttribute
自動載入提供此功能的延伸模組。 |
| 將類別成員指定為需要自訂轉換 | @DynamoDBTypeConverted
| @DynamoDbConvertedBy
|
| 指定要儲存為不同屬性類型的類別成員 | @DynamoDBTyped()
| 使用 `AttributeConverter`實作。V2 為常見 Java 類型提供許多內建轉換器。您也可以實作自己的自訂 `AttributeConverter`或 `AttributeConverterProvider`。請參閱本指南[控制屬性轉換](ddb-en-client-adv-features-conversion.md)中的 。 |
| 指定可序列化為 DynamoDB 文件 (JSON 樣式文件） 或子文件的類別 | @DynamoDBDocument
| 使用增強型文件 API。請參閱下列資源：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
### V2 其他註釋
| 使用案例 | V1 | V2 |
| --- | --- | --- |
| 如果 Java 值為 null，則指定類別成員不要儲存為 NULL 屬性 | N/A | @DynamoDbIgnoreNulls
|
| 如果所有屬性都是 null，請將類別成員指定為空白物件 | N/A | @DynamoDbPreserveEmptyObject
|
| 為類別成員指定特殊更新動作 | N/A | @DynamoDbUpdateBehavior
|
| 指定不可變類別 | N/A | @DynamoDbImmutable
|
| 將類別成員指定為自動遞增的計數器屬性 | N/A | @DynamoDbAtomicCounter
自動載入提供此功能的延伸模組。 |
## Configuration
在 V1 中，您通常會使用 執行個體來控制特定行為`DynamoDBMapperConfig`。您可以在建立映射器或提出請求時提供組態物件。在 V2 中，組態專屬於 操作的請求物件。
| 使用案例 | V1 | V1 中的預設值 | V2 |
| --- | --- | --- | --- |
| | DynamoDBMapperConfig.builder()
| | |
| 批次載入/寫入重試策略 | .withBatchLoadRetryStrategy(loadRetryStrategy)
.withBatchWriteRetryStrategy(writeRetryStrategy)
| 重試失敗的項目 | 在基礎 上設定重試策略DynamoDBClient。請參閱本指南[在 中設定重試行為 AWS SDK for Java 2.x](retry-strategy.md)中的 。 |
| 一致的讀取 | .withConsistentReads(CONSISTENT)
| EVENTUAL | 根據預設，讀取操作的一致性讀取為 false。在請求物件.consistentRead(true)上使用 覆寫 。 |
| 具有 marshallers/unmarshallers 集的轉換結構描述 | .withConversionSchema(conversionSchema)
靜態實作提供與舊版的回溯相容性。 | V2\$1COMPATIBLE | 不適用。這是舊版功能，指 DynamoDB (V1) 儲存資料類型的最早版本，而且此行為不會保留在增強型用戶端中。DynamoDB V1 中的行為範例是將布林值儲存為數字而非布林值。 |
| 資料表名稱 | .withObjectTableNameResolver()
.withTableNameOverride()
.withTableNameResolver()
靜態實作提供與舊版的回溯相容性 | 使用 類別的註釋或猜測 | 呼叫 `DynamoDbEnhancedClient#table()`方法時會定義資料表名稱。 |
| 分頁載入策略 | .withPaginationLoadingStrategy(strategy)
選項為：LAZY\$1`EAGER_LOADING`、 `LOADING`或 `ITERATION_ONLY` | LAZY\$1LOADING | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
| 請求指標集合 | .withRequestMetricCollector(collector)
| null | 在建置標準 DynamoDB 用戶端metricPublisher()ClientOverrideConfiguration時使用 。 |
| 儲存行為 | .withSaveBehavior(SaveBehavior.CLOBBER)
選項為 `UPDATE`、`CLOBBER`、`APPEND_SET`、 `PUT`或 `UPDATE_SKIP_NULL_ATTRIBUTES`。 | UPDATE | 在 V2 中，您可以明確呼叫 `putItem()`或 `updateItem()` 。 `CLOBBER or PUT`：v 2 中的對應動作正在呼叫 `putItem()`。沒有特定的`CLOBBER`組態。 `UPDATE`：對應至 `updateItem()` `UPDATE_SKIP_NULL_ATTRIBUTES`：對應至 `updateItem()`。使用請求設定`ignoreNulls`和註釋/標籤 控制更新行為`DynamoDbUpdateBehavior`。 `APPEND_SET`：不支援 |
| 類型轉換器工廠 | .withTypeConverterFactory(typeConverterFactory)
| 標準類型轉換器 | 使用 在 Bean 上設定 @DynamoDbBean(converterProviders = {ConverterProvider.class,
DefaultAttributeConverterProvider.class}) |
### 每個操作組態
在 V1 中，某些操作，例如 `query()`，可透過提交至操作的「運算式」物件進行高度設定。例如：
```
DynamoDBQueryExpression emailBwQueryExpr = new DynamoDBQueryExpression()
.withRangeKeyCondition("Email",
new Condition()
.withComparisonOperator(ComparisonOperator.BEGINS_WITH)
.withAttributeValueList(
new AttributeValue().withS("my")));
mapper.query(Customer.class, emailBwQueryExpr);
```
在 V2 中，您可以使用建置器在請求物件上設定參數，而不是使用組態物件。例如：
```
QueryEnhancedRequest emailBw = QueryEnhancedRequest.builder()
.queryConditional(QueryConditional
.sortBeginsWith(kb -> kb
.sortValue("my"))).build();
customerTable.query(emailBw);
```
## 有條件
在 V2 中，條件式和篩選表達式會使用 物件來表示，該`Expression`物件會封裝條件以及名稱和篩選條件的映射。
| 使用案例 | 作業 | V1 | V2 |
| --- | --- | --- | --- |
| 預期的屬性條件 | save()， delete()， query()， scan() | new DynamoDBSaveExpression()
.withExpected(Collections.singletonMap(
"otherAttribute", new ExpectedAttributeValue(false)))
.withConditionalOperator(ConditionalOperator.AND);
| 已棄用；請ConditionExpression改用 。 |
| 條件表達式 | delete() | deleteExpression.setConditionExpression("zipcode = :zipcode")
deleteExpression.setExpressionAttributeValues(...)
| Expression conditionExpression =
Expression.builder()
.expression("#key = :value OR #key1 = :value1")
.putExpressionName("#key", "attribute")
.putExpressionName("#key1", "attribute3")
.putExpressionValue(":value", AttributeValues.stringValue("wrong"))
.putExpressionValue(":value1", AttributeValues.stringValue("three"))
.build();
DeleteItemEnhancedRequest request = DeleteItemEnhancedRequest.builder()
.conditionExpression(conditionExpression).build();
|
| 篩選條件表達式 | query()， scan() | scanExpression
.withFilterExpression("#statename = :state")
.withExpressionAttributeValues(attributeValueMapBuilder.build())
.withExpressionAttributeNames(attributeNameMapBuilder.build())
| Map values = singletonMap(":key", stringValue("value"));
Expression filterExpression =
Expression.builder()
.expression("name = :key")
.expressionValues(values)
.build();
QueryEnhancedRequest request = QueryEnhancedRequest.builder()
.filterExpression(filterExpression).build();
|
| 查詢的條件表達式 | query() | queryExpression.withKeyConditionExpression()
| QueryConditional keyEqual = QueryConditional.keyEqualTo(b -> b
.partitionValue("movie01"));
QueryEnhancedRequest tableQuery = QueryEnhancedRequest.builder()
.queryConditional(keyEqual)
.build();
|
## 類型轉換
### 預設轉換器
在 V2 中， SDK 為所有常見類型提供一組預設轉換器。您可以在整體供應商層級以及單一屬性變更類型轉換器。您可以在 [AttributeConverter](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/AttributeConverter.html) API 參考中找到可用轉換器的清單。
### 設定屬性的自訂轉換器
在 V1 中，您可以使用 註釋 getter 方法`@DynamoDBTypeConverted`，以指定在 Java 屬性類型和 DynamoDB 屬性類型之間轉換的類別。例如，可在 Java `Currency`類型和 DynamoDB 字串之間`CurrencyFormatConverter`轉換的 可套用，如下列程式碼片段所示。
```
@DynamoDBTypeConverted(converter = CurrencyFormatConverter.class)
public Currency getCurrency() { return currency; }
```
上一個程式碼片段的 V2 對等項目如下所示。
```
@DynamoDbConvertedBy(CurrencyFormatConverter.class)
public Currency getCurrency() { return currency; }
```
**注意**
在 V1 中，您可以將註釋套用至屬性本身 、類型或使用者定義的註釋，V2 僅支援將註釋套用至 getter。
### 新增類型轉換器工廠或供應商
在 V1 中，您可以提供自己的一組類型轉換器，或透過將類型轉換器工廠新增至組態來覆寫您關心的類型。類型轉換器工廠擴展 `DynamoDBTypeConverterFactory`，覆寫是透過取得預設設定的參考並將其擴展來完成。下列程式碼片段示範如何執行此操作。
```
DynamoDBTypeConverterFactory typeConverterFactory =
DynamoDBTypeConverterFactory.standard().override()
.with(String.class, CustomBoolean.class, new DynamoDBTypeConverter() {
@Override
public String convert(CustomBoolean bool) {
return String.valueOf(bool.getValue());
}
@Override
public CustomBoolean unconvert(String string) {
return new CustomBoolean(Boolean.valueOf(string));
}}).build();
DynamoDBMapperConfig config =
DynamoDBMapperConfig.builder()
.withTypeConverterFactory(typeConverterFactory)
.build();
DynamoDBMapper mapperWithTypeConverterFactory = new DynamoDBMapper(dynamo, config);
```
V2 透過`@DynamoDbBean`註釋提供類似的功能。您可以提供單一`AttributeConverterProvider`或一組已排序的 `AttributeConverterProvider`。請注意，如果您提供自己的屬性轉換器提供者鏈，您將覆寫預設轉換器提供者，且必須將其包含在鏈中，才能使用其屬性轉換器。
```
@DynamoDbBean(converterProviders = {
ConverterProvider1.class,
ConverterProvider2.class,
DefaultAttributeConverterProvider.class})
public class Customer {
...
}
```
本指南中[屬性轉換](ddb-en-client-adv-features-conversion.md#ddb-en-client-adv-features-conversion-example)的 區段包含 V2 的完整範例。
# 適用於 Java 的 SDK 第 1 版和第 2 版之間的字串處理差異
將資料傳送至 DynamoDB 時，V1 和 V2 會以不同的方式處理空字串：
+ **V1**：將空字串轉換為 null 值，再傳送至 DynamoDB （無屬性）
+ **V2**：將空字串作為實際空字串值傳送至 DynamoDB
**重要**
遷移至 V2 之後，如果您不希望在 DynamoDB 中存放空字串，則必須實作自訂轉換器。如果沒有自訂轉換器，V2 會將空字串儲存為 DynamoDB 項目中的實際空字串屬性，這與 V1 完全省略這些屬性的行為不同。
**Example 將空字串屬性轉換為 null 的 V2 自訂轉換器**
```
/**
* Custom converter that maintains V1 behavior by converting empty strings to null values
* when writing to DynamoDB, ensuring compatibility with existing data. No attribute will be saved to DynamoDB.
*/
public class NullifyEmptyStringConverter implements AttributeConverter {
@Override
public AttributeValue transformFrom(String value) {
if (value == null || value.isEmpty()) {
return AttributeValue.builder().nul(true).build();
}
return AttributeValue.builder().s(value).build();
}
@Override
public String transformTo(AttributeValue attributeValue) {
if (attributeValue.nul()) {
return null;
}
return attributeValue.s();
}
@Override
public EnhancedType type() {
return EnhancedType.of(String.class);
}
@Override
public AttributeValueType attributeValueType() {
return AttributeValueType.S;
}
}
// V2 usage:
@DynamoDbBean
public class Customer {
private String name;
@DynamoDbConvertedBy(NullifyEmptyStringConverter.class)
public String getName() {
return name;
}
}
```
# 適用於 Java 的 SDK 第 1 版和第 2 版之間的樂觀鎖定差異
V1 和 V2 都實作樂觀鎖定搭配屬性註釋，在您的 Bean 類別上標記一個屬性來存放版本號碼。
**樂觀鎖定行為的差異**
| | V1 | V2 |
| --- | --- | --- |
| Bean 類別註釋 | @DynamoDBVersionAttribute | @DynamoDbVersionAttribute （請注意，V2 使用小寫 "b") |
| 初始儲存 | 版本編號屬性設定為 1。 | 使用 設定的版本屬性的起始值`@DynamoDbVersionAttribute(startAt = X)`。預設值為 0。 |
| 更新 | 如果條件式檢查驗證要更新的物件版本編號符合資料庫中的編號，則版本編號屬性會遞增 1。 | 如果條件式檢查驗證要更新的物件版本編號符合資料庫中的編號，則版本編號屬性會遞增。 使用 設定`incrementBy`的選項遞增的版本編號屬性`@DynamoDbVersionAttribute(incrementBy = X)`。預設值為 1。 |
| 刪除 | DynamoDBMapper 新增條件式檢查，確認要刪除之物件的版本編號符合資料庫中的版本編號。 | V2 不會自動新增刪除操作的條件。如果您想要控制刪除行為，則必須手動新增條件表達式。 在下列範例中， `recordVersion`是 Bean 的版本屬性。 // 1. Read the item and get its current version.
Customer item = customerTable.getItem(Key.builder().partitionValue("someId").build());
AttributeValue currentVersion = item.getRecordVersion();
// 2. Create conditional delete with the `currentVersion` value.
DeleteItemEnhancedRequest deleteItemRequest =
DeleteItemEnhancedRequest.builder()
.key(KEY)
.conditionExpression(Expression.builder()
.expression("recordVersion = :current_version_value")
.putExpressionValue(":current_version_value", currentVersion)
.build()).build();
customerTable.deleteItem(deleteItemRequest);
|
| 具有條件檢查的交易寫入 | 您無法在 addConditionCheck方法@DynamoDBVersionAttribute中使用以 標註的 Bean 類別。 | 您可以在transactWriteItems請求的addConditionCheck建置器方法中使用具有 @DynamoDbVersionAttribute註釋的 Bean 類別。 |
| 停用 | 透過將 DynamoDBMapperConfig.SaveBehavior列舉值從 變更為 UPDATE來停用樂觀鎖定CLOBBER。 | 請勿使用 `@DynamoDbVersionAttribute`註釋。 |
# 適用於 Java 的 SDK 第 1 版和第 2 版之間的流暢設定器差異
您可以在適用於 V1 POJOs 搭配流暢的設定器，以及搭配自 2.30.29 版以來的 V2。 DynamoDB
例如，下列 POJO 會從 `setName`方法傳回`Customer`執行個體：
```
// V1
@DynamoDBTable(tableName ="Customer")
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this;
}
}
```
不過，如果您使用 2.30.29 之前的 V2 版本， 會`setName`傳回`name`值為 的`Customer`執行個體`null`。
```
// V2 prior to version 2.30.29.
@DynamoDbBean
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this; // Bug: returns this instance with a `name` value of `null`.
}
}
```
```
// Available in V2 since version 2.30.29.
@DynamoDbBean
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this; // Returns this instance for method chaining with the `name` value set.
}
}
```