dynamodb-single-table

DynamoDB 单表设计流水线

此技能负责协调一个由 3 个步骤组成的流水线，用于设计和实现 DynamoDB 单表设计。当用户需要完整工作流，或需要了解下一步该做什么时，请使用此技能。

流水线概览

  Step 1                    Step 2                    Step 3
  ┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
  │ Access Patterns   │ ──>  │ Table Design      │ ──>  │ Query Interfaces  │
  │                   │      │                   │      │                   │
  │ Elicit entities   │      │ Design PK/SK/GSI  │      │ Generate method   │
  │ & access patterns │      │ Map AP -> Query   │      │ signatures & types│
  │ Output: .md file  │      │ Output: .md file  │      │ Output: .md file  │
  └──────────────────┘      └──────────────────┘      └──────────────────┘
  Skill:                    Skill:                    Skill:
  dynamodb-access-patterns  dynamodb-table-design     dynamodb-query-interfaces

步骤 0：检测流水线状态

在确定路由前，检查用户的项目是否已有流水线产物。搜索符合以下模式的文件：

• **/access-patterns.md 或 **/access_patterns.md
• **/table-design.md 或 **/table_design.md
• **/query-interfaces.md 或 **/query_interfaces.md

还要检查常见位置：

• docs/dynamodb/
• docs/
• 项目根目录

根据现有文件判断：

找到的文件	状态	操作
无	全新开始	路由到 dynamodb-access-patterns
仅访问模式	步骤 1 已完成	路由到 dynamodb-table-design，并提供文件路径
访问模式 + 表设计	步骤 1-2 已完成	路由到 dynamodb-query-interfaces，并提供文件路径
三个文件齐全	流水线已完成	询问他们是否要添加实体、修改或审查
仅有表设计（无访问模式）	部分完成／旧版	提醒用户应记录访问模式；提供补充文档或继续执行步骤 3 的选项

告诉用户你发现了什么：

I found existing DynamoDB design artifacts in your project:

  [x] Access Patterns: docs/dynamodb/access-patterns.md
  [x] Table Design:    docs/dynamodb/table-design.md
  [ ] Query Interfaces: (not found)

You're ready for Step 3. Should I generate the query interfaces from
your table design?

如何路由

用户想要……	路由到
从头开始设计	dynamodb-access-patterns
定义实体及其查询方式	dynamodb-access-patterns
已有访问模式，需要设计键	dynamodb-table-design
已有表设计，需要代码接口	dynamodb-query-interfaces
向现有表中添加新实体	从新实体的 dynamodb-access-patterns 开始，然后继续执行流水线
了解单表设计概念	直接使用下方的概念作答

核心概念（快速参考）

什么是单表设计？

所有实体类型都存放在同一个 DynamoDB 表中。将相关数据预先联接到项目集合（共享分区键的项目）中，这样便可通过一次 Query 调用获取数据。这消除了联接的需求，并减少了网络往返次数。

何时使用单表设计

• 需要在任何规模下都实现低于 30 毫秒的响应时间
• 访问模式定义明确，且不会频繁变化
• 需要在单个请求中获取多种实体类型
• 正在构建 OLTP 工作负载（而非分析工作负载）

何时不使用单表设计

• 访问模式仍在快速演变（处于早期阶段的初创公司）
• 使用 GraphQL 和按类型解析器（解析器模型会抵消单次查询的优势）
• 需要灵活的临时查询（可考虑改用关系型数据库）

核心原则

1. 先确定访问模式。 不清楚查询方式时，绝不要设计键。
2. 预先联接到项目集合中。 相关数据共享分区键。
3. 一张表，使用通用键名。 使用 pk/sk（而不是 userId/orderId）。
4. 使用 GSI 支持其他访问模式。 优先复用，而非创建新的 GSI（最多 20 个）。
5. 使用复合排序键进行多字段排序。 在 SK 中编码层级结构。
6. 不要使用 Scan。 每个查询都必须使用分区键。如果需要 Scan，请重新设计。
7. 对多项目写入使用事务。 确保项目集合间的一致性。

生成的产物

流水线结束时，用户将获得 3 个文件：

文件	内容	由以下工具生成
access-patterns.md	实体、属性，以及所有读取／写入／删除模式	dynamodb-access-patterns
table-design.md	PK/SK 设计、GSI、访问模式 -> 查询映射	dynamodb-table-design
query-interfaces.md	实体类型、键构造器、存储库方法签名	dynamodb-query-interfaces

这些文件将作为实现阶段的规范。