QMD 仓库 API 设计原则解析从 REST 七条准则到检索评测的实战验证【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd本指南以 test/eval-docs/api-design-principles.md 中沉淀的 REST API 设计原则为核心骨架系统梳理名词化 URL、复数资源、层级关系、过滤分页、版本化、错误处理与限流等七条准则并对照本仓库qmd一个全本地的迷你 CLI 搜索引擎的源码与评测体系说明这些文档在检索评测中的实际用途、如何把它们接入本地知识库以及如何借助 BM25 与语义检索验证 Agent 能否基于它们回答真实的 API 设计问题。读完本文你将既掌握一套可直接落地的 REST API 设计规范也理解规范文档如何成为可评测的语料这一完整闭环。一、文档定位这份 API 设计原则在仓库中的角色在 qmd 仓库中test/eval-docs/api-design-principles.md 并非普通的代码注释而是一份被专门用于检索评测的黄金语料。它位于test/eval-docs/目录与 distributed-systems-overview.md分布式系统、machine-learning-primer.md机器学习、remote-work-policy.md远程办公政策、startup-fundraising-memo.md融资备忘录等文档共同构成评测用文档集。从仓库结构看test/eval-docs目录在多个评测链路中被引用test/eval.test.ts 中通过evalDocsDir定位该目录将其中每份文档插入评测集合对应代码位置 test/eval.test.tstest/eval-bm25.test.ts 同样以eval-docs为插入目标test/eval-bm25.test.tstest/bench-guard.test.ts 使用eval-docs作为基准集合就绪性断言的对象如 test/bench-guard.test.tstest/eval-deep-research.ts 中的查询集直接引用api-design文档作为期望命中结果见下节。也就是说这份 API 设计原则文档在本仓库中扮演知识基准角色搜索引擎的检索质量、重排效果都以能否命中这份文档为衡量标准。这也是为什么理解它本身的内容与理解仓库评测机制同等重要。二、核心原则逐条拆解七条可落地的 REST 设计准则原文档正文完整地给出了七条设计原则以下是每条原则的完整展开与工程化注释。原则一用名词不用动词Use Nouns, Not VerbsURL 应当表示资源而非动作动作交给 HTTP 方法来表达。这是 REST 风格与 RPC 风格最直观的分界线。推荐写法GET /users/123 → 读取 123 号用户资源 POST /orders → 在 orders 集合中创建新订单 DELETE /products/456 → 删除 456 号产品资源应避免的写法GET /getUser?id123 POST /createOrder GET /deleteProduct/456工程化要点当 URL 中出现get、create、delete等动词时通常意味着动作语义被塞进了路径而 HTTP 方法GET/POST/PUT/DELETE/PATCH本就承担了动作表达。保持名词化还有助于路由配置、权限控制基于资源粒度与缓存层设计保持一致。原则二始终使用复数名词Use Plural Nouns为了一致性资源集合应统一用复数形式/users 而不是 /user /orders 而不是 /order /products 而不是 /product工程化要点复数约定消除了单数到底指集合还是指单个资源的歧义配合原则三的层级嵌套GET /users/123/orders与GET /users/123/orders/456能天然读作用户 123 的订单集合与用户 123 的某笔订单。复数集合 数字 ID 的路径模式也是 OpenAPI/Swagger 生态最常见的约定。原则三用 URL 层级表达资源关系Hierarchical Relationships通过 URL 层级表达从属/嵌套关系GET /users/123/orders → 获取用户 123 的全部订单 GET /users/123/orders/456 → 获取用户 123 的订单 456工程化要点层级结构适用于一对多强从属关系当关系变成多对多或资源间无强父子约束时文档原则四给出更合适的做法——用查询参数过滤而非无限加深路径。从源码结构看qmd 自身的 MCP 服务器同样使用层级化资源寻址文档通过qmd://URI 暴露见 src/mcp/server.ts与资源化寻址的思路一脉相承。原则四过滤与分页Filtering and Pagination过滤、排序、分页统一交给查询参数GET /products?categoryelectronicssortpricepage2limit20参数语义参考参数作用常见取值category按字段过滤业务枚举值sort指定排序字段price、-price降序page页码从 1 起1、2…limit每页条数常用10/20/50需设上限工程化要点分页参数务必设置上限并文档化排序字段应白名单化防止任意字段注入导致性能问题或信息泄露。pagelimit之外游标分页cursor-based在大数据集下更稳定但本原则文档以pagelimit为基线两种方案可依业务取舍。原则五版本化VersioningAPI 应当始终携带版本号本原则文档明确偏好 URL 版本化/v1/users /v2/users工程化要点URL 版本化/v1、/v2与 Header 版本化Accept: application/vnd.example.v1json各有取舍本规范选择前者理由是它直观、可缓存、便于在网关层按版本分流。实践中建议破坏性变更升大版本、向后兼容变更留在当前版本内并配合迁移窗口。原则六错误处理Error Handling返回一致的错误响应结构并配以恰当的 HTTP 状态码{ error: { code: VALIDATION_ERROR, message: Email format is invalid, field: email } }错误对象字段语义字段含义示例code机器可读的错误码便于客户端分支处理VALIDATION_ERROR、NOT_FOUND、RATE_LIMITEDmessage面向开发者的可读描述Email format is invalidfield出错字段校验类错误的定位信息email工程化要点code与 HTTP 状态码配合使用——状态码表达大类4xx 客户端错误/5xx 服务端错误code表达精确子类field字段让前端能直接把错误定位到表单控件。错误响应体结构一旦发布即成为对外契约务必与版本化策略绑定。原则七限流Rate Limiting实现限流并通过响应头告知客户端额度与重置时间X-RateLimit-Limit: 1000 # 窗口内允许的总请求数 X-RateLimit-Remaining: 999 # 窗口内剩余请求数 X-RateLimit-Reset: 1640000000 # 额度重置的 Unix 时间戳秒工程化要点这三个响应头Limit/Remaining/Reset已成为事实上的行业惯例客户端可以据此做本地退避而不是盲目重试配合429 Too Many Requests状态码与Retry-After头可构成完整的限流反馈闭环。文档末尾的结论强调最好的 API 是开发者无需阅读文档就能上手的 API——一致性、直觉化正是七条原则的共同目标。三、这些原则在本仓库中的实际价值作为检索评测的语义靶场上文反复强调这份文档在test/eval-docs/中的语料身份这里给出完整的实证链路。3.1 先决条件把 eval-docs 接入本地知识库要让评测运行需先把test/eval-docs注册为 qmd 集合文档只读此处仅说明操作方式qmd collection add test/eval-docs --name eval-docs qmd embed这两步的提示直接出现在 test/eval-deep-research.ts 与 test/eval-harness.ts 中评测脚本会先检查eval-docs集合是否存在不存在则输出上述命令并退出。3.2 评测查询集针对 api-design 的难题test/eval-deep-research.jsonl 中与本文档直接相关的查询有含行号行号查询期望命中难度说明L7how to structure URLs for our serviceapi-designhardREST 端点无精确关键词命中L18why URLs should be things not actionsapi-designhard名词而非动词的概念反转L24how to get user 123s purchasesapi-designhard层级 URL 的示例式提问注意这些查询的刻意设计与目标文档没有任何精确关键词重合notes字段明确标注 no exact match。例如why URLs should be things not actions与文档中的 Use Nouns, Not Verbs 需要语义等价理解才能建立关联——这正是 qmd 查询扩展与重排能力要解决的问题。3.3 评测机制BM25 基线 vs 深度研究链路test/eval-deep-research.ts 实现了双方法对比评测BM25 基线通过bun src/qmd.ts search ${query} -c eval-docs --json -n 5调用纯关键词检索test/eval-deep-research.ts深度研究链路通过bun src/qmd.ts query ${query} -c eval-docs --json -n 5触发查询扩展 → 重排的完整语义链路test/eval-deep-research.ts。评测统计 Hit1 / Hit3 / Hit5 三项指标即期望文档出现在前 1/3/5 条结果中的比例test/eval-deep-research.ts并以findRank定位期望文档的命中排名test/eval-deep-research.ts。运行方式bun test/eval-deep-research.ts而 test/eval-bm25.test.ts 则从另一角度验证即使没有语义扩展BM25 对eval-docs集合也能完成索引与检索其插入逻辑位于 test/eval-bm25.test.ts为对比提供基线参照。3.4 通用检索入口在命令行里问这份文档不依赖评测脚本也可以直接用 qmd CLI 检索这份原则文档# 建立集合首次 qmd collection add test/eval-docs --name eval-docs qmd embed # 关键词检索BM25 bun src/qmd.ts search how to get user 123s purchases -c eval-docs --json -n 5 # 语义检索查询扩展 重排 bun src/qmd.ts query why URLs should be things not actions -c eval-docs --json -n 5-c eval-docs指定集合--json输出结构化结果含file、score、title-n 5限制返回条数。这套 CLI 参数在评测脚本中与上述两条命令完全一致。四、延伸REST 原则与 qmd 架构的对应观察从源码结构看qmd 自身的对外接口设计也体现了资源化、一致性的思路可作为七条原则的仓库内印证资源寻址MCP 服务器将文档以qmd://URI 资源形式暴露并实现qmd://资源的模板化访问见 src/mcp/server.ts对应资源而非动作的资源化设计结构化响应搜索结果以统一结构返回docid、file、title、score、context、line、snippet等字段src/mcp/server.ts类似错误处理原则中一致响应结构的实践限制与防御仓库包含 src/mcp/origin-guard.ts来源校验是服务端防御性设计的一环与限流/错误处理所强调的服务端自我保护精神一致。需要说明的是以上是基于仓库现有结构的对应性观察并非文档声称 qmd 实现了某条 REST 原则——文档本身只是作为评测语料存在。五、结语规范文档如何成为可评测资产回到这份 api-design-principles.md它同时具备双重身份——对开发者是一份可直接落地的 REST 设计清单名词化 URL、复数资源、层级关系、查询参数过滤分页、URL 版本化、结构化错误、限流头对 qmd 仓库则是一份语义难度拉满的评测语料三条例证查询均无关键词重合强制依赖语义理解。七条原则最终指向同一目标——让 API 直觉化、一致化最好的 API 是开发者无需读文档就能上手的 API。而在本仓库中检验Agent 是否真的理解这份文档的方式同样朴素而严格构造无关键词重合的问题看检索链路能否把它找回来。这份文档因此成为规范 → 语料 → 评测 → 反哺闭环中的一环也是理解 qmd 检索与重排能力的绝佳起点。如需深入评测脚本见 test/eval-deep-research.ts 与 test/eval-bm25.test.ts查询集见 test/eval-deep-research.jsonl集合注册与状态检查见 test/eval-harness.ts 与 test/bench-guard.test.ts。【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QMD 仓库 API 设计原则解析：从 REST 七条准则到检索评测的实战验证
QMD 仓库 API 设计原则解析从 REST 七条准则到检索评测的实战验证【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd本指南以 test/eval-docs/api-design-principles.md 中沉淀的 REST API 设计原则为核心骨架系统梳理名词化 URL、复数资源、层级关系、过滤分页、版本化、错误处理与限流等七条准则并对照本仓库qmd一个全本地的迷你 CLI 搜索引擎的源码与评测体系说明这些文档在检索评测中的实际用途、如何把它们接入本地知识库以及如何借助 BM25 与语义检索验证 Agent 能否基于它们回答真实的 API 设计问题。读完本文你将既掌握一套可直接落地的 REST API 设计规范也理解规范文档如何成为可评测的语料这一完整闭环。一、文档定位这份 API 设计原则在仓库中的角色在 qmd 仓库中test/eval-docs/api-design-principles.md 并非普通的代码注释而是一份被专门用于检索评测的黄金语料。它位于test/eval-docs/目录与 distributed-systems-overview.md分布式系统、machine-learning-primer.md机器学习、remote-work-policy.md远程办公政策、startup-fundraising-memo.md融资备忘录等文档共同构成评测用文档集。从仓库结构看test/eval-docs目录在多个评测链路中被引用test/eval.test.ts 中通过evalDocsDir定位该目录将其中每份文档插入评测集合对应代码位置 test/eval.test.tstest/eval-bm25.test.ts 同样以eval-docs为插入目标test/eval-bm25.test.tstest/bench-guard.test.ts 使用eval-docs作为基准集合就绪性断言的对象如 test/bench-guard.test.tstest/eval-deep-research.ts 中的查询集直接引用api-design文档作为期望命中结果见下节。也就是说这份 API 设计原则文档在本仓库中扮演知识基准角色搜索引擎的检索质量、重排效果都以能否命中这份文档为衡量标准。这也是为什么理解它本身的内容与理解仓库评测机制同等重要。二、核心原则逐条拆解七条可落地的 REST 设计准则原文档正文完整地给出了七条设计原则以下是每条原则的完整展开与工程化注释。原则一用名词不用动词Use Nouns, Not VerbsURL 应当表示资源而非动作动作交给 HTTP 方法来表达。这是 REST 风格与 RPC 风格最直观的分界线。推荐写法GET /users/123 → 读取 123 号用户资源 POST /orders → 在 orders 集合中创建新订单 DELETE /products/456 → 删除 456 号产品资源应避免的写法GET /getUser?id123 POST /createOrder GET /deleteProduct/456工程化要点当 URL 中出现get、create、delete等动词时通常意味着动作语义被塞进了路径而 HTTP 方法GET/POST/PUT/DELETE/PATCH本就承担了动作表达。保持名词化还有助于路由配置、权限控制基于资源粒度与缓存层设计保持一致。原则二始终使用复数名词Use Plural Nouns为了一致性资源集合应统一用复数形式/users 而不是 /user /orders 而不是 /order /products 而不是 /product工程化要点复数约定消除了单数到底指集合还是指单个资源的歧义配合原则三的层级嵌套GET /users/123/orders与GET /users/123/orders/456能天然读作用户 123 的订单集合与用户 123 的某笔订单。复数集合 数字 ID 的路径模式也是 OpenAPI/Swagger 生态最常见的约定。原则三用 URL 层级表达资源关系Hierarchical Relationships通过 URL 层级表达从属/嵌套关系GET /users/123/orders → 获取用户 123 的全部订单 GET /users/123/orders/456 → 获取用户 123 的订单 456工程化要点层级结构适用于一对多强从属关系当关系变成多对多或资源间无强父子约束时文档原则四给出更合适的做法——用查询参数过滤而非无限加深路径。从源码结构看qmd 自身的 MCP 服务器同样使用层级化资源寻址文档通过qmd://URI 暴露见 src/mcp/server.ts与资源化寻址的思路一脉相承。原则四过滤与分页Filtering and Pagination过滤、排序、分页统一交给查询参数GET /products?categoryelectronicssortpricepage2limit20参数语义参考参数作用常见取值category按字段过滤业务枚举值sort指定排序字段price、-price降序page页码从 1 起1、2…limit每页条数常用10/20/50需设上限工程化要点分页参数务必设置上限并文档化排序字段应白名单化防止任意字段注入导致性能问题或信息泄露。pagelimit之外游标分页cursor-based在大数据集下更稳定但本原则文档以pagelimit为基线两种方案可依业务取舍。原则五版本化VersioningAPI 应当始终携带版本号本原则文档明确偏好 URL 版本化/v1/users /v2/users工程化要点URL 版本化/v1、/v2与 Header 版本化Accept: application/vnd.example.v1json各有取舍本规范选择前者理由是它直观、可缓存、便于在网关层按版本分流。实践中建议破坏性变更升大版本、向后兼容变更留在当前版本内并配合迁移窗口。原则六错误处理Error Handling返回一致的错误响应结构并配以恰当的 HTTP 状态码{ error: { code: VALIDATION_ERROR, message: Email format is invalid, field: email } }错误对象字段语义字段含义示例code机器可读的错误码便于客户端分支处理VALIDATION_ERROR、NOT_FOUND、RATE_LIMITEDmessage面向开发者的可读描述Email format is invalidfield出错字段校验类错误的定位信息email工程化要点code与 HTTP 状态码配合使用——状态码表达大类4xx 客户端错误/5xx 服务端错误code表达精确子类field字段让前端能直接把错误定位到表单控件。错误响应体结构一旦发布即成为对外契约务必与版本化策略绑定。原则七限流Rate Limiting实现限流并通过响应头告知客户端额度与重置时间X-RateLimit-Limit: 1000 # 窗口内允许的总请求数 X-RateLimit-Remaining: 999 # 窗口内剩余请求数 X-RateLimit-Reset: 1640000000 # 额度重置的 Unix 时间戳秒工程化要点这三个响应头Limit/Remaining/Reset已成为事实上的行业惯例客户端可以据此做本地退避而不是盲目重试配合429 Too Many Requests状态码与Retry-After头可构成完整的限流反馈闭环。文档末尾的结论强调最好的 API 是开发者无需阅读文档就能上手的 API——一致性、直觉化正是七条原则的共同目标。三、这些原则在本仓库中的实际价值作为检索评测的语义靶场上文反复强调这份文档在test/eval-docs/中的语料身份这里给出完整的实证链路。3.1 先决条件把 eval-docs 接入本地知识库要让评测运行需先把test/eval-docs注册为 qmd 集合文档只读此处仅说明操作方式qmd collection add test/eval-docs --name eval-docs qmd embed这两步的提示直接出现在 test/eval-deep-research.ts 与 test/eval-harness.ts 中评测脚本会先检查eval-docs集合是否存在不存在则输出上述命令并退出。3.2 评测查询集针对 api-design 的难题test/eval-deep-research.jsonl 中与本文档直接相关的查询有含行号行号查询期望命中难度说明L7how to structure URLs for our serviceapi-designhardREST 端点无精确关键词命中L18why URLs should be things not actionsapi-designhard名词而非动词的概念反转L24how to get user 123s purchasesapi-designhard层级 URL 的示例式提问注意这些查询的刻意设计与目标文档没有任何精确关键词重合notes字段明确标注 no exact match。例如why URLs should be things not actions与文档中的 Use Nouns, Not Verbs 需要语义等价理解才能建立关联——这正是 qmd 查询扩展与重排能力要解决的问题。3.3 评测机制BM25 基线 vs 深度研究链路test/eval-deep-research.ts 实现了双方法对比评测BM25 基线通过bun src/qmd.ts search ${query} -c eval-docs --json -n 5调用纯关键词检索test/eval-deep-research.ts深度研究链路通过bun src/qmd.ts query ${query} -c eval-docs --json -n 5触发查询扩展 → 重排的完整语义链路test/eval-deep-research.ts。评测统计 Hit1 / Hit3 / Hit5 三项指标即期望文档出现在前 1/3/5 条结果中的比例test/eval-deep-research.ts并以findRank定位期望文档的命中排名test/eval-deep-research.ts。运行方式bun test/eval-deep-research.ts而 test/eval-bm25.test.ts 则从另一角度验证即使没有语义扩展BM25 对eval-docs集合也能完成索引与检索其插入逻辑位于 test/eval-bm25.test.ts为对比提供基线参照。3.4 通用检索入口在命令行里问这份文档不依赖评测脚本也可以直接用 qmd CLI 检索这份原则文档# 建立集合首次 qmd collection add test/eval-docs --name eval-docs qmd embed # 关键词检索BM25 bun src/qmd.ts search how to get user 123s purchases -c eval-docs --json -n 5 # 语义检索查询扩展 重排 bun src/qmd.ts query why URLs should be things not actions -c eval-docs --json -n 5-c eval-docs指定集合--json输出结构化结果含file、score、title-n 5限制返回条数。这套 CLI 参数在评测脚本中与上述两条命令完全一致。四、延伸REST 原则与 qmd 架构的对应观察从源码结构看qmd 自身的对外接口设计也体现了资源化、一致性的思路可作为七条原则的仓库内印证资源寻址MCP 服务器将文档以qmd://URI 资源形式暴露并实现qmd://资源的模板化访问见 src/mcp/server.ts对应资源而非动作的资源化设计结构化响应搜索结果以统一结构返回docid、file、title、score、context、line、snippet等字段src/mcp/server.ts类似错误处理原则中一致响应结构的实践限制与防御仓库包含 src/mcp/origin-guard.ts来源校验是服务端防御性设计的一环与限流/错误处理所强调的服务端自我保护精神一致。需要说明的是以上是基于仓库现有结构的对应性观察并非文档声称 qmd 实现了某条 REST 原则——文档本身只是作为评测语料存在。五、结语规范文档如何成为可评测资产回到这份 api-design-principles.md它同时具备双重身份——对开发者是一份可直接落地的 REST 设计清单名词化 URL、复数资源、层级关系、查询参数过滤分页、URL 版本化、结构化错误、限流头对 qmd 仓库则是一份语义难度拉满的评测语料三条例证查询均无关键词重合强制依赖语义理解。七条原则最终指向同一目标——让 API 直觉化、一致化最好的 API 是开发者无需读文档就能上手的 API。而在本仓库中检验Agent 是否真的理解这份文档的方式同样朴素而严格构造无关键词重合的问题看检索链路能否把它找回来。这份文档因此成为规范 → 语料 → 评测 → 反哺闭环中的一环也是理解 qmd 检索与重排能力的绝佳起点。如需深入评测脚本见 test/eval-deep-research.ts 与 test/eval-bm25.test.ts查询集见 test/eval-deep-research.jsonl集合注册与状态检查见 test/eval-harness.ts 与 test/bench-guard.test.ts。【免费下载链接】qmdmini cli search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current sota approaches while being all local项目地址: https://gitcode.com/GitHub_Trending/qmd1/qmd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考