# getoffer-admin
**Repository Path**: hbuzc/getoffer-admin
## Basic Information
- **Project Name**: getoffer-admin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 9
- **Forks**: 2
- **Created**: 2025-11-12
- **Last Updated**: 2026-05-27
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# GetOffer Admin
**一个专门为 Java 初学者设计的后台管理系统学习项目**
精心准备了从零到一的后台管理系统代码，代码简洁、注释完整、分层清晰，适合用来学习 Spring Boot 后端开发的完整流程。
---
## 这个项目是什么？
这是一个 **Spring Boot 后台管理系统的后端项目**，包含了后台管理系统中最常见的功能：用户管理、角色权限、菜单配置、部门岗位、字典管理、文件上传、系统监控等。
项目的初衷是 **为初学者提供一个完整的、可运行的学习案例**。代码里没有过度封装，每个模块都按照 Controller → Service → Manager → Dao 的分层结构组织，让你能清楚地看到每一层做了什么、数据是如何流转的。
## 适合谁看？
- 学完 Spring Boot 基础，想找一个**完整项目**来练手的同学
- 想理解**后台管理系统**后端是怎么设计的同学
- 准备面试，需要一个项目来讲解自己**对分层架构的理解**的同学
- 想学习 **RBAC 权限模型**实际怎么落地实现的同学
## 你能从这个项目中学到什么？
| 知识点 | 在项目中的体现 |
|--------|---------------|
| **分层架构** | Controller → Service → Manager → Dao 四层调用链路 |
| **RBAC 权限模型** | 用户-角色-菜单 的关联设计与 Sa-Token 集成 |
| **RESTful API 设计** | 统一的 Result 响应体、参数校验、分页查询 |
| **MyBatis-Plus 实战** | 代码生成器、分页插件、逻辑删除、条件构造器 |
| **全局异常处理** | `@RestControllerAdvice` 统一拦截业务异常 |
| **AOP 切面编程** | 操作日志自动记录（`@HandleLog` 注解） |
| **策略模式** | 文件存储支持本地/MinIO/阿里云OSS/腾讯云COS一键切换 |
| **系统监控** | 在线用户、Redis缓存信息、服务器状态、SQL统计 |
| **Druid 连接池** | 慢SQL监控、连接池配置 |
## 技术栈
| 技术 | 说明 | 为什么选它？ |
|------|------|-------------|
| Spring Boot 3.4 | 基础框架 | 最主流的 Java 后端框架，生态丰富 |
| MyBatis-Plus 3.5 | ORM框架 | MyBatis 增强，简化单表CRUD，学习成本低 |
| Sa-Token 1.40 | 权限认证 | 比 Spring Security 更轻量，注解式鉴权，入门友好 |
| MySQL 8.0 | 关系型数据库 | 面试必问，项目必用 |
| Redis 7.0 | 缓存/会话 | Sa-Token 会话存储，面试高频 |
| Druid 1.2 | 数据库连接池 | Alibaba开源，自带监控面板 |
| Hutool 5.8 | 工具类库 | 一个jar包解决大部分工具类需求 |
| Lombok | 代码简化 | 告别 getter/setter 样板代码 |
| Quartz | 定时任务 | Spring Boot 原生集成，配置简单 |
| FreeMarker | 模板引擎 | 用于代码生成器的模板渲染 |
## 项目结构
```
src/main/java/com/getoffer/admin/
│
├── AdminApplication.java # Spring Boot 启动入口
│
├── config/ # 配置类
│ ├── SaTokenConfig.java # Sa-Token 权限框架配置
│ ├── MybatisPlusConfig.java # MyBatis-Plus 分页插件配置
│ ├── JacksonConfig.java # JSON 序列化配置
│ ├── WebMvcConfig.java # 跨域/拦截器等 Web 配置
│ ├── VirtualThreadConfig.java # Java 21 虚拟线程配置
│ └── StpInterfaceImpl.java # Sa-Token 权限数据加载
│
├── common/ # 公共基础层
│ ├── base/
│ │ ├── BaseEntity.java # 所有实体的父类（统一公共字段）
│ │ ├── BaseMapperPlus.java # 增强版 Mapper 基类
│ │ ├── PageQuery.java # 分页查询参数
│ │ └── PageResult.java # 分页查询结果
│ ├── result/
│ │ ├── Result.java # 统一 API 响应体
│ │ └── ResultCode.java # 响应状态码枚举
│ ├── exception/
│ │ ├── BusinessException.java # 业务异常类
│ │ └── GlobalExceptionHandler.java # 全局异常处理器
│ ├── context/
│ │ ├── LoginUserHolder.java # 当前登录用户持有者
│ │ └── TraceContext.java # 请求链路追踪
│ ├── annotation/
│ │ └── HandleLog.java # 操作日志注解（AOP）
│ ├── aspect/
│ │ └── RequestLogAspect.java # 请求日志切面
│ ├── constant/
│ │ └── CommonConstant.java # 全局常量
│ └── util/
│ └── IPUtils.java # IP 地址工具类
│
├── module/ # 业务模块层
│ ├── system/ # 系统管理（核心模块）
│ │ ├── controller/ # Controller - 接收请求
│ │ │ ├── UserController.java # 用户管理
│ │ │ ├── RoleController.java # 角色管理
│ │ │ ├── MenuController.java # 菜单管理
│ │ │ ├── DeptController.java # 部门管理
│ │ │ ├── PostController.java # 岗位管理
│ │ │ ├── DictTypeController.java # 字典类型
│ │ │ ├── DictDataController.java # 字典数据
│ │ │ ├── LoginLogController.java # 登录日志
│ │ │ └── OperateLogController.java # 操作日志
│ │ ├── service/ # Service - 业务逻辑
│ │ ├── manager/ # Manager - 数据操作封装
│ │ ├── dao/ # Dao - 数据库访问（Mapper）
│ │ └── model/
│ │ ├── entity/ # 数据库实体类
│ │ ├── dto/ # 入参对象（Request）
│ │ ├── vo/ # 出参对象（Response）
│ │ └── bo/ # 业务对象
│ │
│ ├── config/ # 系统配置管理
│ ├── file/ # 文件管理
│ │ └── storage/ # 存储策略实现
│ │ ├── StorageStrategy.java # 策略接口
│ │ ├── StorageContext.java # 策略上下文
│ │ ├── LocalStorageStrategy.java # 本地存储
│ │ ├── MinioStorageStrategy.java # MinIO存储
│ │ ├── AliyunOssStrategy.java # 阿里云OSS
│ │ └── TencentCosStrategy.java # 腾讯云COS
│ │
│ └── monitor/ # 系统监控
│ └── controller/
│ ├── OnlineUserController.java # 在线用户
│ ├── CacheController.java # 缓存监控
│ ├── ServerController.java # 服务监控
│ └── SqlStatController.java # SQL统计
│
└── resources/
├── application.yml # 主配置文件
├── application-dev.yml # 开发环境配置
└── application-prod.yml # 生产环境配置
```
## 代码分层设计（重点理解）
这是这个项目最值得学习的地方，每一层职责清晰：
```
┌─────────────────────────────────┐
│ Controller │ ← 接收HTTP请求，参数校验，返回响应
│ 调用 Service，不写业务逻辑 │
└─────────────┬───────────────────┘
│
┌─────────────▼───────────────────┐
│ Service │ ← 写业务逻辑，事务控制
│ 调用 Manager，组装数据 │
└─────────────┬───────────────────┘
│
┌─────────────▼───────────────────┐
│ Manager │ ← 数据操作封装，缓存处理
│ 调用 Dao，处理数据转换 │ 复用性：一个 Manager 可被多个 Service 调用
└─────────────┬───────────────────┘
│
┌─────────────▼───────────────────┐
│ Dao │ ← 数据库访问（MyBatis-Plus Mapper）
│ 不写业务，只做数据查询 │
└─────────────────────────────────┘
```
### 为什么要多一层 Manager？
你可能好奇：为什么 Service 不直接调用 Dao，中间要多一层 Manager？
- **复用性：** 比如获取用户信息的逻辑，UserService 和 RoleService 都可能用到，放在 UserManager 里两者都能调用，避免代码重复。
- **数据转换：** Entity 到 VO/BO 的转换放在 Manager 层，Service 层拿到手就是可直接用的对象。
- **缓存控制：** 如果需要对某些查询加缓存，在 Manager 层统一处理，上层无感知。
## 功能列表
### 系统管理
- **用户管理** - 增删改查、状态启用/禁用、重置密码、分配角色
- **角色管理** - 增删改查、分配菜单权限、设置数据权限范围
- **菜单管理** - 目录/菜单/按钮三级结构、权限标识配置
- **部门管理** - 树形组织架构
- **岗位管理** - 岗位增删改查
- **字典管理** - 字典类型 + 字典数据，系统枚举统一维护
### 日志管理
- **登录日志** - 记录每次登录的时间、IP、地点
- **操作日志** - `@HandleLog` 注解自动记录用户操作
### 文件管理
- 文件上传/下载/预览/删除
- 支持多种存储方式切换：本地 → MinIO → 阿里云OSS → 腾讯云COS
### 系统监控
- **在线用户** - 查看当前登录用户，支持强制下线
- **服务监控** - CPU、内存、JVM 信息
- **缓存监控** - Redis 信息查看
- **SQL 监控** - Druid 慢 SQL 统计
### 系统配置
- 系统参数动态配置，支持分组管理
## 环境准备
在运行项目之前，确保你的电脑安装了以下软件：
| 软件 | 版本要求 | 检查命令 |
|------|---------|---------|
| JDK | 17 或以上（推荐 21） | `java -version` |
| Maven | 3.8+ | `mvn -v` |
| MySQL | 8.0+ | `mysql --version` |
| Redis | 7.0+ | `redis-cli ping` |
> **提示：** 如果你是初学者不知道怎么装这些环境，可以先搜索"Java开发环境搭建教程"，这是每个 Java 开发者的基本功。
## 快速开始
### 第一步：克隆项目
```bash
git clone https://gitee.com/hbuzc/getoffer-admin.git
cd getoffer-admin
```
### 第二步：创建数据库
打开你的 MySQL 客户端，执行以下 SQL：
```sql
-- 创建数据库
CREATE DATABASE getoffer_admin DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```
数据库表结构会在项目启动时由 MyBatis-Plus 自动创建（也可以手动导入 SQL 文件）。
### 第三步：修改配置
打开 `src/main/resources/application-dev.yml`，修改你的数据库和 Redis 连接信息：
```yaml
spring:
datasource:
url: jdbc:mysql://localhost:3306/getoffer_admin?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai
username: root # 改成你的MySQL用户名
password: 你的密码 # 改成你的MySQL密码
data:
redis:
host: localhost # 改成你的Redis地址
port: 6379 # 改成你的Redis端口
password: 你的密码 # 没有密码就留空
```
> **提示：** 这个修改只需要改3个地方——数据库密码、Redis 地址和密码。
### 第四步：启动项目
```bash
# 在项目根目录下执行
mvn clean package -DskipTests
mvn spring-boot:run
```
看到 `Started AdminApplication` 就说明启动成功了。后端运行在 `http://localhost:8081/api`。
### 第五步：测试接口
用浏览器或 Postman 访问 `http://localhost:8081/api`，如果能正常返回，说明项目启动成功。
> **配套前端：** 这个项目是纯后端，需要配合前端项目一起使用。推荐使用 Apifox 或 Postman 来测试接口。
## 如何学习这个项目？
建议按以下顺序阅读代码：
```
第1步：看启动流程
└── AdminApplication.java → application.yml → 理解一个 Spring Boot 项目是怎么启动的
第2步：看公共层设计
└── common/result/Result.java → 理解统一响应体的设计
└── common/exception/ → 理解全局异常处理
└── common/base/BaseEntity.java → 理解实体类的公共字段抽取
第3步：看一个完整的 CRUD 模块（以用户管理为例）
└── UserController.java → 接收请求，看看有哪些接口
└── UserService.java → 业务逻辑怎么写
└── UserManager.java → 数据操作怎么写
└── SysUserDao.java → MyBatis-Plus 怎么用
└── SysUser.java → 数据库表怎么映射
第4步：看权限是怎么做的
└── config/StpInterfaceImpl.java → 权限数据从哪来
└── controller 里的 @SaCheckPermission 注解 → 权限怎么控制
第5步：看设计模式
└── module/file/storage/ → 策略模式的实际应用
第6步：看切面编程
└── common/annotation/HandleLog.java → 自定义注解
└── common/aspect/RequestLogAspect.java → 切面实现
```
## 常见问题
**Q: 启动时报 MySQL 连接失败？**
A: 检查 `application-dev.yml` 中的数据库用户名和密码是否正确，以及 MySQL 服务是否已启动。
**Q: 启动时报 Redis 连接失败？**
A: 确保 Redis 服务已启动。可以用 `redis-cli ping` 测试，如果返回 `PONG` 说明正常。
**Q: 为什么选择 Sa-Token 而不是 Spring Security？**
A: Spring Security 功能强大但配置复杂，对初学者不太友好。Sa-Token 更轻量、注解式鉴权更容易理解，等理解了权限模型后再学 Spring Security 也不迟。
**Q: 我想给这个项目加前端怎么办？**
A: 建议先把这个后端的代码理解透彻，然后用 Vue 3 + Element Plus 或者 React + Ant Design 来写前端。理解后端接口的入参出参后，前端就是页面展示和接口对接的工作了。
## 开源协议
本项目基于 [MIT License](LICENSE) 开源，你可以自由地学习、修改和使用代码。
---
**如果这个项目对你有帮助，请给一个 Star 支持一下！**