DynamoDB：如何在PutItem时避免创建用户名和邮箱组合已存在的项

你之前的ConditionExpression写法无效的核心原因是：DynamoDB的条件表达式仅针对当前操作指向的项（即基于主表分区键username定位的项）做检查，无法全局遍历所有项判断email是否重复。把email设为排序键也只能保证同一username下的email唯一，做不到全局约束。

下面是两种可行的实现方案，推荐使用第一种原子性方案：

方案一：辅助表+事务（原子性保证，高并发安全） #

要同时保证username和email的全局唯一性，最可靠的方式是借助辅助表和事务操作，确保两个唯一性校验同时生效：

1. 创建辅助表：新建一张表（比如叫UserEmailUnique），把email设为分区键，无需排序键。这张表专门用来记录已被占用的邮箱，确保每个邮箱只对应一个用户名。
2. 原子事务写入：使用TransactWriteItemsCommand执行两个原子操作，只有两个条件都满足时才会提交：
   • 主表写入时，校验username未被使用（attribute_not_exists(username)）
   • 辅助表写入时，校验email未被使用（attribute_not_exists(email)）

TypeScript代码示例 #

import { DynamoDBClient, TransactWriteItemsCommand } from "@aws-sdk/client-dynamodb";
import { marshall } from "@aws-sdk/util-dynamodb";

const dbClient = new DynamoDBClient({ region: "你的AWS区域" });

async function createUniqueUser(username: string, email: string) {
  const transactParams = {
    TransactItems: [
      // 主表写入：确保username未被占用
      {
        Put: {
          TableName: "你的主表名称",
          Item: marshall({ username, email }),
          ConditionExpression: "attribute_not_exists(username)"
        }
      },
      // 辅助表写入：确保email未被占用
      {
        Put: {
          TableName: "UserEmailUnique",
          Item: marshall({ email, username }),
          ConditionExpression: "attribute_not_exists(email)"
        }
      }
    ]
  };

  try {
    await dbClient.send(new TransactWriteItemsCommand(transactParams));
    console.log("用户创建成功");
  } catch (err) {
    if (err.name === "ConditionalCheckFailedException") {
      console.log("用户名或邮箱已被占用");
    } else {
      console.error("创建用户失败", err);
    }
  }
}

方案二：GSI+预查询（低并发场景可用） #

如果你的业务并发量很低，可以用全局二级索引（GSI）配合预查询来实现，但这种方式存在竞态风险（高并发下可能出现重复写入）：

1. 创建GSI：在主表上创建一个GSI，把email设为分区键，投影类型选ALL（或至少投影username）。
2. 预查询校验：先通过GSI查询是否存在该email的记录，确认无重复后再写入主表，同时校验username的唯一性。

TypeScript代码示例 #

import { DynamoDBClient, PutItemCommand, QueryCommand } from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";

const dbClient = new DynamoDBClient({ region: "你的AWS区域" });

async function createUser(username: string, email: string) {
  // 先查GSI确认email未被占用
  const queryParams = {
    TableName: "你的主表名称",
    IndexName: "EmailIndex", // 你的GSI名称
    KeyConditionExpression: "email = :email",
    ExpressionAttributeValues: marshall({ ":email": email })
  };

  const queryRes = await dbClient.send(new QueryCommand(queryParams));
  if (queryRes.Items?.length) {
    console.log("邮箱已被占用");
    return;
  }

  // 写入主表，校验username唯一性
  const putParams = {
    TableName: "你的主表名称",
    Item: marshall({ username, email }),
    ConditionExpression: "attribute_not_exists(username)"
  };

  try {
    await dbClient.send(new PutItemCommand(putParams));
    console.log("用户创建成功");
  } catch (err) {
    if (err.name === "ConditionalCheckFailedException") {
      console.log("用户名已被占用");
    } else {
      console.error("创建用户失败", err);
    }
  }
}

方案对比 #

• 方案一的事务操作是原子性的，完全避免竞态条件，适合所有场景，尤其是高并发业务。
• 方案二无需额外表，但存在并发写入风险，仅适合低并发场景。

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