# @baselinejs/dynamodb 中文文档

规范地址：https://npmcn.com/package/%40baselinejs/dynamodb/

版本：0\.2\.5
npm 元数据更新时间：2026-08-10T06:22:09.918Z
中文译文更新时间：2026-11-07T17:41:28.876Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40baselinejs/dynamodb
原文对照：https://npmcn.com/package/%40baselinejs/dynamodb/?lang=original
项目主页：https://github.com/Baseline-JS/dynamodb#readme
源码仓库：https://github.com/Baseline-JS/dynamodb

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：151 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2024-04-15T05:58:10.132Z
- 最新版本发布：2025-03-03T02:23:23.480Z
- 近 30 天下载量：4419（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

DynamoDB 库,用于简单和优化的方式使用 AWS DynamoDB

## 安装

```sh
npm install @baselinejs/dynamodb
```

也可以使用：`pnpm add @baselinejs/dynamodb`、`yarn add @baselinejs/dynamodb`、`bun add @baselinejs/dynamodb`

## README

# 基线 DynamoDB

基线 DynamoDB是一个优化的公用库,可以简化标准的DynamoDB操作. 它专注于多表设计应用,旨在提供一套适合这些应用的具体用途案例的功能.

## 特征

-   简化项目操作:使用较少锅炉板码的CRUD.
-   高级查询:方便使用排序的关键条件,包括开始 与中间,来过滤查询.
-   批量操作:自动处理批量获取的分块,分批创建,分批删除操作.
-   轻巧

## 目录

-   [安装](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-installation)
-   [快速启动](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-quick-start)
    -   [建立连接](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-establishing-a-connection)
    -   [创建项目](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-creating-an-item)
    -   [获取单个项目](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-getting-a-single-item)
    -   [更新项目](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-updating-an-item)
    -   [删除项目](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-deleting-an-item)
    -   [获取所有项目](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-retrieving-all-items)
    -   [查询项目](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-querying-items)
-   [扩展用途](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-extended-usages)
    -   [批次获取](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-batch-get)
    -   [批次创建](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-batch-create)
    -   [删除批次](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-batch-delete)
    -   [查询范围](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-query-range)
    -   [查询范围](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-query-range-between)
    -   [创建、更新、删除条件](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-create-update-delete-conditions)
    -   [限制](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-limit)
    -   [投影表达式](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-projection-expressions)
-   [工具函数](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-utility-functions)
    -   [解约](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-unmarshalling)
    -   [马歇尔](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-marshalling)
-   [处理错误](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-error-handling)
-   [环境变量](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-environment-variables)
    -   [无服务器离线](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-serverless-offline)

## 安装

```sh
npm install @baselinejs/dynamodb
```

```sh
yarn add @baselinejs/dynamodb
```

```sh
pnpm install @baselinejs/dynamodb
```

## 快速启动

### 建立连接

首先创建连接到您的 DynamoDB 表格 .

必须指定一个区域.

本地既处理当地环境,也处理部署环境。 见 [环境变量](https://npmcn.com/package/%40baselinejs/dynamodb/#readme-environment-variables) 更多信息.

```ts
const dynamo = getDynamodbConnection({
  region: 'us-east-1',
});
```

### 创建项目

在表格中添加新项目, 提供先前创建的连接 .

```ts
const user = await putItem<User>({
  dynamoDb: dynamo,
  table: 'user-table-staging',
  item: { userId: '123', email: 'example@example.com', name: 'Alice' },
});
```

### 获取单个项目

从桌子上拿个单件.

```ts
const user = await getItem<User>({
  dynamoDb: dynamo,
  table: 'user-table-staging',
  key: {
    userId: '123',
  },
});
```

### 更新项目

更新表格中的项目 .

密钥属性会自动从字段去除,以防止属性出错.

```ts
const updatedUser = await updateItem<User>({
  dynamoDb: dynamo,
  table: 'user-table-staging',
  key: {
    userId: '123',
  },
  fields: {
    name: 'Bob',
  },
});
```

### 删除项目

从表格中删除一个项目.

```ts
const deletedUser = await deleteItem({
  dynamoDb: dynamo,
  table: 'user-table-staging',
  key: {
    userId: '123',
  },
});
```

### 获取所有项目

从表格中获取所有项目.

```ts
const allUsers = await getAllItems<User>({
  dynamoDb: dynamo,
  table: 'user-table-staging',
});
```

### 查询项目

从索引查询项目.

```ts
const users = await queryItems<User>({
  dynamoDb: dynamo,
  table: 'user-table-staging',
  keyName: 'email',
  keyValue: 'example@example.com',
  indexName: 'email-index',
});
```

## 扩展用途

### 批次获取

批次从表格中获取项目 自动处理将密钥分割为100块.

返回的项目顺序不一定与输入顺序相同.

```ts
const users = await batchGetItems<User>({
  dynamoDb: dynamo,
  table: 'user-table-staging',
  keys: [{ userId: '123' }, { userId: '456' }],
});
```

### 批次创建

批次创建表格中的项目 . 自动处理将项目分成25个块.

```ts
const users = await batchPutItems<User>({
  dynamoDb: dynamo,
  table: 'user-table-staging',
  items: [
    { userId: '123', name: 'Alice' },
    { userId: '456', name: 'Bob' },
  ],
});
```

### 删除批次

批次删除表格中的项目 . 自动处理将键分割为25个块.

```ts
const isDeleted = await batchDeleteItems({
  dynamoDb: dynamo,
  table: 'user-table-staging',
  keys: [{ userId: '123' }, { userId: '456' }],
});
```

### 查询范围

从带有范围密钥的表格中查询项目.

```ts
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`

```ts
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',
  },
});
```

### 查询范围

查询表格中两个值之间带有范围密钥的项目.

```ts
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`

```ts
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结合.

```ts
try {
  const user = await putItem<User>({
    dynamoDb: dynamo,
    table: 'user-table-staging',
    item: { userId: '123', email: 'example2@example.com', 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` 函数.

该函数将在内部处理页化,直到达到极限.

```ts
const userPurchases = await queryItems<Purchase>({
  dynamoDb: dynamo,
  table: 'purchase-table-staging',
  keyName: 'userId',
  keyValue: '123',
  limit: 10,
});
```

### 投影表达式

投影表达式用于限制从查询返回到只指定字段的属性.

为了维护类型安全,可以使用第二个通用类型参数指定要返回的字段.

```ts
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记录返回,需要解析.

```ts
const user = unmarshallItem<User>(record.dynamodb?.NewImage);
```

### 马歇尔

Marshalling用于将一个JavaScript对象转换为DynatomDB记录.

```ts
const user = {
  userId: '123',
  email: 'example@example.com',
  name: 'Alice',
};
const marshalledUser = marshallItem(user);
```

## 处理错误

错误不是内部发现的,而是传播到呼叫码上.

为了有效处理这些错误,在您的应用程序中将函数包在尝试捕获块中呼叫 。 这允许自定义错误处理策略,例如日志错误或重试失败的操作.

## 环境变量

### 无服务器离线

`IS_OFFLINE`

将会是 `"true"` 在使用无服务器离线时,在操作器中. 何时 `"true"` 将使用合适的值与 DynamoDB Local 合作.

```
region: "localhost",
endpoint: "http://localhost:8000",
```

`FORCE_ONLINE`

设定为 `"true"` 以覆盖 `IS_OFFLINE` 环境变量并使用已部署的 DynamoDB 实例.

## 常见问题

### @baselinejs/dynamodb 是什么？

DynamoDB 库,用于简单和优化的方式使用 AWS DynamoDB

### 如何安装 @baselinejs/dynamodb？

在项目目录运行 npm install @baselinejs/dynamodb，或使用 pnpm add / yarn add / bun add。

### @baselinejs/dynamodb 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @baselinejs/dynamodb 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @baselinejs/dynamodb 可以商用吗？

@baselinejs/dynamodb 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @baselinejs/dynamodb 的下载量有多少？

根据 npm 官方下载统计，@baselinejs/dynamodb 在 2026/10/08 – 2026/11/06 这 30 天内被下载 4,419 次，日均约 147 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @baselinejs/dynamodb 还在维护吗？

最新版本 0\.2\.5 发布于 2025/03/03（1\.7 年前）；至今共发布 4 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/04/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。