[适用于 JavaScript 的 Amazon SDK V3 API 参考指南](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/)详细描述了 适用于 JavaScript 的 Amazon SDK 版本 3 (V3) 的所有 API 操作。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 从 2.x 版迁移到 3.x 版 适用于 JavaScript 的 Amazon SDK
适用于 JavaScript 的 Amazon SDK 版本 3 是对版本 2 的重大改写。本节描述了两个版本之间的区别，并说明了如何从适用的 SDK 的版本 2 迁移到版本 3 JavaScript。
## 使用 codemod 将你的代码迁移到适用于 JavaScript v3 的 SDK
适用于 JavaScript 的 Amazon SDK 版本 3 (v3) 带有用于客户端配置和实用程序的现代化界面，包括凭证、Amazon S3 分段上传、DynamoDB 文档客户端、服务员等。您可以在 repo 的[迁移指南](https://github.com/aws/aws-sdk-js-v3/blob/main/UPGRADING.md)中找到 v2 中更改的内容以及每项更改的 v3 等效内容。 适用于 JavaScript 的 Amazon SDK GitHub
要充分利用 适用于 JavaScript 的 Amazon SDK v3，我们建议使用下面描述的 codemod 脚本。
### 使用 codemod 迁移现有的 v2 代码
中的 codemod 脚本集[aws-sdk-js-codemod](https://www.npmjs.com/package/aws-sdk-js-codemod)有助于将现有的 适用于 JavaScript 的 Amazon SDK (v2) 应用程序迁移到使用 v3。 APIs您可以按以下方式运行转换。
```
$ npx aws-sdk-js-codemod -t v2-to-v3 PATH...
```
例如，假设您有以下代码，它用于从 v2 创建一个 Amazon DynamoDB 客户端并调用 `listTables` 运算。
```
// example.ts
import AWS from "aws-sdk";
const region = "us-west-2";
const client = new AWS.DynamoDB({ region });
await client.listTables({}).promise()
.then(console.log)
.catch(console.error);
```
你可以按如下方式对 `example.ts` 运行我们的 `v2-to-v3` 转换。
```
$ npx aws-sdk-js-codemod -t v2-to-v3 example.ts
```
转换会将 DynamoDB 导入转换为 v3，创建 v3 客户端，然后调用 `listTables` 运算，如下所示。
```
// example.ts
import { DynamoDB } from "@aws-sdk/client-dynamodb";
const region = "us-west-2";
const client = new DynamoDB({ region });
await client.listTables({})
.then(console.log)
.catch(console.error);
```
我们已经针对常见使用案例实现了转换。如果您的代码无法正确转换，请使用示例输入代码和 observed/expected 输出代码创建[错误报告](https://github.com/awslabs/aws-sdk-js-codemod/issues/new?assignees=&labels=bug%2Ctriage&template=bug_report.yml&title=%5BBug%3F%5D%3A+)或[功能请求](https://github.com/awslabs/aws-sdk-js-codemod/issues/new?assignees=&labels=enhancement&template=feature_request.yml&title=%5BFeature%5D%3A+)。如果[某个现有问题](https://github.com/awslabs/aws-sdk-js-codemod/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)已经报告了您的特定使用案例，请通过投赞同票表示支持。
## 版本 3 中的新增功能
适用于 JavaScript (v3) 的 SDK 版本 3 包含以下新功能。
模块化软件包
用户现在可以为每项服务使用单独的软件包。
新的中间件堆栈
用户现在可以使用中间件堆栈来控制操作调用的生命周期。
此外，还编写了 SDK TypeScript，它具有许多优点，例如静态输入。
**重要**
本指南中 v3 的代码示例是用 ECMAScript 6 (ES6) 编写的。 ES6带来了新的语法和新功能，使您的代码更现代、更具可读性，并能做更多的事情。 ES6 要求你使用 Node.js 版本 13.x 或更高版本。要下载并安装最新版本的 Node.js，请参阅 [Node.js 下载](https://nodejs.org/en/download/)。有关更多信息，请参阅 [JavaScript ES6/CommonJS 语法](sdk-example-javascript-syntax.md)。
## 模块化软件包
适用于 JavaScript (v2) 的 SDK 版本 2 要求您使用整个 Amazon SDK，如下所示。
```
var AWS = require("aws-sdk");
```
如果您的应用程序使用许多 Amazon 服务，则加载整个 SDK 不是问题。但是，如果您只需要使用少量 Amazon 服务，则意味着使用不需要或不使用的代码来增加应用程序的大小。
在 v3 中，您只能加载和使用所需的各项 Amazon 服务。以下示例显示了这一点，通过它您可以访问 Amazon DynamoDB (DynamoDB)。
```
import { DynamoDB } from "@aws-sdk/client-dynamodb";
```
您不仅可以加载和使用单个 Amazon 服务，还可以仅加载和使用所需的服务命令。以下示例显示了这一点，通过它您可以访问 DynamoDB 客户端和 `ListTablesCommand` 命令。
```
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
```
**重要**
不应将子模块导入模块中。例如，以下代码可能会导致错误：
```
import { CognitoIdentity } from "@aws-sdk/client-cognito-identity/CognitoIdentity";
```
以下是正确的代码。
```
import { CognitoIdentity } from "@aws-sdk/client-cognito-identity";
```
### 比较代码大小
在版本 2（v2）中，列出您在 `us-west-2` 区域的所有 Amazon DynamoDB 表的简单代码示例可能如下所示。
```
var AWS = require("aws-sdk");
// Set the Region
AWS.config.update({ region: "us-west-2" });
// Create DynamoDB service object
var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
// Call DynamoDB to retrieve the list of tables
ddb.listTables({ Limit: 10 }, function (err, data) {
if (err) {
console.log("Error", err.code);
} else {
console.log("Tables names are ", data.TableNames);
}
});
```
V3 如下所示。
```
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({ region: "us-west-2" });
try {
const results = await dbclient.send(new ListTablesCommand);
for (const item of results.TableNames) {
console.log(item);
}
} catch (err) {
console.error(err)
}
```
`aws-sdk` 软件包会为您的应用程序增加大约 40 MB。将 `var AWS = require("aws-sdk")` 替换为 `import {DynamoDB} from "@aws-sdk/client-dynamodb"` 可将开销减少到大约 3 MB。将导入限制为仅 DynamoDB 客户端和 `ListTablesCommand` 命令，可将开销减少到 100 KB 以下。
```
// Load the DynamoDB client and ListTablesCommand command for Node.js
import {
DynamoDBClient,
ListTablesCommand
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({});
```
### 在 v3 中调用命令
您可以使用 v2 或 v3 命令在 v3 中执行操作。要使用 v3 命令，请导入命令和所需的 Serv Amazon ices 包客户端，然后使用使用 async/await 模式的`.send`方法运行命令。
要使用 v2 命令，请导入所需的 Amazon 服务包，然后使用回调或 async/await 模式直接在包中运行 v2 命令。
#### 使用 v3 命令
v3 为每个 Amazon 服务包提供了一组命令，使您能够对该 Amazon 服务执行操作。安装 Amazon 服务后，您可以浏览项目中 `node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder.` 的可用命令
您必须导入要使用的命令。例如，以下代码可加载 DynamoDB 服务和 `CreateTableCommand` 命令。
```
import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
```
要按照推荐的 async/await 模式调用这些命令，请使用以下语法。
```
CLIENT.send(new XXXCommand);
```
例如，以下示例使用推荐的模式创建了一个 DynamoDB 表。 async/await
```
import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const dynamodb = new DynamoDB({ region: "us-west-2" });
const tableParams = {
TableName: TABLE_NAME
};
try {
const data = await dynamodb.send(new CreateTableCommand(tableParams));
console.log("Success", data);
} catch (err) {
console.log("Error", err);
};
```
#### 使用 v2 命令
要在 SDK 中使用 v2 命令 JavaScript，请导入完整的 Amazon 服务包，如以下代码所示。
```
const { DynamoDB } = require('@aws-sdk/client-dynamodb');
```
要按照推荐的 async/await 模式调用 v2 命令，请使用以下语法。
```
client.command(parameters);
```
以下示例使用 v2 `createTable` 命令使用推荐的模式创建 DynamoDB 表。 async/await
```
const { DynamoDB } = require('@aws-sdk/client-dynamodb');
const dynamoDB = new DynamoDB({ region: 'us-west-2' });
var tableParams = {
TableName: TABLE_NAME
};
async function run() => {
try {
const data = await dynamoDB.createTable(tableParams);
console.log("Success", data);
}
catch (err) {
console.log("Error", err);
}
};
run();
```
以下示例使用 v2 `createBucket` 命令，通过回调模式创建 Amazon S3 存储桶。
```
const { S3 } = require('@aws-sdk/client-s3');
const s3 = new S3({ region: 'us-west-2' });
var bucketParams = {
Bucket : BUCKET_NAME
};
function run() {
s3.createBucket(bucketParams, function (err, data) {
if (err) {
console.log("Error", err);
} else {
console.log("Success", data.Location);
}
})
};
run();
```
## 新的中间件堆栈
借助 SDK v2，您可以通过为请求附加事件侦听器，在请求生命周期的多个阶段修改请求。这种方法可能使调试请求生命周期中的错误变得困难。
在 v3 中，您可以使用新的中间件堆栈来控制操作调用的生命周期。这种方法有几个好处。堆栈中的每个中间件阶段都会在对请求对象进行任何更改后调用下一个中间件阶段。这也使调试堆栈中的问题变得更加容易，因为您可以准确地看到哪些被调用的中间件阶段导致了错误。
以下示例使用中间件向 Amazon DynamoDB 客户端（我们之前创建并演示了该客户端）添加自定义标头。第一个参数是一个接受 `next` 的函数，该函数指要调用的堆栈中的下一个中间件阶段，还有 `context`，这是一个包含有关正在调用的操作的一些信息的对象。该函数返回一个接受 `args` 的函数，这是一个包含传递给操作和请求的参数的对象。它使用 `args` 调用下一个中间件，然后返回结果。
```
dbclient.middlewareStack.add(
(next, context) => args => {
args.request.headers["Custom-Header"] = "value";
return next(args);
},
{
name: "my-middleware",
override: true,
step: "build"
}
);
dbclient.send(new PutObjectCommand(params));
```