CouchDB JSON 结构参考大全：数据库、文档、变更流、复制与请求对象的完整字段速查手册

• 数据库
• 文档数据库
• 后端

导读

CouchDB 是一个以 HTTP/JSON API 为核心的文档型数据库，客户端与服务器之间几乎所有交互——读写文档、查询视图、拉取变更流、发起复制、运行展示函数——都通过 JSON 结构承载。本文以官方JSON Structure Reference附录为骨架，完整收录 CouchDB 中 22 种核心 JSON 对象的全部字段定义与语义说明，并结合本仓库源码（如 couch_db.erl 的get_db_info/1实现、couch_replicator_parse.erl 的复制参数解析逻辑）深入讲解字段背后的实际行为。读完本文，你将能够准确读懂 CouchDB 的各类 API 响应、正确构造文档与复制请求体、理解视图与展示函数的运行时对象模型，并避开常见字段误用陷阱。

数据库与视图的查询响应结构

所有数据库文档列表（All Database Documents）

当查询数据库的_all_docs端点或视图时，返回的顶层 JSON 结构如下：

该结构是分页遍历数据库与视图索引的基础：total_rows用于估算总量，offset与rows结合可实现键范围扫描。

视图头部信息（View Head Information）

当使用_view端点配合limit=0之类参数仅请求头部时，返回精简结构：

{ "total_rows": 42, "offset": 3 }

从源码结构看，total_rows/offset的语义由 B-tree 索引的折叠逻辑支撑（见 couch_btree.erl），视图查询通过 MapReduce 索引（couch_mrview）在查询时计算总行数与起始偏移。

文档读写相关的 JSON 结构

CouchDB 文档对象（CouchDB Document）

单条文档的最小结构，也是所有文档对象的公共骨架：

_id用于定位文档，_rev是 CouchDB 实现乐观并发控制（MVCC）的核心：每次更新必须携带当前_rev，否则请求会以冲突错误返回。

批量文档（Bulk Documents）

向_bulk_docs端点提交的请求体：

批量写入是高效导入数据的首选方式，每条子文档可携带各自的_id/_rev/_deleted，服务器逐条处理并在响应中回报结果。

批量文档响应（Bulk Document Response）

_bulk_docs返回的响应数组，每条结果对应请求中的一条文档：

成功时元素通常为{"id": ..., "ok": true, "rev": ...}形式；失败时则以error/reason形式返回错误详情（如conflict、forbidden）。

CouchDB 错误状态对象（CouchDB Error Status）

这是 CouchDB 错误响应的通用 JSON 形状，出现在文档读写、批量操作等各类失败场景中，客户端应优先解析error字段判断错误类别（如not_found、conflict、unauthorized）。

文档修订与附件结构

带详细修订信息的文档（Detailed Revision Info）

当以?revs_info=true查询文档时返回：

_revs_info数组中的status字段标识每条修订的状态（如available、missing、deleted），用于诊断修订树冲突与清理情况。

带修订历史的文档（Revision Info）

当以?revs=true查询文档时返回：

_revisions.start+ids组合起来即完整还原文档修订路径：start是最近修订的代数前缀，ids依序对应各代修订哈希，例如3-a..、2-b..、1-c..。

带附件的文档（写入时，Document with Attachments）

向服务器提交含附件的文档时使用：

带附件的文档（返回时，Returned Document with Attachments）

读取文档（如?attachments=true）时返回的附件结构：

写入时用data携带 Base64 内容；读取时通常返回stub/length/revpos元数据，配合?attachments=true才能取回实际data。revpos用于判定附件在哪个修订中被引入，是附件去重与增量同步的关键依据。

数据库信息与设计文档结构

CouchDB 数据库信息对象（Database Information Object）

GET /db返回的数据库元信息：

该对象的实际生成逻辑可在源码中验证：couch_db.erl 的get_db_info/1通过#db{}记录组装db_name、doc_count、doc_del_count、update_seq、purge_seq、compact_running、instance_start_time、disk_format_version、committed_update_seq等字段。需要特别注意的是，当前版本的实现返回的字段比本文档附录更丰富——还包含engine（存储引擎名）、sizes（含active/disk/external三个字节计数的对象）、compacted_seq、props与uuid，这些可由couch_db_engine:get_size_info/1、get_disk_version/1、get_props/1等调用支撑。因此实际响应中disk_size的语义已被sizes对象取代或并存，解析时建议优先读取sizes。

设计文档（Design Document）

设计文档是以_design/为前缀的特殊文档，定义视图与展示逻辑：

设计文档信息（Design Document Information）

GET /db/_design/ddoc/_info返回视图索引运行状态：

signature由视图定义哈希生成，是索引缓存失效判断的核心；updater_running、waiting_clients、waiting_commit则反映索引更新的实时调度状态，可配合监控索引健康度。

变更流与活动任务结构

数据库变更信息（Changes Information）

GET /db/_changes返回的变更流结构：

pending仅在非连续模式下有意义，表示当前响应之后还有多少未消费的变更；changes数组内的每个元素形如{"rev": "..."}，指明该序列点涉及的修订。连续模式（feed=continuous）下结果流式输出，last_seq用于记录断点以便从since_seq续传。

活动任务列表（List of Active Tasks）

GET /_active_tasks返回当前服务器运行的后台任务：

type标识任务类别（如database_compaction、view_compaction、replication、indexer），status提供可读的进度描述（如"Progress: 40%"），用于观测压缩、索引构建与复制等后台操作的实时状态。

复制相关 JSON 结构

复制设置（Replication Settings）

写入_replicator数据库或调用POST /_replicate时使用的复制请求体：

这些字段的解析与默认值可在 couch_replicator_parse.erl 中验证：default_options/0（第 47-59 行）给出checkpoint_interval默认 30000 毫秒、use_checkpoints默认true、use_bulk_get默认true；convert_options/1（第 338-395 行）则逐一校验各选项类型，例如create_target、winning_revs_only、use_bulk_get必须为布尔值，否则抛出bad_request异常。winning_revs_only的运行时效果可在 couch_replicator_changes_reader.erl 第 46 行 与 couch_replicator_ids.erl 第 115-121 行 看到：开启后会在变更流请求中附加winning_revs_only=true参数，仅拉取每个文档的获胜修订，减少复制流量。selector选项则直接对接 Mango 查询语法，由服务端在源端过滤，避免传输整份变更后再在客户端丢弃。

复制状态（Replication Status）

GET /db/_local/<rep-id>或复制文档状态中返回的结果结构：

history数组按时间倒序记录每次复制会话的统计，是排查复制吞吐与失败率的核心数据源；missing_checked/missing_found反映修订比对阶段的工作量，bulk_get_attempts/bulk_get_docs则量化_bulk_get批处理带来的效率收益。

视图与展示函数运行时对象

请求对象（Request Object）

展示函数（_show）、列表函数（_list）、更新函数（_update）接收的第一个参数即请求对象：

一个完整的请求对象示例（来自官方附录）：

{ "body": "undefined", "cookie": { "AuthSession": "cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw", "m": "3234" }, "form": {}, "headers": { "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8", "Accept-Charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3", "Accept-Encoding": "gzip,deflate,sdch", "Accept-Language": "en-US,en;q=0.8", "Connection": "keep-alive", "Cookie": "m=3234:t|3247:t|6493:t|6967:t|34e2:|18c3:t|2c69:t|5acb:t|ca3:t|c01:t|5e55:t|77cb:t|2a03:t|1d98:t|47ba:t|64b8:t|4a01:t; AuthSession=cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw", "Host": "127.0.0.1:5984", "User-Agent": "Mozilla/5.0 (Windows NT 5.2) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.75 Safari/535.7" }, "id": "foo", "info": { "committed_update_seq": 2701412, "compact_running": false, "db_name": "mailbox", "disk_format_version": 6, "doc_count": 2262757, "doc_del_count": 560, "instance_start_time": "1347601025628957", "purge_seq": 0, "sizes": { "active": 7580843252, "disk": 14325313673, "external": 7803423459 }, "update_seq": 2701412 }, "method": "GET", "path": [ "mailbox", "_design", "request", "_show", "dump", "foo" ], "peer": "127.0.0.1", "query": {}, "raw_path": "/mailbox/_design/request/_show/dump/foo", "requested_path": [ "mailbox", "_design", "request", "_show", "dump", "foo" ], "secObj": { "admins": { "names": [ "Bob" ], "roles": [] }, "members": { "names": [ "Mike", "Alice" ], "roles": [] } }, "userCtx": { "db": "mailbox", "name": "Mike", "roles": [ "user" ] }, "uuid": "3184f9d1ea934e1f81a24c71bde5c168" }

注意示例中info对象已体现出现代版本的字段扩展（如sizes对象），与上文get_db_info/1的实现相互印证。

精简请求对象（Request2 Object）

Request2是部分场景下的简化请求对象，字段为Request的子集：

与完整请求对象的差异在于：Request2不包含form、id、info、uuid字段，适用于不需要表单解析、文档定位或数据库元信息的轻量处理场景。

响应对象（Response Object）

展示/列表函数返回的响应对象：

官方附录对此结构给出两条重要告诫：

警告：body、base64与json三个键彼此重叠，后出现的键胜出（last one wins）。由于多数键值对象的实现不保留键顺序，混用时极易出现令人困惑的结果，尽量只使用其中一种。

注意：任何自定义属性都会使 CouchDB 抛出内部异常。此外，响应对象可以是一个简单字符串值，它会被隐式包装为{"body": ...}对象。

这意味着展示函数应严格遵守字段白名单：要么返回{code, body}，要么返回{json: obj}，要么直接返回字符串；混用body与json且依赖键序是不可靠的。

安全对象（Security Object）

数据库_security端点使用的权限结构：

{ "admins": { "names": [ "Bob" ], "roles": [] }, "members": { "names": [ "Mike", "Alice" ], "roles": [] } }

admins中的用户/角色可执行管理操作（包括修改安全对象本身），members中的用户/角色可读写普通文档。权限校验在 HTTP 层由 couch_httpd_auth.erl 等模块完成，解析secObj后结合用户上下文userCtx决定请求是否放行。

用户上下文对象（User Context Object）

请求对象中的userCtx结构，描述当前请求的认证上下文：

{ "db": "mailbox", "name": null, "roles": [ "_admin" ] }

未认证请求的name为null，匿名用户通常拥有_users角色；管理员用户的roles中会出现_admin。展示与列表函数常依赖userCtx实现基于角色的个性化输出（如按用户过滤可见字段）。

速查要点总结

1. 写文档必带_rev：更新已有文档时遗漏_rev将触发冲突；_bulk_docs批量场景同理。
2. 附件写入用data（Base64），读取看元数据：返回结构中的stub/length/revpos用于判断附件状态与所属修订。
3. 数据库信息以sizes对象为准：现代版本在disk_size之外返回sizes.active/disk/external，解析时优先使用（依据 couch_db.erl 的get_db_info/1）。
4. 复制参数有类型校验：create_target、winning_revs_only、use_bulk_get、use_checkpoints必须为布尔值，checkpoint_interval默认 30000ms（依据 couch_replicator_parse.erl）。
5. 响应对象三键互斥：json/body/base64只用一个，且不得添加自定义属性，否则触发内部异常。
6. query不支持多值键：重复键时后者覆盖前者，构造 URL 参数需自行避免。

掌握以上 JSON 结构的字段语义，即可准确解析 CouchDB 的一切 HTTP 响应、构造合规的请求体，并在展示函数、复制调度与权限设计中做出正确决策。各结构的字段定义原文位于仓库 src/docs/src/json-structure.rst，可随时对照查阅。

• 数据库
• 文档数据库
• 后端