RESTful API 设计规范：打造优雅的接口

REST 核心原则

REST（Representational State Transfer）是一种架构风格，遵循以下原则：

• 资源导向：一切皆资源，用 URI 标识
• 无状态：每次请求包含完整信息
• 统一接口：使用标准 HTTP 方法
• 可缓存：响应可被缓存提升性能

URI 设计规范

✅ 正确做法

GET    /users          # 获取用户列表
GET    /users/123      # 获取指定用户
POST   /users          # 创建用户
PUT    /users/123      # 更新用户
DELETE /users/123      # 删除用户
GET    /users/123/posts # 获取用户的文章

❌ 避免做法

GET /getUsers
POST /createUser
/users/delete/123

HTTP 状态码使用

状态码	含义	使用场景
200	OK	成功获取/更新
201	Created	资源创建成功
204	No Content	删除成功
400	Bad Request	请求参数错误
401	Unauthorized	未认证
403	Forbidden	无权限
404	Not Found	资源不存在
500	Server Error	服务器错误

响应格式规范

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

版本控制

• URI 版本：/api/v1/users
• Header 版本：Accept: application/vnd.api.v1+json

分页与过滤

GET /users?page=1&limit=20&sort=-created_at
GET /users?status=active&role=admin

好的 API 设计让前端开发事半功倍，值得投入时间打磨！