URL 设计规范

资源导向的 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

嵌套层级建议

查询参数

用于过滤、排序和分页：

javascript// 分页
GET /api/users?page=1&limit=10

// 过滤
GET /api/users?status=active&city=beijing

// 排序
GET /api/users?sort=created_at&order=desc

// 搜索
GET /api/users?search=张三

API 版本控制

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

URL 路径版本控制

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

请求头版本控制

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