虽然 RESTful API 主要是围绕资源（名词）设计的，但在某些特定场景中，使用动词是合理的，尤其是在处理超出基本 CRUD（创建、读取、更新、删除）操作的行为或操作时。以下是使用动词的 RESTful URL 示例，按使用场景分类。
1. 与资源无关的操作
当需要暴露与资源无关的操作端点时，可以在 URL 中使用动词：
/auth/login— 用户登录。/auth/logout— 用户登出。/auth/reset-password— 重置用户密码。/reports/generate— 生成报告。/system/ping— 检查系统健康状态（健康检查端点）。/notifications/send— 触发发送通知。/search— 执行跨多个资源的搜索查询。
2. 资源上的特定操作
当需要在资源上执行超出基本 CRUD 的具体操作时，可以使用动词：
/users/{id}/activate— 激活用户账户。/users/{id}/deactivate— 禁用用户账户。/users/{id}/ban— 封禁用户。/orders/{id}/cancel— 取消订单。/orders/{id}/refund— 为订单发起退款。/devices/{id}/restart— 重启设备。
3. 批量或批处理操作
当需要对多个资源同时进行操作时，URL 中使用动词可以更清楚地表达意图：
/users/batch-create— 批量创建多个用户。/users/batch-delete— 批量删除多个用户。/orders/batch-process— 同时处理多个订单。/emails/batch-send— 一次发送多个邮件。
4. RPC 风格的操作
虽然 REST 是以资源为中心的，但某些 API 可能倾向于 RPC（远程过程调用）模式，适合使用动词：
/calculate-tax— 根据输入数据计算税。/convert-currency— 货币转换。/validate-address— 验证邮寄地址。/generate-invoice— 生成客户发票。/upload-file— 上传文件（例如到云存储系统）。
5. 系统管理或管理员操作
有时，API 包括一些用于管理任务或系统级操作的端点：
/system/restart— 重启系统。/system/shutdown— 关闭系统。/cache/clear— 清除缓存。/database/backup— 触发数据库备份。
6. 搜索和过滤
虽然 RESTful API 通常使用查询参数来进行搜索和过滤，但在某些复杂搜索场景中，URL 中使用动词可以更直观：
/search/users— 搜索用户。/search/orders— 搜索订单。/filter/products— 根据特定条件过滤产品。
7. 通知和消息
一些 API 涉及与消息或通知相关的操作，在这些场景中，使用动词是合理的：
/notifications/send— 发送通知。/messages/send— 发送消息。/emails/send— 发送邮件。
8. 子资源上的自定义操作
当资源有子资源或特定行为时，可以使用动词来清晰表达操作：
/users/{id}/roles/assign— 为用户分配角色。/users/{id}/permissions/revoke— 撤销用户权限。/projects/{id}/tasks/complete— 将任务标记为完成。
9. 触发事件或工作流
如果 API 需要触发工作流或事件，使用动词可能是一个合适的选择：
/workflows/start— 启动工作流。/workflows/stop— 停止工作流。/events/trigger— 触发事件。/jobs/execute— 执行任务。
使用动词的最佳实践
虽然在某些情况下可以在 URL 中使用动词，但需要遵循以下最佳实践：
- 尽可能使用 HTTP 方法： 对于 CRUD 操作，请坚持使用名词，并使用 HTTP 方法（GET、POST、PUT、DELETE）来定义操作。
- 示例：不要使用
/createUser，而是使用POST /users。
- 示例：不要使用
- 保持 URL 一致性： 如果在某些 URL 中使用动词，确保整个 API 设计具有一致性。
- 清晰记录 API： 明确说明每个端点的用途，尤其是在打破传统 RESTful 规范的情况下。
总结
在 RESTful URL 中使用动词通常仅限于处理与资源无关的操作、自定义操作或无法完全适配 CRUD 模式的工作流。虽然 REST 主要是以资源为导向的，但在某些场景下，使用动词可以是一个实用的解决方案，只要你确保 API 设计的一致性和清晰性即可。
浙公网安备 33010602011771号