数据库文档数据库后端【免费下载链接】couchdbSeamless multi-primary syncing database with an intuitive HTTP/JSON API, designed for reliability项目地址https://gitcode.com/gh_mirrors/co/couchdb点击查看免费下载导读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文档列表开始时的偏移量配合skip/startkey使用update_seq可选数据库当前的更新序列号rows[数组]文档对象数组每个元素描述一条文档该结构是分页遍历数据库与视图索引的基础total_rows用于估算总量offset与rows结合可实现键范围扫描。视图头部信息View Head Information当使用_view端点配合limit0之类参数仅请求头部时返回精简结构{ total_rows: 42, offset: 3 }字段说明total_rows视图中的文档总数offset文档列表开始时的偏移量从源码结构看total_rows/offset的语义由 B-tree 索引的折叠逻辑支撑见 couch_btree.erl视图查询通过 MapReduce 索引couch_mrview在查询时计算总行数与起始偏移。文档读写相关的 JSON 结构CouchDB 文档对象CouchDB Document单条文档的最小结构也是所有文档对象的公共骨架字段说明_id可选文档 ID_rev可选修订 ID更新已有文档时必须提供_id用于定位文档_rev是 CouchDB 实现乐观并发控制MVCC的核心每次更新必须携带当前_rev否则请求会以冲突错误返回。批量文档Bulk Documents向_bulk_docs端点提交的请求体字段说明docs[数组]批量文档数组每个元素是一条文档_id可选文档 ID_rev可选修订 ID更新已有文档时使用_deleted可选是否将文档标记为删除批量写入是高效导入数据的首选方式每条子文档可携带各自的_id/_rev/_deleted服务器逐条处理并在响应中回报结果。批量文档响应Bulk Document Response_bulk_docs返回的响应数组每条结果对应请求中的一条文档字段说明docs[数组]批量返回的文档对象id文档 IDerror错误类型reason附带详细原因的错误字符串成功时元素通常为{id: ..., ok: true, rev: ...}形式失败时则以error/reason形式返回错误详情如conflict、forbidden。CouchDB 错误状态对象CouchDB Error Status字段说明id文档 IDerror错误类型reason附带详细原因的错误字符串这是 CouchDB 错误响应的通用 JSON 形状出现在文档读写、批量操作等各类失败场景中客户端应优先解析error字段判断错误类别如not_found、conflict、unauthorized。文档修订与附件结构带详细修订信息的文档Detailed Revision Info当以?revs_infotrue查询文档时返回字段说明_id可选文档 ID_rev可选修订 ID_revs_info[数组]文档扩展修订信息rev完整修订字符串status修订状态_revs_info数组中的status字段标识每条修订的状态如available、missing、deleted用于诊断修订树冲突与清理情况。带修订历史的文档Revision Info当以?revstrue查询文档时返回字段说明_id可选文档 ID_rev可选修订 ID_revisions文档修订历史对象ids[数组]有效修订 ID 数组按逆序排列最新在前start最新修订的前缀编号_revisions.startids组合起来即完整还原文档修订路径start是最近修订的代数前缀ids依序对应各代修订哈希例如3-a..、2-b..、1-c..。带附件的文档写入时Document with Attachments向服务器提交含附件的文档时使用字段说明_id可选文档 ID_rev可选修订 ID_attachments可选文档附件对象filename附件信息以附件文件名为键content_typeMIME 内容类型字符串data附件内容Base64 编码带附件的文档返回时Returned Document with Attachments读取文档如?attachmentstrue时返回的附件结构字段说明_id可选文档 ID_rev可选修订 ID_attachments可选文档附件对象filename附件名称stub是否仅为附件存根stub布尔值content_typeMIME 内容类型字符串length附件数据长度字节revpos该附件存在的修订版本号写入时用data携带 Base64 内容读取时通常返回stub/length/revpos元数据配合?attachmentstrue才能取回实际data。revpos用于判定附件在哪个修订中被引入是附件去重与增量同步的关键依据。数据库信息与设计文档结构CouchDB 数据库信息对象Database Information ObjectGET /db返回的数据库元信息字段说明db_name数据库名称committed_update_seq已提交的更新数doc_count数据库中的文档数doc_del_count已删除文档数compact_running若数据库压缩例程正在运行则为truedisk_format_version数据落盘时使用的物理格式版本disk_size磁盘上数据的字节数不包含视图索引instance_start_time数据库打开时间戳自 epoch 以来的微秒数purge_seq数据库上的 purge 操作次数update_seq数据库当前的更新序列号该对象的实际生成逻辑可在源码中验证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/为前缀的特殊文档定义视图与展示逻辑字段说明_id设计文档 ID如_design/app_rev设计文档修订views视图对象viewname视图定义以视图名为键map视图的 Map 函数reduce可选视图的 Reduce 函数设计文档信息Design Document InformationGET /db/_design/ddoc/_info返回视图索引运行状态字段说明name设计文档名称/IDview_index视图索引compact_running视图压缩例程当前是否正在运行disk_size视图在磁盘上占用的字节数language视图定义所用的语言purge_seq已处理的 purge 序列signature设计文档视图的 MD5 签名update_seq已建立索引的对应数据库更新序列updater_running视图当前是否正在被更新waiting_clients等待该设计文档视图的客户端数量waiting_commit是否存在需要处理的对底层数据库的未完成提交signature由视图定义哈希生成是索引缓存失效判断的核心updater_running、waiting_clients、waiting_commit则反映索引更新的实时调度状态可配合监控索引健康度。变更流与活动任务结构数据库变更信息Changes InformationGET /db/_changes返回的变更流结构字段说明last_seq最后一次更新序列pending馈送中剩余条目的数量results[数组]对数据库做出的变更列表seq更新序列id文档 IDchanges[数组]该文档逐字段的变更列表pending仅在非连续模式下有意义表示当前响应之后还有多少未消费的变更changes数组内的每个元素形如{rev: ...}指明该序列点涉及的修订。连续模式feedcontinuous下结果流式输出last_seq用于记录断点以便从since_seq续传。活动任务列表List of Active TasksGET /_active_tasks返回当前服务器运行的后台任务字段说明tasks[数组]活动任务数组pid进程 IDstatus任务状态消息task任务名称type操作类型type标识任务类别如database_compaction、view_compaction、replication、indexerstatus提供可读的进度描述如Progress: 40%用于观测压缩、索引构建与复制等后台操作的实时状态。复制相关 JSON 结构复制设置Replication Settings写入_replicator数据库或调用POST /_replicate时使用的复制请求体字段说明source源数据库名称或 URLtarget目标数据库名称或 URLcancel可选取消复制checkpoint_interval可选检查点间隔毫秒continuous可选配置为连续复制create_target可选创建目标数据库doc_ids可选需同步的文档 ID 数组filter可选过滤器函数名称形式为ddoc/myfiltersource_proxy可选源复制应经过的代理服务器地址target_proxy可选目标复制应经过的代理服务器地址query_params可选传给过滤器函数的查询参数值为包含参数成员的文档selector可选选择复制中包含的文档与filter相比有性能优势since_seq可选复制开始的序列点use_checkpoints可选是否使用复制检查点winning_revs_only可选仅复制获胜修订use_bulk_get可选尝试使用_bulk_get获取修订这些字段的解析与默认值可在 couch_replicator_parse.erl 中验证default_options/0第 47-59 行给出checkpoint_interval默认 30000 毫秒、use_checkpoints默认true、use_bulk_get默认trueconvert_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_onlytrue参数仅拉取每个文档的获胜修订减少复制流量。selector选项则直接对接 Mango 查询语法由服务端在源端过滤避免传输整份变更后再在客户端丢弃。复制状态Replication StatusGET /db/_local/rep-id或复制文档状态中返回的结果结构字段说明ok复制状态session_id唯一会话 IDsource_last_seq从源数据库读到的最后一个序列号history[数组]复制历史session_id该次复制操作的会话 IDrecorded_seq最后记录的序列号docs_read读取的文档数docs_written写入目标的文档数doc_write_failures文档写入失败数start_time复制操作开始时间start_last_seq变更流中的第一个序列号end_time复制操作完成时间end_last_seq变更流中的最后一个序列号missing_checked已检查的缺失文档数missing_found发现的缺失文档数bulk_get_attempts尝试的_bulk_get获取次数bulk_get_docs通过_bulk_get读取的文档数history数组按时间倒序记录每次复制会话的统计是排查复制吞吐与失败率的核心数据源missing_checked/missing_found反映修订比对阶段的工作量bulk_get_attempts/bulk_get_docs则量化_bulk_get批处理带来的效率收益。视图与展示函数运行时对象请求对象Request Object展示函数_show、列表函数_list、更新函数_update接收的第一个参数即请求对象字段说明body请求体数据字符串。GET请求时值为undefinedDELETE或HEAD时值为空字符串cookieCookie 对象form表单数据对象。当Content-Type为application/x-www-form-urlencoded时包含解码后的键值对headers请求头对象id请求的文档 ID 字符串若指定否则为nullinfo数据库信息对象method请求方法字符串或数组。字符串为HEAD、GET、POST、PUT、DELETE、OPTIONS、TRACE之一否则表示为字符码数组path请求路径分段列表peer请求来源 IP 地址queryURL 查询参数对象。注意不支持多值键后出现的键值会覆盖先前的requested_path实际请求路径分段列表raw_path原始请求路径字符串secObj安全对象userCtx用户上下文对象uuid按配置文件中指定算法生成的 UUID一个完整的请求对象示例来自官方附录{ body: undefined, cookie: { AuthSession: cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw, m: 3234 }, form: {}, headers: { Accept: text/html,application/xhtmlxml,application/xml;q0.9,*/*;q0.8, Accept-Charset: ISO-8859-1,utf-8;q0.7,*;q0.3, Accept-Encoding: gzip,deflate,sdch, Accept-Language: en-US,en;q0.8, Connection: keep-alive, Cookie: m3234: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; AuthSessioncm9vdDo1MDZBRjQzRjrfcuikzPRfAn-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 ObjectRequest2是部分场景下的简化请求对象字段为Request的子集字段说明body请求体数据字符串取值规则同请求对象cookieCookie 对象headers请求头对象method请求方法字符串或数组path请求路径分段列表peer请求来源 IP 地址queryURL 查询参数对象不支持多值键requested_path实际请求路径分段列表raw_path原始请求路径字符串secObj安全对象userCtx用户上下文对象与完整请求对象的差异在于Request2不包含form、id、info、uuid字段适用于不需要表单解析、文档定位或数据库元信息的轻量处理场景。响应对象Response Object展示/列表函数返回的响应对象字段说明codeHTTP 状态码数字json可 JSON 编码的对象隐式将Content-Type头设为application/jsonbody原始响应文本字符串隐式将Content-Type头设为text/html; charsetutf-8base64Base64 编码字符串隐式将Content-Type头设为application/binaryheaders响应头对象其中的Content-Type会覆盖任何隐式分配的值stop布尔信号用于停止对视图结果行的迭代仅列表函数使用官方附录对此结构给出两条重要告诫警告body、base64与json三个键彼此重叠后出现的键胜出last one wins。由于多数键值对象的实现不保留键顺序混用时极易出现令人困惑的结果尽量只使用其中一种。注意任何自定义属性都会使 CouchDB 抛出内部异常。此外响应对象可以是一个简单字符串值它会被隐式包装为{body: ...}对象。这意味着展示函数应严格遵守字段白名单要么返回{code, body}要么返回{json: obj}要么直接返回字符串混用body与json且依赖键序是不可靠的。安全对象Security Object数据库_security端点使用的权限结构字段说明admins具有管理员权限的角色/用户roles[数组]具有父级权限的角色列表names[数组]具有父级权限的用户列表members具有非管理员权限的角色/用户roles[数组]具有父级权限的角色列表names[数组]具有父级权限的用户列表{ admins: { names: [ Bob ], roles: [] }, members: { names: [ Mike, Alice ], roles: [] } }admins中的用户/角色可执行管理操作包括修改安全对象本身members中的用户/角色可读写普通文档。权限校验在 HTTP 层由 couch_httpd_auth.erl 等模块完成解析secObj后结合用户上下文userCtx决定请求是否放行。用户上下文对象User Context Object请求对象中的userCtx结构描述当前请求的认证上下文字段说明db所提供操作上下文中的数据库名称name用户名roles用户角色列表{ db: mailbox, name: null, roles: [ _admin ] }未认证请求的name为null匿名用户通常拥有_users角色管理员用户的roles中会出现_admin。展示与列表函数常依赖userCtx实现基于角色的个性化输出如按用户过滤可见字段。速查要点总结写文档必带_rev更新已有文档时遗漏_rev将触发冲突_bulk_docs批量场景同理。附件写入用dataBase64读取看元数据返回结构中的stub/length/revpos用于判断附件状态与所属修订。数据库信息以sizes对象为准现代版本在disk_size之外返回sizes.active/disk/external解析时优先使用依据 couch_db.erl 的get_db_info/1。复制参数有类型校验create_target、winning_revs_only、use_bulk_get、use_checkpoints必须为布尔值checkpoint_interval默认 30000ms依据 couch_replicator_parse.erl。响应对象三键互斥json/body/base64只用一个且不得添加自定义属性否则触发内部异常。query不支持多值键重复键时后者覆盖前者构造 URL 参数需自行避免。掌握以上 JSON 结构的字段语义即可准确解析 CouchDB 的一切 HTTP 响应、构造合规的请求体并在展示函数、复制调度与权限设计中做出正确决策。各结构的字段定义原文位于仓库 src/docs/src/json-structure.rst可随时对照查阅。赞分享数据库文档数据库后端【免费下载链接】couchdbSeamless multi-primary syncing database with an intuitive HTTP/JSON API, designed for reliability项目地址https://gitcode.com/gh_mirrors/co/couchdb点击查看免费下载相关推荐CouchDB HTTP/JSON API 参考指南URL 结构、请求格式与状态码全解CouchDB HTTP/JSON API 参考指南URL 结构、请求格式与状态码全解 本文是 CouchDB 官方 API Reference 的深度导读数据库文档数据库后端landscape.yml 文件结构深度剖析云原生项目数据字段完全参考手册landscape.yml 文件结构深度剖析云原生项目数据字段完全参考手册 landscape.yml 是 CNCF 云原生交互景观图Interactive云原生Bottle 微框架 API 参考全局函数、请求/响应对象与核心数据结构全解析Bottle 微框架 API 参考全局函数、请求/响应对象与核心数据结构全解析 导读 本文是 Bottle 微框架 bottle.py https://li后端Web框架上一篇如何用Refly在5分钟内构建你的第一个AI代理技能下一篇Mantle性能优化指南让你的iOS应用加载速度提升40%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/9 4:48:58 · 阅读 1.2k CouchDB JSON 结构参考大全：数据库、文档、变更流、复制与请求对象的完整字段速查手册
数据库文档数据库后端【免费下载链接】couchdbSeamless multi-primary syncing database with an intuitive HTTP/JSON API, designed for reliability项目地址https://gitcode.com/gh_mirrors/co/couchdb点击查看免费下载导读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文档列表开始时的偏移量配合skip/startkey使用update_seq可选数据库当前的更新序列号rows[数组]文档对象数组每个元素描述一条文档该结构是分页遍历数据库与视图索引的基础total_rows用于估算总量offset与rows结合可实现键范围扫描。视图头部信息View Head Information当使用_view端点配合limit0之类参数仅请求头部时返回精简结构{ total_rows: 42, offset: 3 }字段说明total_rows视图中的文档总数offset文档列表开始时的偏移量从源码结构看total_rows/offset的语义由 B-tree 索引的折叠逻辑支撑见 couch_btree.erl视图查询通过 MapReduce 索引couch_mrview在查询时计算总行数与起始偏移。文档读写相关的 JSON 结构CouchDB 文档对象CouchDB Document单条文档的最小结构也是所有文档对象的公共骨架字段说明_id可选文档 ID_rev可选修订 ID更新已有文档时必须提供_id用于定位文档_rev是 CouchDB 实现乐观并发控制MVCC的核心每次更新必须携带当前_rev否则请求会以冲突错误返回。批量文档Bulk Documents向_bulk_docs端点提交的请求体字段说明docs[数组]批量文档数组每个元素是一条文档_id可选文档 ID_rev可选修订 ID更新已有文档时使用_deleted可选是否将文档标记为删除批量写入是高效导入数据的首选方式每条子文档可携带各自的_id/_rev/_deleted服务器逐条处理并在响应中回报结果。批量文档响应Bulk Document Response_bulk_docs返回的响应数组每条结果对应请求中的一条文档字段说明docs[数组]批量返回的文档对象id文档 IDerror错误类型reason附带详细原因的错误字符串成功时元素通常为{id: ..., ok: true, rev: ...}形式失败时则以error/reason形式返回错误详情如conflict、forbidden。CouchDB 错误状态对象CouchDB Error Status字段说明id文档 IDerror错误类型reason附带详细原因的错误字符串这是 CouchDB 错误响应的通用 JSON 形状出现在文档读写、批量操作等各类失败场景中客户端应优先解析error字段判断错误类别如not_found、conflict、unauthorized。文档修订与附件结构带详细修订信息的文档Detailed Revision Info当以?revs_infotrue查询文档时返回字段说明_id可选文档 ID_rev可选修订 ID_revs_info[数组]文档扩展修订信息rev完整修订字符串status修订状态_revs_info数组中的status字段标识每条修订的状态如available、missing、deleted用于诊断修订树冲突与清理情况。带修订历史的文档Revision Info当以?revstrue查询文档时返回字段说明_id可选文档 ID_rev可选修订 ID_revisions文档修订历史对象ids[数组]有效修订 ID 数组按逆序排列最新在前start最新修订的前缀编号_revisions.startids组合起来即完整还原文档修订路径start是最近修订的代数前缀ids依序对应各代修订哈希例如3-a..、2-b..、1-c..。带附件的文档写入时Document with Attachments向服务器提交含附件的文档时使用字段说明_id可选文档 ID_rev可选修订 ID_attachments可选文档附件对象filename附件信息以附件文件名为键content_typeMIME 内容类型字符串data附件内容Base64 编码带附件的文档返回时Returned Document with Attachments读取文档如?attachmentstrue时返回的附件结构字段说明_id可选文档 ID_rev可选修订 ID_attachments可选文档附件对象filename附件名称stub是否仅为附件存根stub布尔值content_typeMIME 内容类型字符串length附件数据长度字节revpos该附件存在的修订版本号写入时用data携带 Base64 内容读取时通常返回stub/length/revpos元数据配合?attachmentstrue才能取回实际data。revpos用于判定附件在哪个修订中被引入是附件去重与增量同步的关键依据。数据库信息与设计文档结构CouchDB 数据库信息对象Database Information ObjectGET /db返回的数据库元信息字段说明db_name数据库名称committed_update_seq已提交的更新数doc_count数据库中的文档数doc_del_count已删除文档数compact_running若数据库压缩例程正在运行则为truedisk_format_version数据落盘时使用的物理格式版本disk_size磁盘上数据的字节数不包含视图索引instance_start_time数据库打开时间戳自 epoch 以来的微秒数purge_seq数据库上的 purge 操作次数update_seq数据库当前的更新序列号该对象的实际生成逻辑可在源码中验证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/为前缀的特殊文档定义视图与展示逻辑字段说明_id设计文档 ID如_design/app_rev设计文档修订views视图对象viewname视图定义以视图名为键map视图的 Map 函数reduce可选视图的 Reduce 函数设计文档信息Design Document InformationGET /db/_design/ddoc/_info返回视图索引运行状态字段说明name设计文档名称/IDview_index视图索引compact_running视图压缩例程当前是否正在运行disk_size视图在磁盘上占用的字节数language视图定义所用的语言purge_seq已处理的 purge 序列signature设计文档视图的 MD5 签名update_seq已建立索引的对应数据库更新序列updater_running视图当前是否正在被更新waiting_clients等待该设计文档视图的客户端数量waiting_commit是否存在需要处理的对底层数据库的未完成提交signature由视图定义哈希生成是索引缓存失效判断的核心updater_running、waiting_clients、waiting_commit则反映索引更新的实时调度状态可配合监控索引健康度。变更流与活动任务结构数据库变更信息Changes InformationGET /db/_changes返回的变更流结构字段说明last_seq最后一次更新序列pending馈送中剩余条目的数量results[数组]对数据库做出的变更列表seq更新序列id文档 IDchanges[数组]该文档逐字段的变更列表pending仅在非连续模式下有意义表示当前响应之后还有多少未消费的变更changes数组内的每个元素形如{rev: ...}指明该序列点涉及的修订。连续模式feedcontinuous下结果流式输出last_seq用于记录断点以便从since_seq续传。活动任务列表List of Active TasksGET /_active_tasks返回当前服务器运行的后台任务字段说明tasks[数组]活动任务数组pid进程 IDstatus任务状态消息task任务名称type操作类型type标识任务类别如database_compaction、view_compaction、replication、indexerstatus提供可读的进度描述如Progress: 40%用于观测压缩、索引构建与复制等后台操作的实时状态。复制相关 JSON 结构复制设置Replication Settings写入_replicator数据库或调用POST /_replicate时使用的复制请求体字段说明source源数据库名称或 URLtarget目标数据库名称或 URLcancel可选取消复制checkpoint_interval可选检查点间隔毫秒continuous可选配置为连续复制create_target可选创建目标数据库doc_ids可选需同步的文档 ID 数组filter可选过滤器函数名称形式为ddoc/myfiltersource_proxy可选源复制应经过的代理服务器地址target_proxy可选目标复制应经过的代理服务器地址query_params可选传给过滤器函数的查询参数值为包含参数成员的文档selector可选选择复制中包含的文档与filter相比有性能优势since_seq可选复制开始的序列点use_checkpoints可选是否使用复制检查点winning_revs_only可选仅复制获胜修订use_bulk_get可选尝试使用_bulk_get获取修订这些字段的解析与默认值可在 couch_replicator_parse.erl 中验证default_options/0第 47-59 行给出checkpoint_interval默认 30000 毫秒、use_checkpoints默认true、use_bulk_get默认trueconvert_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_onlytrue参数仅拉取每个文档的获胜修订减少复制流量。selector选项则直接对接 Mango 查询语法由服务端在源端过滤避免传输整份变更后再在客户端丢弃。复制状态Replication StatusGET /db/_local/rep-id或复制文档状态中返回的结果结构字段说明ok复制状态session_id唯一会话 IDsource_last_seq从源数据库读到的最后一个序列号history[数组]复制历史session_id该次复制操作的会话 IDrecorded_seq最后记录的序列号docs_read读取的文档数docs_written写入目标的文档数doc_write_failures文档写入失败数start_time复制操作开始时间start_last_seq变更流中的第一个序列号end_time复制操作完成时间end_last_seq变更流中的最后一个序列号missing_checked已检查的缺失文档数missing_found发现的缺失文档数bulk_get_attempts尝试的_bulk_get获取次数bulk_get_docs通过_bulk_get读取的文档数history数组按时间倒序记录每次复制会话的统计是排查复制吞吐与失败率的核心数据源missing_checked/missing_found反映修订比对阶段的工作量bulk_get_attempts/bulk_get_docs则量化_bulk_get批处理带来的效率收益。视图与展示函数运行时对象请求对象Request Object展示函数_show、列表函数_list、更新函数_update接收的第一个参数即请求对象字段说明body请求体数据字符串。GET请求时值为undefinedDELETE或HEAD时值为空字符串cookieCookie 对象form表单数据对象。当Content-Type为application/x-www-form-urlencoded时包含解码后的键值对headers请求头对象id请求的文档 ID 字符串若指定否则为nullinfo数据库信息对象method请求方法字符串或数组。字符串为HEAD、GET、POST、PUT、DELETE、OPTIONS、TRACE之一否则表示为字符码数组path请求路径分段列表peer请求来源 IP 地址queryURL 查询参数对象。注意不支持多值键后出现的键值会覆盖先前的requested_path实际请求路径分段列表raw_path原始请求路径字符串secObj安全对象userCtx用户上下文对象uuid按配置文件中指定算法生成的 UUID一个完整的请求对象示例来自官方附录{ body: undefined, cookie: { AuthSession: cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw, m: 3234 }, form: {}, headers: { Accept: text/html,application/xhtmlxml,application/xml;q0.9,*/*;q0.8, Accept-Charset: ISO-8859-1,utf-8;q0.7,*;q0.3, Accept-Encoding: gzip,deflate,sdch, Accept-Language: en-US,en;q0.8, Connection: keep-alive, Cookie: m3234: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; AuthSessioncm9vdDo1MDZBRjQzRjrfcuikzPRfAn-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 ObjectRequest2是部分场景下的简化请求对象字段为Request的子集字段说明body请求体数据字符串取值规则同请求对象cookieCookie 对象headers请求头对象method请求方法字符串或数组path请求路径分段列表peer请求来源 IP 地址queryURL 查询参数对象不支持多值键requested_path实际请求路径分段列表raw_path原始请求路径字符串secObj安全对象userCtx用户上下文对象与完整请求对象的差异在于Request2不包含form、id、info、uuid字段适用于不需要表单解析、文档定位或数据库元信息的轻量处理场景。响应对象Response Object展示/列表函数返回的响应对象字段说明codeHTTP 状态码数字json可 JSON 编码的对象隐式将Content-Type头设为application/jsonbody原始响应文本字符串隐式将Content-Type头设为text/html; charsetutf-8base64Base64 编码字符串隐式将Content-Type头设为application/binaryheaders响应头对象其中的Content-Type会覆盖任何隐式分配的值stop布尔信号用于停止对视图结果行的迭代仅列表函数使用官方附录对此结构给出两条重要告诫警告body、base64与json三个键彼此重叠后出现的键胜出last one wins。由于多数键值对象的实现不保留键顺序混用时极易出现令人困惑的结果尽量只使用其中一种。注意任何自定义属性都会使 CouchDB 抛出内部异常。此外响应对象可以是一个简单字符串值它会被隐式包装为{body: ...}对象。这意味着展示函数应严格遵守字段白名单要么返回{code, body}要么返回{json: obj}要么直接返回字符串混用body与json且依赖键序是不可靠的。安全对象Security Object数据库_security端点使用的权限结构字段说明admins具有管理员权限的角色/用户roles[数组]具有父级权限的角色列表names[数组]具有父级权限的用户列表members具有非管理员权限的角色/用户roles[数组]具有父级权限的角色列表names[数组]具有父级权限的用户列表{ admins: { names: [ Bob ], roles: [] }, members: { names: [ Mike, Alice ], roles: [] } }admins中的用户/角色可执行管理操作包括修改安全对象本身members中的用户/角色可读写普通文档。权限校验在 HTTP 层由 couch_httpd_auth.erl 等模块完成解析secObj后结合用户上下文userCtx决定请求是否放行。用户上下文对象User Context Object请求对象中的userCtx结构描述当前请求的认证上下文字段说明db所提供操作上下文中的数据库名称name用户名roles用户角色列表{ db: mailbox, name: null, roles: [ _admin ] }未认证请求的name为null匿名用户通常拥有_users角色管理员用户的roles中会出现_admin。展示与列表函数常依赖userCtx实现基于角色的个性化输出如按用户过滤可见字段。速查要点总结写文档必带_rev更新已有文档时遗漏_rev将触发冲突_bulk_docs批量场景同理。附件写入用dataBase64读取看元数据返回结构中的stub/length/revpos用于判断附件状态与所属修订。数据库信息以sizes对象为准现代版本在disk_size之外返回sizes.active/disk/external解析时优先使用依据 couch_db.erl 的get_db_info/1。复制参数有类型校验create_target、winning_revs_only、use_bulk_get、use_checkpoints必须为布尔值checkpoint_interval默认 30000ms依据 couch_replicator_parse.erl。响应对象三键互斥json/body/base64只用一个且不得添加自定义属性否则触发内部异常。query不支持多值键重复键时后者覆盖前者构造 URL 参数需自行避免。掌握以上 JSON 结构的字段语义即可准确解析 CouchDB 的一切 HTTP 响应、构造合规的请求体并在展示函数、复制调度与权限设计中做出正确决策。各结构的字段定义原文位于仓库 src/docs/src/json-structure.rst可随时对照查阅。赞分享数据库文档数据库后端【免费下载链接】couchdbSeamless multi-primary syncing database with an intuitive HTTP/JSON API, designed for reliability项目地址https://gitcode.com/gh_mirrors/co/couchdb点击查看免费下载相关推荐CouchDB HTTP/JSON API 参考指南URL 结构、请求格式与状态码全解CouchDB HTTP/JSON API 参考指南URL 结构、请求格式与状态码全解 本文是 CouchDB 官方 API Reference 的深度导读数据库文档数据库后端landscape.yml 文件结构深度剖析云原生项目数据字段完全参考手册landscape.yml 文件结构深度剖析云原生项目数据字段完全参考手册 landscape.yml 是 CNCF 云原生交互景观图Interactive云原生Bottle 微框架 API 参考全局函数、请求/响应对象与核心数据结构全解析Bottle 微框架 API 参考全局函数、请求/响应对象与核心数据结构全解析 导读 本文是 Bottle 微框架 bottle.py https://li后端Web框架上一篇如何用Refly在5分钟内构建你的第一个AI代理技能下一篇Mantle性能优化指南让你的iOS应用加载速度提升40%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考