# 第四阶段教案：前端基础 + 项目整合（第 4 周）

> **学习周期**：7 天
> **每日用时**：2-3 小时
> **里程碑**：学生管理系统 v1 — Spring Boot + JPA/MP 双轨 + 原生 JS 全栈应用

---

## 前置准备

1. 执行 `sql/init.sql` 初始化数据库（在你的 MySQL 中）
2. IDEA 打开 `week4/pom.xml`
3. 确认 `application.yml` 中数据库密码正确

---

## 第 1 天：JavaScript 基础 —— 让页面"动"起来

### 核心概念

| 概念 | 解释 | 类比 |
|------|------|------|
| **变量** | `let name = "张三"` — 存放数据的容器 | 贴了标签的盒子 |
| **函数** | `function add(a, b) { return a + b; }` — 可复用的代码块 | 微波炉：输入食材，输出热菜 |
| **DOM** | Document Object Model — 把 HTML 文档变成 JS 可操作的对象树 | 遥控器：通过 JS 操控页面元素 |
| **事件** | 用户的操作（点击、输入、提交） | 门铃：按一下触发响应 |

### 阅读 app.js（重点部分）

打开 `static/js/app.js`，找到以下关键模式：

**1. 选择 DOM 元素并操作它**
```javascript
// 获取元素
const tbody = document.getElementById('table-body');
// 修改内容
tbody.innerHTML = '<tr><td>...</td></tr>';
```

**2. 事件绑定**
```javascript
// HTML 中直接绑定（在按钮上写 onclick="doSomething()"）
<button onclick="logout()">退出</button>

// JS 中绑定（更灵活，但在这里我们用上面那种方式入门）
document.addEventListener('DOMContentLoaded', () => { ... });
```

**3. 字符串模板（ES6）**
```javascript
// 反引号 + ${} 插值，比 + 拼接直观很多
return `
    <tr>
        <td>${s.id}</td>
        <td>${s.name}</td>
    </tr>`;
```

### 动手

1. 打开浏览器开发者工具（F12 → Console），输入：
   ```javascript
   document.querySelector('h1').textContent = 'Hello JS!'
   ```
   观察页面标题是否变化
2. 在 `app.js` 的 `renderRow` 函数中，把"年龄"列的显示改成 `${s.age} 岁`（加上"岁"字）
3. 在 Console 中手动创建一个 `<div>`，设置颜色，插入到页面中

---

## 第 2 天：fetch API —— 前后端握手

### fetch 是什么？

fetch 是浏览器内置的 HTTP 客户端，让 JS 可以调用后端 API。

```javascript
// GET 请求
const response = await fetch('/api/students');
const result = await response.json();  // 解析 JSON
console.log(result.data);              // 使用数据

// POST 请求
const response = await fetch('/api/students', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: '新同学', age: 20, email: 'x@mail.com', score: 85 })
});
```

### async / await 是什么？

fetch 是异步操作（需要时间等待服务器响应），`await` 让代码看起来像同步的一样，更好理解。

```javascript
// ❌ 不用 async/await（回调地狱）
fetch(url).then(resp => resp.json()).then(data => console.log(data));

// ✅ 用 async/await（像写同步代码一样）
async function load() {
    const resp = await fetch(url);
    const data = await resp.json();
    console.log(data);
}
```

### 本项目中的请求封装

打开 `app.js`，看 `api()` 函数：

```javascript
async function api(url, options) {
    options.headers['Authorization'] = 'Bearer ' + token;  // 自动带 Token
    const resp = await fetch(url, options);
    const result = await resp.json();

    if (resp.status === 401 || resp.status === 403) {
        logout();  // Token 失效，自动退回登录页
    }
    return result;
}
```

**为什么封装？** 每个请求都需要带 Authorization 头，封装后调用方只需要关心业务数据。

### 动手

1. 在 Console 中手动调用 fetch 测试 API：
   ```javascript
   fetch('/api/students/hello', { headers: { 'Authorization': 'Bearer week4-secret-token' } })
       .then(r => r.json())
       .then(console.log)
   ```
2. 观察 Network 面板（F12 → Network），看请求和响应的完整内容
3. 故意发一个错误的 Token，观察 401 返回和处理逻辑

---

## 第 3 天：Spring MVC 拦截器 —— 请求的"门卫"

### 拦截器原理

```
HTTP 请求
  │
  ▼
DispatcherServlet（前端控制器）
  │
  ▼
[拦截器 preHandle]   ← 在这里决定"放行"还是"拦截"
  │ 通过
  ▼
Controller（处理业务）
  │
  ▼
[拦截器 postHandle/afterCompletion]
  │
  ▼
HTTP 响应
```

### 本项目拦截器做了什么？

打开 `controller/AuthInterceptor.java`：

```java
@Override
public boolean preHandle(HttpServletRequest request, ...) {
    // 1. 白名单直接放行
    if (path.startsWith("/api/hello")) return true;

    // 2. 校验 Authorization 头
    String authHeader = request.getHeader("Authorization");
    if (authHeader == null || !authHeader.startsWith("Bearer ")) {
        response.setStatus(401);     // 返回 401 Unauthorized
        return false;                // 拦截！
    }

    // 3. 验证 Token 是否匹配
    String token = authHeader.substring(7);
    if (!validToken.equals(token)) {
        response.setStatus(403);     // 返回 403 Forbidden
        return false;
    }
    return true;  // 放行
}
```

### 注册拦截器（WebConfig.java）

```java
@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(authInterceptor)
                .addPathPatterns("/api/**")              // 拦截所有 /api/ 路径
                .excludePathPatterns("/api/hello", "/api/login");  // 白名单
    }
}
```

### 动手

1. 用 Postman 不带 Authorization 头发一个 `GET /api/students`，观察 401 响应
2. 带正确的 Token `Bearer week4-secret-token`，观察正常返回
3. 把 `auth.token` 改成另一个值，重启后观察旧 Token 变为 403
4. 思考：真正的用户系统会怎么存储和验证 Token？（预告：JWT，第 5 周）

---

## 第 4 天：统一异常处理 + 参数校验

### GlobalExceptionHandler 做了什么？

```java
@RestControllerAdvice                              // 拦截所有 Controller
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)  // 参数校验失败
    public ResponseEntity<?> handleValidation(...) {
        return ResponseEntity.badRequest()
            .body(ApiResponse.badRequest("参数校验失败: ..."));
    }

    @ExceptionHandler(Exception.class)              // 兜底：所有未捕获异常
    public ResponseEntity<?> handleAll(...) {
        return ResponseEntity.status(500)
            .body(ApiResponse.error(500, "服务器内部错误"));
    }
}
```

### 为什么 Controller 不需要 try-catch？

因为 `@RestControllerAdvice` 在所有 Controller 方法的外层织入了一层异常处理网。任何异常抛出后，都会落入对应的 `@ExceptionHandler` 方法。

```java
// Controller 中
@PostMapping
public ApiResponse<Student> add(@Valid @RequestBody Student s) {
    return ApiResponse.created(service.add(s));
    // 如果 s 的 name 为空 → MethodArgumentNotValidException
    // 如果 service.add 中抛异常 → Exception
    // 都会被 GlobalExceptionHandler 捕获，Controller 不需要处理
}
```

### 统一响应格式（ApiResponse）

所有接口返回统一结构：
```json
{
    "code": 200,
    "message": "success",
    "data": { ... },
    "extra": { "total": 10, "orm": "JPA" }
}
```

这样前端只需要判断 `result.code === 200` 来确定请求是否成功。

### 动手

1. 故意提交空的姓名，观察返回的 400 错误详情
2. 在 Student 实体类中新增一个校验规则：`@Min(0) @Max(100) private int score`
3. 测试传入 score=999，观察校验是否生效

---

## 第 5 天：RESTful 设计规范 + ORM 切换

### RESTful API 最佳实践

| 原则 | 规则 |
|------|------|
| **用名词，不用动词** | `/api/students` ✅ `/api/getStudents` ❌ |
| **HTTP 方法表达操作** | GET=查 / POST=增 / PUT=改 / DELETE=删 |
| **资源用复数** | `/api/students` 而不是 `/api/student` |
| **层级表示关系** | `/api/students/5/avatar` = 学生 5 的头像 |
| **正确使用状态码** | 200=成功 / 201=创建成功 / 400=参数错误 / 404=未找到 / 500=服务器错误 |

### ORM 模式切换

本项目用 `orm.mode` 配置实现了 JPA 和 MP 的无缝切换：

```yaml
# application.yml
orm:
  mode: jpa  # 改成 mp 即可切换到 MyBatis-Plus
```

原理：`StudentServiceSelector` 读取 `@Value("${orm.mode}")`，根据值选择调用 `StudentJpaService` 还是 `StudentMpService`。Controller 层完全不感知底层用的是哪个 ORM。

### 动手

1. 修改 `orm.mode` 为 `mp`，重启，观察前端页面显示的 ORM 标签
2. 测试同一个接口的返回数据是否完全一致
3. 对比控制台 SQL 输出，JPA 和 MP 生成的 SQL 有何不同
4. 思考：如果要在运行时动态切换（不重启），需要怎么改？

---

## 第 6 天：文件上传 + CORS 跨域

### Spring Boot 文件上传

Controller 中处理文件只需 `@RequestParam("file") MultipartFile file`：

```java
@PostMapping("/{id}/avatar")
public ResponseEntity<?> uploadAvatar(
        @PathVariable Long id,
        @RequestParam("file") MultipartFile file) {

    // 1. 文件校验
    if (file.isEmpty()) return badRequest("文件为空");
    String ext = originalName.substring(originalName.lastIndexOf("."));

    // 2. 保存到磁盘
    String filename = UUID.randomUUID() + ext;  // 随机名防冲突
    file.transferTo(new File("./uploads", filename));

    // 3. 更新数据库
    service.updateAvatar(id, filename);
}
```

### 前端如何上传文件

```javascript
const formData = new FormData();
formData.append('file', fileInput.files[0]);  // 从 <input type="file"> 取文件

fetch(`/api/students/${id}/avatar`, {
    method: 'POST',
    body: formData  // 不设 Content-Type！浏览器自动设置 multipart/form-data + boundary
});
```

### CORS 跨域

当前前后端同端口，不存在跨域。但项目已经预置了 CORS 配置（`WebConfig.addCorsMappings`），为后续前后端分离做准备。

### 静态资源映射

```java
// 将本地 uploads/ 目录映射到 URL /uploads/**
registry.addResourceHandler("/uploads/**")
        .addResourceLocations("file:./uploads/");
```

这样通过 `http://localhost:8080/uploads/xxx.jpg` 就能访问上传的头像。

### 动手

1. 新增一个学生，编辑该学生 → 上传一张头像 → 观察表格中头像显示
2. 打开 `./uploads/` 目录，确认文件已保存
3. 故意上传一个超过 2MB 的文件，观察错误提示
4. 修改 `application.yml` 中 `spring.servlet.multipart.max-file-size` 为 5MB

---

## 第 7 天：项目整合与总结

### 本周完整请求流程

```
浏览器
  │
  ├── 1. GET / → 加载 index.html + style.css + app.js
  │
  ├── 2. 用户输入 Token → JS 调用 /api/students/hello 验证
  │
  ├── 3. Token 验证通过 → 进入主面板 → JS 调用 /api/students 加载数据
  │       │
  │       ▼
  │   [AuthInterceptor] 校验 Authorization 头
  │       │ 通过
  │       ▼
  │   [StudentController] 接收请求 → 参数校验（@Valid）
  │       │
  │       ▼
  │   [StudentServiceSelector] 根据 orm.mode 选择 JPA 或 MP Service
  │       │
  │       ▼
  │   [StudentJpaService / StudentMpService] 执行业务逻辑
  │       │
  │       ▼
  │   [Repository / Mapper] 操作数据库
  │       │
  │       ▼
  │   返回 ApiResponse 格式 JSON → JS 渲染到页面
  │
  └── 异常 → [GlobalExceptionHandler] 拦截 → 返回统一错误 JSON
```

### 完整验收清单

**后端（Postman 逐项测试）**：

- [ ] `GET /api/students/hello` 无需 Token，返回运行状态
- [ ] `GET /api/students` 需 Token，返回全部学生
- [ ] `GET /api/students?keyword=张` 模糊搜索
- [ ] `POST /api/students` 新增一个学生
- [ ] `GET /api/students/1` 查询 ID=1
- [ ] `PUT /api/students/1` 更新学生信息
- [ ] `DELETE /api/students/1` 删除学生
- [ ] `POST /api/students/1/avatar` 上传头像
- [ ] 不带 Token 发请求 → 401
- [ ] 带错误 Token 发请求 → 403
- [ ] 提交空 name → 400 校验错误
- [ ] 修改 `orm.mode: mp` 后功能不变

**前端（浏览器）**：

- [ ] 输入正确 Token → 进入主面板
- [ ] 输入错误 Token → 显示错误
- [ ] 表格正确展示全部学生（头像、成绩徽章颜色正确）
- [ ] 新增学生 → 表单提交 → 表格刷新
- [ ] 编辑学生 → 回填数据 → 更新成功
- [ ] 上传头像 → 头像显示在表格中
- [ ] 搜索 → 过滤数据
- [ ] 删除 → 确认弹窗 → 删除成功
- [ ] 退出登录 → 回到登录页

### 本周产出

```
✅ 原生 JS 前后端交互（fetch + DOM 操作）
✅ Token 认证与 401/403 处理
✅ Spring MVC 拦截器（登录权限校验）
✅ 全局异常处理（统一 JSON 格式错误返回）
✅ 参数校验（@Valid + Bean Validation + 自定义错误消息）
✅ RESTful API 设计规范
✅ ORM 配置切换（JPA ↔ MyBatis-Plus，一行配置切换）
✅ 文件上传（头像，前端 FormData + 后端 MultipartFile）
✅ CORS 跨域预配置
✅ 统一 API 响应格式（ApiResponse<T>）
```

---

> **本周核心**：你已从 Java 基础走到了能独立交付一个**全栈应用**的水平。后端有三层架构和双 ORM，前端有原生 JS 交互和文件上传，系统有拦截器保护、统一异常处理、参数校验。这是你第一个真正的里程碑项目。