DynamoDB-Toolbox 中处理时间戳属性的最佳实践

在使用 DynamoDB-Toolbox 进行开发时，时间戳属性的处理是一个常见但容易出错的问题。本文将深入探讨如何正确配置和管理时间戳属性，避免常见的运行时错误。

时间戳属性的默认行为

DynamoDB-Toolbox 默认会自动为每个实体添加两个内部时间戳属性：

• created - 记录项目创建时间
• modified - 记录项目最后修改时间

这些属性默认会映射到 DynamoDB 中的 _ct 和 _md 字段。这种设计虽然方便，但可能与开发者自定义的时间戳属性产生冲突。

常见错误场景

当开发者同时使用自定义时间戳属性和默认时间戳属性时，可能会遇到"Missing required attribute for formatting: '_ct'"这样的运行时错误。这通常发生在以下情况：

1. 在实体模式中定义了自定义的时间戳字段（如 createdAt）
2. 同时保留了默认的时间戳功能
3. 在查询时没有正确处理这些属性

解决方案

方案一：禁用默认时间戳

如果希望完全控制时间戳属性，可以在实体配置中禁用默认时间戳：

const BaseEntity = new Entity({
  name: 'Agent',
  table: UsersTable,
  schema: schema({
    id: string().key(),
    // 其他字段...
    lastUpdated: number().default(() => getTime()),
    createdAt: number().putDefault(() => getTime()).updateDefault(() => getTime())
  }),
  timestamps: false // 禁用默认时间戳
})

注意点：

• 使用函数而非直接值作为默认值（() => getTime() 而非 getTime()）
• 对于创建时间字段，同时使用 putDefault 和 updateDefault 确保正确行为

方案二：重命名默认时间戳

如果希望保留默认时间戳功能但使用自定义字段名：

const BaseEntity = new Entity({
  name: 'Agent',
  table: UsersTable,
  schema: schema({
    id: string().key(),
    // 其他字段...（不需要定义lastUpdated和createdAt）
  }),
  timestamps: {
    created: { name: 'createdAt' }, // 将created映射到createdAt
    modified: { name: 'lastUpdated' } // 将modified映射到lastUpdated
  }
})

这种方法既保留了自动管理时间戳的便利性，又保持了字段命名的统一性。

最佳实践建议

1. 一致性：在整个项目中保持时间戳字段命名的一致性
2. 明确性：明确选择是使用自定义时间戳还是默认时间戳，避免混用
3. 测试验证：在修改时间戳配置后，务必测试创建和更新操作
4. 文档记录：在项目文档中记录时间戳策略，方便团队协作

通过合理配置 DynamoDB-Toolbox 的时间戳功能，可以避免运行时错误，同时保持代码的整洁和可维护性。