REST规范下批量查询用户信息的API设计方案咨询

方案1：优化GET请求参数（适合ID数量较少的场景） #

如果ID列表长度未超出多数服务器/客户端的URI限制（通常2KB-8KB），可以先通过参数优化压缩URI长度：

• 缩短参数名：用/users?ids=1,2,3,4替代/users?id=1,2,3,4，减少冗余字符
• 简化ID格式：对连续ID用范围表示（如ids=1-5,7），或对ID列表做Base64编码（注意可读性下降，需客户端/服务器额外处理）
• 分批次请求：将大ID列表拆分为多个小批量GET请求（比如每次查50个ID），虽增加请求次数，但严格符合GET「只读、幂等」的语义

若ID列表过长超出URI限制，可采用以下方案。

方案2：POST到语义明确的批量查询端点（适合ID数量大的场景） #

不必被「POST只能创建资源」的刻板认知束缚——HTTP方法的核心是语义清晰与幂等性/安全性，POST的本质是「让目标资源处理一个子请求」，并非只能用于创建。

可专门设计批量查询端点：

• 路径：POST /users/batch 或 POST /users/query
• 请求体：{"userIds": ["123", "456", "789"]}
• 响应：返回匹配的用户信息列表

该设计优势：

• 彻底规避URI长度限制，支持任意数量的ID
• 端点语义清晰，/users/batch明确指向批量查询操作，与POST /users（创建用户）的职责完全分离，无混淆风险
• 虽用POST，但查询操作不会修改服务器资源状态，保持了「安全」特性（且批量查询多次请求返回结果一致，实际具备幂等性）

方案3：需规避的不良实践 #

不要尝试用GET /users携带请求体传递ID列表——HTTP规范明确不推荐GET请求带请求体，多数客户端、代理服务器会忽略GET的请求体，导致功能异常。

• ID数量少、URI长度足够时，优先用方案1，严格遵循GET语义
• ID数量大时用方案2，兼顾技术可行性与API语义清晰度
• 绝对避免用POST /users做批量查询，这会与创建用户的接口职责冲突，造成API语义混乱

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