资源导向的 URL 设计

在 RESTful API 里，URL 更适合用来指向“资源”，而不是直接写成“动作”。

可以把 URL 理解成图书馆里书架上的分类标签。看到它，基本就知道该去哪里，以及能找到什么资源。

好的设计

GET /api/users          # 获取所有用户
GET /api/users/123      # 获取 ID 为 123 的用户
POST /api/users         # 创建新用户
PUT /api/users/123      # 更新用户 123
DELETE /api/users/123   # 删除用户 123

不好的设计

GET /api/getUsers       # 动词出现在 URL 中
POST /api/createUser    # 动作导向而非资源导向
GET /api/user/delete/123 # 混乱的结构

URL 命名规范

使用名词而非动词

• GET /api/books
• GET /api/getBooks

使用复数形式

• GET /api/users
• GET /api/user

使用小写字母

• GET /api/user-orders

• GET /api/UserOrders

使用连字符分隔单词

• GET /api/user-profiles

• GET /api/user_profiles
• GET /api/userProfiles

嵌套资源

当资源之间有从属关系时，可以使用嵌套 URL。

// 获取用户 123 的所有订单
GET /api/users/123/orders
// 获取用户 123 的订单 456
GET /api/users/123/orders/456
// 为用户 123 创建新订单
POST /api/users/123/orders

嵌套层级建议

查询参数

查询参数用于过滤、排序和分页。

ja vascript// 分页
GET /api/userspage=1&limit=10
// 过滤
GET /api/usersstatus=active&city=beijing
// 排序
GET /api/userssort=created_at&order=desc
// 搜索
GET /api/userssearch=张三

API 版本控制

为了保持向后兼容，API 需要版本控制。

URL 路径版本控制

GET /api/v1/users
GET /api/v2/users

请求头版本控制

GET /api/users
Accept: application/vnd.api+json;version=1

《夸克》非常好用的免费AI浏览器

下载APP查看