将操作映射到 Rest URI

Question

我有一个资源“客户”，我将其 REST 端点定义为，

| URI                            | Function                            |
| ------------------------------ | ----------------------------------  |
| /apiv1/customers/              | {GET} Fetch all customers           |
| /apiv1/customers/{customer-id} | {GET} Fetch details of the customer |
| /apiv1/customers/              | {POST} Add a new customer           |
| /apiv1/customers/{customer-id} | {PUT} Update a customer             |

现在，我还必须设计一些非 CRUD 操作，例如

• 按支付金额获取前5名客户
• 获取最后 3 位顾客
• 等等

如何为上述操作设计 URI？

我的看法是引入一个新的控制器，每个功能都有单独的端点，例如：

• /apiv1/客户/fetch-top-5
• /apiv1/客户/fetch-last-3

我对上述方法仍然没有信心。另外，如果我想参数化这些操作（例如 fetch-top-n 客户）怎么办

Answer 1

/apiv1/customers/fetch-top-5
/apiv1/customers/fetch-last-3

这些都“很好”，但受限于您的实现可以告诉这些终端路径段不是客户 ID。

如果我想参数化这些操作（例如 fetch-top-n 客户）怎么办

参数的一般答案是设计标识符，以便它们与 URI 模板很好地对齐。

最熟悉的变体是在查询部分使用键值对，主要是因为 HTML 表单支持该拼写约定。 所以你的标识符可能是

/apiv1/customers?fetch-top=5
/apiv1/customers?fetch-last=3

但这不是必需的 - 您可以将信息编码到路径中

/apiv1/customers?fetch-top=5
/apiv1/customers/fetch-top=5
/apiv1/customers/fetch-top/5
/apiv1/customers/fetch/top=5
/apiv1/customers/fetch/top/5

这些都“很好”。 使用最适合您关心的人的拼写。

Answer 2

我会将它们添加为查询参数。 ?顶部=5 ?最后=3

如果客户端同时提供两者，请确保后端返回状态 400 (?top=5&last=3)