api接口文档

1. 电商管理后台 API 接口文档

1.1. API V1 接口说明

• 接口基准地址：http://127.0.0.1:8888/api/private/v1/
• 服务端已开启 CORS 跨域支持
• API V1 认证统一使用 Token 认证
• 需要授权的 API ，必须在请求头中使用 Authorization 字段提供 token 令牌
• 使用 HTTP Status Code 标识状态
• 数据返回格式统一使用 JSON

1.1.1. 支持的请求方法

• GET（SELECT）：从服务器取出资源（一项或多项）。
• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
• DELETE（DELETE）：从服务器删除资源。
• HEAD：获取资源的元数据。
• OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

1.1.2. 通用返回状态说明

状态码	含义	说明
200	OK	请求成功
201	CREATED	创建成功
204	DELETED	删除成功
400	BAD REQUEST	请求的地址不存在或者包含不支持的参数
401	UNAUTHORIZED	未授权
403	FORBIDDEN	被禁止访问
404	NOT FOUND	请求的资源不存在
422	Unprocesable entity	[POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误
500	INTERNAL SERVER ERROR	内部错误

---

1.2. 登录

1.2.1. 登录验证接口

• 请求路径：login
• 请求方法：post
• 请求参数

参数名	参数说明	备注
username	用户名	不能为空
password	密码	不能为空

• 响应参数

参数名	参数说明	备注
id	用户 ID
rid	用户角色 ID
username	用户名
mobile	手机号
email	邮箱
token	令牌	基于 jwt 的令牌

• 响应数据

{
   
    "data": {
   
        "id": 500,
        "rid": 0,
        "username": "admin",
        "mobile": "123",
        "email": "123@qq.com",
        "token": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOjUwMCwicmlkIjowLCJpYXQiOjE1MTI1NDQyOTksImV4cCI6MTUxMjYzMDY5OX0.eGrsrvwHm-tPsO9r_pxHIQ5i5L1kX9RX444uwnRGaIM"
    },
    "meta": {
   
        "msg": "登录成功",
        "status": 200
    }
}

1.3. 用户管理

1.3.1. 用户数据列表

• 请求路径：users
• 请求方法：get
• 请求参数

参数名	参数说明	备注
query	查询参数	可以为空
pagenum	当前页码	不能为空
pagesize	每页显示条数	不能为空

• 响应参数

参数名	参数说明	备注
totalpage	总记录数
pagenum	当前页码
users	用户数据集合

• 响应数据

{
   
    "data": {
   
        "totalpage": 5,
        "pagenum": 4,
        "users": [
            {
   
                "id": 25,
                "username": "tige117",
                "mobile": "18616358651",
                "type": 1,
                "email": "tige112@163.com",
                "create_time": "2017-11-09T20:36:26.000Z",
                "mg_state": true, // 当前用户的状态
                "role_name": "炒鸡管理员"
            }
        ]
    },
    "meta": {
   
        "msg": "获取成功",
        "status": 200
    }
}

1.3.2. 添加用户

• 请求路径：users
• 请求方法：post
• 请求参数

参数名	参数说明	备注
username	用户名称	不能为空
password	用户密码	不能为空
email	邮箱	可以为空
mobile	手机号	可以为空

• 响应参数

参数名	参数说明	备注
id	用户 ID
rid	用户角色 ID
username	用户名
mobile	手机号
email	邮箱

• 响应数据

{
   
    "data": {
   
        "id": 28,
        "username": "tige1200",
        "mobile": "test",
        "type": 1,
        "openid": "",
        "email": "test@test.com",
        "create_time": "2017-11-10T03:47:13.533Z",
        "modify_time": null,
        "is_delete": false,
        "is_active": false
    },
    "meta": {
   
        "msg": "用户创建成功",
        "status": 201
    }
}

1.3.3. 修改用户状态

• 请求路径：users/:uId/state/:type
• 请求方法：put
• 请求参数

参数名	参数说明	备注
uId	用户 ID	不能为空携带在url中
type	用户状态	不能为空携带在url中，值为 true 或者 false

• 响应数据

{
   
  "data": {
   
    "id": 566,
    "rid": 30,
    "username": "admin",
    "mobile": "123456",
    "email": "bb@itcast.com",
    "mg_state": 0
  },
  "meta": {
   
    "msg": "设置状态成功",
    "status": 200
  }
}

1.3.4. 根据 ID 查询用户信息

• 请求路径：users/:id
• 请求方法：get
• 请求参数

参数名	参数说明	备注
id	用户 ID	不能为空携带在url中

• 响应参数

参数名	参数说明	备注
id	用户 ID
role_id	角色 ID
mobile	手机号
email	邮箱

• 响应数据

{
   
    "data": {
   
        "id": 503,
        "username": "admin3",
        "role_id": 0,
        "mobile": "00000",
        "email": "new@new.com"
    },
    "meta": {
   
        "msg": "查询成功",
        "status": 200
    }
}

1.3.5. 编辑用户提交

• 请求路径：users/:id
• 请求方法：put
• 请求参数

参数名	参数说明	备注
id	用户 id	不能为空 参数是url参数:id
email	邮箱	可以为空
mobile	手机号	可以为空

• 响应参数

参数名	参数说明	备注
id	用户 ID
role_id	角色 ID
mobile	手机号
email	邮箱

• 响应数据

/* 200表示成功，500表示失败 */
{
   
    "data": {
   
        "id": 503,
        "username": "admin3",
        "role_id": 0,
        "mobile": "111",
        "email": "123@123.com"
    },
    "meta": {
   
        "msg": "更新成功",
        "status": 200
    }
}

1.3.6. 删除单个用户

• 请求路径：users/:id
• 请求方法：delete
• 请求参数

参数名	参数说明	备注
id	用户 id	不能为空参数是url参数:id

• 响应参数
• 响应数据

{
   
    "data": null,
    "meta": {
   
        "msg": "删除成功",
        "status": 200
    }
}

1.3.7. 分配用户角色

• 请求路径：users/:id/role
• 请求方法：put
• 请求参数

参数名	参数说明	备注
id	用户 ID	不能为空参数是url参数:id
rid	角色 id	不能为空参数body参数

• 响应参数

参数名	参数说明	备注
id	用户 ID
role_id	角色 ID
mobile	手机号
email	邮箱

• 响应数据

{
   
    "data": {
   
        "id": 508,
        "rid": "30",
        "username": "asdf1",
        "mobile": "123123",
        "email": "adfsa@qq.com"
    },
    "meta": {
   
        "msg": "设置角色成功",
        "status": 200
    }
}

1.4. 权限管理

1.4.1.