185 lines
7.0 KiB
Markdown
185 lines
7.0 KiB
Markdown
# Week 8：工程化能力
|
||
|
||
**目标**：掌握测试、文档、部署等工程化技能，交付可测试、有文档、容器化的完整项目。
|
||
|
||
**前置**：完成 Week 7（前后端分离项目）。
|
||
|
||
**本周产出**：学生管理系统 v4 — 有单元测试、集成测试、API 文档。
|
||
|
||
**启动方式**：
|
||
```bash
|
||
cd week8
|
||
|
||
# 运行测试
|
||
mvn test
|
||
|
||
# 启动应用后访问 API 文档
|
||
http://localhost:8080/doc.html
|
||
```
|
||
|
||
---
|
||
|
||
## Day 1：JUnit 5 + Mockito 单元测试
|
||
|
||
**知识点**：
|
||
- 测试金字塔：单元测试 → 集成测试 → E2E 测试
|
||
- JUnit 5 注解：`@Test`、`@BeforeEach`、`@DisplayName`
|
||
- 断言：`assertEquals`、`assertTrue`、`assertThrows`
|
||
- Mockito：`@Mock`（模拟依赖）、`@InjectMocks`（注入模拟对象）
|
||
- `when(...).thenReturn(...)`：控制 Mock 行为
|
||
- `verify()`：验证方法被调用
|
||
- `@ExtendWith(MockitoExtension.class)`：初始化 Mockito
|
||
- 测试覆盖率：行覆盖 vs 分支覆盖
|
||
|
||
**动手 → 理解**：
|
||
1. 阅读 `AuthServiceTest.java`，理解每个 `@Mock` 的含义
|
||
2. 运行 `mvn test -Dtest=AuthServiceTest`，观察 5 个测试全部通过
|
||
3. 故意把 `testLoginBadPassword` 的期望密码改为正确值，观察测试失败信息
|
||
4. 在 `when(...)` 中把返回值改成 `false`，看哪个测试会失败
|
||
5. 写一个测试：验证 `register` 成功时 `userRepo.save()` 被调用了 1 次
|
||
|
||
**核心文件**：
|
||
- `src/test/java/com/learn/service/AuthServiceTest.java` — 单元测试示例
|
||
|
||
**思考题**：为什么不直接测试 Service 的真实数据库操作，而是用 Mockito 模拟？
|
||
|
||
---
|
||
|
||
## Day 2：@SpringBootTest 集成测试
|
||
|
||
**知识点**：
|
||
- `@SpringBootTest`：启动完整 Spring 容器
|
||
- `@AutoConfigureMockMvc`：模拟 HTTP 请求
|
||
- `MockMvc`：`perform(get(...))`、`andExpect(status().isOk())`、`jsonPath()`
|
||
- H2 内存数据库：`jdbc:h2:mem:testdb` — 不依赖外部 MySQL
|
||
- `@ActiveProfiles("test")`：测试专用配置
|
||
- `application-test.yml`：测试环境的 H2 + 禁用 Redis
|
||
- `@TestMethodOrder` + `@Order`：控制测试顺序
|
||
|
||
**动手 → 理解**：
|
||
1. 阅读 `StudentControllerTest.java`，理解测试流程
|
||
2. 运行 `mvn test`，观察 Spring Boot 启动日志中的 `Using profile: "test"`
|
||
3. 在测试日志中找到 H2 的 `HikariPool-1 - Starting...` 确认使用内存库
|
||
4. 访问 `http://localhost:8080/h2-console`（测试模式下），查看表结构
|
||
5. 添加一个测试：验证用 user/123456（USER 角色）新增学生时返回 403
|
||
|
||
**核心文件**：
|
||
- `src/test/java/com/learn/controller/StudentControllerTest.java` — 集成测试
|
||
- `src/main/resources/application-test.yml` — 测试环境配置
|
||
|
||
**思考题**：H2 和 Testcontainers（真实 MySQL 容器）各有什么优劣？什么时候该用 Testcontainers？
|
||
|
||
---
|
||
|
||
## Day 3：Knife4j API 文档
|
||
|
||
**知识点**：
|
||
- 为什么需要 API 文档：前后端协作、接口调试、新人上手
|
||
- Swagger / OpenAPI 3.0 规范
|
||
- Knife4j：国产增强版 Swagger UI（界面更友好）
|
||
- `@Tag`、`@Operation`、`@Parameter` 注解增强文档
|
||
- `application.yml` 配置：`springdoc.swagger-ui.path=/doc.html`
|
||
- `OpenAPI` Bean：自定义文档标题、版本、描述
|
||
- 在线调试：在文档页面直接发送请求
|
||
|
||
**动手 → 理解**：
|
||
1. 启动项目，访问 `http://localhost:8080/doc.html`
|
||
2. 点击 "Auth" 标签，展开 `/api/auth/login`，点击"发送"直接测试
|
||
3. 在文档右上角设置全局 Token：`Bearer <你的JWT>`
|
||
4. 用文档页面的"调试"功能完成一次完整的增删改查
|
||
5. 在 Controller 方法上添加 `@Operation(summary = "...")` 注解，刷新文档查看效果
|
||
|
||
**核心文件**：
|
||
- `config/Knife4jConfig.java` — API 文档配置
|
||
- `pom.xml` → `knife4j-openapi3-jakarta-spring-boot-starter`
|
||
- `application.yml` → `springdoc.*`
|
||
|
||
**思考题**：API 文档应该暴露在生产环境吗？如果不应该，怎么关闭？
|
||
|
||
**生产环境安全提示**：
|
||
```yaml
|
||
# 生产环境 application-prod.yml 中关闭文档
|
||
springdoc:
|
||
api-docs:
|
||
enabled: false # 关闭 /v3/api-docs
|
||
swagger-ui:
|
||
enabled: false # 关闭 /doc.html
|
||
```
|
||
或在 SecurityConfig 中按 Profile 条件放行：
|
||
```java
|
||
// 开发环境放行文档，生产环境不放行
|
||
@Profile("!prod")
|
||
```
|
||
**原则**：API 文档暴露所有接口结构和参数，生产环境应关闭或加认证保护。
|
||
|
||
---
|
||
|
||
## Day 4：阶段总结 & 里程碑项目 v4
|
||
|
||
**知识点**：
|
||
- 回顾 Week 1-8 的技术栈全景图
|
||
- 理解"测试金字塔"在项目中的落地
|
||
- 对比 v1 → v4 四个版本的进化
|
||
|
||
**v1 → v4 进化史**：
|
||
|
||
| 版本 | 周次 | 新增能力 |
|
||
|------|------|---------|
|
||
| v1 | Week 4 | Spring Boot + JPA/MP + 原生 JS 全栈 |
|
||
| v2 | Week 5 | Spring Security + JWT + Redis + Actuator |
|
||
| v3 | Week 7 | Vue 3 前后端分离 + Axios + 导航守卫 |
|
||
| v4 | Week 8 | 单元测试 + 集成测试 + API 文档 |
|
||
|
||
**Actuator 端点说明**（Week 5 遗留问题）：
|
||
- `/actuator` — 返回所有**可用端点列表**的 JSON，这是正常的
|
||
- 真正的监控数据在这些端点：
|
||
- `/actuator/health` → 健康状态（UP/DOWN）
|
||
- `/actuator/beans` → Spring 容器中所有 Bean
|
||
- `/actuator/env` → 环境变量和配置
|
||
- `/actuator/mappings` → 所有 URL 映射
|
||
- **安全建议**：`/actuator/env` 可能泄露数据库密码等敏感信息，生产环境不应暴露
|
||
|
||
**动手 → 理解**：
|
||
1. 画出 v4 的完整架构图（Vue → Axios → Spring Boot → JPA/MP → MySQL）
|
||
2. 检查所有测试是否通过：`mvn test`
|
||
3. 检查 API 文档是否完整：`http://localhost:8080/doc.html`
|
||
4. 确认 `docker-compose up --build` 能成功启动
|
||
5. 补充 `.gitignore`、`README.md`
|
||
|
||
**最终项目文件清单**：
|
||
```
|
||
week8/
|
||
├── pom.xml # 含 test + knife4j 依赖
|
||
├── sql/init.sql # 数据库初始化
|
||
├── src/main/
|
||
│ ├── java/com/learn/
|
||
│ │ ├── config/
|
||
│ │ │ ├── Knife4jConfig.java # Day 3: API 文档
|
||
│ │ │ └── SecurityConfig.java # 含 CORS
|
||
│ │ ├── controller/ # REST API
|
||
│ │ ├── entity/ # Student + User
|
||
│ │ └── service/ # 双 ORM 实现
|
||
│ └── resources/
|
||
│ ├── application.yml # 主配置 + springdoc
|
||
│ └── application-test.yml # Day 2: H2 测试配置
|
||
└── src/test/java/com/learn/
|
||
├── service/AuthServiceTest.java # Day 1: 单元测试
|
||
└── controller/StudentControllerTest.java # Day 2: 集成测试
|
||
```
|
||
|
||
---
|
||
|
||
## Week 8 总结
|
||
|
||
| 维度 | 工具 | 掌握程度 |
|
||
|------|------|---------|
|
||
| 单元测试 | JUnit 5 + Mockito | Service 层全 Mock 测试 |
|
||
| 集成测试 | @SpringBootTest + H2 | Controller 全流程测试 |
|
||
| API 文档 | Knife4j / SpringDoc | 自动生成 + 在线调试 |
|
||
|
||
**下一阶段：Week 9-12 — AI Agent 开发**
|
||
- Week 9：AI & LLM 基础，调用大模型 API
|
||
- Week 10：Agent 架构 + Function Calling
|
||
- Week 11：算法入门 + Agent 前端
|
||
- Week 12：最终项目 —— AI Agent 网站
|