Alpha冲刺接口文档

Posted on 2024-05-03 19:45  Aderversa  阅读(109)  评论(0)    收藏  举报

Alpha冲刺

用户模块

POST 注册

POST /user/register

用户在注册时需要设定好：用户名、用户密码、用户的邮箱、邮箱验证码
绑定邮箱不是输入邮箱就可以了，而是要发送验证码到指定的邮箱中，确认完验证码之后才能绑定
发送邮箱验证码会单独提供一个接口。
逻辑可以参照，以下序列图

sequenceDiagram User->>Client: 输入基本信息 activate Client Client->>Server: 调用邮箱接口，发送验证码 activate Server Server->>Redis: 生成并缓存验证码 Server-->>User: 发送验证码 User->>Client: 从邮箱确认后，输入验证码 Client->>Server: 用户名username，用户密码password，确认密码confirmPassword，邮箱email,验证码captcha Server->>Redis: 获取先前缓存的验证码 activate Redis Redis-->>Server: 返回验证码 deactivate Redis Server->>Server: 对比验证码 par Server to MySQL Server->>MySQL: 验证成功，注册用户 Server-->>Client: 注册成功 and Server to Client Server-->>Client: 验证失败 end deactivate Server Client-->>User: 显示响应 deactivate Client

Body 请求参数

{
  "username": "Aderversa",
  "password": "123456",
  "confirmPassword": "123456",
  "email": "2457699535@qq.com",
  "captcha": "465432"
}

请求参数

名称 位置 类型 必选 中文名 说明
body body object 否 none
» username body string 是 用户名 5-16位非空字符
» password body string(password) 是 密码 5-16位非空字符
» confirmPassword body string(password) 是 确认密码 5-16位非空字符
» email body string(email) 是 邮箱 符合邮箱格式
» captcha body string 是 验证码 6位的数字

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": "null"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

POST 发送邮箱验证码

POST /user/captcha

发送验证码给指定邮箱

请求参数

名称 位置 类型 必选 中文名 说明
email query string(email) 是 邮箱

返回示例

200 Response

{
  "code": 1,
  "message": "string",
  "data": "string"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

POST 登录

POST /user/login

用户登录，返回JWT令牌
大概流程是这样的：

sequenceDiagram user->>client: username，password activate client client->>server: username，password deactivate client activate server server->>database: 查找username是否存在 activate database database-->>server: 返回查找到的用户 deactivate database server->>server: 登录逻辑 server->>redis: 封装username和id到JWT令牌，并在redis中缓存 server-->>client: 响应信息（包含JWT令牌） deactivate server activate client client-->>user: 显示响应 deactivate client

需要为JWT令牌设置过期时间
一个用户可以有多个JWT令牌，所以可以采用Redis的一种存储结构：
以username作为键，JWT令牌作为元素的集合Set
当用户修改密码是，这个键将会被强制删除，这就要求用户重新登录

请求参数

名称 位置 类型 必选 中文名 说明
username query string 是 用户名
password query string(password) 是 密码

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": "eyJ0eXAiOiJqd3QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE3MTQxNDMyMjUsImV4cCI6MTcxNDE0NjgyNSwiaWQiOjQsInVzZXJuYW1lIjoiQWRlcnZlcnNhIn0.YJBiDAtNT2i5OXcWUhCz8MmNzaSOrNto1j-0_OqyaS0"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

GET 获取用户基本信息

GET /user/getInfo

用户首先要查看他的一些基本信息，然后才能做出修改。但是这些信息不包括密码和权限。

请求参数

名称 位置 类型 必选 中文名 说明
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "id": 2,
    "username": "Aderversa",
    "nickname": "",
    "email": "",
    "userImg": "",
    "createTime": "2024-04-23T10:26:32",
    "updateTime": "2024-04-23T10:26:32"
  }
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

用户模块/修改用户信息

PATCH 修改用户昵称

PATCH /user/changeNickname

就是将数据库中对应用户的nickname做出修改，并且保证nickname是唯一的。
就像王者荣耀里的名字不能唯一那样。

请求参数

名称 位置 类型 必选 中文名 说明
nickname query string 是 2-10位非空字符
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": null
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

PATCH 修改用户邮箱

PATCH /user/changeEmail

前端调用接口发送验证码给用户，用户输入验证码后，将邮箱和验证码同时发送给后端。
后端负责验证验证码是否正确，正确则绑定成功，错误则绑定失败。

请求参数

名称 位置 类型 必选 中文名 说明
email query string(email) 是 邮箱
captcha query string 是 验证码,6位的数字
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": null
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

PATCH 修改用户密码

PATCH /user/changePwd

用户密码不能简单地通过旧密码就能修改，因为考虑到账号密码泄露，可能会导致密码被非法篡改。
从而导致账号真正的主人失去登陆的权限。
所以，修改密码必须先通过邮箱的验证。

Body 请求参数

{
  "oldPwd": "123456",
  "newPwd": "abc123",
  "confirmPwd": "abc123",
  "email": "2457699535@aliyun.com",
  "captcha": "765388"
}

请求参数

名称 位置 类型 必选 中文名 说明
Authorization header string 是 JWT令牌
body body object 否 none
» oldPwd body string 是 旧密码 5-16位非空字符
» newPwd body string 是 新密码 5-16位非空字符
» confirmPwd body string 是 确认密码 5-16位非空字符
» email body string(email) 是 邮箱 邮箱
» captcha body string 是 验证码 6位数字

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": null
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

书籍模块

POST 添加书籍分类

POST /book/addType

书籍分类默认存在有一个“全部”分类。
其余分类都是其他分类，在获取全部分类时，不会根据分类id进行查找，而是返回整张待售书籍表
查询其他分类时，根据分类id进行查找，然后返回查找结果到前端
该接口的调用需要管理员权限，管理员权限需要向开发人员申请，开发人员会直接操纵数据库修改权限

请求参数

名称 位置 类型 必选 中文名 说明
name query string 是 分类名，1-10个非空字符
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": null
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

GET 获取所有的书籍分类

GET /book/getTypes

请求参数

名称 位置 类型 必选 中文名 说明
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "全部"
    },
    {
      "id": 2,
      "name": "教材"
    },
    {
      "id": 3,
      "name": "实验报告"
    },
    {
      "id": 4,
      "name": "小说"
    },
    {
      "id": 5,
      "name": "科幻"
    }
  ]
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

POST 添加待售书籍

POST /book/add

Body 请求参数

{
  "name": "红楼梦",
  "typeId": 1,
  "price": 59.7,
  "isbn": "978-7-02-000220-7",
  "detail": "红楼梦是我国的四大名著之一"
}

请求参数

名称 位置 类型 必选 中文名 说明
Authorization header string 是 JWT令牌
body body object 否 none
» name body string 是 书名 1-50位非空字符
» typeId body integer 否 分类ID 默认为1
» price body number 是 价格 不得小于或等于0
» isbn body string 是 ISBN号 none
» detail body string 是 简介 500字以内

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": null
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

GET 按分类获取待售书籍

GET /book/getByType

按照分类来获取待售书籍

请求参数

名称 位置 类型 必选 中文名 说明
id query integer 是 分类ID
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "红楼梦",
      "typeId": 1,
      "price": "59.70",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-03",
      "sellerId": 1,
      "sellerName": "Aderversa",
      "purchased": 0
    }
  ]
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

GET 搜索待售书籍

GET /book/search

后端不分页，只把符合条件的书籍返回给前端。
采用模糊匹配的方式，将符合的结果返回给前端。

请求参数

名称 位置 类型 必选 中文名 说明
content query string 是 匹配的文本
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": 4,
      "name": "三国演义",
      "typeId": 1,
      "price": "59.70",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-01",
      "sellerId": 1,
      "purchased": 0
    },
    {
      "id": 5,
      "name": "三国战纪",
      "typeId": 1,
      "price": "59.70",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-01",
      "sellerId": 1,
      "purchased": 0
    }
  ]
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

GET 排序待售书籍

GET /book/sort

前端将待售书籍列表传回后端，由后端对书籍进行排序，目前主要提供两种排序功能。

  1. 按价格升序排序
  2. 按价格降序排序

Body 请求参数

{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "红楼梦",
      "typeId": 1,
      "price": "59.70",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-01",
      "sellerId": 1,
      "sellerName": "Aderversa",
      "purchased": 0
    },
    {
      "id": 3,
      "name": "西游记",
      "typeId": 1,
      "price": "40",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-01",
      "sellerId": 1,
      "sellerName": "Aderversa",
      "purchased": 0
    },
    {
      "id": 4,
      "name": "三国演义",
      "typeId": 1,
      "price": "30",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-01",
      "sellerId": 1,
      "sellerName": "Aderversa",
      "purchased": 0
    },
    {
      "id": 2,
      "name": "水浒传",
      "typeId": 1,
      "price": "10",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-01",
      "sellerId": 1,
      "sellerName": "Aderversa",
      "purchased": 0
    }
  ]
}

请求参数

名称 位置 类型 必选 中文名 说明
mode query integer 是 1-按价格升序排序；2-按价格降序排序
Authorization header string 是 JWT令牌
body body object 否 none
» code body integer 是 none
» message body string 是 none
» data body [object] 是 none
»» id body integer 是 none
»» name body string 是 none
»» typeId body integer 是 none
»» price body string 是 none
»» isbn body string 是 none
»» img body null 是 none
»» detail body string 是 none
»» releaseTime body string 是 none
»» sellerId body integer 是 none
»» sellerName body string 是 none
»» purchased body integer 是 none

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "name": "红楼梦",
      "typeId": 1,
      "price": "59.70",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-01",
      "sellerId": 1,
      "purchased": 0
    },
    {
      "id": 3,
      "name": "西游记",
      "typeId": 1,
      "price": "40",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-01",
      "sellerId": 1,
      "purchased": 0
    },
    {
      "id": 4,
      "name": "三国演义",
      "typeId": 1,
      "price": "30",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-01",
      "sellerId": 1,
      "purchased": 0
    },
    {
      "id": 2,
      "name": "水浒传",
      "typeId": 1,
      "price": "10",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-01",
      "sellerId": 1,
      "purchased": 0
    }
  ]
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

PUT 删除待售书籍

PUT /book/delete

用户不想卖书了，或者书被买了，都可能会导致书籍不应该出现在待售书籍中。
所以前端应该在用户点击对应功能的时候，将删除请求发送到后端

请求参数

名称 位置 类型 必选 中文名 说明
id query integer 否 待售书籍的ID
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": null
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

订单模块

GET 用户的预订列表

GET /order/userReverse

后端返回用户的预订列表，其实就是用户的订单列表。
用户预订一本书后，能从预订列表中看到预订的书籍，以及这些预订书籍的状态，如果这些书籍被卖家卖给其他人，会有提示该书籍已出售给他人的提示。

在我们的预想中，买家对待售书籍只能预订，而不能真正的成功购买。买家一旦进行预订，卖家的后台就会出现买家对待售书籍的订单，同一本待售书籍可能会对应多个订单，卖家决定卖给谁，就由买卖双方通过聊天协商决定。
预订列表一个ITEM包含以下信息：

  1. 订单ID
  2. User的基本信息
  3. 待售书籍的基本信息
  4. 下单时间
  5. 售货地址
  6. 订单状态

请求参数

名称 位置 类型 必选 中文名 说明
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": {
    "id": 1,
    "user": {
      "id": 2,
      "username": "Aderversa",
      "nickname": "",
      "email": "",
      "userImg": "",
      "createTime": "2024-04-23T10:26:32",
      "updateTime": "2024-04-23T10:26:32"
    },
    "book": {
      "id": 1,
      "name": "红楼梦",
      "typeId": 1,
      "price": "59.70",
      "isbn": "978-7-02-000220-7",
      "img": null,
      "detail": "红楼梦是我国的四大名著之一",
      "releaseTime": "2024-05-03",
      "sellerId": 1,
      "sellerName": "Aderversa",
      "purchased": 0
    },
    "pay_time": "2024-04-23T10:26:32",
    "address": "广东工业大学大学城校区西3-333",
    "status": "1"
  }
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data object true none 响应数据 操作成功会返回请求的数据

POST 预订书籍

POST /book/reserve

用户预订书籍，产生订单。
定义订单的状态：

  1. 卖家正在处理
  2. 交易达成
  3. 卖家将书籍出售给他人

请求参数

名称 位置 类型 必选 中文名 说明
id query integer 是 待售书籍的ID
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": null
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

GET 用户的出售列表

GET /order/sellList

返回用户售卖书籍的信息，前端应该提供一个接口，让用户可以查看某本书籍有谁要买。

查看哪本书有谁要买的功能，将由另外的后端接口来提供
这里应该保证：用户的出售列表中只有他自己出售的列表，这就需要后端在数据库中精准地查找

请求参数

名称 位置 类型 必选 中文名 说明
Authorization header string 是 JWT令牌

返回示例

200 Response

{
  "code": 1,
  "message": "string",
  "data": "string"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

GET 查看某本待售书籍的所有预订者

GET /order/bookBuyer

只有当待售书籍的卖家ID和请求该接口的用户ID相同时，才能运行该接口。
该接口返回所有预定者的nickname和邮箱，以及对应订单的ID

请求参数

名称 位置 类型 必选 中文名 说明
id query integer 是 待售书籍的ID
Authorization header string 是 JWT令牌

返回示例

200 Response

{
  "code": 1,
  "message": "string",
  "data": "string"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

POST 确认订单

POST /order/confirm

当用户查看自己出售的某本书籍的预订者时，用户可以点击前端页面的接口来确认订单。
本接口就是用于前端发送确认订单的请求的。
当用户确认订单后，前端向后端发送请求。后端需要将订单ID对应的订单的状态设置成“2”（表示交易达成），然后将该书籍剩余订单的状态设置成“3”（表示该书籍已被卖家出售给他人），最后在待售书籍表中，删除出售的书籍。

请求参数

名称 位置 类型 必选 中文名 说明
id query integer 是 订单ID
Authorization header string 是 JWT令牌

返回示例

成功

{
  "code": 0,
  "message": "操作成功",
  "data": null
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

聊天模块

GET 获取聊天记录

GET /chat/getRecord

聊天记录需要聊天双方的ID，聊天记录将会按发送顺序从早到晚排序好发送到前端。前端将这些数据渲染出来
由于聊天双方无法得知对方何时发送消息并且后端无法通知前端接收信息，只能由前端主动请求，因此可以采用轮询的方式查看是否有新的信息。
这个接口由于技术能力不足暂时搁置

请求参数

名称 位置 类型 必选 中文名 说明
id query integer 是 用户想要交流的对方的ID
Authorization header string 是 JWT令牌

返回示例

200 Response

{
  "code": 1,
  "message": "string",
  "data": "string"
}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

状态码 200

名称 类型 必选 约束 中文名 说明
» code integer true none 响应码 0-成功；1-失败
» message string true none 响应信息 说明操作的结果
» data string true none none

POST 发送消息

POST /chat/send

发送消息给指定用户

请求参数

名称 位置 类型 必选 中文名 说明
id query integer 否 接收方ID
Authorization header string 是 JWT令牌

返回示例

200 Response

{}

返回结果

状态码 状态码含义 说明 数据模型
200 OK 成功 Inline

返回数据结构

数据模型

BaseResponse




{
  "code": 1,
  "message": "string",
  "data": "string"
}

属性

名称 类型 必选 约束 中文名 说明
code integer true none 响应码 0-成功；1-失败
message string true none 响应信息 说明操作的结果
data string true none none

博客园  ©  2004-2026
浙公网安备 33010602011771号 浙ICP备2021040463号-3