* 概览

DynamoDB 客户端 SDK 是一个TypeScript-First库,它为AWS DynamotB带来了类似MongoDB的简单. 它为现代的无服务器应用程序所建,它提供了一个熟悉的API,同时为最佳性能和成本效率而利用DynamoDB的单表设计模式.

为什么是迪纳摩DB客户SDK?

• * 熟悉的API: 使用 MongoDB 风格的查询, 并使用 DynamoDB 的力量
• 单表设计: 在不复杂的情况下优化数据模型
• QQ 阴影记录: 高效的分类,不昂贵的全球二级指数
• QQ 类型安全: 具有编译时间验证的完整类型脚本支持
• QQ 无服务器准备: AWS Lambda 以 ARM64 优化构建
• 管理UI: 内容管理的综合反应-管理员界面
• 基础设施: 完成用于生产部署的Terraform模块

适合构建可扩展的网络应用程序,内容管理系统,以及无服务器的API,这些API需要DynamoDB与MongoDB的开发者经验的性能.

* 特性

* 安装

# npm
npm install @exabugs/dynamodb-client

# pnpm (recommended)
pnpm add @exabugs/dynamodb-client

# yarn
yarn add @exabugs/dynamodb-client

建筑

graph TB
    subgraph "Client Applications"
        A[React Admin]
        B[Mobile App]
        C[Custom App]
    end

    subgraph "AWS Lambda"
        D[Lambda Function<br/>Function URL]
    end

    subgraph "AWS DynamoDB"
        E[(DynamoDB<br/>Single Table)]
    end

    A -->|HTTPS| D
    B -->|HTTPS| D
    C -->|HTTPS| D
    D -->|AWS SDK| E

    style A fill:#2563eb,stroke:#333,stroke-width:2px,color:#fff
    style B fill:#2563eb,stroke:#333,stroke-width:2px,color:#fff
    style C fill:#2563eb,stroke:#333,stroke-width:2px,color:#fff
    style D fill:#ff9900,stroke:#333,stroke-width:2px
    style E fill:#527fff,stroke:#333,stroke-width:2px

QQ 快速启动实例( E)

3个步骤开始: Schema定义 部署基础设施 使用客户端

完成示例项目

我们提供了一个完整的示范项目,展示所有特征:

👉 客户-实例 - 与React Admin一起全面收集实例

这个例子包括:

• * ** 完整类型脚本计划(文章、任务)
• 地面基础设施(迪纳摩DB、Lambda、Cognitto)
• QQ 使用认证重现管理 UI
• 用于高效排序的影子记录
• 生产准备配置
• QUICKSTART 分步骤指南

作为模板使用 为了自己的项目!

快速示例

// 1. Define your data types
interface Article {
  id: string;
  title: string;
  content: string;
  createdAt: string;
  updatedAt: string;
}

// 2. Deploy with Terraform (see dynamodb-client-example)
// terraform apply

// 3. Use the client
const client = new DynamoClient(FUNCTION_URL);
const articles = client.db().collection<Article>('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 (中文(简体) )
3. 自定义您的需要: 修改计划, 添加资源, 部署到 AWS

页:1

可用文档

• 建筑 - 系统结构和设计
• 客户端使用 - 客户端 API 指南
• 反应管理员集成 - 管理UI的设置和许多关系
• 授权安全设置( S) - aud 検証
• 疎な検索の警告と対応 - 検索を打ち切らず、警告(SPARSE SCAN) で気づいてインデックス・スキーマ・ロジックを見直す
• 记录 - Lambda QQ 记录 ()createRecordsClient 编号 : withCollection 编号 : lazyCollection(中文(简体) )
• 運用通知 {\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(中文(简体) )
• システム変更履歴 - インフラの変更・リリースを systemChanges {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}"黑" 兰布达"@exabugs/dynamodb-client/system-changes)),缩写为QQ CLI(dynamodb-system-change(中文(简体) )
• 管理者 - 说吧 admins 页:1@exabugs/dynamodb-client/admins) adminsResource* dynamodb-admins add。管理画面の日本語化は @exabugs/dynamodb-client/integrations/react-admin/i18n(单位:千美元)反应- admin- 整合. md(中文(简体) )
• 部署 - 生产部署指南
• 地形模块 - 基础设施作为代码

GitHub 动作

• GitHub 动作设置 - CI/CD配置
• 解决问题 - 共同问题和解决办法

发展

先决条件

• 节点.js >= 20.0.0
• npm, pnpm, 或纱线
• AWS账户(用于部署)

设置

# 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

可用命令

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

部署

使用示例项目

最简单的部署方法是使用 客户-实例 项目:

# Clone the example
git clone https://github.com/exabugs/dynamodb-client-example.git
cd dynamodb-client-example

make infra-apply

见 示例项目文档 详细部署指示.

配置管理

参数存储集成

库支持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数字 :

// 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 函数数字 :

// 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配置文件. 配置完全通过环境变量管理.

环境变量

支持类型

• 字符串: 字符串(以100字节运行)
• 编号:数字(抵消方法,范围:-10^15至+10^15)
• 布尔:布尔斯(真=1,假=0)
• 约会时间: ISO 8601 日期时间字符串
• 数组: 阵列( JSON 字符串, 以 200 字节折出)
• 对象: 对象( JSON 字符串, 以 200 字节显示)

自动阴影生成

只有每个记录中存在的字段自动被阴影:

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返回消耗能力信息:

// 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 }

// 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 }

// 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 }

散装操作

所有块的散装操作自动汇总成本 :

// 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)

// 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 查找操作

查找所有页面的操作总成本 :

// 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 字段包含:

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. 阴影记录: 高效的分类,不昂贵的全球二级指数

日志

所有业务的费用信息自动登录:

// 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 规格

   # Edit the OpenAPI spec
   vim docs/specs/openapi.yaml
   

2. 生成类型

   # Regenerate TypeScript types from OpenAPI spec
   npm run generate-types
   

3. 校验更改

   # Build and test
   npm run build
   npm test
   

OpenAPI 规格

• 地点数字 : docs/specs/openapi.yaml
• 构成部分数字 : docs/specs/components/schemas/
• 产出数字 : src/__generated__/ (自动生成, 不手动编辑)

许可证

这个项目根据麻省理工学院许可证颁发——见 自由主义 详细文件.

承认

• 与 用于 JavaScript 的 AWS SDK
• 灵感来自 蒙戈DB API 设计
• 电源 类型脚本