DynamoDB Toolbox 中键属性的默认值处理实践

键属性默认值的设计考量

在使用 DynamoDB Toolbox 进行开发时，键属性的默认值处理是一个需要特别注意的设计点。当我们在实体定义中为键属性设置默认值时，需要理解不同方法之间的区别及其对类型系统的影响。

核心问题分析

在实际开发中，我们经常会遇到这样的场景：希望主键的一部分由系统自动生成（如使用 ULID），而另一部分由用户提供。这种情况下，我们需要确保：

1. 创建项目时，自动生成的键属性是可选的
2. 查询、更新或删除项目时，所有键属性都是必需的

正确的默认值设置方法

DynamoDB Toolbox 提供了三种设置默认值的方法，需要根据属性是否为键属性来选择：

1. keyDefault() - 专为键属性设计，在计算键值时自动填充默认值
2. putDefault() - 用于非键属性，仅在执行 Put 操作时填充默认值
3. default() - 智能方法，根据属性是否为键自动选择上述两种方法之一

对于键属性，正确的做法是使用 keyDefault() 或 default() 方法：

export const MyEntity = new Entity({
  name: 'MYENTITY',
  table: MyTable,
  schema: schema({
    owner: string().key(),
    id: string()
      .key()
      .default(() => ulid()), // 使用default或keyDefault
    status: string().enum(...Object.values(StatusEnum)),
  })
)}

类型系统的配合使用

当正确使用 keyDefault() 后，类型系统会自动处理以下场景：

1. 创建项目：键属性变为可选，因为系统会自动填充默认值
2. 查询/删除项目：使用 KeyInputItem 类型时，类型系统知道这些操作需要完整的键

如果需要强制要求某些键属性必须提供（即使有默认值），可以使用 TypeScript 的 Required 工具类型或 DynamoDB Toolbox 提供的 ValidItem 类型：

// 方法一：使用Required工具类型
export const deleteItem = async (key: Required<KeyInputItem<typeof MyEntity>>) => {
  await MyEntity.build(DeleteItemCommand).key(key).send();
};

// 方法二：使用ValidItem类型
export const deleteItem = async (key: ValidItem<typeof MyEntity, { mode: 'key' }>) => {
  await MyEntity.build(DeleteItemCommand).key(key).send();
};

最佳实践建议

1. 对于需要自动生成的键属性，优先使用 default() 方法
2. 在业务逻辑层明确区分创建操作和查询/更新/删除操作的参数类型
3. 考虑在应用层而非数据库层生成唯一ID，这样可以更灵活地控制ID生成逻辑
4. 对于复杂的业务场景，可以在服务层封装创建逻辑，确保ID生成的正确性

通过合理利用 DynamoDB Toolbox 的类型系统和默认值机制，可以构建出既安全又灵活的数据库访问层。