CouchDB - 创建文档

CouchDB - 创建文档

文档是 CouchDB 的核心数据结构，数据以灵活的 JSON 对象形式存储。与关系数据库中的表不同，同一数据库中的文档无需共享相同的结构。

每个文档在其数据库中都需要一个唯一的 _id 字段。您有两种主要方法来创建文档：

• PUT 请求： 您自己指定 _id。当文档 ID 具有自然含义时（例如 user:jane.doe），这很有用。
• POST 请求： 您让 CouchDB 自动生成一个唯一的 ID (UUID)。这是最常见且推荐的方法，可以避免 ID 冲突。

使用 HTTP API (cURL) 创建文档

要创建文档，您需要向数据库端点发送 PUT 或 POST 请求，并在请求体中包含 JSON 数据。至关重要的是要将 Content-Type 头设置为 application/json。

示例 1：让 CouchDB 自动生成 ID (POST)

这是创建新文档的首选方法。我们将 JSON 对象 POST 到数据库的 URL。

$ curl -X POST http://127.0.0.1:5984/user_profiles -u admin:secret \
-H 'Content-Type: application/json' \
-d '{"name": "John Smith", "email": "john.smith@example.com", "plan": "premium", "registered_at": "2023-10-27T10:00:00Z"}'

{
    "ok": true,
    "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "rev": "1-a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4"
}

CouchDB 的响应包括：

• "ok": true：表示操作成功。
• "id"：CouchDB 为此新文档自动生成的唯一 ID。
• "rev"：文档的第一个修订版本 ID。此 _rev 令牌对于后续更新或删除文档至关重要，因为它是 CouchDB 实现乐观并发控制的机制。

示例 2：指定自己的 ID (PUT)

如果您需要定义特定的 ID，可以使用 PUT 请求并将 ID 包含在 URL 中。

$ curl -X PUT http://127.0.0.1:5984/user_profiles/user:jane.doe -u admin:secret \
-H 'Content-Type: application/json' \
-d '{"name": "Jane Doe", "email": "jane.doe@example.com", "plan": "free", "registered_at": "2023-10-27T11:30:00Z"}'

{
    "ok": true,
    "id": "user:jane.doe",
    "rev": "1-b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a1"
}

验证

您可以通过向文档的 URL 发送 GET 请求来检索文档，以验证其创建。

$ curl -X GET http://127.0.0.1:5984/user_profiles/user:jane.doe -u admin:secret

{
    "_id": "user:jane.doe",
    "_rev": "1-b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6a1",
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "plan": "free",
    "registered_at": "2023-10-27T11:30:00Z"
}

使用 Fauxton 创建文档

Fauxton 提供了一个方便的 JSON 编辑器，用于创建和修改文档。

• 在 Fauxton UI 中，点击左侧列表中的您想要添加文档的数据库（例如 user_profiles）。
• 点击顶部菜单栏中的 + 按钮，并选择 New Doc。
• 将出现一个编辑器，其中包含一个随机生成的 _id 模板。您可以保留此 ID，或将其替换为自定义字符串。
• 删除模板内容，并在编辑器区域中添加您自己的有效 JSON 数据。
• 点击右侧的 Create Document 按钮保存文档。

常见错误

一个常见错误是 Document update conflict（文档更新冲突）。如果您使用 PUT 请求，并且 _id 在数据库中已存在，就会发生此错误。创建现有文档的新版本是更新，而不是创建，需要您在 JSON 体中提供最新的 _rev 字段。我们将在后面的章节中介绍更新操作。