# 第二阶段教案：Spring Boot 入门（第 2 周）

> **学习周期**：7 天
> **每日用时**：2-3 小时
> **最终产出**：RESTful 学生管理 API（分层架构 + 参数校验 + 多环境配置）
> **项目结构**：Maven + Spring Boot 3.2

---

## Maven 项目导入

在 IDEA 中：File → Open → 选择 `week2/pom.xml` → Open as Project。
IDEA 会自动下载依赖，等待右下角进度条完成即可。

---

## 第 1 天：Spring 是什么？IoC 和 DI

### 核心概念

**没有 Spring 时**：你写代码手动 `new` 对象，所有对象的创建和关联都由你自己管理。

```java
UserRepository repo = new UserRepository();     // 自己创建
UserService service = new UserService();         // 自己创建
service.setUserRepository(repo);                 // 自己关联
```

**有了 Spring 后**：对象的创建和关联由容器负责，你只需要声明"我需要什么"。

```java
@Service
public class UserService {
    private final UserRepository repo;   // Spring 会自动注入
    // ...
}
```

### 三个关键术语

| 术语 | 白话解释 |
|------|---------|
| **IoC**（控制反转） | 创建对象的控制权从你手里"反转"给了 Spring 容器 |
| **DI**（依赖注入） | 当 A 需要 B 时，Spring 自动把 B "注入"到 A 里，你不需要 `new` |
| **容器** | 一个巨大的 Map，存着所有被 Spring 管理的对象（称为 Bean） |

### 动手：运行 IoC 演示

打开 `src/main/java/com/learn/ioc/SimpleIocDemo.java`，右键 Run。

这个文件包含了一个用纯 Java 手写的极简 IoC 容器（约 100 行），没有依赖任何框架。它会输出：

```
========== IoC 容器原理演示 ==========

--- 方式一：手动 setter 注入 ---
调用结果: 张三（来自数据库）

--- 方式二：注解自动注入 ---
调用结果: 订单 #12345

========== 总结 ==========
没有 IoC 容器时：A a = new A(); a.setB(new B());  // 自己控制一切
有了 IoC 容器后：@Autowired B b;  // 容器自动注入，你只管用
```

**今日任务**：
1. 逐行读懂 `SimpleIocDemo.java`，理解容器/注册/注入三步
2. 尝试在 `SimpleIocDemo` 里新增一个类（如 `ProductService`），并把它注册到容器中
3. 思考：为什么反射（Reflection）是实现 IoC 的关键技术？

---

## 第 2 天：Spring Boot 项目结构

### 核心概念

Spring Boot 不是新框架，它是对 Spring 的**封装和简化**。传统 Spring 需要大量 XML 配置，Spring Boot 通过"约定大于配置"消除了这些繁琐步骤。

### 项目结构详解

```
week2/
├── pom.xml                          # Maven 配置（依赖管理）
└── src/
    ├── main/
    │   ├── java/com/learn/
    │   │   ├── Week2Application.java    # 启动入口
    │   │   ├── controller/              # 控制器层（接收 HTTP 请求）
    │   │   ├── service/                 # 业务逻辑层
    │   │   ├── repository/              # 数据访问层
    │   │   ├── model/                   # 数据模型
    │   │   ├── config/                  # 配置类
    │   │   └── exception/               # 全局异常处理
    │   └── resources/
    │       ├── application.yml          # 主配置文件
    │       ├── application-dev.yml      # 开发环境
    │       └── application-prod.yml     # 生产环境
    └── test/                            # 测试代码
```

### Spring Boot 启动流程

1. `main()` 调用 `SpringApplication.run()`
2. 创建 `ApplicationContext`（即 IoC 容器）
3. 扫描 `@SpringBootApplication` 所在包及子包
4. 找到所有带 `@Component` / `@Service` / `@Repository` / `@Controller` 的类
5. 实例化它们并处理依赖注入
6. 启动内嵌 Tomcat，监听 8080 端口

### 动手：观察启动日志

在 IDEA 中运行 `Week2Application.main()`，观察控制台输出：

```
Started Week2Application in 1.234 seconds
Tomcat started on port 8080
```

你会看到 Spring Boot 的 Banner、自动配置报告、Tomcat 启动信息。

**今日任务**：
1. 对着上面的目录结构，在你的项目中找到每个文件的位置
2. 打开 `pom.xml`，理解每个 `<dependency>` 的作用
3. 尝试改 `application.yml` 中的 `server.port` 为 9090，重启验证

---

## 第 3 天：第一个 REST API

### 核心概念

| 注解 | 作用 | 举例 |
|------|------|------|
| `@RestController` | 标记 REST 控制器，方法返回值自动转 JSON | 写在类上 |
| `@GetMapping("/xxx")` | 映射 HTTP GET 请求 | `@GetMapping("/hello")` |
| `@PathVariable` | 从 URL 路径中取值 | `/hello/{id}` → `@PathVariable Long id` |
| `@RequestParam` | 从 URL 查询参数中取值 | `/greet?name=张三` → `@RequestParam String name` |

### 动手：测试接口

运行 `Week2Application`，打开浏览器或 Postman 访问：

| URL | 预期结果 |
|-----|---------|
| `http://localhost:8080/hello` | `Hello, Spring Boot!` |
| `http://localhost:8080/hello/小明` | `你好，小明！欢迎来到 Spring Boot 的世界。` |
| `http://localhost:8080/greet?name=张三&age=20` | `你好，张三！你今年 20 岁。` |
| `http://localhost:8080/greet` | `你好，同学！`（默认值生效） |
| `http://localhost:8080/info` | JSON 对象 `{"status":"UP","message":"...","timestamp":...}` |

### 关键理解

`@RestController` 的请求处理流程：

```
HTTP 请求 → DispatcherServlet（前端控制器）
         → 找到匹配的 Controller 方法
         → 执行方法，得到返回值
         → Jackson 将返回值序列化为 JSON
         → HTTP 响应返回给客户端
```

**今日任务**：
1. 在 `HelloController` 中新增一个接口：`GET /echo?msg=xxx`，返回 `{"echo": "xxx"}`
2. 用 Postman 测试所有接口，观察请求头和响应头
3. 思考：`@RestController` 和普通 `@Controller` 有什么区别？（提示：`@ResponseBody`）

---

## 第 4 天：RESTful CRUD（上）—— 请求映射

### 核心概念

RESTful API 用 HTTP 方法表达操作意图：

| HTTP 方法 | 对应注解 | 语义 |
|-----------|---------|------|
| GET | `@GetMapping` | 查询（安全、幂等） |
| POST | `@PostMapping` | 新增 |
| PUT | `@PutMapping` | 更新（幂等） |
| DELETE | `@DeleteMapping` | 删除（幂等） |

### @RequestBody —— 接收 JSON 请求体

```java
@PostMapping
public ResponseEntity<?> add(@RequestBody Student student) {
    // Spring 自动将请求体的 JSON → Student 对象
}
```

客户端发送：
```json
POST /api/students
Content-Type: application/json

{
    "name": "张三",
    "age": 20,
    "email": "zhangsan@mail.com",
    "score": 85
}
```

### 动手：测试 CRUD 接口

> 第 4 天的代码在 `StudentController` 中，此时还没有 Service/Repository 分层。
> 阅读 `StudentController` 的代码，理解每个方法的注解和 URL 设计。

| 操作 | 方法 | URL | 请求体 |
|------|------|-----|--------|
| 查全部 | GET | `/api/students` | - |
| 查单个 | GET | `/api/students/1` | - |
| 搜索 | GET | `/api/students?keyword=张` | - |
| 新增 | POST | `/api/students` | JSON |
| 更新 | PUT | `/api/students/1` | JSON |
| 删除 | DELETE | `/api/students/1` | - |

用 Postman 逐个测试（启动后已有 5 条预置数据）。

**今日任务**：
1. 用 Postman 完成"新增→查询→更新→删除"的完整流程
2. 观察 PUT 更新时只传部分字段的效果
3. 尝试故意传一个错误的 JSON（少字段、错类型），观察返回什么

---

## 第 5 天：分层架构 —— Controller → Service → Repository

### 为什么需要分层？

第 4 天所有逻辑挤在 Controller 里。当项目变复杂时：

- Controller 既处理请求又写业务逻辑，又操作数据 → **难以维护**
- 一个地方改了，可能影响不相关的地方 → **难以测试**

### 三层架构

```
┌──────────────────────────────────────┐
│  Controller 层（@RestController）     │  ← 接收请求、参数校验、返回响应
│  "我只负责接待客人，不干活"             │
├──────────────────────────────────────┤
│  Service 层（@Service）               │  ← 业务逻辑、事务管理
│  "我负责干活，不知道客人从哪来的"        │
├──────────────────────────────────────┤
│  Repository 层（@Repository）          │  ← 数据存取
│  "我只负责存取数据，不知道业务逻辑"      │
└──────────────────────────────────────┘
```

### 依赖方向（重要！）

```
Controller → Service → Repository
    ↑            ↑
    只能从上往下依赖，不能反着来
```

每个层只依赖下一层，不跨层调用。Repository 不能依赖 Service，Service 不能依赖 Controller。

### 本项目的分层实现

打开对应文件，理解各层职责：

| 文件 | 层 | 关键点 |
|------|-----|--------|
| `controller/StudentController.java` | Controller | 只做参数提取和响应封装，调用 Service |
| `service/StudentService.java` | Service | 业务逻辑（校验、组合），调用 Repository |
| `repository/StudentRepository.java` | Repository | 数据存取，使用 ConcurrentHashMap 模拟数据库 |
| `model/Student.java` | Model | 贯穿三层的数据载体 |

### 注入方式对比

```java
// ❌ 字段注入（不推荐——测试困难，掩盖依赖关系）
@Autowired
private StudentService service;

// ✅ 构造方法注入（推荐——依赖明确，易于测试）
private final StudentService service;
public StudentController(StudentService service) {
    this.service = service;
}
```

**今日任务**：
1. 画出三层架构的依赖关系图
2. 在 `StudentService` 中新增一个方法：`getTopStudents(int n)`，返回成绩最高的 n 个学生
3. 为这个新方法在 Controller 中新增接口 `GET /api/students/top?n=3`

---

## 第 6 天：配置管理

### application.yml vs application.properties

```yaml
# YAML 格式（推荐，层次清晰）
server:
  port: 8080
spring:
  application:
    name: my-app
```

```properties
# properties 格式（传统，扁平）
server.port=8080
spring.application.name=my-app
```

两者等效，YAML 更直观。

### 多环境配置

```
application.yml          # 公共配置
application-dev.yml      # 开发环境
application-prod.yml     # 生产环境
```

`application.yml` 中通过 `spring.profiles.active: dev` 指定激活哪个环境。

激活方式（优先级从高到低）：
1. 命令行：`java -jar app.jar --spring.profiles.active=prod`
2. 环境变量：`SPRING_PROFILES_ACTIVE=prod`
3. application.yml 中的 `spring.profiles.active`

### @Value 读取配置

```java
@Value("${app.name}")
private String appName;
```

### 自定义配置

在 YAML 中写：
```yaml
app:
  name: 学生管理系统
  version: 1.0.0
```

在代码中读：
```java
@Value("${app.name}")
private String appName;
```

**今日任务**：
1. 修改 `spring.profiles.active` 为 `prod`，观察端口和日志变化
2. 在 `HelloController` 中用 `@Value` 注入 `app.name`，新增接口返回应用名称
3. 想一想：为什么数据库密码、API Key 要放在配置文件中而不是代码里？

---

## 第 7 天：整合与总结

### 全局异常处理

复习 `exception/GlobalExceptionHandler.java`：

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

    @ExceptionHandler(MethodArgumentNotValidException.class)  // 参数校验失败
    public ResponseEntity<?> handleValidation(...) { ... }

    @ExceptionHandler(Exception.class)    // 兜底：所有未捕获的异常
    public ResponseEntity<?> handleAll(...) { ... }
}
```

有了这个，Controller 的任何异常都会被拦截并返回友好的 JSON 错误信息。

### 参数校验（Bean Validation）

看 `Student` 类中的注解：
```java
@NotBlank(message = "姓名不能为空")
private String name;

@Min(value = 1, message = "年龄必须大于 0")
private int age;

@Email(message = "邮箱格式不正确")
private String email;
```

Controller 中用 `@Valid` 触发校验：
```java
@PostMapping
public ResponseEntity<?> add(@Valid @RequestBody Student student) { ... }
```

### 本周完整的请求处理流程

```
1. HTTP 请求到达 → DispatcherServlet 接收
2. 根据 URL + HTTP Method 匹配 Controller 方法
3. @Valid 触发参数校验（失败 → GlobalExceptionHandler 捕获 → 返回 400）
4. Controller 调用 Service 处理业务逻辑
5. Service 调用 Repository 存取数据
6. 结果返回 Controller，封装为 ResponseEntity
7. Jackson 序列化为 JSON，写入 HTTP 响应
```

### 测试（预习第 8 周）

打开 `StudentControllerTest.java`，这是一个集成测试示例，用 `TestRestTemplate` 模拟 HTTP 请求来测试真实接口。

运行方式：右键类名 → Run。观察所有测试通过。

### 最终验收清单

用 Postman 完成以下测试：

- [ ] `GET /api/students` 返回 5 条预置数据
- [ ] `GET /api/students/1` 返回张三的信息
- [ ] `GET /api/students?keyword=李` 只返回李四
- [ ] `POST /api/students` 新增一个学生，返回 201
- [ ] `POST /api/students` 传空 name，返回 400 校验错误
- [ ] `PUT /api/students/1` 修改张三的年龄，返回更新后数据
- [ ] `DELETE /api/students/1` 删除张三，返回成功
- [ ] `DELETE /api/students/999` 删除不存在的，返回 404
- [ ] 重启应用，之前新增/修改的数据被重置（内存存储）

---

## 本周产出

**一个完整的 RESTful 学生管理 API 服务**，具备：

```
✅ 三层分层架构（Controller → Service → Repository）
✅ 完整的 CRUD 接口（GET/POST/PUT/DELETE）
✅ 模糊搜索功能
✅ 统一 JSON 响应格式（code + message + data）
✅ 参数校验（@Valid + Bean Validation）
✅ 全局异常处理（@RestControllerAdvice）
✅ 多环境配置（dev/prod）
✅ 启动时预置测试数据（CommandLineRunner）
✅ 基础集成测试
```

---

## 常见问题排查

| 问题 | 原因 | 解决 |
|------|------|------|
| 启动报端口占用 | 8080 端口已被占用 | 改 `application.yml` 中的 `server.port` |
| `@Autowired` 报红 | 类上没有 `@Service` 等注解 | 检查是否漏了 `@Service` / `@Repository` / `@Component` |
| 找不到 Bean | 类不在启动类所在包的子包下 | Spring 默认扫描启动类同级及子包 |
| POST 请求 415 | Content-Type 没设对 | Postman 中 Body 选 raw → JSON |
| 中文乱码 | 未设编码 | Spring Boot 默认 UTF-8，如果乱码检查 Postman 设置 |
| JSON 返回 406 | 可能缺少 Jackson 依赖 | `spring-boot-starter-web` 已包含，检查 pom.xml |
| 修改代码不生效 | 需要重启 | 后续第 8 周会学 DevTools 热重载 |

---

> **本周核心**：理解 Spring 的 IoC/DI 思想 → 掌握分层架构 → 能写标准的 RESTful CRUD API。
> 这 7 天你建立的是整个 Spring 技术栈的地基，后续 JPA、Security、AI 集成都是在这个地基上添砖加瓦。