DynamoDB-Toolbox 中自定义实体包装器的实现方法

在 DynamoDB-Toolbox 项目中，开发者经常需要扩展基础 Entity 类来实现自定义的数据操作方法。本文将深入探讨如何正确地为 DynamoDB-Toolbox 的 Entity 类创建类型安全的包装器。

问题背景

当使用 DynamoDB-Toolbox 时，开发者可能希望封装 Entity 类以添加自定义方法（如特定的 get、create 和 put 操作）。直接继承或包装 Entity 类时会遇到复杂的类型问题，特别是当需要处理泛型参数时。

解决方案分析

方案一：直接继承 Entity 类

最简洁的解决方案是直接继承 Entity 类并扩展其所有泛型参数。这种方法保持了类型系统的完整性，同时允许添加自定义方法：

export class EntityWrapper<
  NAME extends string = string,
  TABLE extends Table = Table,
  SCHEMA extends Schema = Schema,
  ENTITY_ATTRIBUTE_NAME extends string = string extends NAME ? string : 'entity',
  TIMESTAMPS_OPTIONS extends TimestampsOptions = string extends NAME
    ? TimestampsOptions
    : TimestampsDefaultOptions,
  ENTITY_ATTRIBUTE_HIDDEN extends boolean = string extends NAME ? boolean : true
> extends Entity<
  NAME,
  TABLE,
  SCHEMA,
  ENTITY_ATTRIBUTE_NAME,
  TIMESTAMPS_OPTIONS,
  ENTITY_ATTRIBUTE_HIDDEN
> {
  async customGet(k: KeyInput<this>): Promise<FormattedItem<this> | null> {
    const getItemCommand = this.build(GetItemCommand)
    const r = await getItemCommand.key(k).send()
    return r.Item ?? null
  }
}

这种方法的优势在于：

1. 完全保留了原始 Entity 类的所有类型信息
2. 可以无缝添加自定义方法
3. 类型推断工作正常

方案二：组合模式

另一种方法是使用组合而非继承，将 Entity 实例作为类属性：

export class EntityCompositionWrapper<E extends Entity> {
  private entity: E

  constructor(entity: E) {
    this.entity = entity
  }

  async customGet(k: KeyInput<E>): Promise<FormattedItem<E> | null> {
    const getItemCommand = this.entity.build(GetItemCommand)
    const r = await getItemCommand.key(k).send()
    return r.Item ?? null
  }
}

组合模式的特点：

1. 更松散的耦合
2. 可以包装任何 Entity 实例
3. 类型系统支持良好

类型系统注意事项

在实现自定义包装器时，需要注意以下类型细节：

1. 时间戳选项类型：TimestampsOptions 和 TimestampsDefaultOptions 是关键的泛型参数，需要正确处理
2. 实体属性名：ENTITY_ATTRIBUTE_NAME 泛型参数控制着实体类型属性的命名
3. 键计算：如果 Schema 需要自定义键计算，必须提供 computeKey 函数

最佳实践建议

1. 优先考虑继承方案，除非有特殊需求需要使用组合
2. 为自定义方法添加清晰的类型注释
3. 考虑将常用操作（如条件更新、批量操作等）封装到包装器中
4. 保持与原始 Entity 类方法签名的一致性

通过合理设计包装器类，可以显著提升 DynamoDB-Toolbox 的使用体验，同时保持类型安全和代码可维护性。