DynamoDB Toolbox 中如何利用内置时间戳属性构建排序键

在 DynamoDB 数据建模中，时间戳属性经常被用作排序键(Partition Key)的重要组成部分。DynamoDB Toolbox 作为一款优秀的 DynamoDB 操作工具库，提供了便捷的时间戳管理功能，但开发者在使用过程中可能会遇到一些特殊需求。

内置时间戳属性简介

DynamoDB Toolbox 的 Entity 实体类默认提供了两个内置时间戳属性：

• _ct (created timestamp)：记录创建时间
• _md (modified timestamp)：记录最后修改时间

这些属性会在实体创建和更新时自动维护，为开发者省去了手动管理时间戳的麻烦。

在排序键中使用时间戳的挑战

当开发者需要在 GSI 的排序键(Sort Key)中使用创建时间时，会遇到一个典型问题：默认情况下无法直接引用这些内置属性。这是因为：

1. 内置属性是在 Entity 构造函数内部添加的
2. 这些属性不会出现在 schema 的类型定义中
3. 类型系统无法识别这些"隐藏"的属性

解决方案与实践

要解决这个问题，开发者需要显式地在 schema 中重新定义这些时间戳属性：

const UserEntity = new Entity({
  name: "USER",
  table: UsersTable,
  // 禁用自动创建时间戳
  timestamps: {
    created: false,
    modified: true
  },
  schema: schema({
    userId: string().key(),
    // 手动定义创建时间属性
    created: string()
      .default(() => new Date().toISOString())
      .savedAs("_ct"), // 映射到内置字段名
    earned: number().default(0),
  }).and((userSchema) => ({
    GSI1PK: string()
      .link<typeof userSchema>(({ userId }) => userId)
      .transform(prefix("USER"))
      .hidden(),
    GSI1SK: string()
      .putLink<typeof userSchema>(({ userId, created }) => `${created}#${userId}`)
      .transform(prefix("UD"))
      .hidden(),
  })),
  computeKey: ({ userId }) => ({
    PK: `USER#${userId}`,
    SK: `USER#${userId}`,
  }),
});

关键实现细节

1. 禁用自动时间戳：通过设置 timestamps.created = false 来避免冲突
2. 手动定义属性：在 schema 中显式定义 created 属性
3. 字段映射：使用 .savedAs("_ct") 将自定义属性映射到内置字段名
4. 类型安全：确保所有属性都在 schema 中正确定义，以获得完整的类型支持

最佳实践建议

1. 一致性：在整个项目中保持时间戳处理方式的一致性
2. 文档化：在团队内部明确记录这种特殊处理方式
3. 考虑时区：确保时间戳格式考虑到了时区需求
4. 性能考量：ISO 格式的时间戳可以直接用于排序，但也要考虑存储效率

总结

虽然 DynamoDB Toolbox 的内置时间戳属性不能直接用于排序键定义，但通过显式重新定义这些属性，开发者仍然可以实现所需的功能。这种方法既保持了类型安全，又能充分利用 DynamoDB Toolbox 的便利特性。理解这种模式后，开发者可以更灵活地设计符合业务需求的 DynamoDB 数据模型。