REST API设计咨询：多租户下全量订单查询的端点方案选择

方案1：新增仅用于查询的端点/Orders #

• 优势：语义直观到没朋友，一看就知道是查所有订单，完全契合REST直接暴露资源的思路。筛选、排序直接用Query String传递就行，比如/Orders?status=paid&sort=createTime desc，都是开发者熟得不能再熟的用法，不用额外学习规则。
• 劣势：打破了原本租户→订单的层级关系，可能会让新人疑惑——为啥同时存在/Tenants/xxx/Orders和/Orders两个订单查询端点？不过权限校验逻辑和其他方案一致，都是确保只返回用户有权限查看的订单，这点不算大问题。
• 适用场景：如果业务里跨租户查订单的需求很频繁，且订单本身经常被当作独立资源操作，这个方案最省心。

方案2：自定义方法/Tenants:ListOrders #

• 优势：把查询操作和租户集合绑定得非常紧密，明确这是针对所有租户的订单查询动作，符合Google API设计风格里自定义动词的玩法。
• 劣势：纯REST派肯定会吐槽——REST讲究用HTTP方法作为动词，自定义方法属于偏离标准的做法。而且这个端点的语义不够直观，新人得额外记住这个特殊规则。
• 适用场景：只有当团队本身就采用Google API这类规范，且非要强绑定租户与订单查询的关系时，才考虑这个方案。

方案3：使用通配符/Tenants/-/Orders #

• 优势：完美延续了原有的层级结构，用-作为通配符表示“所有租户”，老用户不用重新适应新的API风格，学习成本极低。权限校验还能复用原有单租户订单查询的部分逻辑。
• 劣势：-作为通配符的含义必须团队内部统一共识，不然可能有人会误解成“某个租户ID是-”，未来如果要扩展其他通配符规则，也容易造成混乱。
• 适用场景：如果团队特别在意API结构的一致性，不想新增独立的订单端点，就选这个方案。

其他可选方案 #

• 多租户参数指定：新增/Tenants/Orders端点，用tenantIds参数传递多个租户ID，比如/Tenants/Orders?tenantIds=1,2,3，若不传该参数则返回用户有权限的所有租户订单。这种方式既保留了层级关系，又能灵活支持单租户、多租户、全租户的查询需求，兼容性拉满。
• 请求头传递上下文：不过这种方式不如Query参数直观，顶多作为补充方案，不建议作为主要实现方式。

最终建议 #

优先推荐方案1（/Orders），除非团队硬要维持严格的层级结构，再考虑方案3（/Tenants/-/Orders）。理由如下：

• /Orders的语义最清晰，完全符合开发者对REST API的直觉认知，上手零门槛；
• 筛选、排序的参数传递完全遵循通用规范，不用额外约定特殊规则；
• 权限校验在网关或业务层统一处理即可，和其他方案的实现复杂度相当，没有额外负担。

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