# DynamoDB 查询接口此技能采用 DynamoDB 表设计文档并生成一整套存储库接口：实体类型、方法签名、输入/输出合同和密钥构建实用程序。输出是与语言无关的伪代码，可以直接翻译为任何语言。 ## 何时使用 * 用户有一个表设计`.md`文件（来自`dynamodb-table-design`或手动编写） * 用户想要生成数据访问层骨架 * 用户希望每个访问模式都有类型安全的方法签名 * 用户希望在实施之前看到完整的存储库界面 ## 管道位置 1. 访问模式 --> 2. 表设计 --> [3.查询接口] (dynamodb-access-(dynamodb-table-(此技能) 图案）设计） **输入** : 表设计 `.md` 文件 **输出** : 接口定义 `.md` 文件，并准备好实现伪代码 ** ** ## 先决条件阅读表格设计文件。如果它不存在或不完整，请告诉用户首先运行“dynamodb-table-design”技能。 **阅读`reference/language-conventions.md`以确定目标语言语法。**询问用户他们打算用哪种语言实现。如果他们没有偏好，请使用通用伪代码。 ** ** ## 生成工作流程 ### 第 1 步：生成实体模型对于表设计中的每个实体，创建一个数据模型类型。 **规则：** * 包含 `pk` 和 `sk` 作为字符串字段（这些是 DynamoDB 关键属性） * 仅当实体使用 GSI 时才包含 GSI 关键属性 * 包括表设计中的所有域属性 * 显式标记可选字段 * 添加引用实体描述的文档注释 **模板：** // 实体：[名称] // 描述：[来自表格设计] // PK: [模式] // SK: [模式] 接口 [实体名称] { pk：字符串 sk：字符串 [GSI 属性（如果适用）] [具有类型的域属性] } **示例（通用）：** // 实体：订单 // 描述：客户购买的商品 // PK: USER#<用户ID> // SK: ORDER## 接口顺序{ pk: string // USER# sk: string // ORDER## GSI1PK：可选字符串 // PRODUCT#（仅当已索引时） GSI1SK：可选字符串 // ORDER## orderId: string // ULID 用户 ID: 字符串总计：数量状态：字符串 // 待处理 |已发货 |已交付 |取消项目：列表<订单项目> 创建处：字符串 // ISO 8601 UpdatedAt：可选字符串 // ISO 8601 } ### 第 2 步：生成密钥生成器函数对于每个实体，生成一个函数，根据域参数构建 PK 和 SK。 **模板：** // 为 [EntityName] 构建键 // AP 引用：[使用此密钥的 AP ID 列表] 函数 build[EntityName]Key(params) -> { pk: 字符串, sk: 字符串 } **示例：** // 为订单构建键 // AP 参考号：AP-001、AP-002、AP-010、AP-020 函数 buildOrderKey({ userId: string,createdAt: string, orderId: string }) -> { pk：“用户#”+用户ID， sk：“ORDER#”+createdAt+“#”+orderId } // 构建查询用户所有订单的前缀键 // 美联社参考文献：AP-002 函数 buildOrderCollectionPrefix({ userId: string }) -> { pk：“用户#”+用户ID， sk前缀：“订单#” } **关键构建者规则：** * 每个实体每个唯一的关键模式一个构建器 * 为每个“begins_with”访问模式包含一个前缀构建器 * 如果实体具有 GSI 属性，则包括 GSI 密钥生成器 * 记录哪些 AP ID 使用每个构建器 ### 步骤3：生成存储库接口为每个实体创建一个存储库接口（如果用户更喜欢统一的存储库，则为每个有界上下文创建一个存储库接口）。存储库中的每种方法都准确地映射到表设计中的一种访问模式。 **对于每个方法，定义：** 1.带有类型化参数的**方法签名** 2. **返回类型**（实体、实体列表、分页结果或 void） 3. **AP参考**（它实现哪种访问模式） 4. **DynamoDB操作**（来自表设计映射） 5. **密钥构建**（使用哪个密钥构建器） 6. **备注**（条件、交易详情等） **示例：** 接口订单存储库{ // AP-001：通过orderId获取特定订单 // 操作：查询 // 表/GSI：表 // 键：ORDER# / = ORDER# function getOrderById({ orderId: string }) -> 可选订单 // AP-002：列出用户的所有订单，最新的在前 // 操作：查询 // 表/GSI：表 // 键：USER# /begins_with(ORDER#) // 参数：ScanIndexForward=false，分页函数 listUserOrdersPaginated({ 用户 ID：字符串，限制：数量，光标：可选字符串 }) -> PaginatedResult<订单> // AP-010：创建新订单 // 操作：TransactWriteItems // 项目： // 1. 将 ORDER 放入用户集合中（条件：attribute_not_exists(pk)） // 2.放入ORDER自记录（条件：attribute_not_exists(pk)） // 3. 更新 ORDER_COUNT +1 函数创建订单（{ 用户 ID：字符串，订单 ID：字符串，总数：数量，状态：字符串，项目：列表<订单项目> }) -> 订单 } ### 步骤 4：生成事务助手类型对于涉及多个项目的写操作，定义事务结构： // AP-010: 创建订单交易交易创建订单交易{ 项目：[ { 操作：放置实体：订单（用户集合） key: buildOrderKey({ userId, createdAt, orderId }) 条件：attribute_not_exists(pk) }, { 操作：放置实体：订单（自记录）键：buildOrderCatalogKey({ orderId }) 条件：attribute_not_exists(pk) }, { 操作：更新实体：订单计数键：buildOrderCountKey({ userId }) 更新：SET 计数 = 计数 + :inc 值：{“：inc”：1} } ] } ### 第 5 步：验证覆盖范围创建一个可追溯性矩阵，显示每个 AP 都被覆盖： |应用程序 ID |方法|状态 | |--------|--------|--------| | AP-001 | OrderRepository.getOrderById |覆盖| | AP-002 | OrderRepository.listUserOrdersPaginated | OrderRepository.listUserOrdersPaginated |覆盖| | AP-010 |订单存储库.createOrder |覆盖| 每个 AP 的状态必须为“已覆盖”。如果任何 AP 为“未覆盖”，则设计存在缺陷。 ** ** ## 输出格式将输出保留为 markdown 文件。建议“docs/dynamodb/query-interfaces.md”或与其他文件一起。 **阅读`reference/output-template.md`以获取要使用的确切文件结构。** ** ** ## 多实体读取模式当单个查询返回不同实体类型的项目时（单表设计的力量），存储库方法必须： 1.接受通用PK参数 2. 返回一个结构化对象，其中包含每个实体类型的类型化字段 3. 记录应用程序代码中的实现按 SK 前缀进行过滤 // AP-003：获取包含最近订单的用户个人资料 // 这是返回异构项目的单个 DynamoDB 查询。 // 实现： // 1. 查询 PK=USER#，无 SK 条件（或 begins_with("")） // 2. 迭代结果，按 SK 前缀分组： // - SK 以“USER#”开头 -> 用户实体 // - SK 以“ORDER#”开头 -> 订单实体 // - SK 以“BALANCE”开头 -> 余额实体 // 3.返回结构化结果函数 getUserProfileWithOrders({ userId: string }) -> { 用户：可选用户，订单：列表<订单>，平衡：可选平衡 } ** ** ## 代理规则 1. **先阅读表格设计文件。** 切勿生成没有表格设计的界面。 2. **每种访问模式一种方法。** 不要将多个 AP 合并为一种方法，除非它们确实是相同的查询。 3. **每个方法都引用其 AP ID。** 这保持了从需求到代码的可追溯性。 4. **在注释中包含 DynamoDB 操作详细信息。** 实施者应该准确了解 DynamoDB 仅从接口进行的调用。 5. **使用用户首选的语言语法。** 如果他们说 TypeScript，请使用 TypeScript。如果他们说 Python，请使用 Python 数据类/协议。默认为通用伪代码。 6. **密钥构建器与存储库方法分开。**这允许重用和测试。 7. **分页始终基于游标。**切勿公开页码或偏移量 - DynamoDB 不支持它们。 8. **明确记录事务结构。** 多项写入是最复杂的操作；让它们变得晶莹剔透。 9. **验证完整覆盖率。** 可追溯性矩阵必须显示 100% 覆盖率。 10. **保留文件。** 始终将输出写入“.md”文件。 ## 下一步接口文件完成后，告诉用户：查询接口记录在[文件路径]中。您现在拥有完整的设计流程： 1. 访问模式：[路径] 2.表格设计：[路径] 3. 接口：[路径] 下一步是实施。您可以使用这些接口作为合约用于您的数据访问层。每个方法注释都包含确切的 DynamoDB 运行情况、重点建设及所需条件。推荐的实施顺序： 1.实体模型（类型/接口/类） 2. 关键构建器功能 3. 存储库方法（先读，后写） 4. 针对 DynamoDB Local 或测试表的集成测试

Dynamodb 查询接口

包含技能