Customer资源REST API非CRUD操作URI设计及参数化方案咨询

原有方案的问题 #

你设计的/apiv1/customers/fetch-top-5这类带操作名的端点不符合REST面向资源的设计规范，本质是RPC风格的实现，存在两个明显缺陷：

• 端点会随着业务需求增加不断膨胀，后续如果要加按消费频次排名、按地区筛选排名等需求，需要新增大量端点，维护成本极高
• 无法灵活支持参数化查询，前5、前10、前20就要对应多个端点，复用性很差

推荐设计方案 #

直接复用你已经定义的GET /apiv1/customers/集合资源端点，通过查询参数实现排序、返回条数限制等需求，不需要新增任何独立端点，完全满足你当前的所有场景：

各场景具体URI示例 #

• 查询按支付金额排序的前5名客户：
  GET /apiv1/customers?sort=payment_amount:desc&limit=5
• 查询最近新增的3名客户：
  GET /apiv1/customers?sort=created_at:desc&limit=3
• 参数化top-n客户查询（n可自定义，比如查前10名按支付金额排序的客户）：
  GET /apiv1/customers?sort=payment_amount:desc&limit=10

该方案的优势 #

• 严格符合REST设计规范，所有客户相关的查询都统一指向客户集合资源，语义清晰
• 扩展性极强，后续新增筛选、排序规则只需要加对应查询参数即可，不需要新增端点
• 后端逻辑复用度高，只需要在原有获取客户列表的逻辑基础上增加参数解析、排序、截断的逻辑即可，不需要单独开发新接口

特殊场景扩展 #

如果后续有非常复杂、无法通过简单查询参数描述的聚合类查询（比如计算客户消费等级、多维度联合排名等），可以用子资源的方式设计端点，比如GET /apiv1/customers/rankings/payment，这类端点对应的是「客户排名」这类独立的聚合资源，也符合REST设计规范，你当前的场景完全不需要用到这种方式。

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