RESTful API路径参数与查询参数使用对比及设计实践合规性咨询

首先明确核心判定前提：你当前的设计属于RPC风格接口设计，而非行业通用的REST风格设计，是否违反最佳实践完全取决于你宣称的接口风格和实际使用场景：

一、和REST最佳实践的差异 #

REST风格的核心约定是资源导向，要求用URL定位资源、HTTP方法（GET/POST/PUT/DELETE）定义操作，常规最优设计为：

• 用路径参数定位唯一资源：GET /users/{id} 直接代表id为指定值的用户资源
• 用查询参数做过滤、排序等非定位类操作：GET /users?name=xxx 代表按名称筛选用户集合
• 路径中不出现getbyid这类动作描述，动作完全由HTTP方法承载

对照来看，你的设计将动作写入URL、全部参数走查询参数的逻辑，完全不符合REST的行业最佳实践，如果你对外宣称接口是REST风格，那这种设计是需要修正的。

二、该设计的合理性边界 #

如果你们团队内部统一采用RPC风格的接口约定，没有对外提供开放API的需求，那这种设计属于可接受的选择，它有自己的适用优势：

• 接口功能和路径一一对应，排查问题时无需额外判断参数逻辑，快速定位接口
• 单接口参数规则固定，不需要处理同一个路径下多类参数的校验适配逻辑，适合小团队快速开发

但你需要注意它的潜在问题，出现以下情况时建议修正：

• 接口数量持续膨胀：同个资源的查询维度每增加一个就要新增一个接口，后续维护成本会快速上升，完全可以合并为/users接口，通过id/name/uid不同查询参数实现多维度查询
• 需要对接外部开发者：不符合通用接口设计认知，对接方需要额外记忆每个接口的规则，对接效率极低
• 需要利用HTTP缓存能力：查询参数默认不会被浏览器、CDN缓存，路径参数的资源缓存逻辑更通用，高并发场景下性能差异明显

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