API 设计原则：打造优雅的 RESTful 接口

为什么 API 设计很重要？

糟糕的 API 设计会导致：

• 前端开发效率低下
• 文档难以维护
• 版本升级困难
• 开发者体验差

RESTful 核心原则

1. 使用名词表示资源

# ✅ 好
GET /users
GET /users/123
POST /users
PUT /users/123
DELETE /users/123

# ❌ 差
GET /getUsers
POST /createUser
GET /deleteUser/123

2. 使用 HTTP 方法表达操作

方法	用途	幂等性
GET	获取资源	是
POST	创建资源	否
PUT	全量更新	是
PATCH	部分更新	否
DELETE	删除资源	是

3. 使用复数名词

# ✅ 好
/users
/articles
/comments

# ❌ 差
/user
/article
/comment

4. 嵌套资源表达关系

GET /users/123/articles      # 获取用户的所有文章
GET /articles/456/comments   # 获取文章的所有评论
POST /articles/456/comments  # 给文章添加评论

响应格式规范

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"
  }
}

列表响应

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}

错误响应

{
  "code": 1001,
  "message": "用户不存在",
  "data": null,
  "errors": [
    {
      "field": "userId",
      "message": "无效的用户 ID"
    }
  ]
}

状态码使用

状态码	含义	使用场景
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 版本（推荐）

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

Header 版本

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

过滤、排序、分页

# 过滤
GET /users?status=active&role=admin

# 排序
GET /users?sort=-created_at  # 降序
GET /users?sort=name         # 升序

# 分页
GET /users?page=1&pageSize=20

# 字段选择
GET /users?fields=id,name,email

安全最佳实践

1. 始终使用 HTTPS
2. 认证机制：JWT、OAuth 2.0
3. 速率限制：防止滥用
4. 输入验证：防止注入攻击
5. 敏感信息脱敏：不在响应中返回密码等

文档化

使用 OpenAPI/Swagger 规范：

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        200:
          description: 成功

结语

好的 API 设计是自文档化的，直观的，一致的。遵循这些原则，让你的 API 成为开发者的朋友，而不是敌人。