URL-Designspezifikationen

Ressourcenorientiertes URL-Design

RESTful-API-URLs sollten "Ressourcen" statt "Aktionen" darstellen.

Betrachten Sie eine URL als Etikett eines Bibliotheksregals; sie sagt Ihnen, wo Sie welche Ressourcen finden.

Gutes Design ✅

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

Schlechtes Design ❌

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

URL-Benennungskonventionen

Verwenden Sie Substantive statt Verben

  • ✅ GET /api/books
  • ❌ GET /api/getBooks

Verwenden Sie Pluralformen

  • ✅ GET /api/users
  • ❌ GET /api/user

Kleinbuchstaben verwenden

  • ✅ GET /api/user-orders

  • ❌ GET /api/UserOrders

Verwenden Sie Bindestriche, um Wörter zu trennen

  • ✅ GET /api/user-profiles

  • ❌ GET /api/user_profiles

  • ❌ GET /api/userProfiles

Verschachtelte Ressourcen

Wenn Ressourcen hierarchische Beziehungen haben, können verschachtelte URLs verwendet werden:

// 获取用户 123 的所有订单
GET /api/users/123/orders

// 获取用户 123 的订单 456
GET /api/users/123/orders/456

// 为用户 123 创建新订单
POST /api/users/123/orders

Empfehlungen für verschachtelte Hierarchien

Abfrageparameter

Wird zum Filtern, Sortieren und Paginieren verwendet:

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-Versionierung

Um die Abwärtskompatibilität zu erhalten, benötigen APIs eine Versionierung:

URL-Pfad-Versionierung

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

Request-Header-Versionierung

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