RESTful API 设计规范指南

核心原则

RESTful API 遵循资源导向的设计理念，使用 HTTP 方法操作资源。

HTTP 方法语义

URL 设计规范

# 正确
GET /users/123
POST /users
PUT /users/123
DELETE /users/123

# 错误（避免动词）
GET /getUsers
POST /createUser

状态码使用

• 200 OK：成功
• 201 Created：资源创建成功
• 400 Bad Request：请求参数错误
• 401 Unauthorized：未授权
• 403 Forbidden：禁止访问
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器错误

响应格式

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "example"
  }
}

版本控制

使用 URL 前缀：/api/v1/users

分页与过滤

GET /users?page=1&limit=20&sort=created_at&order=desc