Web作业（八）
API 接口文档
1. 技术架构
┌─────────────────────────────────────────┐ │ 前端层 │ Vue 3 + Element Plus │ │ │ (静态 HTML，CDN 引入) │ ├─────────────────────────────────────────┤ │ Controller │ EmpController │ │ (REST API) │ DeptController │ ├─────────────────────────────────────────┤ │ Mapper 层 │ EmpMapper (MyBatis) │ │ (数据访问) │ DeptMapper (MyBatis) │ ├─────────────────────────────────────────┤ │ 数据库 │ Microsoft SQL Server │ │ │ 库名: 2026shangke │ └─────────────────────────────────────────┘| 层级 | 技术 | 说明 |
|---|---|---|
| 框架 | Spring Boot 3.5.15 | 内嵌 Tomcat，提供 Web 服务 |
| 持久层 | MyBatis 3.0.5 | 注解式 SQL 映射，#{}防注入 |
| 数据库 | SQL Server | 通过mssql-jdbc驱动连接 |
| 前端 | Vue 3 + Element Plus | CDN 引入，无需构建工具 |
| 工具 | Lombok | 自动生成 getter/setter/toString |
2. 统一响应格式
所有接口返回 JSON，结构统一为Result对象：
{"code":1,// 状态码：1 = 成功，0 = 失败"msg":"操作成功",// 提示信息"data":{}// 响应数据（可能是对象、数组或 null）}| 字段 | 类型 | 说明 |
|---|---|---|
code | Integer | 1成功，0失败 |
msg | String | 操作结果的描述信息 |
data | Object | 业务数据，查询时返回，增删改时通常为null |
3. 员工管理接口
基础路径：/api/emps
3.1 查询员工列表（条件搜索）
支持按姓名模糊搜索、性别筛选、入职日期范围筛选。所有参数均可选，不传则不参与筛选。
请求
GET /api/emps?name=&gender=&begin=&end=| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | String | 否 | 员工姓名，模糊匹配（LIKE %xxx%） |
gender | Short | 否 | 性别：1男，2女 |
begin | String | 否 | 入职开始日期，格式YYYY-MM-DD |
end | String | 否 | 入职结束日期，格式YYYY-MM-DD |
请求示例
# 无条件查询全部 GET /api/emps # 按姓名模糊搜索 GET /api/emps?name=张 # 查询所有男员工 GET /api/emps?gender=1 # 查询 2010-01-01 到 2020-12-31 入职的员工 GET /api/emps?begin=2010-01-01&end=2020-12-31 # 组合查询：姓张的男员工，2000年后入职 GET /api/emps?name=张&gender=1&begin=2000-01-01&end=2100-12-31成功响应200 OK
{"code":1,"msg":"操作成功","data":[{"id":1,"username":"jinyong","password":"123456","name":"金庸","gender":1,"image":"1.jpg","job":4,"entrydate":"2000-01-01","deptId":2,"createTime":"2026-06-24T10:00:00","updateTime":"2026-06-24T10:00:00"},{"id":2,"username":"zhangwuji","password":"123456","name":"张无忌","gender":1,"image":"2.jpg","job":2,"entrydate":"2015-01-01","deptId":2,"createTime":"2026-06-24T10:00:00","updateTime":"2026-06-24T10:00:00"}]}3.2 根据 ID 查询员工
请求
GET /api/emps/{id}| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | Integer | 是 | 员工 ID（路径参数） |
请求示例
GET /api/emps/1成功响应200 OK
{"code":1,"msg":"操作成功","data":{"id":1,"username":"jinyong","password":"123456","name":"金庸","gender":1,"image":"1.jpg","job":4,"entrydate":"2000-01-01","deptId":2,"createTime":"2026-06-24T10:00:00","updateTime":"2026-06-24T10:00:00"}}失败响应200 OK
{"code":0,"msg":"员工不存在","data":null}3.3 新增员工
请求
POST /api/emps Content-Type: application/json| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
username | String | 是 | 用户名，必须唯一 |
name | String | 是 | 姓名 |
gender | Short | 是 | 性别：1男，2女 |
job | Short | 是 | 职位编码（详见 数据字典） |
deptId | Integer | 是 | 部门 ID |
entrydate | String | 是 | 入职日期，格式YYYY-MM-DD |
password | String | 否 | 密码，不传则默认为123456 |
image | String | 否 | 头像文件名，如1.jpg |
注意：
id、createTime、updateTime由后端自动生成，不需要传。
请求示例
{"username":"zhangsan","name":"张三","gender":1,"image":"default.jpg","job":2,"entrydate":"2024-06-01","deptId":3}成功响应200 OK
{"code":1,"msg":"操作成功","data":null}3.4 修改员工
请求
PUT /api/emps Content-Type: application/json| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | Integer | 是 | 要修改的员工 ID |
username | String | 是 | 用户名 |
name | String | 是 | 姓名 |
gender | Short | 是 | 性别 |
job | Short | 是 | 职位编码 |
deptId | Integer | 是 | 部门 ID |
entrydate | String | 是 | 入职日期 |
image | String | 否 | 头像文件名 |
password | String | 否 | 密码 |
注意：
updateTime由后端自动更新。
请求示例
{"id":18,"username":"songdaxia","name":"老宋","gender":1,"image":"2.jpg","job":2,"entrydate":"2012-01-01","deptId":2}成功响应200 OK
{"code":1,"msg":"操作成功","data":null}3.5 删除员工
请求
DELETE /api/emps/{id}| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | Integer | 是 | 员工 ID（路径参数） |
请求示例
DELETE /api/emps/23成功响应200 OK
{"code":1,"msg":"操作成功","data":null}4. 部门管理接口
基础路径：/api/depts
4.1 查询全部部门
请求
GET /api/depts无参数，返回所有部门。
成功响应200 OK
{"code":1,"msg":"操作成功","data":[{"id":1,"name":"学工部","createTime":"2026-06-24T10:00:00","updateTime":"2026-06-24T10:00:00"},{"id":2,"name":"教研部","createTime":"2026-06-24T10:00:00","updateTime":"2026-06-24T10:00:00"}]}4.2 根据 ID 查询部门
请求
GET /api/depts/{id}| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | Integer | 是 | 部门 ID（路径参数） |
请求示例
GET /api/depts/1失败响应
{"code":0,"msg":"部门不存在","data":null}4.3 新增部门
请求
POST /api/depts Content-Type: application/json| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
name | String | 是 | 部门名称，最长 10 个字符，必须唯一 |
请求示例
{"name":"财务部"}成功响应200 OK
{"code":1,"msg":"操作成功","data":null}4.4 修改部门
请求
PUT /api/depts Content-Type: application/json| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | Integer | 是 | 要修改的部门 ID |
name | String | 是 | 新的部门名称，最长 10 个字符 |
请求示例
{"id":1,"name":"学生工作部"}成功响应200 OK
{"code":1,"msg":"操作成功","data":null}4.5 删除部门
请求
DELETE /api/depts/{id}| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | Integer | 是 | 部门 ID（路径参数） |
请求示例
DELETE /api/depts/6⚠️ 如果该部门下有员工，SQL Server 的外键约束可能导致删除失败。
成功响应200 OK
{"code":1,"msg":"操作成功","data":null}5. 数据字典
5.1 性别枚举
| 编码 | 含义 |
|---|---|
1 | 男 |
2 | 女 |
5.2 职位枚举
| 编码 | 含义 |
|---|---|
1 | 班主任 |
2 | 讲师 |
3 | 学工主管 |
4 | 教研主管 |
5 | 咨询师 |
5.3 部门初始数据
| ID | 部门名称 |
|---|---|
| 1 | 学工部 |
| 2 | 教研部 |
| 3 | 咨询部 |
| 4 | 就业部 |
| 5 | 人事部 |
6. 前端页面
| 页面 | URL | 说明 |
|---|---|---|
| 首页 | http://localhost:8080/index.html | 系统概览，显示员工/部门统计卡片 |
| 员工管理 | http://localhost:8080/emp.html | 员工搜索、新增、编辑、删除 |
| 部门管理 | http://localhost:8080/dept.html | 部门新增、编辑、删除 |
前端使用 Vue 3 + Element Plus（通过 CDN 引入），无需额外安装依赖，Spring Boot 直接从static/目录提供静态文件服务。
前端调用后端流程：
用户操作页面（emp.html） → fetch('/api/emps', {method: 'GET/POST/PUT/DELETE'}) → EmpController 接收请求 → EmpMapper 执行 SQL → SQL Server 数据库 → 返回 Result JSON → 前端解析 response.json() → 更新页面数据7. 数据库表结构
7.1 员工表（emp）
| 字段 | 类型 | 说明 |
|---|---|---|
id | INT IDENTITY(1,1) PRIMARY KEY | 主键，自增 |
username | VARCHAR(20) NOT NULL UNIQUE | 用户名 |
password | VARCHAR(32) DEFAULT '123456' | 密码，默认 123456 |
name | VARCHAR(10) NOT NULL | 姓名 |
gender | TINYINT NOT NULL | 性别：1 男，2 女 |
image | VARCHAR(300) | 头像文件名 |
job | TINYINT | 职位编码 |
entrydate | DATE | 入职日期 |
dept_id | INT | 部门 ID |
create_time | DATETIME2 NOT NULL | 创建时间 |
update_time | DATETIME2 NOT NULL | 修改时间 |
7.2 部门表（dept）
| 字段 | 类型 | 说明 |
|---|---|---|
id | INT IDENTITY(1,1) PRIMARY KEY | 主键，自增 |
name | VARCHAR(10) NOT NULL UNIQUE | 部门名称 |
create_time | DATETIME2 NOT NULL | 创建时间 |
update_time | DATETIME2 NOT NULL | 修改时间 |
附录 A：接口速查表
| HTTP 方法 | URL | 说明 |
|---|---|---|
GET | /api/emps | 条件查询员工列表（支持 name/gender/begin/end） |
GET | /api/emps/{id} | 根据 ID 查询单个员工 |
POST | /api/emps | 新增员工 |
PUT | /api/emps | 修改员工 |
DELETE | /api/emps/{id} | 删除员工 |
GET | /api/depts | 查询全部部门 |
GET | /api/depts/{id} | 根据 ID 查询部门 |
POST | /api/depts | 新增部门 |
PUT | /api/depts | 修改部门 |
DELETE | /api/depts/{id} | 删除部门 |
附录 B：动态 SQL 说明
员工列表查询接口使用了 MyBatis 动态 SQL，底层对应的 SQL 模板为：
<where><iftest='name != null and name != ""'>and name like concat('%', #{name}, '%')</if><iftest='gender != null'>and gender = #{gender}</if><iftest='begin != null'>and entrydate >= #{begin}</if><iftest='end != null'>and entrydate <= #{end}</if></where>- 只有前端传了某个参数，对应的 WHERE 条件才生效
#{name}使用预编译参数，天然防止 SQL 注入- MyBatis 自动处理多余的
AND关键字