# SpringBoot教学项目

**Repository Path**: thelongestday/spring-boot-teaching-project

## Basic Information

- **Project Name**: SpringBoot教学项目
- **Description**: No description available
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# UMM · 用户管理系统（Spring Boot 教学项目）

一个面向教学的用户信息与用户权限管理模块（User Manager Module）。前端基于 Thymeleaf 服务端渲染 + 原生 CSS 美化，后端严格分层（Controller / Service / DAO / Domain），DAO 层**手写 JdbcTemplate**（不引入 MyBatis / JPA），完整演示了「用户 → 角色 → 权限」的 RBAC 多表关联建模与增删改查、登录态拦截、BCrypt 密码加密等企业级基础能力。

> 仓库：`git@gitee.com:thelongestday/spring-boot-teaching-project.git`

---

## 目录

- [技术栈](#技术栈)
- [功能特性](#功能特性)
- [快速开始](#快速开始)
- [演示账号](#演示账号)
- [页面与接口一览](#页面与接口一览)
- [项目结构](#项目结构)
- [数据库设计](#数据库设计)
- [代码分层与教学要点](#代码分层与教学要点)
- [测试](#测试)
- [规划中模块](#规划中模块)
- [License](#license)

---

## 技术栈

| 类别 | 选型 |
| --- | --- |
| 语言 / 框架 | Java 21 LTS · Spring Boot 4.1.1（`spring-boot-starter-webmvc`） |
| 模板引擎 | Thymeleaf 4（服务端渲染，无前后端分离） |
| 数据访问 | `spring-boot-starter-jdbc` + 手写 `JdbcTemplate` / `NamedParameterJdbcTemplate` |
| 数据库 | MySQL 8.x（`utf8mb4`），提供 MySQL 与 Oracle 两套脚本 |
| 安全 | `spring-security-crypto`（BCrypt 密码加密）· Session 登录拦截器 |
| 校验 | `spring-boot-starter-validation`（Jakarta Validation） |
| 辅助 | Lombok · spring-boot-devtools |
| 测试 | JUnit 5 · `spring-boot-starter-webmvc-test` · `spring-boot-resttestclient` |
| 构建 | Maven（`mvnw` wrapper，版本随 pom 锁定） |

---

## 功能特性

### 认证与注册
- 登录 / 退出，未登录访问自动跳转登录页（`LoginInterceptor` 统一拦截，页面导航重定向、API 返回 JSON 401）
- 注册：用户名重复实时校验（AJAX）、省市级联下拉、爱好多选、密码二次确认、生日等表单校验，密码 BCrypt 加密落库

### 用户权限管理模块（RBAC 核心）
- **工作台**：系统数据概览（用户 / 角色 / 权限数量统计）与快捷入口
- **用户信息管理**：列表分页 + 关键字搜索；新增 / 编辑用户（昵称、性别、生日、籍贯省市级联、爱好多选、**角色多选分配**）；批量删除
  - 守卫逻辑：删除当前登录账号被拦截（ok=4）；用户名重复、密码长度、生日格式等服务端校验回显
- **角色信息管理**：角色新增 / 编辑（勾选权限集合）、删除
  - 守卫逻辑：仍被用户引用的角色禁止删除（ok=5）
- **权限信息管理**：权限点（标识 / URL / 描述）新增 / 编辑、删除
  - 守卫逻辑：仍被角色引用的权限禁止删除（ok=6）
- 删除操作一律走数据库外键 `ON DELETE CASCADE` 自动清理关联行，不产生孤儿数据

### 主框架（美化后的后台布局）
- 渐变顶栏 + 侧边菜单 + iframe 内容区，菜单可折叠、点击高亮、随登录用户显示昵称头像

### 邮件模块（站内信）
- **写邮件**：多收件人（勾选系统用户）、主题、正文；发送后按收件人各写一条 `mail` 记录
- **收邮件**：收件箱分页、未读置顶与未读数、阅读正文自动标记已读、可一键回复
- **发件箱**：已发送列表、正文回看、删除
- 权限边界：只能读写与当前登录用户相关的信件（读取/删除均校验 `toId` / `fromId`）

### 信息发布管理模块（文章管理）
- **文章分类管理**：两级分类（一级 / 二级）维护，删除保护（仍有子分类或文章的分类不可删）
- **文章管理**：标题搜索 + 分类筛选 + 分页 + 批量删除；发布 / 编辑（标题、正文、分类、置顶、推荐）
- **文章阅读**：阅读页正文渲染、阅读量 +1、作者与分类展示（示范 article/articleType/users 三表联查）

---

## 快速开始

### 环境要求
- JDK 21+（本仓库使用 Spring Boot 4，仅支持 Java 17+，推荐 21 LTS）
- Maven 3.9+（可用仓库内置 `./mvnw`，无需单独安装）
- MySQL 5.7 / 8.x，端口 3306

### 第 1 步：初始化数据库（一键）
```bash
cd spring-boot-teaching-project
mysql -uroot -p --default-character-set=utf8mb4 < database/implement/mysql/init.sql
```
脚本会**删除并重建** `umm` 库、创建应用账号 `umm/umm`（与 `application.yml` 对齐）、建表并灌入演示数据与种子账号，无需手工建库。

> ⚠️ **字符集（重要）**：本机 MySQL 客户端连接默认 latin1，导入含中文的 SQL 时**必须带 `--default-character-set=utf8mb4`**（或脚本内已内置 `SET NAMES utf8mb4;`）。否则 UTF-8 字节会被按 latin1 解码后入库，造成中文永久乱码（mojibake，如"前端"变成 `å‰ç«¯`）。三个脚本（init.sql / upgrade_module_mail_article.sql / testdata_demo.sql）均已内置 `SET NAMES utf8mb4;`，命令行仍建议带上该参数。

> 备用脚本：`database/implement/mysql/umm_userInfoManager.sql`、`umm_userPermissionManager.sql`（历史拆分版，可作对照学习）；Oracle 版见 `database/implement/oracle/`。存量库增量升级（邮件表 + 信息发布种子数据）见 `database/implement/mysql/upgrade_module_mail_article.sql`。**补充演示数据**（1 个用户 + 6 篇文章 + 6 封站内信，幂等可重复执行）见 `database/implement/mysql/testdata_demo.sql`：`mysql -uumm -pumm --default-character-set=utf8mb4 umm < database/implement/mysql/testdata_demo.sql`。

### 第 2 步：启动应用
```bash
cd demo
./mvnw spring-boot:run
```
或先打包再运行：
```bash
./mvnw clean package -DskipTests
java -jar target/springBoot2-0.0.1-SNAPSHOT.jar
```

### 第 3 步：访问
浏览器打开 **http://localhost:8888/api/v1/init**（即登录页，默认端口见 `application.yml`）。

> 如需换端口：`java -jar target/springBoot2-0.0.1-SNAPSHOT.jar --server.port=8890`

---

## 演示账号

种子数据已内置 5 个账号（执行 `testdata_demo.sql` 后会新增 `zhaoliu`），**密码统一为 `123456`**（库中存 BCrypt 密文）：

| 用户名 | 昵称 | 角色 | 说明 |
| --- | --- | --- | --- |
| `admin` | 管理员 | 管理员 | 拥有全部权限，可管理用户 / 角色 / 权限 |
| `zhangsan` | 张三 | 普通用户 | 演示默认角色 |
| `lisi` | 李四 | 普通用户 | 演示默认角色 |
| `wangwu` | 王五 | 普通用户 | 演示默认角色 |
| `zhaoliu` | 赵六 | 普通用户 | 演示数据脚本新增，收件箱有未读、发件箱有一篇文章 |

---

## 页面与接口一览

| 模块 | 说明 | 地址 |
| --- | --- | --- |
| 登录页 / 注册页 | 认证 | `GET /api/v1/init`、`POST /api/v1/user/login`、`GET /api/v1/user/doRegister`、`POST /api/v1/user/register` |
| 主框架 | 后台布局 | `GET /api/v1/mg/main` |
| 工作台 | 数据统计 | `GET /api/v1/mg/welcome` |
| 用户管理 | 列表 / 表单 / 保存 / 删除 | `GET|POST /api/v1/mg/user/list|form|save|delete` |
| 角色管理 | 列表 / 表单 / 保存 / 删除 | `GET|POST /api/v1/mg/role/list|form|save|delete` |
| 权限管理 | 列表 / 表单 / 保存 / 删除 | `GET|POST /api/v1/mg/permission/list|form|save|delete` |
| 邮件（站内信） | 收件箱 / 发件箱 / 写邮件 / 阅读 / 删除 | `GET /api/v1/mg/mail/inbox|sent|write|read`、`POST /api/v1/mg/mail/send|delete` |
| 文章管理 | 列表 / 表单 / 保存 / 删除 / 阅读 | `GET|POST /api/v1/mg/article/list|form|save|delete|view` |
| 分类管理 | 列表 / 表单 / 保存 / 删除 | `GET|POST /api/v1/mg/articletype/list|form|save|delete` |
| 辅助字典 | 省市级联 / 爱好 / 用户名查重 | `/api/v1/np/provinces`、`/api/v1/np/cities/{provinceCode}`、`/api/v1/user/ghn`、`/api/v1/user/cud/{userName}` |
| 占位接口 | 小程序 / hello | `/wx/v1/api/test`、`/hello` |

删除操作传逗号分隔 id（如 `ids=1,2`），结果以 `?ok=` 提示码反馈：用户 `1 新增 / 2 编辑 / 3 删除 / 4 禁止自删`；角色 `1 新增 / 2 编辑 / 3 删除 / 5 被引用`；权限 `1 新增 / 2 编辑 / 3 删除 / 6 被引用`；文章分类 `1 新增 / 2 编辑 / 3 删除 / 7 有子分类 / 8 有文章`；文章 `1 发布 / 2 保存 / 3 删除`；邮件 `1 已发送 / 3 删除 / 0 失败`。

---

## 项目结构

```
spring-boot-teaching-project/
├── README.md
├── LICENSE
├── database/                       # 数据库设计 + 脚本
│   ├── design/
│   │   ├── images/databaseModule.png   # 数据库模型图（PowerDesigner 导出）
│   │   └── module/                     # PDM / PDB 设计源文件（MySQL & Oracle）
│   └── implement/
│       ├── mysql/
│       │   ├── init.sql                # ★ 一键初始化（建库建表 + 演示数据）
│       │   ├── umm_userInfoManager.sql # 用户信息管理（历史拆分版）
│       │   └── umm_userPermissionManager.sql  # 权限管理（历史拆分版）
│       └── oracle/                     # Oracle 版脚本
└── demo/                           # Spring Boot 应用
    ├── pom.xml
    ├── mvnw / mvnw.cmd
    └── src/
        ├── main/java/edu/yuhf/
        │   ├── Application.java            # 启动类
        │   ├── config/                     # WebMvcConfig / LoginInterceptor / GlobalExceptionHandler
        │   ├── controller/  (web)          # 页面控制器（登录注册、后台管理）
        │   ├── wx/controller/              # 小程序占位接口
        │   ├── service/  (+iface)          # 业务层：接口 + 实现
        │   ├── dao/mysql (+iface)          # ★ 手写 JdbcTemplate 数据访问层
        │   └── domain/                     # User / UserDetail / Role / Permission / Hobby / NativePlace / Page
        ├── main/resources/
        │   ├── application.yml             # 端口 8888，数据源 umm/umm
        │   ├── static/                     # css（admin.css / auth.css）、js
        │   └── templates/                  # login / register / views(main、manager/*)
        └── test/java/                      # JUnit 5 测试
```

---

## 数据库设计

库名 `umm`（User Manager Module），共 12 张表，分四组：

**业务 / 字典**
| 表 | 说明 |
| --- | --- |
| `users` | 用户主表（用户名、昵称、BCrypt 密码、性别、邮箱、手机号） |
| `userDetail` | 用户明细（籍贯代码、爱好代码、生日），与 `users` 一对一（`ON DELETE CASCADE`） |
| `hobby` / `nativePlaces` | 爱好、省市字典表 |

**RBAC 权限**
| 表 | 说明 |
| --- | --- |
| `role` | 角色 |
| `permission` | 权限点（标识、URL、描述） |
| `userrole` | 用户-角色多对多 |
| `permissionrole` | 角色-权限多对多 |

**信息发布 / 站内信**
| 表 | 说明 |
| --- | --- |
| `articleType` | 文章分类（两级：`parentId=0` 为一级，`levle` 记录层级） |
| `article` | 文章（标题 / 正文 / 分类 / 作者 / 阅读量 / 点赞量 / 置顶 / 推荐） |
| `mail` | 站内信（`fromId` → `toId`，`isRead` 已读标记） |

**预留**
| 表 | 说明 |
| --- | --- |
| `onlines` | 在线状态（预留） |

关系模型如下（完整设计源文件见 `database/design/module/`，模型图见 `database/design/images/databaseModule.png`）：

```
users ──< userrole >── role ──< permissionrole >── permission
  │
  └──1:1── userDetail（籍贯 / 爱好 / 生日）
```

---

## 代码分层与教学要点

- **Controller（页面控制）**：`UserManagerController` / `RoleManagerController` / `PermissionManagerController` 负责列表分页、表单回填、参数校验与「失败重渲染表单 / 成功 `redirect?ok=`」双分支；`UserController` 处理登录注册；`GlobalExceptionHandler` 兜底系统异常。
- **Service**：接口 + 实现分离（`service/iface`），聚合多 DAO 完成跨表事务（如用户 + 明细 + 角色分配）。
- **DAO（教学重点）**：`dao/mysql` 手写 SQL + `JdbcTemplate`，包含 `RowMapper`、`ResultSetExtractor`、`NamedParameterJdbcTemplate` 等常见写法；联表别名通过 `getColumnLabel` 取值；关联表支持批量插入与覆盖式保存。
- **登录态**：`LoginInterceptor` 对 `/api/**` 统一拦截——页面导航重定向到登录页，AJAX/API 返回 JSON 401；静态资源、登录注册、字典接口、小程序接口放行。
- **安全**：密码一律 BCrypt 加密存储与比对；删除类操作含“自删 / 被引用”业务守卫。
- **前端**：`auth.css`（登录注册）、`admin.css` + 行内样式体系（后台框架与各管理页），纯 Thymeleaf 模板 + 少量原生 JS，无前端工程化负担，适合逐行讲解。

---

## 测试

```bash
cd demo
./mvnw test
```
内置示例覆盖：Controller 冒烟与 MockMvc 切片、JdbcTemplate DAO、BCrypt 单元校验等（`src/test/java/`）。

---

## 规划中模块

后台菜单中的「流程管理模块」（流程实例）仍为占位（敬请期待）。邮件模块与信息发布管理模块已实现：

- 邮件模块基于 `mail` 表（站内信），覆盖写邮件 / 收邮件 / 发件箱；
- 信息发布模块基于 `article` / `articleType` 表，覆盖文章管理与两级分类管理；
- 已有库如需增量升级（补建 `mail` 表 + 文章分类 / 示例文章种子），可执行 `database/implement/mysql/upgrade_module_mail_article.sql`（幂等，可重复执行）；全新安装直接使用 `init.sql`。

---

## License

[MIT](LICENSE) © 2026 Albert