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

# KCL 的单表格式
<a name="kcl-single-table-format"></a>

**从 KCL 3.5 开始，您可以使用单表格式将所有 DynamoDB 元数据整合到单个租赁表中。**默认情况下，KCL 3.x 会为每个应用程序创建三个 DynamoDB 表：租赁表、工作器指标表和协调器状态表。单表格式将这三个表缩减为一个，这有助于您避免 DynamoDB 账户级别的表格限制。

## 单表格式的工作原理
<a name="kcl-single-table-how-it-works"></a>

在单表格式中，KCL 将工作人员指标和协调器状态条目与租赁条目一起存储在租赁表中。每个项目都包含一个`entityType`用于区分不同记录类型的属性。

工作器指标和协调器状态项使用与租赁表相同的主键结构，但包含不同的`entityType`值。此属性允许 KCL 在表格扫描期间识别每个项目的用途。

KCL 的每个组件都会根据`entityType`属性筛选出其业务逻辑所需的条目。例如，租赁分配管理器 (LAM) 筛选租赁和工作人员指标条目以执行租赁分配。

## 配置单表格式
<a name="kcl-single-table-config"></a>

如何启用单表格式取决于您当前的 KCL 版本：
+ **如果您使用的是 KCL 2.x：**请按照更新的迁移指南升级到 KCL 3.5。默认情况下，从 2.x 到 3.5 的新迁移使用单表格式。
+ **如果您使用的是 KCL 3.0—3.4：**必须执行两阶段部署才能迁移到单表格式。请参阅以下配置和迁移步骤。

对于现有的 KCL 3.x 客户，请在中设置`migrateAllEntitiesToLeaseTable`配置选项。`CoordinatorConfig`此选项控制 KCL 是否在租赁表中存储所有元数据实体类型。


**`迁移`的配置值 AllEntitiesToLeaseTable**  

| 值 | 默认 | 效果 | 
| --- | --- | --- | 
| false | 是 | KCL 对工作器指标和协调器状态使用单独的表。应用程序代码支持单表格式，但不能将其激活。 | 
| true | 否 | KCL 开始将工作人员指标和协调器状态数据写入租赁表。`TableMigrationStatus`到达后在第 2 阶段部署上设置此值`DEPLOYED`，您就不会出现任何回归了。 | 

从 KCL 3.x 迁移到单表格式需要分两个阶段进行部署：

1. **第 1 阶段：**部署更新后的 KCL 3.5 代码，`migrateAllEntitiesToLeaseTable`设置为`false`（默认）。这将安装支持单表格式但不会激活迁移的新代码。

1. **第 2 阶段：**在所有工作人员都运行新代码并`TableMigrationStatus`到达之后`DEPLOYED`，并且您已验证没有回归，请重新部署并`migrateAllEntitiesToLeaseTable`设置`true`为开始迁移。

## 迁移状态
<a name="kcl-single-table-states"></a>

`TableMigrationStateMachine`管理从多表格式到单表格式的过渡。KCL 在协调器状态表中调用的单独协调器状态条目`TableMigration3.5`中跟踪当前的迁移状态。有关状态、过渡和描述的完整列表，请参阅 [KCL 单表迁移状态](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java)。


**单表格式迁移状态**  

| 州 | 说明 | 过渡条件 | 
| --- | --- | --- | 
| INIT | 初始状态。所有工作人员都在工作人员指标统计数据中发出最低支持代码。工作人员继续将工作人员指标发送到旧表中，并从旧表和租赁表中读取工作人员指标和协调器状态。从功能上讲，INIT 和 DEPLOYED 之间没有区别。 | 在烘焙时间内，所有工作人员都会稳定地发出最低支持代码。应用程序已准备好进入第 2 阶段部署。 | 
| DEPLOYED | 所有工作人员都已使用新代码进行部署（第 1 阶段已完成）。该应用程序支持单表格式，但尚未将其激活。 | 第 2 阶段的部署从`migrateAllEntitiesToLeaseTable`设置为`true`。 | 
| PENDING | 所有工作人员都运行新代码。KCL 将工作器指标和协调器状态表中的数据迁移到租赁表中。 | 迁移完成后，默认烘焙时间为 24 小时。 | 
| COMPLETE | 迁移已完成。KCL 仅使用租用表进行所有读取和写入。不再使用旧的工作器指标和协调器状态表。 | 终端状态。不会发生进一步的过渡。 | 

有关每种状态、过渡条件和完整状态机行为的详细信息，请参阅 [KCL 单表迁移状态机](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/src/main/java/software/amazon/kinesis/coordinator/migration/TableMigrationStatus.java)。

**注意**  
“待处理” 和 “完成” 状态之间的默认烘焙时间为 24 小时，但您最多可以将其配置为一周。在此期间，KCL 使用租用表进行所有读取和写入，但不会删除旧表。确认迁移成功后，必须手动删除旧的工作器指标和协调器状态表。KCL 不会自动删除这些表。

## 回滚注意事项
<a name="kcl-single-table-rollback"></a>

回滚支持取决于当前：`TableMigrationStatus`
+ **在第 1 阶段**（`TableMigrationStatus`已设置`DEPLOYED`或尚未设置）：您可以安全地回滚到以前的版本。新代码在向后兼容模式下运行，并且未向租用表中的非租赁条目写入任何数据。
+ **在第 2 阶段**（`TableMigrationStatus`是`DEPLOYED`或`PENDING`）：您可以回滚到第 1 阶段。工作人员恢复使用旧表（多表格式）来表示工作人员指标和协调器状态。迁移已撤消。
+ **完成状态后**：不支持回滚。KCL 仅对所有实体使用租赁表。即使代码回滚到第 1 阶段，工作程序仍会继续使用所有实体的租赁表，并且配置将被忽略。

**警告**  
迁移到达 COMPLETE 状态后，应用程序仅在单表模式下运行。`migrateAllEntitiesToLeaseTable`配置将被忽略，KCL 不会恢复为使用单独的表。确保在移至 COMPLETE 之前的烘焙时间足够长，因为在那之后，即使是代码回滚也不会切换回多个表。

## 最佳实践
<a name="kcl-single-table-best-practices"></a>

采用单表格式时，请遵循以下最佳实践：
+ 第 1 阶段部署后，验证协调器状态条目是否`TableMigration3.5`达到`DEPLOYED`状态。在进入第 2 阶段之前，请确保没有回归。
+ 监视处于`TableMigration3.5`协调器状态的条目，跟踪已部署、待处理和完成状态的进度。`TableMigrationStatus`在迁移到达 COMPLETE 之前，状态作为单独的条目存储在协调器状态表中（不存储在租用表中）。
+ 确保在移至 COMPLETE 之前的烘焙时间足够长，因为在那之后，即使是代码回滚也不会切换回多个表。该应用程序仅在单表模式下运行。
+ 迁移完成后，手动删除旧的工作器指标和协调器状态表。KCL 不会自动删除这些表，而只是停止使用它们。
+ 如果您已配置`CoordinatorConfig.coordinatorStateTableConfig`或`LeaseManagementConfig.workerUtilizationAwareAssignmentConfig.workerMetricsTableConfig`，则可以在迁移完成后删除这些配置。在 KCL 3.5 及更高版本中，这些配置已被弃用。