多属性查询的REST标准表示及Employee实体多场景查询的RESTful实现方案探讨

先来看大家已经达成共识的两个查询场景：

• 查询所有员工列表：/employee
• 查询指定ID的员工：/employee/{employee-id}

接下来重点聊聊多属性筛选的场景，也就是你提到的后两个查询需求：

1. 查询指定ID和姓名的员工
2. 查询指定ID、姓名且手机号开头符合要求的员工

你最初想到的方案是用查询参数（Query Parameters）来实现：

• 场景3：/employee/{employee-id}?name=abc
• 场景4：/employee/{employee-id}?name=abc&phoneNumber=123

而有人提出了另一种用路径参数（Path Parameters）的方案：

• 场景3：/employee/{employee-id}/{name}
• 场景4：/employee/{employee-id}/{name}/{phoneNumber}

两种方案的优劣分析 #

其实你的判断是对的，路径参数的方案确实违反了RESTful的核心设计原则：

• REST中，路径参数通常用来标识唯一的资源实例，而不是作为筛选条件。比如/employee/{employee-id}已经明确指向了一个特定的员工，再把name放进路径里，逻辑上就说不通——难道一个ID会对应多个同名员工？这不符合ID作为唯一标识的定义。
• 路径参数的扩展性极差：如果后续需要增加更多筛选条件（比如部门、入职日期），路径会变得冗长且难以维护，比如/employee/{id}/{name}/{phone}/{dept}，完全不符合REST的简洁性要求。
• 查询参数天生就是用来做筛选、过滤、排序这类操作的，它的语义更清晰，也更灵活：你可以轻松添加或移除筛选条件，而不需要修改资源的路径结构，同时也能让API的使用者一眼就明白这是在对资源进行过滤查询。

结论 #

所以你的初始方案才是更符合RESTful规范的最优实现：

• 用路径参数标识核心的唯一资源（这里就是employee-id）
• 用查询参数来传递额外的筛选条件（name、phoneNumber等）

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