('articles'); await articles.insertOne({ title: 'Hello DynamoDB', content: 'Getting started...' }); const article = await articles.findOne({ title: 'Hello DynamoDB' }); ``` ### 开始 1. **克隆实例项目**数字 : `git clone https://github.com/exabugs/dynamodb-client-example.git` 2. **遵循 QUICKSTART 指南**: 见 [QUICKSTART.md (中文(简体) )](https://github.com/exabugs/dynamodb-client-example/blob/main/QUICKSTART.md) 3. **自定义您的需要**: 修改计划, 添加资源, 部署到 AWS * * * ## 页:1 ### 可用文档 - **[建筑](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/ARCHITECTURE.md)** - 系统结构和设计 - **[客户端使用](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/CLIENT_USAGE.md)** - 客户端 API 指南 - **[反应管理员集成](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/react-admin-integration.md)** - 管理UI的设置和许多关系 - **[授权安全设置( S)](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/AUTHORIZATION.md)** - `aud` 検証 - **[疎な検索の警告と対応](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/SCAN_WARNING.md)** - 検索を打ち切らず、警告(SPARSE SCAN) で気づいてインデックス・スキーマ・ロジックを見直す - **[记录](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/RECORDS_CLIENT.md)** - Lambda QQ 记录 ()`createRecordsClient` 编号 : `withCollection` 编号 : `lazyCollection`(中文(简体) ) - **[運用通知](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/NOTIFY.md)** {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080} - \\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080} - {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080} - {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080} - {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080} - {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080} - {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}`@exabugs/dynamodb-client/notify`兰布达 `@exabugs/dynamodb-client/notify/ops`(中文(简体) ) - **[システム変更履歴](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/SYSTEM_CHANGES.md)** - インフラの変更・リリースを `systemChanges` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}"黑" 兰布达"`@exabugs/dynamodb-client/system-changes`)),缩写为QQ CLI(`dynamodb-system-change`(中文(简体) ) - **[管理者](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/ADMINS.md)** - 说吧 `admins` 页:1`@exabugs/dynamodb-client/admins`) `adminsResource`\* `dynamodb-admins add`。管理画面の日本語化は `@exabugs/dynamodb-client/integrations/react-admin/i18n`(单位:千美元)[反应- admin- 整合. md](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/react-admin-integration.md)(中文(简体) ) - **[部署](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/DEPLOYMENT.md)** - 生产部署指南 - **[地形模块](https://npmcn.com/package/%40exabugs/dynamodb-client/terraform/README.md)** - 基础设施作为代码 ### GitHub 动作 - **[GitHub 动作设置](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/GITHUB_ACTIONS_SETUP.md)** - CI/CD配置 - **[解决问题](https://npmcn.com/package/%40exabugs/dynamodb-client/docs/GITHUB_ACTIONS_TROUBLESHOOTING.md)** - 共同问题和解决办法 * * * ## 发展 ### 先决条件 - 节点.js >= 20.0.0 - npm, pnpm, 或纱线 - AWS账户(用于部署) ### 设置 ```bash # Clone repository git clone https://github.com/exabugs/dynamodb-client.git cd dynamodb-client # Install dependencies npm install # Run tests npm test # Build npm run build ``` ### 可用命令 ```bash npm test # Run tests npm run test:coverage # Run tests with coverage npm run lint # Lint code npm run format # Format code npm run build # Build package npm run clean # Clean build artifacts ``` * * * ## 部署 ### 使用示例项目 最简单的部署方法是使用 [客户-实例](https://github.com/exabugs/dynamodb-client-example) 项目: ```bash # Clone the example git clone https://github.com/exabugs/dynamodb-client-example.git cd dynamodb-client-example make infra-apply ``` 见 [示例项目文档](https://github.com/exabugs/dynamodb-client-example) 详细部署指示. * * * ## 配置管理 ### 参数存储集成 库支持AWS参数存储器进行灵活的配置管理,消除了应用程序代码中对Terraform输出的需求. #### 参数结构 参数按等级排列: ``` /{project_name}/{environment}/ ├── app/ │ ├── records-api-url # Lambda Function URL │ └── admin-ui/ │ ├── cognito-user-pool-id │ ├── cognito-client-id │ └── cognito-domain ├── infra/ │ └── dynamodb-table-name └── lambda/ └── records-function-arn ``` #### 福利 - **QQ 动态配置**: 不重新部署而更新设置 - **安全存储**: 所有参数用 AWS 管理的 KMS 密钥加密 - **成本效益**: 标准等级对于典型使用是免费的 - **审计轨迹**: 通过 CloudTrail 完成历史变化 - **环境分离**: 清除 dev/stg/prd 隔离 #### 应用程序中的使用 **反应管理员 UI**数字 : ```typescript // Read configuration from Parameter Store const config = await getParametersByPath(`/${PROJECT_NAME}/${ENV}/app/admin-ui/`); const cognitoConfig = { userPoolId: config['cognito-user-pool-id'], clientId: config['cognito-client-id'], domain: config['cognito-domain'], }; ``` **Lambda 函数**数字 : ```typescript // Read specific parameters const recordsApiUrl = await getParameter(`/${PROJECT_NAME}/${ENV}/app/records-api-url`); ``` #### IAM 权限 Terraform模块自动创建适当的IAM政策: - **管理 UI**: 阅读访问 `/app/admin-ui/*` 参数 - **找到兰布达**: 读取特定所需参数 - **最小权限**遵循最少特权原则 #### 从Terraform产出迁移 1. **部署参数存储模块** (列入v. 6.0+) 2. **更新应用程序代码** 读取参数存储器 3. **删除地形输出依赖性** 4. **实行灵活的配置管理** * * * ## QQ 阴影配置 ### 概览 阴影特性可以自动使所有字段的排序无需JSON配置文件. 配置完全通过环境变量管理. ### 环境变量 | 变量 | 默认 | 说明 | | --- | --- | --- | | `SHADOW_CREATED_AT_FIELD` | `createdAt` | 创建时间戳的字段名称 | | `SHADOW_UPDATED_AT_FIELD` | `updatedAt` | 更新时间戳的字段名称 | | `SHADOW_STRING_MAX_BYTES` | `100` | 原始类型的最大字节( 阵列/ 对象使用 2x) | | `SHADOW_NUMBER_PADDING` | `15` | 数字的位数 | ### 支持类型 - **字符串**: 字符串(以100字节运行) - **编号**:数字(抵消方法,范围:-10^15至+10^15) - **布尔**:布尔斯(真=1,假=0) - **约会时间**: ISO 8601 日期时间字符串 - **数组**: 阵列( JSON 字符串, 以 200 字节折出) - **对象**: 对象( JSON 字符串, 以 200 字节显示) ### 自动阴影生成 只有每个记录中存在的字段自动被阴影: ```typescript const record = { id: '01HQXYZ123', title: 'Article', viewCount: 123, published: true, tags: ['tech', 'aws'], metadata: { category: 'tech' }, }; // Automatically generates shadow records: // - title#Article#id#01HQXYZ123 // - viewCount#1000000000000123#id#01HQXYZ123 // - published#1#id#01HQXYZ123 // - tags#["aws","tech"]#id#01HQXYZ123 // - metadata#{"category":"tech"}#id#01HQXYZ123 // // Note: 'id' field does NOT generate a shadow record // Main record (SK = id#01HQXYZ123) is used for id-based sorting ``` ### 不适用规则 - **`id` 字段除外** - 主要记录`SK = id#{ULID}`)用于基于id的排序 - 从字段开始 `__` 不包括(内部元数据) - `null` 或者说 `undefined` 数值排除在外 ### 重要说明 - 没有具体字段的记录不会以某种结果出现 - 初级类型以100字节为切分,复杂类型以200字节为切分 - 数字范围为-10^15至+10^15(在JavaScript的安全整数范围内) * * * ## 成本跟踪 ### 概览 DynamoDB客户SDK为所有DynamoDB业务提供内置成本跟踪. 这个功能帮助您通过跟踪每个操作所消耗的读取容量单位(RCU)和写取容量单位(WCU)来监控和优化您的 DynamoDB 使用. ### 特征 - **自动跟踪**:所有业务自动包括消耗能力信息 - **合计费用**: 多个作业(多管、散装作业)自动汇总 - **零 间接**: 最小性能影响(小于5ms) - **类型安全**: 全类型脚本支持 `AggregatedCost` 类型 ### 用法实例 #### 单一业务 所有单一业务`insertOne`, (中文(简体) ), `updateOne`, (中文(简体) ), `deleteOne`返回消耗能力信息: ```typescript // Insert operation const result = await collection.insertOne({ title: 'New Article', content: 'Content here...', }); console.log('Inserted ID:', result.insertedId); console.log('Cost:', result.consumedCapacity); // Output: { totalRCU: 0, totalWCU: 1.0, operationCount: 1 } ``` ```typescript // Update operation const result = await collection.updateOne( { id: '01HQXYZ123' }, { $set: { title: 'Updated Title' } } ); console.log('Modified:', result.modifiedCount); console.log('Cost:', result.consumedCapacity); // Output: { totalRCU: 0.5, totalWCU: 1.0, operationCount: 1 } ``` ```typescript // Delete operation const result = await collection.deleteOne({ id: '01HQXYZ123' }); console.log('Deleted:', result.deletedCount); console.log('Cost:', result.consumedCapacity); // Output: { totalRCU: 0.5, totalWCU: 1.0, operationCount: 1 } ``` #### 散装操作 所有块的散装操作自动汇总成本 : ```typescript // Insert many documents const result = await collection.insertMany([ { title: 'Article 1', content: '...' }, { title: 'Article 2', content: '...' }, { title: 'Article 3', content: '...' }, // ... 100 documents ]); console.log('Inserted:', result.insertedCount); console.log('Cost:', result.consumedCapacity); // Output: { totalRCU: 0, totalWCU: 100.0, operationCount: 4 } // Note: 100 documents processed in 4 chunks (25 per chunk) ``` ```typescript // Update many documents const result = await collection.updateMany({ status: 'draft' }, { $set: { status: 'published' } }); console.log('Modified:', result.modifiedCount); console.log('Cost:', result.consumedCapacity); // Output: { totalRCU: 25.0, totalWCU: 50.0, operationCount: 10 } ``` #### 用 PGination 查找操作 查找所有页面的操作总成本 : ```typescript // Find with pagination const cursor = collection.find({ status: 'active' }).limit(100); const results = await cursor.toArray(); // Get aggregated cost for all pages const cost = await cursor.getConsumedCapacity(); console.log('Found:', results.length); console.log('Cost:', cost); // Output: { totalRCU: 15.5, totalWCU: 0, operationCount: 3 } // Note: 3 pages fetched to retrieve all results ``` ### 成本信息结构 这个 `consumedCapacity` 字段包含: ```typescript interface AggregatedCost { /** Total Read Capacity Units consumed */ totalRCU: number; /** Total Write Capacity Units consumed */ totalWCU: number; /** Number of DynamoDB operations performed */ operationCount: number; } ``` ### 成本优化提示 1. **监测高成本操作**操作 `totalRCU > 100` 或者说 `totalWCU > 50` 可能需要优化 2. **使用旁观**: 大结果集自动被分解以避免高成本 3. **批量操作**: 使用 `insertMany`, (中文(简体) ), `updateMany`, (中文(简体) ), `deleteMany` 用于大宗业务 4. **阴影记录**: 高效的分类,不昂贵的全球二级指数 ### 日志 所有业务的费用信息自动登录: ```typescript // Info log for normal operations logger.info('Operation completed', { operation: 'find', resource: 'articles', consumedCapacity: { totalRCU: 5.5, totalWCU: 0, operationCount: 2 }, }); // Warning log for high-cost operations logger.warn('High cost operation detected', { operation: 'updateMany', resource: 'articles', consumedCapacity: { totalRCU: 150.0, totalWCU: 200.0, operationCount: 50 }, }); ``` ### 后向兼容性 成本跟踪完全向后兼容 : - 现有代码工作不作修改 - `consumedCapacity` 可选字段 - 没有对现有 API 的中断更改 * * * ## 捐款 我们欢迎捐款! ### 发展 工作流量 1. 叉子存储器 2. 创建特性分支( E)`git checkout -b feature/amazing-feature`(中文(简体) ) 3. 提交更改( E)`git commit -m 'Add amazing feature'`(中文(简体) ) 4. 推向分行(`git push origin feature/amazing-feature`(中文(简体) ) 5. 打开拉请求 ### 准则 - 遵循现有的代码样式 - 添加新特性测试 - 视需要更新文件 - 提交前确保所有测试通过 ### OpenAPI 驱动开发 这个项目使用OpenAPI规格作为TypeScript类型定义的"真理单一源"(SSOT). #### 工作流程 1. **更新 OpenAPI 规格** ```bash # Edit the OpenAPI spec vim docs/specs/openapi.yaml ``` 2. **生成类型** ```bash # Regenerate TypeScript types from OpenAPI spec npm run generate-types ``` 3. **校验更改** ```bash # Build and test npm run build npm test ``` #### OpenAPI 规格 - **地点**数字 : `docs/specs/openapi.yaml` - **构成部分**数字 : `docs/specs/components/schemas/` - **产出**数字 : `src/__generated__/` (自动生成, 不手动编辑) * * * ## 许可证 这个项目根据麻省理工学院许可证颁发——见 [自由主义](https://npmcn.com/package/%40exabugs/dynamodb-client/LICENSE) 详细文件. * * * ## 承认 - 与 [用于 JavaScript 的 AWS SDK](https://aws.amazon.com/sdk-for-javascript/) - 灵感来自 [蒙戈DB](https://www.mongodb.com/) API 设计 - 电源 [类型脚本](https://www.typescriptlang.org/) * * * **[回到顶部](https://npmcn.com/package/%40exabugs/dynamodb-client/#readme--dynamodb-client-sdk)** 由 Q 制作 [调试](https://github.com/exabugs) ## 常见问题 ### @exabugs/dynamodb-client 是什么？ DynamoDB 单表客户端 SDK 有类似 MongoDB 的 API , Shadow Records , 以及 Lambda 用于没有服务器的应用程序 ### 如何安装 @exabugs/dynamodb-client？ 在项目目录运行 npm install @exabugs/dynamodb-client，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 dynamodb-admins、dynamodb-access-check、dynamodb-system-change，可以用 npx dynamodb-admins 直接运行。 ### @exabugs/dynamodb-client 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @exabugs/dynamodb-client 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @exabugs/dynamodb-client 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @exabugs/dynamodb-client 可以商用吗？ @exabugs/dynamodb-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @exabugs/dynamodb-client 的下载量有多少？ 根据 npm 官方下载统计，@exabugs/dynamodb-client 在 2026/10/14 – 2026/11/12 这 30 天内被下载 3,288 次，日均约 110 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @exabugs/dynamodb-client 还在维护吗？ 最新版本 1\.25\.1 发布于 2026/11/14（今天）；至今共发布 142 个版本，其中过去 12 个月发布了 142 个；首次发布于 2025/11/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。