构造携带多个文档ID的REST API调用实现方案咨询

现有原始接口 #

http://localhost:9033/api/v1/myapi/account/123456/collection/COLL12345

两种方案都可落地，没有绝对的对错，只需要根据业务场景选择即可：

完全可行，属于GET请求传递数组参数的通用实现，几乎所有主流后端Web框架都原生支持解析，不需要额外开发特殊解析逻辑。
常见的两种传参格式：

• 重复同名参数：直接在Query部分重复拼接文档ID参数，示例：
  http://localhost:9033/api/v1/myapi/account/123456/collection/COLL12345?docId=DOC001&docId=DOC002&docId=DOC003
• 带方括号标识的参数：部分框架默认适配这种数组标记格式，示例：
  http://localhost:9033/api/v1/myapi/account/123456/collection/COLL12345?docId[]=DOC001&docId[]=DOC002&docId[]=DOC003

适用边界：适合单次传的文档ID数量少的场景——一般全URL长度控制在2048字符以内（主流浏览器、网关的默认长度阈值），换算成短ID大概支持几十到上百个。GET请求天然支持缓存、可被直接收藏为书签，语义上匹配「查询获取资源」的操作，更符合RESTful设计惯例。

同样可行，不存在规范层面的问题。
实现方式：请求头设置Content-Type: application/json，直接在请求体里放ID数组即可，示例：

{
  "docIds": ["DOC001", "DOC002", "DOC003"]
}

适用边界：适合两种场景：一是单次传递的文档ID数量很大（几百上千个），会超出URL长度限制；二是接口后续需要扩展传递复杂结构化参数（比如自定义过滤规则、批量操作的配置项）。要注意POST请求默认不会被CDN、客户端缓存，如果接口是纯查询类逻辑，选POST会丢失GET自带的缓存优势。

• 如果接口是做查询操作（比如获取指定ID的文档详情、列表），ID数量不多，优先选保留GET的URL传参方案。
• 如果接口是做批量操作（比如批量导出、批量修改、批量删除文档），或者ID量级很大，优先选POST请求体传参的方案。

内容的提问来源于stack exchange，提问作者runnerpaul