API 设计最佳实践：让前后端协作更顺畅

好的 API 设计能让前后端协作事半功倍。分享一些实战经验。

RESTful 规范

资源命名

# ✅ 好
GET    /users          # 获取用户列表
GET    /users/123      # 获取单个用户
POST   /users          # 创建用户
PUT    /users/123      # 更新用户
DELETE /users/123      # 删除用户

# ❌ 避免
GET    /getUserList
POST   /createUser

使用复数名词

/users      # ✅
/user       # ❌

响应格式统一

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

错误响应：

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

状态码正确使用

状态码	含义	使用场景
200	成功	GET/PUT 成功
201	已创建	POST 成功创建资源
204	无内容	DELETE 成功
400	请求错误	参数验证失败
401	未授权	未登录
403	禁止访问	无权限
404	未找到	资源不存在
500	服务器错误	服务端异常

版本控制

# URL 版本（推荐）
/api/v1/users
/api/v2/users

# Header 版本
Accept: application/vnd.api.v1+json

分页设计

GET /users?page=1&pageSize=20

响应：

{
  "code": 200,
  "data": {
    "list": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 156,
      "totalPages": 8
    }
  }
}

过滤和排序

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

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

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

认证与授权

JWT Token

Authorization: Bearer <token>

Token 刷新

POST /auth/refresh
{
  "refreshToken": "xxx"
}

文档先行

用 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

---

好的 API 是自解释的。前端开发者看文档就能理解，不需要反复沟通。

设计 API 就是设计产品。