REST架构中，何时拆分带模式的GET请求为两个独立请求？

这是个非常典型的REST资源建模问题，核心得回到资源的本质定义和接口的可维护性、语义清晰度上来。以下几种场景下，我强烈建议把GET /customers?mode={type}拆成两个独立的GET端点（比如GET /customers/employees和GET /customers/owners）：

• 当两种模式对应完全不同的资源类型时
  你提到employee和owner的业务逻辑、返回字段差异明显（owner仅含姓名，employee额外带护照ID），这其实已经说明它们是两类具备不同业务属性的实体。如果用mode参数，会模糊资源的边界——REST的核心是“资源导向”，每个端点应该对应明确的资源集合。拆分后，接口语义更直观，开发者一眼就能知道/customers/employees是获取雇员客户，/customers/owners是获取业主客户，而非同一资源的不同视图。同时，拆分后也能更清晰地维护各自的返回结构，避免在同一个接口里写大量条件判断来组装响应数据。

• 当权限控制逻辑差异显著时
  既然访问两类客户的权限集合不同，比如只有HR系统能查看employee的敏感信息，而店铺管理员仅能访问owner数据，那么单接口的权限校验会变得复杂：你需要在接口内部根据mode参数分支处理权限逻辑，容易出现疏漏或bug。拆分后，可以直接给两个端点配置独立的权限规则（比如在网关层做路由权限拦截，或者在业务层用注解指定权限），权限管控更精准，代码也更易维护。

• 当接口的扩展性需求较高时
  假设未来要给雇员接口新增departmentId、hireDate这类专属查询参数，给业主接口新增storeId、registrationDate参数，单接口的话你需要处理大量可选参数的兼容性，还要判断哪些参数仅适用于特定mode，代码会快速臃肿。拆分后，每个端点可以独立扩展参数、返回结构，甚至做版本迭代（比如GET /customers/employees/v2），互不影响，迭代效率更高。

• 当客户端的使用场景完全分离时
  如果调用雇员列表的都是HR系统，调用业主列表的都是店铺管理系统，拆分接口能让客户端更直观地选择对应端点，无需额外处理mode参数。在API文档（如Swagger）中，独立的端点也更容易被开发者理解和使用，减少沟通成本。

例外情况：无需拆分的场景 #

如果两种模式只是同一资源的不同视图（比如只是返回字段的精简版和完整版，且权限逻辑完全一致），那用mode参数是合理的。比如GET /customers?mode=simple返回基础信息，mode=detail返回完整信息，这种情况下没必要拆分。

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