# @aws/dynamodb-data-marshaller 中文文档

规范地址：https://npmcn.com/package/%40aws/dynamodb-data-marshaller/

版本：0\.7\.3
npm 元数据更新时间：2026-10-15T22:06:40.843Z
中文译文更新时间：2026-11-07T11:34:49.359Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws/dynamodb-data-marshaller
原文对照：https://npmcn.com/package/%40aws/dynamodb-data-marshaller/?lang=original
项目主页：https://awslabs.github.io/dynamodb-data-mapper-js/packages/dynamodb-data-marshaller/
源码仓库：https://github.com/awslabs/dynamodb-data-mapper-js

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

- 包体积（解压后）：105 kB，42 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：aws-sdk ^2\.7\.0
- 首次发布：2017-11-20T23:43:47.406Z
- 最新版本发布：2018-08-15T19:53:48.927Z
- 近 30 天下载量：129347（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 0 个）

## 中文简介

Amazon DynamoDB的基于计划的数据 Marxler

## 安装

```sh
npm install @aws/dynamodb-data-marshaller
```

也可以使用：`pnpm add @aws/dynamodb-data-marshaller`、`yarn add @aws/dynamodb-data-marshaller`、`bun add @aws/dynamodb-data-marshaller`

## README

# 亚马逊迪纳摩DB 数据马歇尔

[![Apache 2 License](https://img.shields.io/github/license/awslabs/dynamodb-data-mapper-js.svg?style=flat)](http://aws.amazon.com/apache-2-0/)

这个图书馆提供 `marshallItem` 财务报告和审定财务报表 `unmarshallItem` 函数 将本地 JavaScript 值转换为 DynamoDB 属性变量并再次返回, (b) 分别根据一个定义的计划。 许多 JavaScript 值映射 干净到DynamoDB 数据类型,反之亦然,计划允许你无所不失 坚持任何 JavaScript 类型,包括日期、类例和空 字符串.

## 开始

要使用数据Marxler,首先定义一个描述 应用程序域对象与其序列化形式之间的关系 在迪纳摩DB表格中:

```javascript
const schema = {
    foo: {type: 'Binary'},
    bar: {type: 'Boolean'},
    baz: {type: 'String'},
    quux: {
        type: 'Document',
        members: {
            fizz: {type: 'Set', memberType: 'String'},
            buzz: {
                type: 'Tuple',
                members: [
                    {
                        type: 'List',
                        memberType: {type: 'Set', memberType: 'Number'},
                    },
                    {
                        type: 'Map',
                        memberType: {type: 'Date'},
                    }
                ]
            },
        },
    },
};
```

此方案可能用于将 JavaScript 值写入 DynamoDB 属性 值 :

```javascript
import {marshallItem} from '@aws/dynamodb-data-marshaller';

const marshalled = marshallItem(schema, {
    foo: Uint8Array.from([0xde, 0xad, 0xbe, 0xef]),
    bar: false,
    baz: '',
    quux: {
        fizz: new Set(['a', 'b', 'c']),
        buzz: [
            [
                new Set([1, 2, 3]),
                new Set([2, 3, 4]),
                new Set([3, 4, 5]),
            ],
            new Map([
                ['now', new Date()],
                ['then', new Date(0)],
            ]),
        ]
    }
});
```

Schema 也可以用于解除 DynamoDB 属性值返回到 它们最初的 JavaScript 表示:

```javascript
import {unmarshallItem} from '@aws/dynamodb-data-marshaller';

const unmarshalled = unmarshallItem(schema, {
    foo: {B: Uint8Array.from([0xde, 0xad, 0xbe, 0xef])},
    bar: {BOOL: false},
    baz: {NULL: true},
    quux: {
        fizz: {SS: ['a', 'b', 'c']},
        buzz: {
            L: [
                L: [
                    {NS: ['1', '2', '3']},
                    {NS: ['2', '3', '4']},
                    {NS: ['3', '4', '5']},
                ],
                M: {
                    now: {N: '1507189047'},
                    then: {N: '0'}
                },
            ],
        },
    },
});
```

## 指定密钥

DynamoDB表格必须定义散列键并可能可选择定义范围键. 单位 DynamoDB文档,这些密钥有时被称为 _分区_ 财务报告和审定财务报表 _排序_ 键。 宣布财产为密钥时,添加 `keyType` 财产的图案(例如: [DynamoDB 开发者 指南](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html):

```javascript
// Table model taken from http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html
const gameScores = {
    UserId: {
        type: 'String',
        keyType: 'HASH'
    },
    GameTitle: {
        type: 'String',
        keyType: 'RANGE'
    },
    TopScore: {type: 'Number'},
    TopScoreDateTime: {type: 'Date'},
    Wins: {type: 'Number'},
    Losses: {type: 'Number'}
};
```

这个 `keyType` 属性只能用于序列化为 字符串、数字或二进制属性。 临Τ `'String'`, (中文(简体) ), `'Number'`, (中文(简体) ), 财务报告和审定财务报表 `'Binary'` 属性,可用于 `'Date'` 财务报告和审定财务报表 `'Custom'` 属性.

索引密钥使用对象映射索引名称指定为 该值用于给定索引。 继续 `gameScores` 的索引关键声明 [页:1 DynamoDB 全球中学 索引开发者指南](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html) 内容如下:

```javascript
const gameScores = {
    UserId: {
        type: 'String',
        keyType: 'HASH'
    },
    GameTitle: {
        type: 'String',
        keyType: 'RANGE',
        indexKeyConfigurations: {
            GameTitleIndex: 'HASH'
        }
    },
    TopScore: {
        type: 'Number',
        indexKeyConfigurations: {
            GameTitleIndex: 'RANGE'
        }
    },
    TopScoreDateTime: {type: 'Date'},
    Wins: {type: 'Number'},
    Losses: {type: 'Number'}
};
```

## 提供默认值

任何财产计划都可以定义 `defaultProvider` 函数在 字段为 `undefined` 输入 `marshallItem`。该函数必须 返回一个原始 JavaScript 值, 并且不应返回一个已标记的 DynamoDB 属性Value形状.

```javascript
const uuidV4 = require('uuid/v4');

const schema = {
    key: {
        type: 'String',
        defaultProvider: uuidV4,
        keyType: 'HASH',
    },
    // ...
};
```

## 支持类型

### 任意

将使用 `@aws/dynamodb-auto-marshaller` 包,在运行时检测给定值的类型.

#### 示例

```javascript
const anyProperty = {
    type: 'Any',
    // optionally, you may specify configuration options for the
    // @aws/dynamodb-auto-marshaller package's Marshaller class:
    unwrapNumbers: false,
    onInvalid: 'omit',
    onEmpty: 'nullify',
};
```

### 二进制

用于 `ArrayBuffer` 财务报告和审定财务报表 `ArrayBufferView` 对象,以及节点。 联合来文 缓冲.

**可用作表格或索引键.**

#### 示例

```javascript
const binaryProperty = {type: 'Binary'};
```

### 布尔

用于 `true`编号 :`false` 数值.

#### 示例

```javascript
const booleanProperty = {type: 'Boolean'};
```

### 收藏

说明未类型项目列表。 将汇总组成项目 使用 `@aws/dynamodb-auto-marshaller`。 。 。 .

#### 示例

```javascript
const collectionProperty = {
    type: 'Collection',
    // optionally, you may specify configuration options for the
    // @aws/dynamodb-auto-marshaller package's Marshaller class:
    unwrapNumbers: false,
    onInvalid: 'omit',
    onEmpty: 'nullify',
};
```

### 自定义

允许使用讲解的集合功能和解析功能。 类型 定义 `'Custom'` 属性必须包括: `marshall` 函数 将类型中的 JavaScript 表达式转换为 DynamoDB 属性Value 和 a 一个 `unmarshall` 将属性Value 转换回 JavaScript 的函数 数值.

**可用作表格或索引键.**

#### 示例

```javascript
// This custom property handles strings
const customProperty = {
    type: 'Custom',
    marshall(input) {
        return {S: input};
    },
    unmarshall(persistedValue) {
        return persistedValue.S;
    }
};
```

### 日期

用于时间数据. 日期将作为时间戳被序列化到 DynamoDB 与DynamoDB的时空功能进行简单整合 因此,时区 信息不会持续存在.

**可用作表格或索引键.**

#### 示例

```javascript
const dateProperty = {type: 'Date'};
```

### 文档

用于具有自身图案和(可选的)构造器的对象值.

#### 示例

```javascript
class MyCustomDocument {
    method() {
        // pass
    }
    
    get computedProperty() {
        // pass
    }
}

class documentSchema = {
    fizz: {type: 'String'},
    buzz: {type: 'Number'},
    pop: {type: 'Date'}
}

const documentProperty = {
    type: 'Document',
    members: documentSchema,
    // optionally, you may specify a constructor to use to create the object
    // that will underlie unmarshalled instances. If not specified,
    // Object.create(null) will be used.
    valueConstructor: MyCustomDocument
};
```

### 散开

用于有字符串密钥和无类型值的对象.

#### 示例

```javascript
const collectionProperty = {
    type: 'Hash',
    // optionally, you may specify configuration options for the
    // @aws/dynamodb-auto-marshaller package's Marshaller class:
    unwrapNumbers: false,
    onInvalid: 'omit',
    onEmpty: 'nullify',
};
```

### 列表

用于数组或可移动对象,其元素均为同类型.

#### 示例

```javascript
const listOfStrings = {
    type: 'List',
    memberType: {type: 'String'}
};
```

### 地图

用于 `Map` 对象,其值都是同类型.

#### 示例

```javascript
const mapOfStrings = {
    type: 'Map',
    memberType: {type: 'String'}
};
```

### 无

用于序列化 `null`。常用作西格值.

#### 示例

```javascript
const nullProperty = {type: 'Null'};
```

### 数目

用来序列数字.

**可用作表格或索引键.**

#### 示例

```javascript
const numberProperty = {type: 'Number'};
```

### 设定

用来序列化其值都是同一类的集. DynamoDB 允许 组合数字、组合字符串和组合二进制值.

#### 示例

```javascript
const binarySetProperty = {type: 'Set', memberType: 'Binary'};
const numberSetProperty = {type: 'Set', memberType: 'Number'};
const stringSetProperty = {type: 'Set', memberType: 'String'};
```

### 字符串

用于串行.

**可用作表格或索引键.**

#### 示例

```javascript
const stringProperty = {type: 'String'};
```

### 调皮

用于存储具有特定长度和元素序列的数组.

#### 示例

```javascript
const tupleProperty = {
    type: 'Tuple',
    members: [
        {type: 'Boolean'},
        {type: 'String'}
    ]
};
```

## 常见问题

### @aws/dynamodb-data-marshaller 是什么？

Amazon DynamoDB的基于计划的数据 Marxler

### 如何安装 @aws/dynamodb-data-marshaller？

在项目目录运行 npm install @aws/dynamodb-data-marshaller，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：aws-sdk（^2\.7\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws/dynamodb-data-marshaller 支持 TypeScript 吗？

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

### @aws/dynamodb-data-marshaller 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws/dynamodb-data-marshaller 可以商用吗？

@aws/dynamodb-data-marshaller 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws/dynamodb-data-marshaller 的下载量有多少？

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

### @aws/dynamodb-data-marshaller 还在维护吗？

最新版本 0\.7\.3 发布于 2018/08/16（8 年前）；至今共发布 13 个版本，其中过去 12 个月发布了 0 个；首次发布于 2017/11/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。