使用 Oak 和 Deno KV 构建完整 CRUD API 的指南

Deno KV 不仅是一个灵活的键值存储，还具备生产级数据库的特性，例如原子事务、一致性控制以及出色的性能。在本指南中，我们将通过一个示例，使用 Oak 框架和 Deno KV 构建一个功能完整的 CRUD API。

一. 数据库模型设计

我们将设计两个模型：

• 用户（User）：保存用户基本信息；
• 地址（Address）：每个用户可选关联一个地址。

二. 初始化项目并定义数据库逻辑

创建 db.ts 文件

在项目根目录创建 db.ts，用于存放数据库操作逻辑。

用户相关操作

1. 获取用户信息

async function getUserById(id: string) { ... }

• 使用主键前缀 user 与用户 ID 查询数据。

2. 通过电子邮件获取用户

• 使用辅助索引 user_by_email 将电子邮件映射到用户 ID；
• 先查询索引，再获取完整用户信息。

3. 更新用户信息

• 同时更新主键与辅助索引；
• 使用 Deno KV 的 kv.atomic() 保证数据一致性；
• 如果用户邮箱变化，需删除旧索引并创建新索引。

4. 获取所有用户

• 使用键迭代器枚举数据；
• 可使用 { limit: 50 } 分批获取，提高性能。

地址模型相关操作

1. 获取用户地址

async function getAddressByUser(userId: string) { ... }

• 数据存储在 user_address 前缀下。

2. 更新用户及地址

• 同时更新 user、user_by_email 和 user_address 键值对；
• 使用事务 kv.atomic() 确保原子性。

删除用户及其关联数据

async function deleteByUserId(userId: string) { ... }

• 删除主键、辅助索引及关联地址，实现完整 CRUD 功能。

三. 构建 API 路由

创建 main.ts 文件

使用 Oak 框架处理 HTTP 请求，主要路由包括：

• POST /users：添加新用户；
• GET /users：获取所有用户；
• GET /users/email/\:email：通过电子邮件获取用户；
• PUT /users：更新用户信息；
• DELETE /users/\:id：删除用户及关联数据；
• POST /users/\:id/address：添加用户地址；
• GET /users/\:id/address：获取用户地址。

四. 运行与测试 API

启动服务

deno run --allow-net --watch --unstable main.ts

测试示例

1. 添加用户

curl -X POST http://localhost:8000/users \
-H "Content-Type: application/json" \
-d '{"id": "1", "email": "andy@deno.com", "name": "安迪", "password": "12345"}'

2. 获取用户列表

访问 http://localhost:8000/users，返回 JSON 列表。

3. 通过电子邮件获取用户

访问 http://localhost:8000/users/email/andy@deno.com。

4. 为用户添加地址

curl -X POST http://localhost:8000/users/1/address \
-H "Content-Type: application/json" \
-d '{"city": "洛杉矶", "street": "主街"}'

5. 更新用户信息

curl -X PUT http://localhost:8000/users \
-H "Content-Type: application/json" \
-d '{"id": "1", "email": "andy@deno.com", "name": "更好的安迪", "password": "12345"}'

6. 删除用户

curl -X DELETE http://localhost:8000/users/1

五. 总结

通过本文示例，我们展示了如何使用 Oak 框架和 Deno KV 构建完整的 CRUD API：

• 简单易用：Deno KV 提供高性能键值存储；
• 事务支持：使用 kv.atomic() 保证操作原子性；
• 扩展性强：可轻松添加地址模型或其他业务模型。

本示例为构建有状态 API 提供了完整的实践参考，帮助开发者快速上手并维护高效数据服务。

原文链接: https://deno.com/blog/build-crud-api-oak-denokv