REST API设计：自定义与规范标识符路由命名方案咨询

首先直接给方案优先级排序：复用带查询参数的列表接口 > 兼容单资源路径自动识别参数类型 > 3.b方案 > 3.a方案，具体判断依据如下：

• 3.a方案 GET /api/students/find-by-custom-property/{customId} 确实不符合REST设计规范，你的判断完全正确。REST路径的核心作用是标识资源，而非描述操作动作，find-by-xxx属于典型的动词式操作描述，不应该出现在资源路径中。
• 3.b方案 GET /api/students/custom-property/{customId} 虽然去掉了动词，但依然存在语义缺陷：custom-property是学生资源的属性，而非独立存在的资源层级，这种设计会导致后续每新增一个唯一查询属性，就要新增一层路径段，造成接口路径冗余膨胀，也不符合资源定位的逻辑。
• 你之前顾虑的查询参数方案 GET /api/students?customId=test 完全可以满足业务需求，不存在所谓“必须返回集合”的REST强制要求：
  REST从来没有规定带查询参数的接口只能返回集合类型，返回结构只需要和查询条件的匹配逻辑对齐即可：由于customId是学生的全局唯一属性，你可以在接口逻辑中做明确约定：
  • 传入customId参数查询时，若未匹配到对应学生，返回404状态码
  • 若恰好匹配到1个学生，直接返回单个学生资源结构（或单元素集合，只要团队统一约定、文档写清楚即可，两种实现都有大量工业界落地案例）
  • 只有传入非唯一属性做筛选、命中多条结果时，才返回多元素集合
• 如果你不想在列表接口里做单/多结果的分支判断，还有一个更符合REST资源定位语义的通用实践：直接复用单资源接口GET /api/students/{id}，在接口内部自动识别传入的路径参数是规范主键ID，还是自定义友好属性值，自动匹配对应的查询逻辑即可。这种设计不需要新增额外路径，用户侧感知最流畅，也是GitHub、Stripe等成熟公开API的常用做法——比如GitHub的用户接口/users/{identifier}，既支持传入用户的数字主键ID，也支持传入用户唯一的登录名，不需要为不同标识设计不同路径。

额外提示：如果你担心内部自动识别参数类型会增加逻辑复杂度，非要把两种标识的查询路径做明确区分，也不建议用属性名做路径段，这种设计的扩展性极差。

内容的提问来源于stack exchange，提问作者Tiago Aleff da Silva