RESTful API 设计最佳实践

好的 API 设计能让前端开发更高效，让系统更易维护。以下是经过实战验证的 RESTful API 设计原则。

核心原则

1. 使用名词表示资源

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

资源用复数形式，表示集合。

2. 用 HTTP 方法表达操作

方法	用途	示例
GET	获取资源	GET /users/123
POST	创建资源	POST /users
PUT	更新资源（全量）	PUT /users/123
PATCH	更新资源（部分）	PATCH /users/123
DELETE	删除资源	DELETE /users/123

3. 使用嵌套表示关系

# 获取用户的所有文章
GET /users/123/articles

# 获取文章的评论
GET /articles/456/comments

# 获取用户的某篇文章的评论
GET /users/123/articles/456/comments

嵌套不要超过 3 层，太深说明设计有问题。

URL 设计规范

使用小写字母和连字符

✅ /user-profiles ❌ /UserProfiles ❌ /user_profiles

避免动词

✅ POST /articles 创建文章 ❌ POST /createArticle

✅ DELETE /articles/123 删除文章 ❌ POST /articles/123/delete

使用查询参数过滤

# 分页
GET /articles?page=2&limit=20

# 排序
GET /articles?sort=created_at&order=desc

# 过滤
GET /articles?status=published&category=tech

# 搜索
GET /articles?q=python+tutorial

响应格式

统一响应结构

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

列表响应

{
  "code": 0,
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "limit": 20
  }
}

错误响应

{
  "code": 400,
  "message": "参数错误",
  "errors": [
    {"field": "email", "message": "邮箱格式不正确"}
  ]
}

HTTP 状态码

状态码	含义	使用场景
200	OK	成功
201	Created	创建成功
204	No Content	删除成功
400	Bad Request	参数错误
401	Unauthorized	未登录
403	Forbidden	无权限
404	Not Found	资源不存在
409	Conflict	资源冲突
422	Unprocessable Entity	验证失败
429	Too Many Requests	请求过多
500	Internal Server Error	服务器错误

版本控制

URL 版本

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

Header 版本

GET /users
Accept: application/vnd.myapi.v1+json

推荐 URL 版本，更直观、易调试。

安全考虑

1. 使用 HTTPS

生产环境必须使用 HTTPS。

2. 认证授权

• JWT Token
• OAuth 2.0
• API Key

3. 限流

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

4. 敏感数据脱敏

{
  "id": 123,
  "email": "a***@gmail.com",
  "phone": "138****1234"
}

文档

使用 OpenAPI/Swagger 自动生成文档：

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        200:
          description: 成功

结语

好的 API 设计是一门艺术。遵循这些最佳实践，能让你的 API 更优雅、更易用、更易维护。

记住：API 是产品，不是实现细节。