DynamoDB Toolbox 核心概念：Entity 实体详解-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00130/article/details/148918078

DynamoDB Toolbox 核心概念：Entity 实体详解

dynamodb-toolbox dynamodb-toolbox: 是一个用于 Amazon DynamoDB 的命令行工具箱，提供了许多有用的 DynamoDB 管理命令，如创建表、查询数据等。适合开发者使用 dynamodb-toolbox 管理 DynamoDB 数据库。项目地址: https://gitcode.com/gh_mirrors/dy/dynamodb-toolbox

什么是 Entity 实体

在 DynamoDB Toolbox 中，Entity（实体）代表 DynamoDB 表中一个具有明确定义模式的项。它类似于关系型数据库中的表结构定义，但更加灵活。一个实体可以表示用户(User)、订单(Order)、发票行项目(Invoice Line Item)、配置对象(Configuration Object)等各种业务对象。

实体与表的关系

实体必须与一个表(Table)相关联，这是使用 DynamoDB Toolbox 的基本要求。值得注意的是：

一个表可以包含多个实体
一个实体只能属于一个表
实体可以共享相同表上的属性（显式或巧合）

每个实体必须指定一个属性作为分区键(partitionKey)，如果表启用了排序键(sortKey)，则还需要指定一个排序键属性。

如何定义实体

定义新实体非常简单，首先导入 Entity 类：

import { Entity } from 'dynamodb-toolbox'

然后创建一个新的实体实例：

const MyEntity = new Entity({
  // 实体定义
  // 在 TypeScript 中，需要使用 "as const" 来确保类型推断正确
} as const)

实体定义详解

实体定义是一个对象，包含以下重要属性：

基本配置

name (必需)：实体名称，在关联表中必须唯一
timestamps：是否自动添加和管理创建/修改时间戳
created/modified：覆盖默认的时间戳属性名
createdAlias/modifiedAlias：覆盖默认的时间戳别名
typeAlias：覆盖默认的实体类型别名
typeHidden：是否在返回数据中隐藏实体类型
table：关联的表实例（虽然可以延迟指定，但大多数方法需要表才能执行）

执行控制

autoExecute：是否自动执行 DocumentClient 方法（默认继承自表）
autoParse：当 autoExecute 为 true 时，是否自动解析返回数据（默认继承自表）

实体属性详解

attributes 是实体定义中最关键的部分，它定义了实体的数据结构。每个属性可以有以下几种定义方式：

简单字符串定义

最简单的定义方式是使用字符串指定 DynamoDB 类型：

attributes: {
  username: 'string',
  age: 'number',
  tags: 'list',
  metadata: 'map'
}

支持的类型包括：string, boolean, number, list, map, binary, set。

对象定义

对于更复杂的场景，可以使用对象定义属性：

attributes: {
  user_id: { 
    partitionKey: true,
    type: 'string'
  },
  email: {
    type: 'string',
    required: true,
    alias: 'user_email'
  }
}

对象定义支持丰富的配置选项：

通用选项

type：DynamoDB 数据类型
coerce：是否强制类型转换（默认对 string/boolean/number 启用）
default：默认值（可以是静态值或函数）
dependsOn：默认值依赖的其他属性
onUpdate：是否在每次更新时强制传递默认值
save：是否保存到表（默认为 true）
hidden：是否在返回数据中隐藏
required：是否必需（"always" 表示在 put 和 update 时都必需）
alias/map：属性别名和映射
transform：写入前的转换函数
format：读取后的格式化函数

类型特定选项

setType：set 类型的元素类型（string/number/binary）
prefix/suffix：字符串前缀/后缀（存储时添加，读取时移除）
delimiter：复合键分隔符

键配置

partitionKey：标记为分区键（true 或索引名）
sortKey：标记为排序键（true 或索引名）

复合键的高级用法

复合键是 DynamoDB 中实现层次结构和一对多关系的强大工具。DynamoDB Toolbox 提供了多种处理复合键的方式。

基本复合键映射

attributes: {
  pk: { partitionKey: true },
  sk: { sortKey: true },
  status: ['sk', 0],  // 映射到 sk 的第 0 部分
  date: ['sk', 1]     // 映射到 sk 的第 1 部分
}

这种映射允许将多个属性组合存储在一个字段中（默认使用 # 分隔），同时保持代码中的分离访问。

复合键配置

可以为复合键部分指定类型或额外配置：

status: [
  'sk', 
  0, 
  { 
    type: 'boolean', 
    save: false,  // 不单独存储
    default: true 
  }
],
date: ['sk', 1, { required: true }]

动态默认值

默认值可以是函数，实现动态计算：

created: { 
  default: () => new Date().toISOString() 
},
full_name: {
  default: (data) => `${data.first_name} ${data.last_name}`
},
composite_key: {
  default: (data) => {
    if (data.type && data.id) {
      return `${data.type}#${data.id}`
    }
    return null
  }
}

这种灵活性支持各种高级用例，如条件默认值、复合键生成等。