接口须知

后端技术栈

  • Spring
  • SpringBoot
  • junit
  • aliyun-oss
  • spring-session
  • mysql
  • lombok
  • hutool-http
  • fastjson
  • mybatis-plus
  • JWT
  • pagehelper
  • jackson
  • aspectjrt

关于响应结果

  • 返回数据采用统一响应结果
{
	"code":200,
	"msg":"操作成功",
	"data":...
}
  • code为int类型，表示响应码：200成功，4xx客户端错误，5xx服务器错误
  • msg为String类型，表示提示信息
  • data类型不限，是后端返回的数据

关于权限校验

  • 在初始开发阶段，不对接口进行权限校验。
  • 接口的权限校验基于SpringSecurity和JWT。
  • 在登录后收到JWT令牌，存入本地存储。
  • 此后所有的接口访问都需要在请求头(Header)中添加Authorization参数
  • Authorization的内容为：Bearer
  • 后端在收到令牌后会对请求的身份进行校验。
  • 若校验不通过，则返回如下数据：
{     
	"code": 500,     
	"msg": "NO_LOGIN",      
	"data": null  
}

关于会话验证

  • 考虑到跨域请求的问题，不使用传统session和cookie进行验证是否为同一请求。
  • 使用jwt技术和redis相结合进行会话校验。
  • 所以在第一次请求后一定会包含sessionId或者token来标识客户端，前端需要妥善保管这两个值。

预约相关接口

预约信息上传

  • 接口描述：

填写预约表单

  • 请求方式：POST

  • 接口地址：/posts/release

  • 请求参数
    | 参数名称 | 参数类型 | 是否必须 | 备注 |
    | ----------- | --------- | -------- | ----------------------------------- |
    | serviceType | int | 是 | 服务类型 |
    | userName | String | 是 | 申请者姓名 |
    | className | String | 是 | 专业班级 |
    | place | String | 是 | 地点 |
    | timestamp | timestamp | 是 | 预约时间，格式为yyyy-MM-dd HH:mm:ss |
    | phone | String | 是 | 联系手机 |
    | studentId | String | 是 | 学生id |
    | details | String | 是 | 详细信息 |
    | imageIds | String | 是 | 图片，为image的id集合 |

  • 时间格式：yyyy-MM-dd HH:mm:ss

  • 请求示例：

    • 参数格式：application/json
{
    "serviceType": 1,
    "userName": "QC",
    "className": "软件工程222",
    "place": "劲竹327",
    "timestamp": "2023-05-10 14:17:29",
    "phone": "18357789776",
    "studentId": "1220204124",
    "details": "测试测试测试",
    "imageIds": [
                    "1653429808434016257",
                    "1653576591235710978"
                ]
}
  • 响应示例：
    • 格式：application/json
{
    "code": 200,
    "msg": "发布成功",
    "data": null
}
  • code为200表示服务器正常响应，4xx客户端错误，5xx服务器错误
  • msg为提示词
  • data表示后端返回的数字，此时为null表示发布后后端为传回数据

列举预约帖子

  • 接口描述：

获取全部的预约帖子
对于用户，通过用户验证，查找是哪个用户，放回对于用户发布预约帖子的信息
对于管理员，则列举全部帖子

  • 请求方式：GET

  • 接口地址：/posts/list

  • 请求参数：无

  • 响应示例：

    • 参数格式：application/json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": "1653602310892306433",
            "author": "1651586727296425986",
            "serviceType": 1,
            "userName": "QC",
            "className": "软件工程222",
            "place": "劲竹327",
            "timestamp": "1970-01-20 19:31:24.0",
            "phone": "18357789776",
            "studentId": "1220204124",
            "details": "测试测试测试",
            "status": 0,
            "msg": null,
            "createTime": "2023-05-03 11:28:08.0",
            "imageIds": [
                "1653429808434016257",
                "1653576591235710978"
            ]
        },
        {
            "id": "1653602561728462850",
            "author": "1651586727296425986",
            "serviceType": 1,
            "userName": "QC",
            "className": "软件工程222",
            "place": "劲竹327",
            "timestamp": "1970-01-20 19:31:24.0",
            "phone": "18357789776",
            "studentId": "1220204124",
            "details": "测试测试测试",
            "status": 0,
            "msg": "",
            "createTime": "2023-05-03 11:29:07.0",
            "imageIds": [
                "1653429808434016257",
                "1653576591235710978"
            ]
        }
    ]
}
  • 响应失败示例：表示未登录
{
    "code": 500,
    "msg": "NOT_LOGIN"
}

分页查询帖子

  • 接口描述：

分页查询帖子，可传入关键词进行筛选
对于用户，通过用户验证，查找是哪个用户，放回对于用户发布预约帖子的信息
对于管理员，则列举全部帖子

  • 请求方式：GET

  • 接口地址：/posts

  • 请求参数：

    • 格式：queryString
      | 参数名 | 类型 | 是否必须 | 备注 |
      | ------ | ------ | -------- | -------------------- |
      | page | String | 是 | 当前页数 |
      | size | String | 是 | 每页大小（几个对象） |
      | search | String | 否 | 关键字 |

  • 请求示例：/posts/page?page=2&size=4

  • 请求示例：/posts/page?page=2&size=4&search=劲竹

  • 响应示例：

    • 参数格式：application/json
{
    "code": 200,
    "msg": "success",
    "data": {
        "total": "2",
        "records": [
            {
                "id": "1653602561728462850",
                "author": "1651586727296425986",
                "serviceType": 1,
                "userName": "QC",
                "className": "软件工程222",
                "place": "劲竹327",
                "timestamp": "1970-01-20 19:31:24.0",
                "phone": "18357789776",
                "studentId": "1220204124",
                "details": "测试测试测试",
                "status": 0,
                "msg": "123123123",
                "createTime": "2023-05-03 11:29:07.0",
                "imageIds": [
                    "1653429808434016257",
                    "1653576591235710978"
                ]
            },
            {
                "id": "1653602310892306433",
                "author": "1651586727296425986",
                "serviceType": 1,
                "userName": "QC",
                "className": "软件工程222",
                "place": "劲竹327",
                "timestamp": "1970-01-20 19:31:24.0",
                "phone": "18357789776",
                "studentId": "1220204124",
                "details": "测试测试测试",
                "status": 0,
                "msg": null,
                "createTime": "2023-05-03 11:28:08.0",
                "imageIds": [
                    "1653429808434016257",
                    "1653576591235710978"
                ]
            }
        ]
    }
}

  • data中tatal表示的是当前返回的数据数量，records是列举出来的帖子

  • 响应失败示例：表示未登录

{
    "code": 500,
    "msg": "NOT_LOGIN"
}

获取帖子总数

  • 接口描述：

根据关键字查询匹配的帖子，返回数量
对于用户，通过用户验证，查找是哪个用户，放回对于用户发布预约帖子的信息
对于管理员，则列举全部帖子

  • 请求方式：GET

  • 接口地址：/posts/total

  • 请求参数：

    • 格式：queryString
      | 参数名 | 类型 | 是否必须 | 备注 |
      | ------ | ------ | -------- | ------ |
      | search | String | 否 | 关键字 |

  • 请求示例：/posts/total?search=劲竹

  • 响应示例：

    • 参数格式：application/json
{
    "code": 200,
    "msg": "success",
    "data": "12"
}
  • data返回数量

上传下载

上传图片

  • 接口描述：

上传文件

  • 请求方式：POST

  • 接口地址：/common/upload

  • 请求参数：

    • 格式：multipart/form-data
      | 参数名称 | 参数类型 | 是否必须 | 备注 |
      | -------- | -------- | -------- | -------- |
      | imaage | file | 是 | 上传图片 |

  • 响应数据：

    • 参数格式：application/json
{
    "code": 200,
    "msg": "文件上传成功",
    "data": {
        "id": "1653721858752167937",
        "originalFilename": "红-日.webp",
        "url": "/common/download/红-日.webp",
        "uploadUser": "1653704050551590913",
        "uploadTime": "2023-05-03 19:23:10"
    }
}

{
    "code": 200,
    "msg": "重复的文件",
    "data": {
        "id": "1653721858752167937",
        "originalFilename": "红-日.webp",
        "url": "/common/download/红-日.webp",
        "uploadUser": "1653704050551590913",
        "uploadTime": "2023-05-03 19:23:10"
    }
}
  • msg为"文件上传成功"或"重复的文件"
  • data中返回图片的相关信息，其中url可以作为图片的src进行回显，在表单上传时也需要这个链接地址。如果文件已经存在，则直接返回数据库中的信息。

文件下载1

  • 接口描述：

根据文件名或者id查询图片链接

  • 请求方式：GET

  • 接口地址：common/download

  • 请求参数：queryString
    | 参数名 | 类型 | 是否必须 | 备注 |
    | ------ | ------ | -------- | ------ |
    | name | String | 二选一 | 文件名 |
    | id | String | 二选一 | 文件id |

  • 请求示例1：/common/download?name=code.png

  • 请求示例2：/common/download?id=1653757308967632897

  • 响应数据：文件

文件下载2

  • 接口描述：

根据文件名查询图片链接

  • 请求方式：GET

  • 接口地址：common/download/

  • 请求参数：PathVariable
    | 参数名 | 类型 | 是否必须 | 备注 |
    | ------ | ------ | -------- | ------ |
    | name | String | 是 | 文件名 |

  • 请求示例：/common/download/code.png

  • 响应数据：文件

列举文件

  • 接口描述：

获取所有的图片文件

  • 请求方式：GET

  • 接口地址：/common/list

  • 请求参数：无

  • 响应示例：

    • 格式：application/json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": "2132762627",
            "originalFilename": "123",
            "url": "/common/download?id=2132762627",
            "uploadTime": "2023-04-01 17:49:38",
            "uploadUserName": "未知用户"
        },
        {
            "id": "1653429808434016257",
            "originalFilename": "QQ截图20230110192939.png",
            "url": "/common/download?id=1653429808434016257",
            "uploadTime": "2023-05-03 00:02:40",
            "uploadUserName": "未知用户"
        }
    ]
}
  • 响应参数：
    | 参数名 | 类型 | 是否必须 | 备注 |
    | ---------------- | ------ | -------- | ------------ |
    | id | String | 是 | 图片id |
    | originalFilename | String | 是 | 文件名 |
    | url | String | 是 | 图片下载地址 |
    | uploadTime | String | 是 | 上传时间 |
    | uploadUserName | String | 是 | 上传用户名 |

用户登录

获取sessionId

  • 接口描述：

获取后端登录凭证

  • 请求方式：GET

  • 接口地址：/user/getSessionId

  • 请求参数：

    • 格式：queryString
      | 参数名 | 类型 | 是否必须 | 备注 |
      | ------ | ------ | -------- | ------ |
      | code | String | 是 | 微信登录凭证 |

  • 请求示例：/user/getSessionId?code=abc123456789

  • 响应示例：

    • 格式：application/json
{	
	"code": 200,
	 "msg": "success",	
	 "data": {		
		 "sessionId": "1ed57a89-a550-409a-baf1-8b6ef1582600"	
	 }
 }
  • 失败示例：
{	
	"code": 500,
	"msg": "invalid appid",
	"data": null
}
  • 参数说明：sessionId为登录凭证

微信登录

  • 接口描述：

上传加密的用户信息，后端进行解密验证登录

  • 请求方式：POST

  • 接口地址：/user/authLogin

  • 请求参数：
    | 参数名 | 类型 | 是否必须 | 备注 |
    | ------------- | ------ | -------- | -------------- |
    | encryptedData | String | 是 | 加密的用户信息 |
    | iv | String | 是 | 加密初始向量 |
    | sessionId | String | 是 | 后端登录凭证 |

  • 请求示例：

    • 格式：application/json
{  
	"encryptedData": "2fvjouA8ykrvyhfIhPwsuE6JhA9UrAQrDJCl8pemYLFBmW7sQJtCGfTck5wy3ATTn1Ig5tt3c+YirtyAo0r+7omK/RM8si+cakQ6rrcfcgeOFvh5DPJFdtPiE4sdfbHLk2zL2G0AEL0wZuenr5edxlQIHiqEzAui0Wj4ml2W9BPkVxs3J0KbfDr8x7gkUgmQq5rNgZP4goMXTSzEguRbuOX09OGLryJKFGRhOEiUexcHWnMPgOyQYrI7d2pJxTHOHJwPI6vvsmjaxr9oUmZEDqnNhA7Z2oMRxW64u0onRKvZRxU8iR/SO7BHTyed0PHp4eUaDFt1ICmlCSSinH1KVDhOBqBhOsCbnW0wSixx0j4oe3npuEr4oL0mw5UgNQDJsRFYcUNZH4Bu798OLnxj+RuBqlSbI/UU9Bd7PwfnkTcJy2WczZnTuqxXvWgsTDfa",    
	 "iv": "Ebefqfdxp03bW+lAoXBPPA==",    
	 "sessionId": "1ed57a89-a550-409a-baf1-8b6ef1582600"
}
  • 响应示例：
    • 格式：application/json
{
	"code": 200,
	"msg": "success",
	"data": {
		"id": "1651172985932300290",
		"nickName": "前程QCQCQC",
		"city": "温州",
		"province": "浙江",
		"country": "中国",
		"avatar": "http://web-myapp.oss-cn-beijing.aliyuncs.com/2023-04-20/%E5%A4%B4%E5%83%8F1681999217002.jpg",
		"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODMxMTQ2NjB9.aIVO88dVCrkJcTFGbDFXWP5vNTu8MRZaLg3c-hNmM6g",
		"status": 1
	}
}
  • 参数说明：
    | 参数名 | 参数类型 | 是否必须 | 备注 |
    | --------- | -------- | -------- | ----------- |
    | code | String | 是 | 响应码 |
    | msg | String | 是 | 消息 |
    | data | Object | 是 | 数据 |
    | -id | String | 是 | 用户标识 |
    | -nickName | String | 是 | 用户名 |
    | -city | String | 是 | 城市 |
    | -province | String | 是 | 省份 |
    | -country | String | 是 | 国家 |
    | -avatar | String | 是 | 头像URL |
    | -token | String | 是 | JWT身份凭证 |
    | -status | int | 是 | 启用状态 |

通过手机号注册用户，发送短信验证码接口

  • 接口描述：

提供openid与手机号，用于注册用户

  • 请求方式：GET

  • 接口地址：/user/sendSms

  • 请求参数：

  • 格式：queryString
    | 参数名 | 类型 | 是否必须 | 备注 |
    | ------------- | ------ | -------- | -------------- |
    | phone | String | 是 | 手机号 |
    | openId | String | 是 | 微信唯一id |

  • 请求示例：/user/sendSms?phone=18357789776&openId=testtesttesttest

  • 响应成功：

{
	"code": 200,
	"msg": "success",
	"data": {
		"sessionId": "21533ea6-db3b-4c03-800e-11eb10836424"
	}
}
  • 响应失败:
{ 
	"code": 500,
	"msg": "验证码已发送，请勿重复发送", 
	"data": null 
}
  • 参数说明：sessionId为会话标识

注意：前端一定要妥善保管sessionId，在提交验证时会使用到，短信验证接口，对于每一个号码的发送间隔时限为1分钟，每一个验证码的有效期为5分钟。值得一提的是这里的openId是必须的，作为注册或者登录的用户唯一标识，前端可以通过wx.login来获取这个openId将其发送给后端。

通过手机号注册用户，验证短信验证码接口

  • 接口描述：

校验验证码进行注册或登录

  • 请求方式：POST

  • 接口地址：/user/smsLogin

  • 请求参数：
    | 参数名 | 类型 | 是否必须 | 备注 |
    | ------------- | ------ | -------- | -------------- |
    | code | String | 是 | 验证码 |
    | sessionId | String | 是 | 会话标识 |

  • 请求示例：

    • 格式：application/json
{    
	"code": "278042",    
	"sessionId": "aca85665-cf8e-4c2a-b05d-33ecaf4934f8"
}
  • 成功示例：
{	
	"code": 200,	
	"msg": "success",	
	"data": {		
		"id": "1651939555080683522",		
		"nickName": "18357789776",		
		"city": null,	
		"province": null,	
		"country": null,		
		"avatar": null,		
		"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODMzNDc3MDN9.EfiiYDH8IVYOVFxIK-JGpj362MyTMJRGwNPW3rVZBCk",	
		"status": 0	
	}
}
  • 失败案例
{	
	"code": 500,	
	"msg": "验证码已过期，请重新获取",	
	"data": null
}
  • 参数说明：
    | 参数名 | 参数类型 | 是否必须 | 备注 |
    | --------- | -------- | -------- | ----------- |
    | code | String | 是 | 响应码 |
    | msg | String | 是 | 消息 |
    | data | Object | 是 | 数据 |
    | -id | String | 是 | 用户标识 |
    | -nickName | String | 是 | 用户名 |
    | -city | String | 是 | 城市 |
    | -province | String | 是 | 省份 |
    | -country | String | 是 | 国家 |
    | -avatar | String | 是 | 头像URL |
    | -token | String | 是 | JWT身份凭证 |
    | -status | int | 是 | 启用状态 |

获取用户信息

  • 接口描述：

用户自己获取个人信息

  • 请求方式：GET

  • 接口地址：/user/userinfo

  • 请求参数：

    • 格式：queryString
      | 参数名 | 类型 | 是否必须 | 备注 |
      | ------ | ------ | -------- | ------ |
      | refresh | int | 是 | 是否刷新 |

  • 请求示例：/user/userinfo?refresh=0

  • 响应示例：

    • 参数格式：application/json
{
    "code": 200,
    "msg": "success",
    "data": {
        "id": "1653704050551590913",
        "nickName": "微信用户",
        "city": "",
        "province": "",
        "country": "",
        "avatar": "https://thirdwx.qlogo.cn/mmopen/vi_32/POgEwh4mIHO4nibH0KlMECNjjGxQUq24ZEaGT4poC6icRiccVGKSyXwibcPq4BWmiaIGuG1icwxaQX6grC9VemZoJ8rg/132",
        "phone": null,
        "token": null,
        "status": 1
    }
}
  • data参数解释：
    | 参数名 | 类型 | 备注 |
    | -------- | ------ | ---------------------------- |
    | id | String | 用户id |
    | nickName | String | 用户名 |
    | city | String | 城市 |
    | province | String | 省份 |
    | country | String | 国家 |
    | avatar | String | 头像，图片id |
    | phone | String | 手机号注册的用户会有这个信息 |
    | token | String|根据用户id重新生成的token |
    | status | int|用户状态，1启用0禁用 |

更新用户信息

  • 接口描述：

提交需要更改的用户信息，id为必须字段，其他可以没有

  • 请求方式：PUT

  • 接口地址：/user/userinfo

  • 请求参数：
    | 参数名 | 参数类型 | 是否必须 | 备注 |
    | -------- | -------- | -------- | -------- |
    | id | String | 是 | 用户标识 |
    | nickName | String | 否 | 用户名 |
    | city | String | 否 | 城市 |
    | province | String | 否 | 省份 |
    | country | String | 否 | 国家 |
    | avatar | String | 否 | 头像地址 |
    | gender | int | 否 | 性别 |
    | status | int | 否 | 启用状态 |

  • 请求示例：

    • 格式：application/json
{ 
	"id": "1651172985932300290", 
	"nickName": "前程QCQCQC", 
	"city": "温州", 
	"province": "浙江", 
	"country": "中国",
	"avatar": "http://web-myapp.oss-cn-beijing.aliyuncs.com/2023-04-20/%E5%A4%B4%E5%83%8F1681999217002.jpg", 
	"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODMxMTMzMzZ9.KdbgmoC5guQgpnQrwnxzbCRYXBWvva0EShGivH7m9U8", 
	"status": 1 
}
  • 响应成功示例：
{	
	"code": 200,	
	"msg": "success",	
	"data": {		
		"id": "1651172985932300290",		
		"nickName": "前程QCQCQC",		
		"gender": 0,		
		"city": "温州",		
		"province": "浙江",		
		"country": "中国",		
		"avatar": "http://web-myapp.oss-cn-beijing.aliyuncs.com/2023-04-20/%E5%A4%B4%E5%83%8F1681999217002.jpg",		
		"status": 1	
	}
}
  • 失败示例：
{	
	"code": 500,	
	"msg": "更新失败",	
	"data": null
}
  • 参数说明：
    | 参数名 | 参数类型 | 是否必须 | 备注 |
    | -------- | -------- | -------- | -------- |
    | code | String | 是 | 响应码 |
    | msg | String | 是 | 消息 |
    | data | String | 是 | 数据 |
    | id | String | 是 | 用户标识 |
    | nickName | String | 否 | 用户名 |
    | city | String | 否 | 城市 |
    | province | String | 否 | 省份 |
    | country | String | 否 | 国家 |
    | avatar | String | 否 | 头像地址 |
    | gender | int | 否 | 性别 |
    | status | int | 否 | 启用状态 |

注意：这里的更新用户数据接口可以复用，比如开发禁用某个用户时，只需要将status设为0，后端会自动进行鉴权等操作，若status为0则返回用户已经禁用。

后台管理界面

后台管理员登录

  • 接口描述：

  • 请求方式：POST

  • 接口地址：/employee/login

  • 请求参数：

    • 格式：application/json

  • 请求示例：

{
    "username": "admin",
    "password": "adminadmin"
}
  • 响应示例：
{
    "code": 200,
    "msg": "success",
    "data": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2ODQzMzIyNjd9.B97MzlnvclotDCAskLPdpFXLVTpHhboMsm2Ab8ER1rM"
}
  • 参数说明：
  • data记录了jwt令牌，用来验证身份

查询系统信息

  • 接口描述：

  • 请求方式：

  • 接口地址：

  • 请求参数：

    • 格式：

  • 请求示例：

  • 响应示例：

  • 参数说明：

后台获取管理员信息

  • 接口描述：

  • 请求方式：GET

  • 接口地址：/employee/userinfo

  • 请求参数：无

  • 响应示例：

{
    "code": 200,
    "msg": "success",
    "data": {
        "id": "1",
        "username": "admin",
        "avatar": "https://img.51miz.com/Element/00/88/60/42/3cb805be_E886042_a75650be.png",
        "name": "Admin",
        "password": "PASSWORD_NOT_DISPLAYED",
        "phone": null,
        "sex": null,
        "status": 1,
        "createTime": "2023-05-05 21:36:28",
        "updateTime": "2023-05-05 21:36:28",
        "createUser": "0",
        "updateUser": "0"
    }
}
  • 失败示例：
{
    "code": 500,
    "msg": "Cannot invoke \"cn.bluecore.bookapp.pojo.Employee.setPassword(String)\" because \"currentEmployee\" is null",
    "data": null
}
  • 参数说明：