RESTful API 设计最佳实践：打造优雅的接口

核心原则

1. 使用名词而非动词

✅ /users、/articles ❌ /getUsers、/createArticle

2. 正确使用 HTTP 方法

• GET：获取资源
• POST：创建资源
• PUT：全量更新
• PATCH：部分更新
• DELETE：删除资源

3. 资源嵌套要适度

✅ /users/123/articles ❌ /users/123/articles/456/comments/789/replies

状态码规范

200 OK          # 成功
201 Created     # 创建成功
204 No Content  # 删除成功
400 Bad Request # 请求错误
401 Unauthorized # 未授权
403 Forbidden   # 禁止访问
404 Not Found   # 资源不存在
429 Too Many Requests # 请求过多
500 Internal Server Error # 服务器错误

响应格式

{
  "success": true,
  "data": { ... },
  "message": "操作成功",
  "timestamp": 1710900000
}

版本控制

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

或在 Header 中：Accept: application/vnd.api.v1+json

分页设计

GET /articles?page=1&limit=20
GET /articles?cursor=abc123&limit=20

响应包含分页信息：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "hasMore": true
  }
}

错误处理

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "邮箱格式不正确",
    "field": "email"
  }
}

总结

良好的 API 设计能显著提升开发体验和系统可维护性。