RESTful API 设计：7 个让前端开发者感谢你的细节

作为全栈开发者，我见过太多让人头疼的 API。今天分享 7 个设计细节，能让前端同事少加班。

1. 统一的响应格式

错误示范：

// 成功时
{"users": [...]}

// 失败时
{"error": "not found"}

推荐格式：

{
  "code": 200,
  "data": {...},
  "message": "success",
  "timestamp": 1711526400
}

前端只需要处理一种结构，减少判断逻辑。

2. 合理的 HTTP 状态码

别都用 200！

场景	状态码
成功	200 OK
创建资源	201 Created
无内容返回	204 No Content
参数错误	400 Bad Request
未授权	401 Unauthorized
禁止访问	403 Forbidden
资源不存在	404 Not Found
服务器错误	500 Internal Server Error

前端可以根据状态码做不同处理。

3. 分页参数标准化

混乱的命名：

• /users?page=1&size=20
• /users?offset=0&limit=20
• /users?start=1&count=20

统一推荐：

GET /users?page=1&pageSize=20

响应中包含分页元数据：

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 150,
    "totalPages": 8
  }
}

4. 字段命名一致性

不要这样：

{
  "userId": 1,
  "user_name": "john",
  "createdAt": "2024-01-01",
  "create_time": "2024-01-01T00:00:00Z"
}

推荐：

• 全部用 camelCase（JavaScript 友好）
• 或者全部用 snake_case（数据库友好）
• 时间字段统一 ISO 8601 格式

5. 错误信息要具体

模糊的错误：

{"error": "validation failed"}

具体的错误：

{
  "code": 400,
  "errors": [
    {
      "field": "email",
      "message": "邮箱格式不正确",
      "code": "INVALID_EMAIL"
    },
    {
      "field": "password",
      "message": "密码长度至少 8 位",
      "code": "PASSWORD_TOO_SHORT"
    }
  ]
}

前端可以直接在表单对应位置显示错误。

6. 支持字段过滤

允许前端指定返回字段：

GET /users/1?fields=id,name,email

返回：

{
  "id": 1,
  "name": "John",
  "email": "john@example.com"
}

减少不必要的数据传输，提升性能。

7. 版本控制

错误做法：

• 直接修改现有 API（会破坏现有客户端）

推荐做法：

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

或者用 Header：

Accept: application/vnd.myapi.v1+json

给客户端迁移时间。

额外建议

• 提供 Swagger/OpenAPI 文档：前端可以自己看文档
• 添加请求 ID：便于排查问题
• 速率限制：在响应头中告知限制

总结

好的 API 设计是隐形的。前端开发者感觉不到你的存在，说明你做得对。

花 1 小时设计，节省 100 小时沟通。