基线 DynamoDB
基线 DynamoDB是一个优化的公用库,可以简化标准的DynamoDB操作. 它专注于多表设计应用,旨在提供一套适合这些应用的具体用途案例的功能.
特征
- 简化项目操作:使用较少锅炉板码的CRUD.
- 高级查询:方便使用排序的关键条件,包括开始 与中间,来过滤查询.
- 批量操作:自动处理批量获取的分块,分批创建,分批删除操作.
- 轻巧
目录
安装
npm install @baselinejs/dynamodb
yarn add @baselinejs/dynamodb
pnpm install @baselinejs/dynamodb
快速启动
建立连接
首先创建连接到您的 DynamoDB 表格 .
必须指定一个区域.
本地既处理当地环境,也处理部署环境。 见 环境变量 更多信息.
const dynamo = getDynamodbConnection({
region: 'us-east-1',
});
创建项目
在表格中添加新项目, 提供先前创建的连接 .
const user = await putItem<User>({
dynamoDb: dynamo,
table: 'user-table-staging',
item: { userId: '123', email: '[email protected]', name: 'Alice' },
});
获取单个项目
从桌子上拿个单件.
const user = await getItem<User>({
dynamoDb: dynamo,
table: 'user-table-staging',
key: {
userId: '123',
},
});
更新项目
更新表格中的项目 .
密钥属性会自动从字段去除,以防止属性出错.
const updatedUser = await updateItem<User>({
dynamoDb: dynamo,
table: 'user-table-staging',
key: {
userId: '123',
},
fields: {
name: 'Bob',
},
});
删除项目
从表格中删除一个项目.
const deletedUser = await deleteItem({
dynamoDb: dynamo,
table: 'user-table-staging',
key: {
userId: '123',
},
});
获取所有项目
从表格中获取所有项目.
const allUsers = await getAllItems<User>({
dynamoDb: dynamo,
table: 'user-table-staging',
});
查询项目
从索引查询项目.
const users = await queryItems<User>({
dynamoDb: dynamo,
table: 'user-table-staging',
keyName: 'email',
keyValue: '[email protected]',
indexName: 'email-index',
});
扩展用途
批次获取
批次从表格中获取项目 自动处理将密钥分割为100块.
返回的项目顺序不一定与输入顺序相同.
const users = await batchGetItems<User>({
dynamoDb: dynamo,
table: 'user-table-staging',
keys: [{ userId: '123' }, { userId: '456' }],
});
批次创建
批次创建表格中的项目 . 自动处理将项目分成25个块.
const users = await batchPutItems<User>({
dynamoDb: dynamo,
table: 'user-table-staging',
items: [
{ userId: '123', name: 'Alice' },
{ userId: '456', name: 'Bob' },
],
});
删除批次
批次删除表格中的项目 . 自动处理将键分割为25个块.
const isDeleted = await batchDeleteItems({
dynamoDb: dynamo,
table: 'user-table-staging',
keys: [{ userId: '123' }, { userId: '456' }],
});
查询范围
从带有范围密钥的表格中查询项目.
const userPurchases = await queryItemsRange<Purchase>({
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
rangeKeyName: 'createdAt',
rangeKeyValue: '2022',
// Fuzzy search will use a begins_with condition
fuzzy: true,
indexName: 'userId-createdAt-index',
});
使用等价查询 queryItems
const userPurchases = await queryItems<Purchase>({
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
indexName: 'userId-createdAt-index',
rangeCondition: {
operator: 'BeginsWith',
field: 'createdAt',
value: '2022',
},
});
查询范围
查询表格中两个值之间带有范围密钥的项目.
const userPurchases = await queryItemsRangeBetween<Purchase>({
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
rangeKeyName: 'createdAt',
rangeKeyValueMin: '2022-01-01T00:00:00.000Z',
rangeKeyValueMax: '2023-01-01T00:00:00.000Z',
indexName: 'userId-createdAt-index',
});
使用等价查询 queryItems
const userPurchases = await queryItems<Purchase>({
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
indexName: 'userId-createdAt-index',
rangeCondition: {
operator: 'Between',
field: 'createdAt',
value: '2022-01-01T00:00:00.000Z',
betweenSecondValue: '2023-01-01T00:00:00.000Z',
},
});
创建、更新、删除条件
A 类 conditions 数组可以提供给 putItem, (中文(简体) ), updateItem,以及 deleteItem 函数以指定操作成功必须满足的条件.
条件与AND结合.
try {
const user = await putItem<User>({
dynamoDb: dynamo,
table: 'user-table-staging',
item: { userId: '123', email: '[email protected]', name: 'Alice' },
conditions: [
{
// Only create if this userId does not already exist
operator: 'AttributeNotExists',
field: 'userId',
},
],
});
} catch (error) {
if (error.name === 'ConditionalCheckFailedException') {
// error.Item contains the item that already exists with the specified userId
}
}
限制
您可以通过指定 limit 参数.
这适用于: query 职能以及 getAllItems 函数.
该函数将在内部处理页化,直到达到极限.
const userPurchases = await queryItems<Purchase>({
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
limit: 10,
});
投影表达式
投影表达式用于限制从查询返回到只指定字段的属性.
为了维护类型安全,可以使用第二个通用类型参数指定要返回的字段.
const userPurchases = await queryItems<Purchase, 'userId' | 'createdAt'>({
dynamoDb: dynamo,
table: 'purchase-table-staging',
keyName: 'userId',
keyValue: '123',
projectionExpression: ['userId', 'createdAt'],
});
工具函数
解约
Unmarshalling 用于将 DynamotB 记录转换为 JavaScript 对象.
这在使用dynamodb流时有用,因为新的和旧的图像作为DynamoDB记录返回,需要解析.
const user = unmarshallItem<User>(record.dynamodb?.NewImage);
马歇尔
Marshalling用于将一个JavaScript对象转换为DynatomDB记录.
const user = {
userId: '123',
email: '[email protected]',
name: 'Alice',
};
const marshalledUser = marshallItem(user);
处理错误
错误不是内部发现的,而是传播到呼叫码上.
为了有效处理这些错误,在您的应用程序中将函数包在尝试捕获块中呼叫 。 这允许自定义错误处理策略,例如日志错误或重试失败的操作.
环境变量
无服务器离线
IS_OFFLINE
将会是 "true" 在使用无服务器离线时,在操作器中.
何时 "true" 将使用合适的值与 DynamoDB Local 合作.
region: "localhost",
endpoint: "http://localhost:8000",
FORCE_ONLINE
设定为 "true" 以覆盖 IS_OFFLINE 环境变量并使用已部署的 DynamoDB 实例.