Спецификации проектирования URL
Проектирование URL, ориентированное на ресурсы
URL-адреса RESTful API должны представлять «ресурсы», а не «действия».
Представьте 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Другие расширения