DynamoDB-Toolbox 中复合键的类型问题解析

问题背景

在使用 DynamoDB-Toolbox v1.14.1 版本时，开发者遇到了一个关于复合键的类型问题。具体场景是在定义 Item 实体时，尝试使用 schema 链接方法创建复合排序键(sort key)，但遇到了 TypeScript 类型错误，提示某些属性在对象上不存在。

核心问题分析

问题的核心在于 DynamoDB-Toolbox 的类型推断机制。当开发者尝试通过 link 方法创建复合键时，需要明确指定哪些属性将参与复合键的计算。在示例中，开发者希望使用 fileName 和 provider 两个属性来构建排序键，但遇到了类型错误。

解决方案

正确的做法是将参与复合键计算的所有属性都标记为 .key()。这不仅适用于分区键和排序键本身，也适用于所有将被链接到这些键的属性。这是因为：

1. .key() 标记告诉 TypeScript 这些属性是必需的
2. 它确保了类型系统能够正确推断出这些属性在对象上的存在性
3. 它保持了数据模型的完整性

最佳实践建议

1. 明确标记关键属性：所有参与键计算的属性都应使用 .key() 标记
2. 简化必需属性声明：在 v1 版本中，.required() 是默认设置，可以省略
3. 显式声明可选属性：对于非必需属性，应使用 .optional() 明确标记
4. 类型安全优先：充分利用 TypeScript 的类型系统来保证数据模型的正确性

示例修正

修正后的 schema 定义应该如下所示：

const itemSchema = schema({
  itemName: string().transform(prefix(PREFIX)).key().savedAs("id"),
  fileName: string().key(),  // 标记为 key
  status: string(),
  fileKey: string(),
  fileSize: number(),
  fileDuration: number(),
  provider: string().key(),  // 标记为 key
  hd: boolean(),
  mimeType: string(),
  userId: string(),
  archiveFile: boolean(),
  expiration: number().optional(),
  correlationId: string(),
});

总结

在使用 DynamoDB-Toolbox 时，正确处理复合键的类型问题需要开发者理解类型推断机制和属性标记的重要性。通过正确使用 .key() 标记，可以确保类型安全并避免运行时错误。这种模式不仅适用于当前案例，也是 DynamoDB 数据建模中的通用最佳实践。