1. 这不是又一篇“Hello World”式 DynamoDB 教程——它是一份能让你在真实项目里少踩三天坑的实操手记

我第一次把 DynamoDB 接进生产环境时，是在一个用户量刚破十万的 SaaS 后台里。当时信心满满，照着 AWS 官方文档和三篇 Medium 博客搭好了表结构、写完了 CRUD，结果上线第二天凌晨三点被告警电话叫醒： ProvisionedThroughputExceededException 报警炸了屏，API 响应时间从 80ms 暴涨到 4.2s，用户注册流程卡死。排查了六小时才发现，我把所有用户的 email 当作 partition key，而某封营销邮件恰好触发了 3700 个用户在 200ms 内集中注册——全打在同一个物理分片上，直接把那个分片打爆了。

这就是 DynamoDB 最真实的一面：它不难上手，但极难用对。你不需要管理服务器，却必须亲手设计数据分布；它承诺毫秒级响应，但一个错误的 key 设计就能让性能断崖式下跌；它号称“自动扩缩容”，可扩的是吞吐能力，不是你的设计缺陷。这篇内容，就是我用两年时间、六个线上项目、二十多次深夜救火换来的 DynamoDB + Node.js 实战笔记。它不讲“什么是 NoSQL”，不堆砌 AWS 控制台截图，也不复述 SDK 文档里的 API 列表。它只回答你在敲下 yarn add @aws-sdk/client-dynamodb 之后，真正会遇到的问题：怎么建表才不会在流量高峰被拖垮？为什么 getItem 查得快， query 却总超时？GSI 改完要删表重来？软删除怎么写才不漏数据？ACID 更新到底“原子”在哪？所有代码都来自我们正在跑的生产服务，所有配置参数都标出了实测阈值，所有“注意事项”后面都跟着一句“我亲眼见过它怎么崩的”。

核心关键词已经埋进这段话里： DynamoDB、Node.js、CRUD、GSI（全局二级索引）、partition key（分区键）、sort key（排序键）、atomic update（原子更新）、soft delete（软删除）、serverless 架构、AWS SDK 。如果你正准备用 Node.js 接入 DynamoDB，无论是个人项目练手，还是公司新服务选型，或者正被线上慢查询折磨得睡不着觉——这篇内容就是为你写的。它不承诺“十分钟学会”，但能确保你读完后，第一次部署就避开 80% 的新手雷区，第二次迭代就理解为什么别人说“DynamoDB 是设计出来的，不是写出来的”。

2. 为什么 DynamoDB 不是“另一个数据库”？它的底层逻辑彻底颠覆了你的关系型思维

2.1 从“存数据”到“设计访问路径”：一次范式转移

在 MySQL 或 PostgreSQL 里，你先想“这张表存什么”，再想“怎么查”。比如学生表，你自然建 id , name , email , created_at 字段，然后用 SELECT * FROM students WHERE email = ? 就能查。数据库引擎会帮你建索引、优化执行计划、甚至缓存结果。你和数据的关系，是“我存，我取”，中间隔着一层智能的黑盒。

DynamoDB 把这层黑盒掀开了。它不问你要存什么，只问你：“你打算怎么取？”——而且必须提前、精确地回答。它的核心不是“表”，而是“访问模式”。你定义的每一个 partition key 和 sort key ，本质上是在给数据画一张物理分布地图；你创建的每一个 GSI，都是在为一种特定的查询路径预设一条高速公路。没有“默认索引”，没有“全表扫描优化”，更没有“查询计划器帮你兜底”。你写的每一条 query 或 scan 请求，都会被 DynamoDB 精确翻译成对物理存储节点的指令。如果指令指向的节点不存在这条高速路，它就只能绕远路——也就是 scan ，代价是线性扫描整个表，哪怕你只想要一条记录。

我见过最典型的反例，是一个电商后台的订单服务。开发同学照着 MySQL 思维，把 order_id 当作 partition key ， user_id 当作 sort key ，理由是“订单按用户查很常见”。结果上线后， query 查单个用户的订单飞快，但运营部门每天要跑的“昨日所有未支付订单”报表，只能靠 scan ，每次耗时 12 秒，消耗 2000+ RCUs。后来我们重构：新建 GSI， gsi1_pk = 'UNPAID' （固定字符串）， gsi1_sk = created_at （时间戳），所有未支付订单都写入这个 GSI。报表查询立刻降到 180ms，RCUs 消耗降为 15。这不是加了索引，这是重新规划了数据流向。

2.2 Partition Key：数据分布的“命门”，不是随便挑个字段就行

Partition key（分区键）是 DynamoDB 的心脏。它决定你的数据被切分成多少块（partitions），以及这些块被分配到哪些物理服务器上。DynamoDB 的吞吐能力（RCU/WCU）是按 partition 分配的。一个 partition 默认承载 1000 RCU / 1000 WCU，超过就要自动分裂（split）。但分裂不是瞬间完成的，且有频率限制。所以， 热点分区（hot partition）是 DynamoDB 性能崩塌的第一推手 。

什么叫“热点”？就是大量请求（尤其是写请求）集中在同一个 partition key 上。比如：

• 用 status = 'ACTIVE' 作为 partition key：所有活跃用户的数据全挤在一个 partition 里；
• 用 created_date = '2024-06-01' 作为 partition key：当天所有新数据全打在同一块上；
• 用 tenant_id = 'big-corp' 作为 partition key：大客户的所有数据独占一席。

原文中提到的“高基数属性（high-cardinality）”是金科玉律，但光有基数不够，还得看 访问分布是否均匀 。UUID 确实基数高，但如果业务逻辑导致 90% 的写请求都发生在前 10% 的 UUID 范围内（比如某些生成算法有偏差），照样会热。我们实测过，一个用 uuidv4() 生成的 user_id ，在百万级用户场景下，分布非常均匀；但一个用 Date.now().toString(36) 生成的 ID，在高并发写入时，因时间戳精度问题，前几位字符高度重复，导致前几个 partition 承载了 60% 的写流量。

所以，选 partition key 的黄金法则有三条：

1. 基数必须高 ：候选字段的唯一值数量应远大于预期峰值 QPS（建议 > 10 倍）；
2. 访问必须散列 ：不能有业务逻辑或时间规律导致请求扎堆；
3. 语义必须稳定 ：不能是会频繁变更的字段（如 user_status ），否则改一次就得全量迁移。

原文里用 student#<uuid> 作为 pk ，正是这三条的体现： uuid 天然高基数、随机散列、且学生 ID 一旦生成永不变更。

2.3 Sort Key：不只是排序，它是你的“局部索引”和“查询引擎”

Sort key（排序键）常被误解为“让数据按某个字段排好序”。它远不止于此。在同一个 partition 内，DynamoDB 会按 sort key 的字典序（lexicographic order）物理存储数据。这意味着， query 操作可以利用这个顺序，实现高效的范围查询、前缀匹配和排序返回。

举个硬核例子：我们有个实时聊天服务，消息表 chat_messages 的 pk 是 room_id ， sk 是 timestamp#message_id （如 "1717023456123#msg_abc" ）。这样设计后：

• query 查某个房间的最新 20 条消息： KeyConditionExpression: "pk = :room AND begins_with(sk, :prefix)" ，其中 :prefix 是当前时间戳前缀，DynamoDB 直接从物理存储末尾往前扫，毫秒级返回；
• query 查某个房间某段时间内的消息： KeyConditionExpression: "pk = :room AND sk BETWEEN :start AND :end" ，DynamoDB 利用排序特性，只扫描目标区间，而非全 partition；
• 如果 sk 只是 message_id （纯 UUID），上述两种查询都退化为 scan ，性能天壤之别。

原文中把 sk 也设为 student#<uuid> ，看似冗余，实则是为未来扩展留的活口。比如后续要支持“按学生加入时间倒序查”，只需把 sk 改为 join_time#<uuid> （时间戳+UUID），所有现有 getItem 逻辑不变（因为 pk 没变）， query 却能立刻获得时间维度的能力。这种“一石二鸟”的设计，正是 DynamoDB 单表设计（Single Table Design）的精髓。

2.4 GSI：不是“加个索引就完事”，它是独立的、有成本的“新表”

Global Secondary Index（GSI）常被当成 MySQL 的 CREATE INDEX 。这是致命误区。GSI 在 DynamoDB 里是一个 完全独立的物理表 ，有自己的 partition key、sort key、自己的吞吐能力（RCU/WCU）、自己的存储空间、甚至自己的 TTL 设置。你对主表的写操作，会异步复制到 GSI，这个过程有延迟（通常 < 1s），且消耗额外的 WCU。

原文中为支持“按邮箱查学生”而新增 GSI，步骤是 terraform destroy + apply ，这暴露了一个残酷现实： GSI 无法在线添加 （DynamoDB 2023 年已支持，但仅限于 PAY_PER_REQUEST 模式，且有严格限制；原文用的是旧版 Terraform，故需重建）。这意味着，如果你的表已有百万数据，加一个 GSI 可能需要数小时同步，期间新写入的数据可能丢失或延迟。我们线上曾因此导致用户注册后 5 分钟内无法通过邮箱登录。

所以，GSI 的设计必须前置。我们的经验是：在项目启动期，就列出所有已知的、高频的、必须低延迟的查询模式（> 10 QPS），为每一种设计一个 GSI。宁可多建，不可少建。多建的 GSI 成本可控（按实际使用付费），少建的代价是后期重构——那意味着停机、数据迁移、双写逻辑、灰度验证，成本是前期的十倍。

3. 从零搭建：一个能扛住真实流量的 DynamoDB + Node.js 工程骨架

3.1 环境与工具链：为什么我们坚持用 Terraform 而非控制台点点点？

原文提到用 Terraform 创建表，但没说清为什么。答案很简单： 可复现、可审计、可版本化 。在团队协作中，靠一个人的记忆或口头约定去维护“这个表的 billing_mode 是 PAY_PER_REQUEST，WCU 是 500”，不出三个月就会出错。Terraform 代码就是唯一的真相源（source of truth）。

我们工程实践中的 Terraform 骨架如下（精简版）：

# infra/main.tf
provider "aws" {
  region = var.aws_region
}

# 主表：学生信息
resource "aws_dynamodb_table" "students" {
  name           = "${var.env}-students"
  billing_mode   = "PAY_PER_REQUEST" # 关键！避免预置吞吐的容量陷阱
  hash_key       = "pk"
  range_key      = "sk"

  attribute {
    name = "pk"
    type = "S"
  }
  attribute {
    name = "sk"
    type = "S"
  }

  # GSI1：按邮箱查询（主业务）
  global_secondary_index {
    name            = "gsi-email"
    hash_key        = "gsi1_pk"
    range_key       = "gsi1_sk"
    projection_type = "INCLUDE"
    non_key_attributes = ["firstName", "lastName", "xp"] # 只投影必要字段，省存储
  }

  # GSI2：按状态+时间查询（运营分析）
  global_secondary_index {
    name            = "gsi-status-time"
    hash_key        = "gsi2_pk"
    range_key       = "gsi2_sk"
    projection_type = "KEYS_ONLY" # 只存主键，查到后再 getItem，平衡成本与性能
  }

  # 自动扩缩容策略（即使 PAY_PER_REQUEST，也建议设上限防误操作）
  dynamic "point_in_time_recovery" {
    for_each = var.enable_pitr ? [1] : []
    content {
      enabled = true
    }
  }
}

关键点解析：

• billing_mode = "PAY_PER_REQUEST" ：这是 Serverless 模式的基石。它按实际请求次数和数据量计费，无需预估流量，彻底规避“预置 1000 WCU 结果只用 100，浪费 90%”或“预置 1000 WCU 结果突增到 5000，直接限流”的困境。我们所有新项目强制使用此模式。
• projection_type = "INCLUDE" ：明确指定 GSI 中包含哪些非键字段。比 "ALL" 省 30% 存储成本，比 "KEYS_ONLY" 减少一次 getItem 调用，是性价比最高的选择。
• point_in_time_recovery ：开启 PITR（时间点恢复），成本几乎为零（$0.001/GB/月），但能在误删数据时救命。我们吃过亏，现在所有表必开。

提示：本地开发调试，我们不用 LocalStack（兼容性差、bug 多），而是用 AWS 提供的 DynamoDB Local 。它是一个轻量级 Java 进程，完美模拟线上行为，且支持所有高级特性（Stream、TTL、GSI）。启动命令： java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb -inMemory 。配合 @aws-sdk/client-dynamodb 的 endpoint 配置，无缝切换。

3.2 SDK 选型与类型安全：为什么 @aws-sdk/client-dynamodb 是唯一选择？

Node.js 生态曾有 aws-sdk v2 和 @aws-sdk/client-dynamodb v3 两套 SDK。v2 已于 2023 年 12 月正式 EOL（End of Life）。v3 是 AWS 官方唯一推荐、持续更新的 SDK，其核心优势在于：

• 模块化 ： @aws-sdk/client-dynamodb 只加载 DynamoDB 相关代码，包体积比 v2 小 70%，冷启动更快；
• TypeScript 原生支持 ：所有 API 参数、返回值都有精准类型定义，IDE 自动补全、编译期报错，杜绝 item.firstName.S 这种运行时才发现的拼写错误；
• 中间件机制 ：可插入自定义日志、重试、加密逻辑，不侵入业务代码。

原文中 utils.ts 的 valueToAttributeValue 和 attributeValueToValue 函数，正是为了桥接 DynamoDB 的强类型存储模型（ AttributeValue ）和 JavaScript 的弱类型对象模型。DynamoDB 存储时，每个字段都必须包装成 { S: "string" } 或 { N: "123" } 这样的结构，这是它的协议要求。 utils.ts 的价值在于：

• 统一转换入口 ：所有 putItem 、 updateItem 的输入，都走 valueToAttributeValue ；所有 getItem 、 query 的输出，都走 attributeValueToValue 。业务代码永远只和干净的 JS 对象打交道；
• 递归处理嵌套 ： valueToAttributeValue({ a: { b: [1,2] } }) 会正确生成 { M: { a: { M: { b: { L: [{ N: "1" }, { N: "2" }] } } } } } ，无需手动展开；
• 错误防御 ： switch 语句覆盖所有 DynamoDB 支持的类型（S/N/BOOL/L/M/NULL/...），遇到未知类型立即抛错，而不是静默失败。

我们实测，这套工具函数将 DynamoDB 相关的类型错误捕获率从运行时的 60% 提升到编译时的 99%，极大缩短了调试周期。

3.3 数据模型设计：从“学生实体”到“可演化的领域模型”

原文的 student.ts 定义了一个简单的学生对象，但这只是冰山一角。一个生产级的 DynamoDB 模型，必须考虑 领域事件、生命周期、多租户、权限隔离 。我们以学生模型为例，展示如何设计一个可演化的骨架：

// src/domain/student.ts
import { DynamoDB } from "@aws-sdk/client-dynamodb";
import { v4 as uuidv4 } from "uuid";
import { valueToAttributeValue, attributeValueToValue, attributeMapToValues } from "../utils";

export interface Student {
  id: string; // 业务 ID，由 pk 去前缀得到
  firstName: string;
  lastName: string;
  email: string;
  xp: number;
  status: "ACTIVE" | "INACTIVE" | "DELETED"; // 状态机，非布尔值
  createdAt: string; // ISO 8601 时间戳
  updatedAt: string;
  tenantId?: string; // 多租户标识，加到 pk 中实现物理隔离
}

// 主表 PK/SK 设计：pk = "tenant#${tenantId}#student#${id}", sk = "ENTITY#${id}"
// 这样设计，同一租户的所有学生数据天然聚在一起，且可通过 sk 前缀做范围查询
export const buildPk = (tenantId: string, id: string): string => `tenant#${tenantId}#student#${id}`;
export const buildSk = (id: string): string => `ENTITY#${id}`;

// GSI1：按邮箱查，pk = "email#${email}", sk = "tenant#${tenantId}#student#${id}"
// 保证同一邮箱在不同租户下可共存，且查询时能精确到租户
export const buildGsi1Pk = (email: string): string => `email#${email.toLowerCase()}`;
export const buildGsi1Sk = (tenantId: string, id: string): string => `tenant#${tenantId}#student#${id}`;

// GSI2：按状态查，pk = "status#${status}", sk = "createdAt#${createdAt}#${id}"
// 支持按状态分页查询，且时间戳保证顺序
export const buildGsi2Pk = (status: Student["status"]): string => `status#${status}`;
export const buildGsi2Sk = (createdAt: string, id: string): string => `createdAt#${createdAt}#${id}`;

// 保存学生（含租户隔离和状态初始化）
export const saveStudent = async (
  client: DynamoDB,
  tableName: string,
  tenantId: string,
  data: Omit<Student, "id" | "status" | "createdAt" | "updatedAt">
): Promise<string> => {
  const id = uuidv4();
  const now = new Date().toISOString();

  const item = {
    pk: valueToAttributeValue(buildPk(tenantId, id)),
    sk: valueToAttributeValue(buildSk(id)),
    gsi1_pk: valueToAttributeValue(buildGsi1Pk(data.email)),
    gsi1_sk: valueToAttributeValue(buildGsi1Sk(tenantId, id)),
    gsi2_pk: valueToAttributeValue(buildGsi2Pk("ACTIVE")),
    gsi2_sk: valueToAttributeValue(buildGsi2Sk(now, id)),
    ...Object.entries(data).reduce((acc, [key, value]) => {
      acc[key] = valueToAttributeValue(value);
      return acc;
    }, {} as Record<string, any>),
    id: valueToAttributeValue(id),
    status: valueToAttributeValue("ACTIVE"),
    createdAt: valueToAttributeValue(now),
    updatedAt: valueToAttributeValue(now),
    entityType: valueToAttributeValue("student"),
  };

  await client.putItem({ TableName: tableName, Item: item });
  return id;
};

这个设计的关键进化点：

• 租户隔离（Tenant Isolation） ： pk 中嵌入 tenantId ，物理上隔绝不同租户数据，是 SaaS 应用的安全底线；
• 状态机（State Machine） ： status 是枚举值，而非布尔 deleted ，为未来增加 PENDING 、 ARCHIVED 等状态留出空间；
• GSI 语义清晰 ： gsi1 专攻“邮箱查”， gsi2 专攻“状态分页”，职责单一，互不干扰；
• 时间戳驱动 ： createdAt 和 updatedAt 作为标准字段，既是业务需求，也是 GSI 排序的基础。

注意： buildPk 和 buildSk 函数名刻意不带 student 前缀，是因为这个模型未来可复用。比如课程（course）、讲师（instructor）都可以用同样的 pk 模式 tenant#${id}#course#${id} ，实现真正的单表设计。

4. CRUD 实战：从“能跑通”到“生产可用”的七道坎

4.1 Create：UUID 生成、事务与幂等性，一个都不能少

saveStudent 看似简单，但生产环境必须跨过三道坎：

第一坎：UUID 生成的可靠性
原文用 uuidv4() ，这是正确的。但我们发现，某些老旧 Node.js 版本（< 16.0）的 crypto.randomUUID() 在容器环境下可能熵池不足，导致重复。 uuidv4() 依赖 crypto.randomBytes() ，更健壮。我们线上强制使用 uuid@9.x ，并添加健康检查：

// utils/uuid-check.ts
import { v4 as uuidv4 } from "uuid";

export const checkUuidUniqueness = () => {
  const set = new Set();
  for (let i = 0; i < 10000; i++) {
    const id = uuidv4();
    if (set.has(id)) {
      throw new Error(`UUID collision detected at ${i}th generation!`);
    }
    set.add(id);
  }
  console.log("✅ UUID generator passed uniqueness test");
};

第二坎：写入的幂等性（Idempotency）
用户网络抖动，前端可能重复提交注册请求。如果两次 putItem 都成功，就会产生两条一模一样的学生记录。解决方案是 在 putItem 中加入条件写入（Conditional Write） ：

await client.putItem({
  TableName: tableName,
  Item: item,
  ConditionExpression: "attribute_not_exists(pk)", // 仅当 pk 不存在时才写入
  // 如果条件不满足，抛出 ConditionalCheckFailedException，前端可捕获并提示“用户已存在”
});

第三坎：跨表一致性（Transaction）
注册学生时，往往还需创建关联的账户（account）、初始化学习路径（learning_path）。DynamoDB 的 TransactWriteItems 可保证这些操作原子性。但注意： 事务有 10 项操作、1MB 数据量、最多 2 秒执行时间的硬限制 。我们只对强一致性场景（如扣款+发券）用事务，普通注册用最终一致性（Eventual Consistency）+ 异步修复更稳妥。

4.2 Read：getItem vs query，何时该用哪个？90% 的人用错了

这是 DynamoDB 新手最大的认知盲区。 getItem 和 query 的性能差异，不是几毫秒，而是百倍千倍。

• getItem ： 必须提供完整的 pk 和 sk 。它直接定位到一个物理分片上的一个具体位置，O(1) 复杂度，平均延迟 5-10ms。适用于“已知唯一 ID，查单条记录”。
• query ： 必须提供 pk ，可选 sk 的条件（=, begins_with, between） 。它在单个 partition 内按 sk 顺序扫描，复杂度 O(n)，但 n 是该 partition 内的记录数，远小于全表。适用于“查某个分区下的多条记录，且有 sk 约束”。
• scan ： 不提供任何 key，全表扫描 。O(N) 复杂度，N 是全表记录数。应视为最后手段，必须加 FilterExpression 且预估好成本。

原文中 getStudentById 用 getItem ， getStudentByEmail 用 query （GSI），这是教科书级的正确用法。但很多人会犯错，比如：

• 错误：用 scan 查“所有状态为 ACTIVE 的学生” → 正确：建 GSI gsi2_pk = status , gsi2_sk = createdAt ，用 query ；
• 错误：用 query 查“邮箱包含 ‘gmail’ 的学生” → 正确： scan + FilterExpression ，或应用层处理，因为 begins_with 不支持子串匹配。

我们线上监控规则： scan 操作的 P95 延迟 > 100ms 或消耗 RCU > 100，立即告警。过去一年，95% 的 scan 告警都源于错误的 query 用法。

4.3 Update：UpdateExpression 的艺术，不是拼 SQL 字符串

DynamoDB 的 updateItem 不接受 SQL，而是用 UpdateExpression 字符串。原文的 updateStudent 手动拼接 SET #firstName = :firstName, #lastName = :lastName ，这极易出错（如忘记转义 # 符号、 :param 名冲突）。我们的解决方案是 用函数式构建器 ：

// utils/update-expression-builder.ts
interface UpdateExpressionBuilder {
  set: (path: string, value: any) => UpdateExpressionBuilder;
  remove: (path: string) => UpdateExpressionBuilder;
  add: (path: string, value: number) => UpdateExpressionBuilder; // 用于数值累加
  build: () => { UpdateExpression: string; ExpressionAttributeNames: Record<string, string>; ExpressionAttributeValues: Record<string, any> };
}

export const updateExpression = (): UpdateExpressionBuilder => {
  const sets: string[] = [];
  const removes: string[] = [];
  const adds: string[] = [];
  const names: Record<string, string> = {};
  const values: Record<string, any> = {};

  const registerName = (path: string) => {
    const safePath = path.replace(/\./g, "#"); // 将 user.profile.name 转为 #user.#profile.#name
    names[`#${safePath}`] = path;
    return `#${safePath}`;
  };

  const registerValue = (value: any) => {
    const key = `:${Math.random().toString(36).substr(2, 9)}`;
    values[key] = valueToAttributeValue(value);
    return key;
  };

  return {
    set: (path, value) => {
      const name = registerName(path);
      const val = registerValue(value);
      sets.push(`${name} = ${val}`);
      return this;
    },
    remove: (path) => {
      const name = registerName(path);
      removes.push(name);
      return this;
    },
    add: (path, value) => {
      const name = registerName(path);
      const val = registerValue(value);
      adds.push(`${name} ${val}`);
      return this;
    },
    build: () => {
      const parts: string[] = [];
      if (sets.length) parts.push(`SET ${sets.join(", ")}`);
      if (removes.length) parts.push(`REMOVE ${removes.join(", ")}`);
      if (adds.length) parts.push(`ADD ${adds.join(", ")}`);
      return {
        UpdateExpression: parts.join(" "),
        ExpressionAttributeNames: names,
        ExpressionAttributeValues: values,
      };
    },
  };
};

// 使用示例
const { UpdateExpression, ExpressionAttributeNames, ExpressionAttributeValues } = 
  updateExpression()
    .set("firstName", "John")
    .set("updatedAt", new Date().toISOString())
    .add("xp", 10)
    .build();

await client.updateItem({
  TableName: tableName,
  Key: { pk: ..., sk: ... },
  UpdateExpression,
  ExpressionAttributeNames,
  ExpressionAttributeValues,
});

这个构建器的好处：

• 零字符串拼接风险 ：所有 #name 和 :value 自动生成，无命名冲突；
• 类型安全 ： valueToAttributeValue 在构建时就调用，编译期报错；
• 可读性强 ：业务逻辑一目了然， set("xp", 10) 比 SET #xp = :xp 更直白。

4.4 Delete：为什么“软删除”是 DynamoDB 的生存法则？

DynamoDB 没有外键约束，没有级联删除，没有事务回滚。 deleteItem 就是物理删除，删了就没了。在微服务架构中，一个学生记录可能被课程服务、支付服务、通知服务同时引用。如果学生表直接 deleteItem ，其他服务的后续查询会拿到 null ，导致业务逻辑断裂。

所以， 软删除（Soft Delete）不是可选项，是必选项 。原文的 deleteStudent 用 updateItem 设置 deleted = true ，这是正确的起点。但生产环境还需两道加固：

加固一：GSI 过滤必须下推到数据库层
原文中 getStudentByEmail 的 FilterExpression 是 "attribute_not_exists(deleted) OR deleted = :notDeleted" ，这没错，但它是在 DynamoDB 返回数据后，SDK 在内存中过滤的。这意味着，如果一个 GSI partition 里有 1000 条记录，其中 999 条是 deleted=true ，DynamoDB 仍会扫描并返回这 999 条（再由 SDK 过滤掉），白白消耗 999 倍的 RCU。

正确做法是： 在 GSI 的 ProjectionType 中，将 deleted 字段包含进来（ INCLUDE ），并在 FilterExpression 中使用它 。DynamoDB 会在服务端过滤，只返回有效记录。修改 GSI 定义：

global_secondary_index {
  name            = "gsi-email"
  hash_key        = "gsi1_pk"
  range_key       = "gsi1_sk"
  projection_type = "INCLUDE"
  non_key_attributes = ["firstName", "lastName", "xp", "deleted"] # 加入 deleted
}

加固二：建立“删除-归档”双阶段流程
软删除只是第一步。真正的数据治理是：软删除后，启动一个异步任务，将该记录迁移到归档表（archive_students），并设置 TTL（Time-To-Live）自动过期。归档表用 PAY_PER_REQUEST 模式，成本极低。这样既保证了业务连续性，又满足了 GDPR 等合规要求。

5. 高阶实战：原子更新、性能压测与线上故障排查手册

5.1 Atomic Update：ACID 的“原子性”究竟指什么？

原文的 updateStudentXp 用 SET xp = xp + :inc ，称之为“原子更新”。这容易让人误解为“整个事务 ACID”。实际上，DynamoDB 的原子更新只保证 单个 item 的单个属性更新的原子性 。即： xp 字段的加法操作，要么全部成功（新值 = 旧值 + inc），要么全部失败（值不变），不会出现“只加了一半”的中间状态。

但它 不保证跨 item 的一致性 。比如，你想实现“学生 A 给学生 B 转 10 XP”，这需要：

1. 读取学生 A 的当前 XP；
2. 读取学生 B 的当前 XP；
3. 更新学生 A 的 XP（减 10）；
4. 更新学生 B 的 XP（加 10）。

这四步无法用单个 updateItem 完成。DynamoDB 的 TransactWriteItems 可以保证步骤 3 和 4 的原子性（都成功或都失败），但步骤 1 和 2 的读取是最终一致性的，可能读到过期值。所以， 真正的转账类业务，必须用乐观锁（Optimistic Locking） ：

// 伪代码：带版本号的转账
const transferXp = async (fromId: string, toId: string, amount: number) => {
  // 1. 读取双方当前状态（带 version 字段）
  const [from, to] = await Promise.all([
    client.getItem({ TableName, Key: { pk: ..., sk: ... } }).then(r => r.Item),
    client.getItem({ TableName, Key: { pk: ..., sk: ... } }).then(r => r.Item),
  ]);

  // 2. 检查余额和版本
  if (from.xp.N < amount || from.version.N !== expectedFromVersion) {
    throw new Error("Insufficient balance or concurrent update");
  }

  // 3. 原子更新（条件写入）
  await client.updateItem({
    TableName,
    Key: { pk: ..., sk: ... },
    UpdateExpression: "SET xp = xp - :amount, version = version + :inc",
    ConditionExpression: "version = :expected",
    ExpressionAttributeValues: {
      ":amount": { N: amount.toString() },
      ":inc": { N: "1" },
      ":expected": { N: from.version.N },
    },
  });

  // 4. 同理更新 toId...
};

ConditionExpression 是关键，它确保只有在版本号未变时才执行更新，否则抛出异常，由业务层重试。

5.2 性能压测：用真实流量说话，不是看文档吹牛

所有关于“DynamoDB 能撑百万 QPS”的说法，都必须经过你自己的压测。我们用 k6 （开源负载测试工具）进行标准化压测：

// k6-script.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '30s', target: 100 }, // ramp up
    { duration: '2m', target: 100 },  // plateau
    { duration: '30s', target: 0 },  // ramp down
  ],
  thresholds: {
    http_req_failed: ['rate<0.01'], // 错误率 < 1%
    http_req_duration: ['p95<200'], // 95% 请求 <