mirror of
https://github.com/SOR2171/Springboot4-Vue3_Demo.git
synced 2026-10-23 19:41:12 +08:00
docs: 将 README
设为默认中文并全面优化说明与部署文档
This commit is contained in:
SOR
@@ -1,122 +1,272 @@
|
|||||||
## Springboot4-Vue3
|
# Springboot4-Vue3
|
||||||
|
|
||||||
###### ~~*Long may the Student Pack*~~
|
> 基于 **Spring Boot 4 (Kotlin + WebFlux)** 与 **Vue 3 (Vite + TypeScript + Element Plus)**
|
||||||
|
> 的现代化前后端分离全栈脚手架 / 示例项目。
|
||||||
|
|
||||||
English / [简体中文](./README_CN.md)
|
[](https://spring.io/projects/spring-boot)
|
||||||
|
[](https://vuejs.org/)
|
||||||
|
[](https://vitejs.dev/)
|
||||||
|
|
||||||
|
[](https://kotlinlang.org/)
|
||||||
|
[](https://openjdk.org/)
|
||||||
|
[](https://www.typescriptlang.org/)
|
||||||
|
|
||||||
|
[](./LICENSE)
|
||||||
|
|
||||||
|
###### ~~*赞美学生包*~~
|
||||||
|
|
||||||
|
简体中文 / [English](./README_EN.md)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Tech Stack
|
## 项目简介
|
||||||
|
|
||||||
#### Backend
|
本项目是一套采用前沿技术栈构建的现代化前后端分离基础模板。后端基于 **Spring Boot 4 + Kotlin**，采用全异步响应式（Reactive
|
||||||
|
WebFlux）与协程架构，结合 Spring Security 与 JWT 实现了完备的安全认证；前端采用 **Vue 3 + Vite 7 + TypeScript + Element
|
||||||
|
Plus**，提供了开箱即用的登录、注册、找回密码与主页框架。
|
||||||
|
|
||||||
- Kotlin with Gradle.kts
|
### 核心特性
|
||||||
- Spring Security
|
|
||||||
- Spring Mail
|
|
||||||
- Mybatis Plus
|
|
||||||
- JWT
|
|
||||||
- MySQL
|
|
||||||
- Redis
|
|
||||||
- RabbitMQ
|
|
||||||
|
|
||||||
#### Frontend
|
- **前沿技术选型**：基于 Spring Boot 4.0、Kotlin 2.3 与 JDK 25，拥抱最新的现代化语言与框架特性。
|
||||||
|
- **响应式与协程**：基于 Spring WebFlux + Reactor + Kotlin Coroutines，高并发、低资源占用。
|
||||||
- Vue3 with Vite and TypeScript
|
- **认证与安全**：集成 Spring Security + JWT，支持无状态鉴权、Token 自动刷新（Relogin）、注销黑名单机制与全局 CORS 跨域处理。
|
||||||
- vue-router
|
- **接口限流防护**：基于 Redis Reactive 实现滑动窗口限流与频次控制（Flow Limit），防止接口被恶意刷取。
|
||||||
- axios
|
- **异步消息解耦**：集成 RabbitMQ + Spring Mail，实现邮件验证码异步发送（支持用户注册与密码重置）。
|
||||||
- element-plus
|
- **实时通讯支持**：集成响应式 WebSocket 握手与消息通信。
|
||||||
|
- **工程化前端**：Vue 3 (Composition API `<script setup>`) + Vite 7 + TypeScript，结合 Element Plus 自动按需导入、统一
|
||||||
|
Axios 请求拦截与路由鉴权守卫。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
#### Project Setup
|
## 🛠️ 技术栈
|
||||||
|
|
||||||
##### General Requirements
|
### 后端 (Backend)
|
||||||
|
|
||||||
- JDK 25+
|
| 组件 / 依赖 | 技术选型 | 说明 |
|
||||||
- Kotlin 2.3.20+
|
|:----------------------|:--------------------------------------|:----------------------------------|
|
||||||
- Node.js 16+
|
| **开发语言** | Kotlin `2.3.20` | 基于 JVM 25 运行环境 |
|
||||||
- MySQL 8+
|
| **基础框架** | Spring Boot `4.0.4` | 核心脚手架 |
|
||||||
- Redis 6+
|
| **Web 架构** | Spring WebFlux | 响应式非阻塞 Web 框架 |
|
||||||
- RabbitMQ 3.8+
|
| **异步方案** | Kotlin Coroutines + Reactor | 协程与响应式流 |
|
||||||
|
| **安全框架** | Spring Security + `java-jwt` | 权限控制与无状态 JWT 鉴权 |
|
||||||
|
| **持久层** | MyBatis-Plus `3.5.15` + MySQL 8.0+ | ORM 框架与关系型数据库 |
|
||||||
|
| **缓存 / 响应式存储** | Spring Data Redis (Reactive) | 响应式 Redis 缓存与限流计数器 |
|
||||||
|
| **消息队列** | RabbitMQ (`spring-boot-starter-amqp`) | 异步邮件发送解耦 |
|
||||||
|
| **邮件服务** | Spring Boot Starter Mail | 验证码邮件发送 |
|
||||||
|
| **构建工具** | Gradle (`build.gradle.kts`) | Kotlin DSL 构建脚本，内置 Wrapper |
|
||||||
|
|
||||||
##### Git clone
|
### 前端 (Frontend)
|
||||||
|
|
||||||
|
| 组件 / 依赖 | 技术选型 | 说明 |
|
||||||
|
|:--------------|:---------------------------------------|:--------------------------------------|
|
||||||
|
| **核心框架** | Vue `3.5` | Composition API (`<script setup>`) |
|
||||||
|
| **构建工具** | Vite `7.2` | 极速冷启动与热重载 |
|
||||||
|
| **开发语言** | TypeScript `5.9` | 强类型支持 |
|
||||||
|
| **UI 组件库** | Element Plus `2.11` | 桌面端组件库，支持自动按需导入 |
|
||||||
|
| **路由管理** | Vue Router `4.6` | 单页应用路由管理与导航守卫 |
|
||||||
|
| **网络请求** | Axios `1.13` | 统一封装拦截器、响应结构与 Token 传递 |
|
||||||
|
| **常用工具** | VueUse, marked, markdown-it, DOMPurify | 组合式工具集与 Markdown 安全渲染 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 环境要求
|
||||||
|
|
||||||
|
在部署与运行项目之前，请确保本地已安装并配置好以下基础环境：
|
||||||
|
|
||||||
|
- **JDK**：`25` 及以上
|
||||||
|
- **Kotlin**：`2.3.20` 及以上
|
||||||
|
- **Node.js**：`18.0.0` 或更高版本（推荐 Node 20 LTS）
|
||||||
|
- **MySQL**：`8.0` 及以上
|
||||||
|
- **Redis**：`6.0` 及以上
|
||||||
|
- **RabbitMQ**：`3.8` 及以上
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 1. 克隆仓库
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/SOR2171/Springboot4-Vue3_Demo.git
|
git clone https://github.com/SOR2171/Springboot4-Vue3_Demo.git
|
||||||
cd Springboot4-Vue3_Demo
|
cd Springboot4-Vue3_Demo
|
||||||
```
|
```
|
||||||
|
|
||||||
##### Backend Setup
|
---
|
||||||
|
|
||||||
1. Go to backend directory
|
### 2. 后端配置与运行
|
||||||
|
|
||||||
|
#### 步骤 1：导入数据库
|
||||||
|
|
||||||
|
1. 在 MySQL 中创建名为 `kotlin_springboot` 的数据库（字符编码建议为 `utf8mb4`）。
|
||||||
|
2. 导入预置 SQL 脚本：[`backend/src/main/resources/springboot_vue3.sql`](./backend/src/main/resources/springboot_vue3.sql)。
|
||||||
|
|
||||||
|
> **预置默认用户**：
|
||||||
|
> - 用户名：`test`
|
||||||
|
> - 密码：`123456`
|
||||||
|
> - *说明：SQL 脚本中已包含该用户的 BCrypt 密文哈希。如果需要重置测试用户或重新生成密文，可运行单元测试类
|
||||||
|
`BackendApplicationTests`。*
|
||||||
|
|
||||||
|
#### 步骤 2：配置应用参数
|
||||||
|
|
||||||
|
1. 进入后端目录：
|
||||||
```bash
|
```bash
|
||||||
cd backend
|
cd backend
|
||||||
```
|
```
|
||||||
|
2. 参考模板创建配置文件：
|
||||||
|
将 [`src/main/resources/application-example.yaml`](./backend/src/main/resources/application-example.yaml) 复制为
|
||||||
|
`src/main/resources/application.yaml`，并填写你的本地实际配置：
|
||||||
|
- 数据库连接与账号密码 (`spring.datasource`)
|
||||||
|
- Redis 连接信息
|
||||||
|
- RabbitMQ 连接信息 (`spring.rabbitmq`)
|
||||||
|
- 邮件 SMTP 服务配置 (`spring.mail`)
|
||||||
|
- JWT 签名密钥 (`spring.security.jwt.key`)
|
||||||
|
|
||||||
2. Configure application properties
|
#### 步骤 3：编译与运行
|
||||||
|
|
||||||
Crate `src/main/resources/application.yml`
|
|
||||||
or edit `src/main/resources/application-example.yml`
|
|
||||||
to set your own configurations.
|
|
||||||
|
|
||||||
3. Load Database
|
|
||||||
|
|
||||||
Import `src/main/resources/springboot_vue3.sql`
|
|
||||||
> default database user:
|
|
||||||
>
|
|
||||||
> username: `test`
|
|
||||||
> password: `123456`
|
|
||||||
>
|
|
||||||
> (the password saved in SQL needs to be obtained through the test class)
|
|
||||||
|
|
||||||
4. Grade build
|
|
||||||
|
|
||||||
|
- **本地开发直接运行**：
|
||||||
```bash
|
```bash
|
||||||
gradle build
|
# Linux / macOS
|
||||||
|
./gradlew bootRun
|
||||||
|
|
||||||
|
# Windows
|
||||||
|
.\gradlew.bat bootRun
|
||||||
```
|
```
|
||||||
|
|
||||||
jar directory: `build/libs/backend-(ver).jar`
|
- **打包为 JAR 文件**：
|
||||||
|
|
||||||
5. Run the backend server
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
java -jar build/libs/backend-(ver).jar
|
# Linux / macOS
|
||||||
|
./gradlew build -x test
|
||||||
|
|
||||||
|
# Windows
|
||||||
|
.\gradlew.bat build -x test
|
||||||
|
```
|
||||||
|
打包生成的 JAR 文件位于：`build/libs/backend-1.0.0.jar`。
|
||||||
|
|
||||||
|
- **运行 JAR 包**：
|
||||||
|
```bash
|
||||||
|
java --enable-native-access=ALL-UNNAMED -jar build/libs/backend-1.0.0.jar
|
||||||
```
|
```
|
||||||
|
|
||||||
##### Frontend Setup
|
---
|
||||||
|
|
||||||
1. Go to frontend directory
|
### 3. 前端配置与运行
|
||||||
|
|
||||||
|
#### 步骤 1：安装依赖
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd frontend
|
cd frontend
|
||||||
|
npm install
|
||||||
```
|
```
|
||||||
|
|
||||||
2. prepare some picture
|
#### 步骤 2：本地开发运行
|
||||||
|
|
||||||
you need a `frontend/src/assets/welcome-image.png`, which is the background of welcome page.
|
```bash
|
||||||
|
npm run dev
|
||||||
3. Build
|
```
|
||||||
|
|
||||||
|
启动成功后，浏览器访问控制台提示地址（默认：`http://localhost:5173`）。
|
||||||
|
|
||||||
|
> **背景图片说明**：
|
||||||
|
> 欢迎页与登录界面的背景图位于 [`frontend/src/assets/welcome-image.png`](./frontend/src/assets/welcome-image.png)
|
||||||
|
> 。项目中已内置默认图片，如有需要可直接替换为你喜欢的图片。
|
||||||
|
|
||||||
|
#### 步骤 3：生产环境打包
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install
|
|
||||||
npm run build
|
npm run build
|
||||||
```
|
```
|
||||||
|
|
||||||
The build files will be generated in `dist` directory.
|
打包完成后，生成的静态文件将位于 `frontend/dist` 目录。
|
||||||
|
|
||||||
##### Nginx Setup (Optional)
|
---
|
||||||
|
|
||||||
If you want to serve the frontend with Nginx, you can follow these steps:
|
## Nginx 部署示例（可选）
|
||||||
|
|
||||||
1. Install Nginx if you don't have it.
|
若在生产环境使用 Nginx 托管前端并代理后端接口，可参考以下配置片段：
|
||||||
|
|
||||||
[download Nginx](https://nginx.org/en/download.html)
|
```nginx
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name localhost; # 替换为你的域名或服务器 IP
|
||||||
|
|
||||||
2. Copy the contents of the `dist` directory to your Nginx `html` directory.
|
# 前端静态资源托管
|
||||||
3. Configure Nginx to serve the frontend and proxy API requests to the backend server.
|
location / {
|
||||||
4. Restart Nginx.
|
root /path/to/Springboot4-Vue3/frontend/dist;
|
||||||
|
index index.html;
|
||||||
|
# 支持 Vue Router 的 History 模式
|
||||||
|
try_files $uri $uri/ /index.html;
|
||||||
|
}
|
||||||
|
|
||||||
|
# 后端 RESTful API 代理
|
||||||
|
location /api/ {
|
||||||
|
proxy_pass http://127.0.0.1:8080/api/;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
proxy_set_header X-Forwarded-Proto $scheme;
|
||||||
|
}
|
||||||
|
|
||||||
|
# WebSocket 代理（如需使用）
|
||||||
|
location /ws/ {
|
||||||
|
proxy_pass http://127.0.0.1:8080/ws/;
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
配置完成后检查并重新加载 Nginx：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
sudo systemctl restart nginx
|
sudo nginx -t
|
||||||
|
sudo systemctl reload nginx
|
||||||
```
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
```text
|
||||||
|
Springboot4-Vue3/
|
||||||
|
├── backend/ # 后端项目 (Kotlin + Spring Boot 4)
|
||||||
|
│ ├── src/main/kotlin/ # Kotlin 源码
|
||||||
|
│ │ └── com/github/sor2171/backend/
|
||||||
|
│ │ ├── config/ # 安全、RabbitMQ、序列化与 WebSocket 配置
|
||||||
|
│ │ ├── controller/ # RESTful API 控制器
|
||||||
|
│ │ ├── entity/ # 实体类、DTO、VO 与枚举定义
|
||||||
|
│ │ ├── filter/ # 跨域 (CORS)、限流与 JWT 认证过滤器
|
||||||
|
│ │ ├── listener/ # RabbitMQ 消息监听器 (异步邮件等)
|
||||||
|
│ │ ├── mapper/ # MyBatis-Plus 数据访问接口
|
||||||
|
│ │ ├── service/ # 业务逻辑接口及实现
|
||||||
|
│ │ └── utils/ # JWT、限流、日期等通用工具类
|
||||||
|
│ ├── src/main/resources/ # 配置文件与 SQL 初始化脚本
|
||||||
|
│ ├── api.md # 详细的后端 API 接口文档
|
||||||
|
│ └── build.gradle.kts # Gradle 依赖与构建配置
|
||||||
|
├── frontend/ # 前端项目 (Vue 3 + Vite + TypeScript)
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── api/ # Axios 请求封装与接口统一管理
|
||||||
|
│ │ ├── assets/ # 静态静态资源 (包含登录背景图)
|
||||||
|
│ │ ├── interfaces/ # TypeScript 接口与类型定义
|
||||||
|
│ │ ├── router/ # 路由配置与全局导航守卫
|
||||||
|
│ │ ├── utils/ # JWT 存储与本地工具类
|
||||||
|
│ │ └── views/ # 页面视图 (欢迎、登录、注册、找回密码、主页)
|
||||||
|
│ ├── package.json # 前端项目依赖与脚本
|
||||||
|
│ └── vite.config.ts # Vite 构建与插件配置
|
||||||
|
├── LICENSE # 开源协议 (MIT)
|
||||||
|
├── README.md # 中文主说明文档
|
||||||
|
└── README_EN.md # 英文说明文档
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 详细文档
|
||||||
|
|
||||||
|
- 接口设计与调用说明详见：[后端 API 接口文档](./backend/api.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 开源许可
|
||||||
|
|
||||||
|
本项目基于 [MIT License](./LICENSE) 协议开源。
|
||||||
|
|||||||
-129
@@ -1,129 +0,0 @@
|
|||||||
## Springboot4-Vue3
|
|
||||||
|
|
||||||
###### ~~*赞美学生包*~~
|
|
||||||
|
|
||||||
[English](./README.md) / 简体中文
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 技术栈
|
|
||||||
|
|
||||||
#### 后端
|
|
||||||
|
|
||||||
- Kotlin + Gradle.kts
|
|
||||||
- Spring Security
|
|
||||||
- Spring Mail
|
|
||||||
- Mybatis Plus
|
|
||||||
- JWT
|
|
||||||
- MySQL
|
|
||||||
- Redis
|
|
||||||
- RabbitMQ
|
|
||||||
|
|
||||||
#### 前端
|
|
||||||
|
|
||||||
- Vue3 + Vite + TypeScript
|
|
||||||
- vue-router
|
|
||||||
- axios
|
|
||||||
- element-plus
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 项目搭建
|
|
||||||
|
|
||||||
#### 基础要求
|
|
||||||
|
|
||||||
- JDK 25+
|
|
||||||
- Kotlin 2.3.20+
|
|
||||||
- Node.js 16+
|
|
||||||
- MySQL 8+
|
|
||||||
- Redis 6+
|
|
||||||
- RabbitMQ 3.8+
|
|
||||||
|
|
||||||
#### Git 克隆项目
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/SOR2171/Springboot4-Vue3_Demo.git
|
|
||||||
cd Springboot4-Vue3_Demo
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 后端配置
|
|
||||||
|
|
||||||
1. 进入后端目录
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd backend
|
|
||||||
```
|
|
||||||
|
|
||||||
2. 配置应用属性
|
|
||||||
|
|
||||||
创建 `src/main/resources/application.yml`
|
|
||||||
或编辑 `src/main/resources/application-example.yml`
|
|
||||||
以设置你自己的配置。
|
|
||||||
|
|
||||||
3. 导入数据库
|
|
||||||
|
|
||||||
导入 `src/main/resources/springboot_vue3.sql`
|
|
||||||
|
|
||||||
> 默认数据库用户：
|
|
||||||
>
|
|
||||||
> 用户名：`test`
|
|
||||||
> 密码：`123456`
|
|
||||||
>
|
|
||||||
> (SQL中保存的密码需要通过测试类获取)
|
|
||||||
|
|
||||||
4. Gradle 构建
|
|
||||||
|
|
||||||
```bash
|
|
||||||
gradle build
|
|
||||||
```
|
|
||||||
|
|
||||||
jar 文件目录：`build/libs/backend-(ver).jar`
|
|
||||||
|
|
||||||
5. 启动后端服务器
|
|
||||||
|
|
||||||
```bash
|
|
||||||
java -jar build/libs/backend-(ver).jar
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### 前端配置
|
|
||||||
|
|
||||||
1. 进入前端目录
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
```
|
|
||||||
|
|
||||||
2. 准备一些图片
|
|
||||||
|
|
||||||
你需要一张 `frontend/src/assets/welcome-image.png` 用作登陆界面的背景
|
|
||||||
|
|
||||||
3. 构建前端
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm install
|
|
||||||
npm run build
|
|
||||||
```
|
|
||||||
|
|
||||||
构建结果会生成在 `dist` 目录中。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### Nginx 部署（可选）
|
|
||||||
|
|
||||||
如果你想使用 Nginx 来部署前端，可以按以下步骤操作：
|
|
||||||
|
|
||||||
1. 若未安装 Nginx，请先安装。
|
|
||||||
|
|
||||||
[下载 Nginx](https://nginx.org/en/download.html)
|
|
||||||
|
|
||||||
2. 将 `dist` 目录中的内容复制到 Nginx 的 `html` 目录。
|
|
||||||
|
|
||||||
3. 配置 Nginx，使其能够提供前端页面，并将 API 请求代理到后端服务器。
|
|
||||||
|
|
||||||
4. 重启 Nginx。
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo systemctl restart nginx
|
|
||||||
```
|
|
||||||
+277
@@ -0,0 +1,277 @@
|
|||||||
|
# Springboot4-Vue3
|
||||||
|
|
||||||
|
> A modern full-stack starter template / demo project based on **Spring Boot 4 (Kotlin + WebFlux)** and **Vue 3 (Vite +
|
||||||
|
TypeScript + Element Plus)**.
|
||||||
|
|
||||||
|
[](https://spring.io/projects/spring-boot)
|
||||||
|
[](https://vuejs.org/)
|
||||||
|
[](https://vitejs.dev/)
|
||||||
|
|
||||||
|
[](https://kotlinlang.org/)
|
||||||
|
[](https://openjdk.org/)
|
||||||
|
[](https://www.typescriptlang.org/)
|
||||||
|
|
||||||
|
[](./LICENSE)
|
||||||
|
|
||||||
|
###### ~~*Long may the Student Pack*~~
|
||||||
|
|
||||||
|
[简体中文](./README.md) / English
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Introduction
|
||||||
|
|
||||||
|
This project is a modern boilerplate for front-end and back-end separation built with cutting-edge technologies. The
|
||||||
|
backend uses **Spring Boot 4 + Kotlin** with a fully asynchronous reactive architecture (Spring WebFlux) and coroutines,
|
||||||
|
integrated with Spring Security and JWT for authentication. The frontend is powered by **Vue 3 + Vite 7 + TypeScript +
|
||||||
|
Element Plus**, providing out-of-the-box pages for login, registration, password recovery, and the home dashboard.
|
||||||
|
|
||||||
|
### Features
|
||||||
|
|
||||||
|
- **Modern Tech Stack**: Spring Boot 4.0, Kotlin 2.3, and JDK 25, embracing the latest language and framework
|
||||||
|
improvements.
|
||||||
|
- **Reactive & Coroutines**: Built on Spring WebFlux + Reactor + Kotlin Coroutines for high throughput and low resource
|
||||||
|
footprint.
|
||||||
|
- **Authentication & Security**: Spring Security + JWT stateless authentication, token renewal (relogin), token
|
||||||
|
blacklisting on logout, and global CORS configuration.
|
||||||
|
- **Rate Limiting**: Reactive Redis-backed sliding window rate limiter and IP/user ban controls (Flow Limit).
|
||||||
|
- **Asynchronous Queue**: RabbitMQ + Spring Mail for decoupled async email verification (user registration & password
|
||||||
|
reset).
|
||||||
|
- **Real-time Communication**: Reactive WebSocket handshake and messaging support.
|
||||||
|
- **Engineered Frontend**: Vue 3 (Composition API `<script setup>`) + Vite 7 + TypeScript, on-demand component
|
||||||
|
auto-importing, Axios request/response interceptors, and route guards.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ Tech Stack
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
|
||||||
|
| Component / Dependency | Technology | Notes |
|
||||||
|
|:-----------------------------|:--------------------------------------|:---------------------------------------|
|
||||||
|
| **Language** | Kotlin `2.3.20` | JVM 25 target |
|
||||||
|
| **Framework** | Spring Boot `4.0.4` | Core starter |
|
||||||
|
| **Web Layer** | Spring WebFlux | Reactive non-blocking web framework |
|
||||||
|
| **Concurrency** | Kotlin Coroutines + Reactor | Coroutines & Reactive streams |
|
||||||
|
| **Security** | Spring Security + `java-jwt` | Stateless JWT authentication & filters |
|
||||||
|
| **Persistence** | MyBatis-Plus `3.5.15` + MySQL 8.0+ | ORM & Relational database |
|
||||||
|
| **Caching / Reactive Store** | Spring Data Redis (Reactive) | Caching & rate limiting counter |
|
||||||
|
| **Message Queue** | RabbitMQ (`spring-boot-starter-amqp`) | Decoupled async email queue |
|
||||||
|
| **Mail Service** | Spring Boot Starter Mail | Verification code delivery |
|
||||||
|
| **Build Tool** | Gradle (`build.gradle.kts`) | Kotlin DSL with Gradle Wrapper |
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
|
||||||
|
| Component / Dependency | Technology | Notes |
|
||||||
|
|:-----------------------|:---------------------------------------|:---------------------------------------------|
|
||||||
|
| **Framework** | Vue `3.5` | Composition API (`<script setup>`) |
|
||||||
|
| **Build Tool** | Vite `7.2` | Fast HMR & bundling |
|
||||||
|
| **Language** | TypeScript `5.9` | Type safety |
|
||||||
|
| **UI Library** | Element Plus `2.11` | Desktop UI with auto-import support |
|
||||||
|
| **Routing** | Vue Router `4.6` | SPA routing & navigation guards |
|
||||||
|
| **HTTP Client** | Axios `1.13` | Unified interceptors & token injection |
|
||||||
|
| **Utilities** | VueUse, marked, markdown-it, DOMPurify | Utility hooks & sanitized Markdown rendering |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
Ensure the following environments are installed before running the project:
|
||||||
|
|
||||||
|
- **JDK**: `25` or higher
|
||||||
|
- **Kotlin**: `2.3.20` or higher
|
||||||
|
- **Node.js**: `18.0.0` or higher (Node 20 LTS recommended)
|
||||||
|
- **MySQL**: `8.0` or higher
|
||||||
|
- **Redis**: `6.0` or higher
|
||||||
|
- **RabbitMQ**: `3.8` or higher
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### 1. Clone Repository
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/SOR2171/Springboot4-Vue3_Demo.git
|
||||||
|
cd Springboot4-Vue3_Demo
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. Backend Setup & Run
|
||||||
|
|
||||||
|
#### Step 1: Database Initialization
|
||||||
|
|
||||||
|
1. Create a MySQL database named `kotlin_springboot` (recommended charset: `utf8mb4`).
|
||||||
|
2. Import the initial SQL script: [`backend/src/main/resources/springboot_vue3.sql`](./backend/src/main/resources/springboot_vue3.sql).
|
||||||
|
|
||||||
|
> **Default Test User**:
|
||||||
|
> - Username: `test`
|
||||||
|
> - Password: `123456`
|
||||||
|
> - *Note: The SQL script contains a pre-hashed BCrypt password. You can run unit tests in `BackendApplicationTests` to
|
||||||
|
generate new hashes or reset the user.*
|
||||||
|
|
||||||
|
#### Step 2: Configure Properties
|
||||||
|
|
||||||
|
1. Navigate to the backend directory:
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
```
|
||||||
|
2. Create `application.yaml` based on the example:
|
||||||
|
Copy [`src/main/resources/application-example.yaml`](./backend/src/main/resources/application-example.yaml) to
|
||||||
|
`src/main/resources/application.yaml`, and update with your actual credentials:
|
||||||
|
- MySQL datasource (`spring.datasource`)
|
||||||
|
- Redis host & port
|
||||||
|
- RabbitMQ connection (`spring.rabbitmq`)
|
||||||
|
- Mail SMTP credentials (`spring.mail`)
|
||||||
|
- JWT secret key (`spring.security.jwt.key`)
|
||||||
|
|
||||||
|
#### Step 3: Build & Start
|
||||||
|
|
||||||
|
- **Development Mode**:
|
||||||
|
```bash
|
||||||
|
# Linux / macOS
|
||||||
|
./gradlew bootRun
|
||||||
|
|
||||||
|
# Windows
|
||||||
|
.\gradlew.bat bootRun
|
||||||
|
```
|
||||||
|
|
||||||
|
- **Build Executable JAR**:
|
||||||
|
```bash
|
||||||
|
# Linux / macOS
|
||||||
|
./gradlew build -x test
|
||||||
|
|
||||||
|
# Windows
|
||||||
|
.\gradlew.bat build -x test
|
||||||
|
```
|
||||||
|
The packaged JAR will be located at `build/libs/backend-1.0.0.jar`.
|
||||||
|
|
||||||
|
- **Run JAR**:
|
||||||
|
```bash
|
||||||
|
java --enable-native-access=ALL-UNNAMED -jar build/libs/backend-1.0.0.jar
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Frontend Setup & Run
|
||||||
|
|
||||||
|
#### Step 1: Install Dependencies
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Step 2: Development Server
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Open the displayed URL in your browser (default: `http://localhost:5173`).
|
||||||
|
|
||||||
|
> **Background Image**:
|
||||||
|
> The welcome & login background image is located at [`frontend/src/assets/welcome-image.png`](./frontend/src/assets/welcome-image.png). A default image is already provided;
|
||||||
|
> replace it with your own image if desired.
|
||||||
|
|
||||||
|
#### Step 3: Production Build
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
The compiled static assets will be output to the `frontend/dist` directory.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Nginx Deployment (Optional)
|
||||||
|
|
||||||
|
For production deployment with Nginx hosting the frontend and reverse proxying backend APIs:
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name localhost; # Replace with your domain or IP
|
||||||
|
|
||||||
|
# Frontend SPA static files
|
||||||
|
location / {
|
||||||
|
root /path/to/Springboot4-Vue3/frontend/dist;
|
||||||
|
index index.html;
|
||||||
|
# Support Vue Router history mode
|
||||||
|
try_files $uri $uri/ /index.html;
|
||||||
|
}
|
||||||
|
|
||||||
|
# Backend RESTful API reverse proxy
|
||||||
|
location /api/ {
|
||||||
|
proxy_pass http://127.0.0.1:8080/api/;
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
proxy_set_header X-Forwarded-Proto $scheme;
|
||||||
|
}
|
||||||
|
|
||||||
|
# WebSocket proxy (if needed)
|
||||||
|
location /ws/ {
|
||||||
|
proxy_pass http://127.0.0.1:8080/ws/;
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Validate and reload Nginx:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo nginx -t
|
||||||
|
sudo systemctl reload nginx
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
Springboot4-Vue3/
|
||||||
|
├── backend/ # Backend project (Kotlin + Spring Boot 4)
|
||||||
|
│ ├── src/main/kotlin/ # Kotlin source code
|
||||||
|
│ │ └── com/github/sor2171/backend/
|
||||||
|
│ │ ├── config/ # Security, RabbitMQ, Serialization, WebSocket config
|
||||||
|
│ │ ├── controller/ # RESTful API controllers
|
||||||
|
│ │ ├── entity/ # Entity, DTO, VO, and enum definitions
|
||||||
|
│ │ ├── filter/ # CORS, Flow limit, and JWT authentication filters
|
||||||
|
│ │ ├── listener/ # RabbitMQ message listeners (async email, etc.)
|
||||||
|
│ │ ├── mapper/ # MyBatis-Plus database mappers
|
||||||
|
│ │ ├── service/ # Business service interfaces and implementations
|
||||||
|
│ │ └── utils/ # Utilities (JWT, flow limit, date, etc.)
|
||||||
|
│ ├── src/main/resources/ # Config files and database SQL init script
|
||||||
|
│ ├── api.md # Detailed backend API documentation
|
||||||
|
│ └── build.gradle.kts # Gradle dependencies and build script
|
||||||
|
├── frontend/ # Frontend project (Vue 3 + Vite + TypeScript)
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── api/ # Axios request wrappers & API services
|
||||||
|
│ │ ├── assets/ # Static assets (including welcome image)
|
||||||
|
│ │ ├── interfaces/ # TypeScript interfaces & types
|
||||||
|
│ │ ├── router/ # Route definitions & guards
|
||||||
|
│ │ ├── utils/ # JWT storage & local utilities
|
||||||
|
│ │ └── views/ # Views (Welcome, Login, Register, Reset, Home)
|
||||||
|
│ ├── package.json # Dependencies and scripts
|
||||||
|
│ └── vite.config.ts # Vite build and plugin configurations
|
||||||
|
├── LICENSE # Open-source license (MIT)
|
||||||
|
├── README.md # Chinese documentation (Default)
|
||||||
|
└── README_EN.md # English documentation
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
- Detailed API specifications can be found in: [Backend API Documentation](./backend/api.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is licensed under the [MIT License](./LICENSE).
|
||||||
Reference in New Issue
Block a user