RESTful API 中的 URL 设计规范（最佳实践）
URL（Uniform Resource Identifier）是 RESTful API 的核心入口，良好的 URL 设计能让 API 直观、可预测、易维护。以下是业界广泛认可的 URL 设计规范和最佳实践。
1. 核心原则总结（口诀）
“资源用名词、复数形式、层级清晰、动词靠方法、版本要明确、查询用参数”
2. 详细规范表
| 规范类别 | 推荐做法 | 示例 | 不推荐示例 | 原因说明 |
|---|---|---|---|---|
| 资源命名 | 使用名词表示资源（避免动词） | /users、/articles | /getUsers、/createArticle | 动词应由 HTTP 方法表达 |
| 复数 vs 单数 | 统一使用复数形式（业界主流约定） | /users、/orders | /user、/order | 更一致，便于集合和单个资源统一处理 |
| 层级结构 | 用路径表示资源的从属关系（嵌套不超过 2-3 层） | /users/123/orders | /getUserOrders?id=123 | 更直观，体现资源层次 |
| 子资源操作 | 子资源用嵌套路径 | /articles/123/comments | /comments?articleId=123 | 更 RESTful（可选，视场景） |
| 动作非资源时 | 如果是动作而非资源，用动词放在路径末尾（谨慎使用） | /orders/123/cancel | 大多数情况应转为资源设计 | 只在无法建模为资源时使用 |
| 版本控制 | 在 URL 中显式指定版本（最常见方式） | /v1/users、/api/v2/articles | 无版本或只用 Header | 更直观，便于文档和客户端切换 |
| 大小写与分隔符 | 全小写，用连字符 – 分隔（kebab-case） | /blog-posts、/user-profiles | /blogPosts（camelCase） | URL 区分大小写，小写更安全、可读性更好 |
| 文件扩展名 | 避免在 URL 中使用 .json、.xml 等扩展名 | /users/123 | /users/123.json | 内容协商用 Accept Header 处理 |
| ID 命名 | 用 {id} 占位符（文档中），实际用具体 ID | /users/{id}（文档）/users/123（实际） | /users/userId=123 | 更简洁 |
| 查询参数 | 用于过滤、排序、分页、搜索等 | /articles?tag=rest&page=2&limit=20&sort=created_at:desc | 把参数放路径 | 查询参数专为此设计 |
| 避免过深嵌套 | 嵌套不超过 3 层，过多时用查询参数或扁平化 | /users/123/orders/456/items（可接受） | 嵌套 5 层以上 | 过深 URL 复杂、不易维护 |
3. 常见操作的 URL 示例（用户 + 文章 + 评论）
| 操作 | 推荐 URL | HTTP 方法 | 说明 |
|---|---|---|---|
| 获取用户列表 | GET /users | GET | 支持查询参数过滤 |
| 获取单个用户 | GET /users/123 | GET | |
| 创建用户 | POST /users | POST | |
| 更新用户（全量） | PUT /users/123 | PUT | |
| 部分更新用户 | PATCH /users/123 | PATCH | |
| 删除用户 | DELETE /users/123 | DELETE | |
| 获取用户的所有订单 | GET /users/123/orders | GET | 嵌套子资源 |
| 获取某篇文章的所有评论 | GET /articles/456/comments | GET | |
| 为文章添加评论 | POST /articles/456/comments | POST | |
| 搜索文章 | GET /articles/search?q=restful | GET | 或直接用 /articles?q=restful |
| 获取当前登录用户信息 | GET /me 或 GET /users/me | GET | 常见特殊路径 |
4. 特殊场景处理建议
| 场景 | 推荐设计方式 | 示例 |
|---|---|---|
| 分页 | 用查询参数 page 和 limit 或 offset 和 limit | /articles?page=3&limit=20 |
| 排序 | 用 sort 参数，支持字段+方向 | /users?sort=-created_at,name |
| 过滤 | 用查询参数，直接字段名或特定前缀 | /orders?status=paid&min_amount=100 |
| 批量操作 | 单独路径（非标准 REST，但实用） | POST /users/batch-delete（Body: [1,2,3]） |
| 文件上传 | 用资源路径 + multipart/form-data | POST /users/123/avatar |
| 触发动作（如支付） | 优先建模为资源（如创建支付订单），否则用动词路径 | POST /orders/123/pay（谨慎使用） |
5. 常见反模式（避免）
- 把 HTTP 方法放进 URL：
/users/getAll、/users/addUser - 混用单复数：项目中既有
/user又有/articles - 过长 URL：嵌套太多层或参数太多
- 用查询参数做主要操作：
GET /users?action=delete&id=123（应为 DELETE） - 无版本控制，导致旧客户端无法兼容
6. 总结
优秀的 URL 设计应该做到：
- 一眼看出资源和关系
- 无需文档也能猜到大部分接口
- 前后一致、易于扩展
遵循以上规范，你的 RESTful API 将更专业、更易被开发者接受和使用。
如果你想看具体框架（如 Express、Spring Boot、FastAPI）的路由实现示例，或者某个复杂场景的 URL 设计讨论，随时告诉我！
