API接口设计

API 接口设计

接口地址

环境	URL
开发环境	`http://like.suevily.cn/`
生产环境	待定

通用

以下接口分为开放接口和私有接口
- 开放接口：无需登录校验即可请求
- 私有接口：需校验登录 token 方可请求
以下所有接口 url 都默认自带 /api 前缀
token 在使用统一身份验证成功登录后会附带到 redirect url 的 query 参数上，前端需自行存储，开发环境的 redirect url 为 http://localhost:8081/#/
私有接口请求方法：将 token 附在请求 Headers 中的 Authorization 字段上，value 格式为 Bearer ${token} （PS: 建议使用 postman 进行接口测试）
前端在拿到返回数据时务必先检查 code 是否为零，如若不为零，需给用户正确的反馈，回传数据遵循以下格式：

{
  code: Number,
  data: Object
}

code	说明
0	成功
-1	未知错误，查看 message
1	拒绝访问
2	无效的请求参数
3	上传图片出错
4	token 校验失败
其它	待定

获取用户信息

method	url	type
GET	/user	私有接口

请求参数

无

返回参数

参数	类型	说明
cardId	String	校园卡号
name	String	姓名
college	String	学院
stuId	String	学号
privilege	Number	0 为超级管理员，1为普通管理员，如没有该字段则为普通师生

获取管理人员

method	url	type
POST	/getManagers	私有接口

请求参数

参数	类型	说明	必填
perPage	Number	每页包含元素个数	是
page	Number	页码，第几页	是

返回参数

参数	字段	类型	说明
length	-	Number	管理人员总数
managers	-	Array	一个包含指定页数内所有管理人员的数组
-	id	Number	该管理员在数据库中的唯一标识
-	name	String	姓名
-	cardId	String	校园卡号
-	authorizer	String	授权人姓名
-	createdAt	Date	添加时间戳
-	privilege	String	管理权限，超级管理员或普通管理员

添加管理人员

method	url	type
POST	/addManager	私有接口

请求参数

参数	类型	说明	必填
name	String	姓名	是
cardId	String	校园卡号	是
privilege	Number	权限，0 为超级管理员，1为普通管理员	是

返回参数

参数	类型	说明
message	String	添加结果

错误代码

code	说明
1001	校园卡号冲突

修改管理人员

method	url	type
POST	/updateManager	私有接口

请求参数

参数	类型	说明	必填
id	Number	要修改的管理员的id	是
name	String	姓名	是
cardId	String	校园卡号	是
privilege	Number	权限，0 为超级管理员，1为普通管理员	是

返回参数

参数	类型	说明
message	String	修改结果

错误代码

code	说明
1002	当你要把最后一个超级管理员更改为普通管理员时会出错

删除管理人员

method	url	type
POST	/deleteManager	私有接口

请求参数

参数	类型	说明	必填
id	String	要删除的管理员的id	是

返回参数

参数	类型	说明
message	String	删除结果

错误代码

code	说明
1003	当你要把最后一个超级管理员删除时会出错

搜索管理人员

method	url	type
POST	/searchManagers	私有接口

请求参数

参数	类型	说明	必填
keyword	String	搜索关键词	是
maxLength	Number	搜索结果最大返回数目（默认为5）	否

返回参数

参数	字段	类型	说明
managers	-	Array	满足搜索关键词的管理员数组
-	id	Number	该管理员在数据库中的唯一标识
-	name	String	姓名
-	cardId	String	校园卡号
-	authorizer	String	授权人姓名
-	createdAt	Date	添加时间戳
-	privilege	String	管理权限，超级管理员或普通管理员

获取课程信息

method	url	type
POST	/getCourses	私有接口

请求参数

参数	类型	说明	必填
perPage	Number	每页包含元素个数	是
page	Number	页码，第几页	是

返回参数

参数	字段	类型	说明
length	-	Number	课程总数
courses	-	Array	一个包含指定页数所有课程信息的数组
-	courseName	String	课程名称
-	teacher	String	讲师姓名
	time	String	上课时间，前端直接展示即可
	courseId	String	课程编号
	location	String	上课地点
	studentCount	Number	选课人数

根据课程编号获取课程详细信息

method	url	type
POST	/getCourseInfo	私有接口

请求参数

参数	类型	说明	必填
courseId	String	课程编号	是

返回参数

参数	字段	类型	说明
courseName	-	String	课程名称
teacherId	-	String	讲师在数据库中的id
teacherName	-	String	讲师姓名
startTime	-	Date	上课开始时间戳
endTime	-	Date	上课结束时间戳
location	-	String	上课地点
students	-	Array	一个包含指定课程选课所有学生信息的数组
	name	String	学生姓名
	stuId	String	学生学号

错误代码

code	说明
2003	课程编号错误

查询选课名单

method	url	type
POST	/getStudentList	私有接口

请求参数

参数	类型	说明	必填
courseId	String	课程编号	是
perPage	Number	每页包含元素个数	是
page	Number	页码，第几页	是

返回参数

参数	字段	类型	说明
length	-	Number	选课总人数
students	-	Array	一个包含指定课程选课所有学生信息的数组
	name	String	学生姓名
	stuId	String	学生学号

删除课程

method	url	type
POST	/deleteCourse	私有接口

请求参数

参数	类型	说明	必填
courseId	String	要删除的课程的课程编号	是

返回参数

参数	类型	说明
message	String	删除结果

搜索课程

method	url	type
POST	/searchCourses	私有接口

请求参数

参数	类型	说明	必填
keyword	String	搜索关键词	是
maxLength	Number	搜索结果最大返回数目（默认为5）	否

返回参数

参数	字段	类型	说明
courses	-	Array	满足搜索关键词的课程数组
-	courseName	String	课程名称
-	teacher	String	讲师姓名
	time	String	上课时间，前端直接展示即可
	courseId	String	课程编号
	location	String	上课地点
	studentCount	Number	选课人数

生成课程

method	url	type
POST	/addCourse	私有接口

请求参数

参数	字段	类型	说明	必填
courseName	-	String	课程名称	是
teacherId	-	String	讲师在数据库中的id	是
startTime	-	Date	上课开始时间戳	是
endTime	-	Date	上课结束时间戳	是
location	-	String	上课地点	是
students	-	Array	选课学生数组	是
-	name	String	学生姓名	是
-	stuId	String	学生学号	是

返回参数

参数	类型	说明
courseId	String	生成的课程编号

错误代码

code	说明
2001	讲师不存在

修改课程

method	url	type
POST	/updateCourse	私有接口

请求参数

参数	字段	类型	说明	必填
courseId	-	String	课程编号（乱传打爆你▄︻┻═┳一）	是
courseName	-	String	课程名称	是
teacherId	-	String	讲师在数据库中的id	是
startTime	-	String	上课开始时间戳	是
endTime	-	String	上课结束时间戳	是
location	-	String	上课地点	是
students	-	Array	选课学生数组	是
-	name	String	学生姓名	是
-	stuId	String	学生学号	是

返回参数

参数	类型	说明
message	String	修改结果

错误代码

code	说明
2001	讲师不存在
2002	课程编号不存在

获取讲师信息

method	url	type
POST	/getTeachers	私有接口

请求参数

参数	类型	说明	必填
perPage	Number	每页包含元素个数	是
page	Number	页码，第几页	是

返回参数

参数	字段	类型	说明
length	-	Number	讲师总数
teachers	-	Array	一个包含指定页数所有讲师信息的数组
-	id	Number	该讲师在数据库的唯一标识
-	name	String	讲师姓名
	imageUrl	String	讲师照片的 url

删除讲师

method	url	type
POST	/deleteTeacher	私有接口

请求参数

参数	类型	说明	必填
id	Number	讲师 id ，在 `/getTeachers` 接口获取到的	是

返回参数

参数	类型	说明
message	String	删除结果

搜索讲师

method	url	type
POST	/searchTeachers	私有接口

请求参数

参数	类型	说明	必填
keyword	String	搜索关键词	是
maxLength	Number	搜索结果最大返回数目（默认为5）	否

返回参数

参数	字段	类型	说明
teachers	-	Array	满足搜索关键字的讲师数组
	id	Number	该讲师在数据库的唯一标识
-	name	String	讲师姓名
	imageUrl	String	讲师照片的 url

查询一个讲师的详细信息

method	url	type
POST	/getTeacherInfo	私有接口

请求参数

参数	类型	说明	必填
id	Number	讲师 id ，在 `/getTeachers` 接口获取到的	是

返回参数

参数	字段	类型	说明
name	-	String	讲师姓名
college	-	String	所属单位
intro	-	String	老师简介
phone	-	String	手机号码
office	-	String	办公地址
email	-	String	邮箱地址
imageUrl	-	String	导师照片 url
teachForm	-	String	授课形式
teachTopic	-	Array	该讲师授课专题的数组
	-	String	授课专题

图片上传接口

method	url	type
POST	/upload	私有接口

请求参数

参数	类型	说明	必填
-	FormData	图片数据	是

返回参数

参数	类型	说明
url	String	图片 url

添加讲师

method	url	type
POST	/addTeacher	私有接口

请求参数

参数	字段	类型	说明	必填
name	-	String	讲师姓名	是
college	-	String	所属单位	是
intro	-	String	老师简介	是
phone	-	String	手机号码	是
office	-	String	办公地址	是
email	-	String	邮箱地址	是
imageUrl	-	String	导师照片 url	是
teachForm	-	String	授课形式	是
teachTopic	-	Array	该讲师授课专题的数组	是
	-	String	授课专题	是

返回参数

参数	类型	说明
id	Number	该讲师在数据库的唯一标识

修改讲师信息

method	url	type
POST	/updateTeacher	私有接口

请求参数

参数	字段	类型	说明	必填
id	-	Number	要修改的讲师的 id	是
name	-	String	讲师姓名	是
college	-	String	所属单位	是
intro	-	String	老师简介	是
phone	-	String	手机号码	是
office	-	String	办公地址	是
email	-	String	邮箱地址	是
imageUrl	-	String	导师照片 url	是
teachForm	-	String	授课形式	是
teachTopic	-	Array	该讲师授课专题的数组	是
	-	String	授课专题	是

返回参数

参数	类型	说明
message	String	修改结果

错误代码

code	说明
3001	指定 id 的老师不存在