从 2.x 版迁移到 3.x 版 Amazon SDK for JavaScript

Amazon SDK for JavaScript 版本 3 是对版本 2 的重大改写。本节描述了两个版本之间的区别，并说明了如何从适用的 SDK 的版本 2 迁移到版本 3 JavaScript。

使用 codemod 将你的代码迁移到适用于 JavaScript v3 的 SDK

Amazon SDK for JavaScript 版本 3 (v3) 带有用于客户端配置和实用程序的现代化界面，包括凭证、Amazon S3 分段上传、DynamoDB 文档客户端、服务员等。您可以在 repo 的迁移指南中找到 v2 中更改的内容以及每项更改的 v3 等效内容。 Amazon SDK for JavaScript GitHub

要充分利用 Amazon SDK for JavaScript v3，我们建议使用下面描述的 codemod 脚本。

使用 codemod 迁移现有的 v2 代码

中的 codemod 脚本集aws-sdk-js-codemod有助于将现有的 Amazon SDK for JavaScript (v2) 应用程序迁移到使用 v3 API。您可以按以下方式运行转换。

$ 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);

我们已经针对常见使用案例实现了转换。如果您的代码无法正确转换，请使用示例输入代码和观察到/预期的输出代码创建错误报告或功能请求。如果某个现有问题已经报告了您的特定使用案例，请通过投赞同票表示支持。

版本 3 中的新增功能

适用于 JavaScript (v3) 的 SDK 版本 3 包含以下新功能。

此外，还编写了 SDK TypeScript，它具有许多优点，例如静态输入。

模块化软件包

适用于 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) 中，列出您在该地区的所有亚马逊 DynamoDB 表的简单代码示例可能如下us-west-2所示。

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 命令，请导入命令和所需的 Amazon 服务包客户端，然后使用 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";

要以推荐的异步/等待模式调用这些命令，请使用以下语法。

CLIENT.send(new XXXCommand);

例如，以下示例使用推荐的异步/等待模式创建 DynamoDB 表。

import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const dynamodb = new DynamoDB({ region: "us-west-2" });
const tableParams = {
  Table: 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 表。

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));