API 开发规范

基本原则

  • RESTful 设计，无状态
  • 统一使用 JSON 格式
  • 路由前缀：/api/v1
  • 认证方式：Authorization: Bearer <token>
  • HTTP状态码统一为200

路由规范

  • 资源名使用复数：/users、/user_profiles
  • HTTP 方法对应操作：
    • GET - 查询
    • POST - 创建
    • PUT/PATCH - 更新
    • DELETE - 删除

统一响应格式

1
2
3
4
5
6
7

{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "meta": {},     // 分页时使用
  "errors": {}    // 验证失败时使用
}

code为业务状态码

业务码说明
200成功
400请求错误
401验证失败
401未认证
403无权限
404未找到
429请求过频
500服务器错误

响应示例

成功响应

1
2
3
4
5
6
7
8

{
  "code": 200,
  "message": "获取成功",
  "data": {
    "id": 1,
    "name": "John Doe"
  }
}

验证失败

1
2
3
4
5
6
7
8

{
  "code": 401,
  "message": "验证失败",
  "errors": {
    "name": ["用户名不能为空"],
    "password": ["密码至少8位"]
  }
}

分页响应

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "code": 200,
  "message": "获取成功",
  "data": [...],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 10,
    "total": 50
  }
}