WatermelonDB 中自动创建/更新时间戳失效问题解析

问题背景

在使用 WatermelonDB 进行 React Native 应用开发时，开发者经常会遇到需要记录数据创建和更新时间的需求。WatermelonDB 提供了自动创建/更新跟踪功能，但有时这个功能可能无法按预期工作。

典型症状

当自动时间戳跟踪功能失效时，通常会观察到以下现象：

• 数据库中的 created_at 和 updated_at 字段显示为 0
• 在 React Native 调试器中看到 created_at: {} 这样的空对象
• 时间戳字段没有被自动填充

根本原因分析

通过分析开发者提供的代码，我们发现导致时间戳失效的主要原因是模型类中字段命名不符合 WatermelonDB 的命名规范。具体来说：

1. 字段命名规范问题：WatermelonDB 要求模型类中的属性使用驼峰命名法(camelCase)，而数据库表中的列名可以使用下划线命名法(snake_case)

2. 装饰器使用不当：虽然 @date 装饰器正确指定了数据库列名，但模型属性名却使用了与列名相同的下划线命名方式

解决方案

正确的实现方式应该是：

export default class Damper extends Model {
  static table = 'dampers';

  @readonly @date('created_at') createdAt;
  @readonly @date('updated_at') updatedAt;

  // 其他字段...
}

关键点：

• 数据库表列名保持为 created_at 和 updated_at
• 模型类属性名改为驼峰式 createdAt 和 updatedAt
• 仍然使用 @date 装饰器将模型属性映射到正确的数据库列

最佳实践建议

1. 命名一致性：在整个项目中保持命名规范的一致性

   • 数据库列名：使用 snake_case
   • 模型属性名：使用 camelCase

2. 类型定义：确保在数据库模式(schema)中正确定义时间戳字段类型为 'number'

3. 避免手动设置：不要尝试在创建记录时手动设置这些字段，WatermelonDB 会自动处理

4. 调试技巧：当时间戳不工作时，检查：

   • 模型类属性命名
   • 数据库模式版本是否已更新
   • 是否有冲突的迁移脚本

深入理解 WatermelonDB 时间戳机制

WatermelonDB 的时间戳自动跟踪功能是通过模型基类实现的。当记录被创建或更新时，系统会自动：

1. 在创建时设置 created_at 为当前时间戳(毫秒数)
2. 在每次更新时更新 updated_at 为当前时间戳
3. 这些操作发生在数据库层面，开发者无需干预

理解这一机制有助于在遇到问题时更快定位原因。记住，这些字段应该始终标记为 @readonly，因为手动修改它们会破坏时间戳的准确性。

总结

WatermelonDB 的自动时间戳功能是一个强大但需要正确配置的特性。通过遵循正确的命名规范和使用方式，开发者可以轻松实现数据的创建和更新时间跟踪。本文描述的问题和解决方案不仅适用于时间戳字段，也适用于其他需要特殊处理的模型属性。