DynamoDB-Toolbox 实体操作详解：GetItem 命令使用指南-CSDN博客

DynamoDB-Toolbox 实体操作详解：GetItem 命令使用指南

概述

在 DynamoDB-Toolbox 中，GetItem 命令是用于从 DynamoDB 表中检索单个项目的基本操作。本文将深入讲解如何使用该命令，包括参数配置、选项设置以及响应处理等核心内容。

基本用法

GetItem 命令的基本使用流程如下：

从实体构建 GetItem 命令
指定要检索的项目键值
可选地配置额外选项
发送命令并获取响应

import { GetItemCommand } from 'dynamodb-toolbox/entity/actions/get'

const { Item } = await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .send()

关键参数详解

键值指定 (.key())

键值是检索项目的必要条件，必须包含实体定义中的所有主键属性（分区键和排序键，如果有的话）。

// 简单键值指定
await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .send()

// 使用类型安全的键值对象
import type { KeyInputItem } from 'dynamodb-toolbox/entity'

const key: KeyInputItem<typeof PokemonEntity> = {
  pokemonId: 'pikachu1'
}

await PokemonEntity.build(GetItemCommand)
  .key(key)
  .send()

选项配置 (.options())

GetItem 命令提供了多个可配置选项来优化查询行为：

await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .options({
    consistent: true,          // 使用强一致性读取
    attributes: ['type', 'level'], // 只获取特定属性
    capacity: 'TOTAL',         // 返回容量消耗信息
    tableName: 'custom-table'  // 覆盖默认表名
  })
  .send()

主要选项说明

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | consistent | boolean | false | 设置为 true 使用强一致性读取（默认是最终一致性） | | attributes | 属性路径数组 | - | 指定要返回的属性列表，提高性能 | | capacity | "NONE"|"TOTAL"|"INDEXES" | "NONE" | 返回容量消耗信息的详细程度 | | tableName | string | - | 覆盖默认表名，常用于多租户场景 |

高级使用场景

1. 属性投影

通过指定 attributes 选项，可以只获取需要的属性，减少网络传输量：

const { Item } = await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .options({ attributes: ['type', 'level'] })
  .send()

2. 多租户支持

在多租户应用中，可以通过动态表名支持多租户：

const { Item } = await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .options({ tableName: `tenant-${tenantId}-pokemons` })
  .send()

3. 请求中止

支持使用 AbortController 中止正在进行的请求：

const abortController = new AbortController()
const abortSignal = abortController.signal

const { Item } = await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .send({ abortSignal })

// 需要时中止请求
abortController.abort()

响应处理

GetItem 命令返回的响应遵循 DynamoDB 的 GetItem API 格式，返回的项目会自动按照实体定义进行格式化。

可以使用类型工具明确指定响应类型：

import type { GetItemResponse } from 'dynamodb-toolbox/entity/actions/get'

const response: GetItemResponse<
  typeof PokemonEntity,
  { attributes: ['type', 'level'] }
> = await PokemonEntity.build(GetItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .options({ attributes: ['type', 'level'] })
  .send()