基于Node.js实现DynamoDB脚本自动化及多环境变更管理

核心逻辑对标RDBMS的SQL迁移脚本，采用增量变更+执行记录校验的模式，实现DynamoDB表结构、数据变更的可追踪、可自动化执行、可多环境对齐。

具体落地步骤 #

• 目录结构设计
  所有变更文件统一纳入Git版本管理，按时间戳命名保证执行顺序，参考目录结构如下：

  dynamodb-migrations/
  ├── pending/                # 待执行的迁移脚本，命名规则：时间戳-变更描述.js
  │   ├── 20240501120000-create-user-table.js
  │   ├── 20240502143000-add-gsi-to-user-table.js
  │   └── 20240503101500-insert-default-admin-user.js
  ├── data/                   # 待同步的静态数据JSON文件
  └── migration-history/      # 已执行脚本记录，也可以直接存入专门的DynamoDB系统表
  

• 依赖选型
  优先使用AWS官方SDK轻量实现，无需引入重框架，安装命令：

  npm install @aws-sdk/client-dynamodb @aws-sdk/util-dynamodb
  

  如果不想从零开发执行器逻辑，也可以直接使用成熟的开源npm包 dynamodb-migrations，内置增量变更、回滚、多环境适配等核心能力。
• 统一迁移脚本模板
  每个迁移脚本固定导出up（执行变更）、down（回滚变更）两个方法，示例如下：

  // 20240501120000-create-user-table.js
  const { CreateTableCommand, DeleteTableCommand } = require("@aws-sdk/client-dynamodb");
  
  // 执行创建表操作
  exports.up = async (dynamoClient) => {
    await dynamoClient.send(new CreateTableCommand({
      TableName: "user",
      KeySchema: [{ AttributeName: "userId", KeyType: "HASH" }],
      AttributeDefinitions: [{ AttributeName: "userId", AttributeType: "S" }],
      ProvisionedThroughput: { ReadCapacityUnits: 5, WriteCapacityUnits: 5 }
    }));
  };
  
  // 回滚操作，删除表
  exports.down = async (dynamoClient) => {
    await dynamoClient.send(new DeleteTableCommand({ TableName: "user" }));
  };
  

• 执行器开发
  编写统一的执行脚本run-migration.js，核心逻辑如下：
  1. 读取当前环境变量初始化DynamoDB客户端，自动适配本地凭证、测试/生产环境IAM角色
  2. 拉取已执行的迁移脚本记录，和pending目录下的脚本做对比，筛选出未执行的变更
  3. 按时间戳升序依次执行每个脚本的up方法，执行成功后更新已执行记录
  4. 执行失败立即终止流程，输出错误日志，支持手动调用down方法回滚到上一版本
• 数据变更处理
  表内记录的增删改可以把原始JSON存在data目录下，通过SDK的序列化工具转换为DynamoDB支持的格式，示例：

  const { PutItemCommand } = require("@aws-sdk/client-dynamodb");
  const { marshall } = require("@aws-sdk/util-dynamodb");
  const defaultAdmin = require("../data/default-admin.json");
  
  exports.up = async (dynamoClient) => {
    await dynamoClient.send(new PutItemCommand({
      TableName: "user",
      Item: marshall(defaultAdmin)
    }));
  };
  

多环境适配注意事项 #

• 不同环境的表名通过环境变量加前缀区分，比如dev_user、prod_user，执行器动态拼接表名，避免跨环境误操作
• 生产环境执行前新增dry run模式，仅打印待执行的变更操作，人工确认后再实际执行
• 禁止修改已经提交到Git的历史迁移脚本，新的变更需要新增独立的迁移文件，保证所有环境的变更历史完全对齐

内容的提问来源于stack exchange，提问作者Swapnil Mhaske