Template

mirror of https://github.com/SOR2171/Springboot4-Vue3_Demo.git synced 2026-10-23 19:41:12 +08:00

Files

T

设为默认中文并全面优化说明与部署文档

2026-10-09 20:48:31 +08:00

11 KiB

Raw Blame History

Springboot4-Vue3

基于 Spring Boot 4 (Kotlin + WebFlux) 与 Vue 3 (Vite + TypeScript + Element Plus) 的现代化前后端分离全栈脚手架 / 示例项目。

赞美学生包

简体中文 / English

项目简介

本项目是一套采用前沿技术栈构建的现代化前后端分离基础模板。后端基于 Spring Boot 4 + Kotlin，采用全异步响应式（Reactive WebFlux）与协程架构，结合 Spring Security 与 JWT 实现了完备的安全认证；前端采用 Vue 3 + Vite 7 + TypeScript + Element Plus，提供了开箱即用的登录、注册、找回密码与主页框架。

核心特性

前沿技术选型：基于 Spring Boot 4.0、Kotlin 2.3 与 JDK 25，拥抱最新的现代化语言与框架特性。
响应式与协程：基于 Spring WebFlux + Reactor + Kotlin Coroutines，高并发、低资源占用。
认证与安全：集成 Spring Security + JWT，支持无状态鉴权、Token 自动刷新（Relogin）、注销黑名单机制与全局 CORS 跨域处理。
接口限流防护：基于 Redis Reactive 实现滑动窗口限流与频次控制（Flow Limit），防止接口被恶意刷取。
异步消息解耦：集成 RabbitMQ + Spring Mail，实现邮件验证码异步发送（支持用户注册与密码重置）。
实时通讯支持：集成响应式 WebSocket 握手与消息通信。
工程化前端：Vue 3 (Composition API <script setup>) + Vite 7 + TypeScript，结合 Element Plus 自动按需导入、统一 Axios 请求拦截与路由鉴权守卫。

🛠️ 技术栈

后端 (Backend)

组件 / 依赖	技术选型	说明
开发语言	Kotlin `2.3.20`	基于 JVM 25 运行环境
基础框架	Spring Boot `4.0.4`	核心脚手架
Web 架构	Spring WebFlux	响应式非阻塞 Web 框架
异步方案	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

前端 (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. 克隆仓库

git clone https://github.com/SOR2171/Springboot4-Vue3_Demo.git
cd Springboot4-Vue3_Demo

2. 后端配置与运行

步骤 1：导入数据库

在 MySQL 中创建名为 kotlin_springboot 的数据库（字符编码建议为 utf8mb4）。
导入预置 SQL 脚本：backend/src/main/resources/springboot_vue3.sql。

预置默认用户：

用户名：test

密码：123456

说明：SQL 脚本中已包含该用户的 BCrypt 密文哈希。如果需要重置测试用户或重新生成密文，可运行单元测试类 BackendApplicationTests。

步骤 2：配置应用参数

进入后端目录：
```
cd 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)

步骤 3：编译与运行

本地开发直接运行：

# Linux / macOS
./gradlew bootRun

# Windows
.\gradlew.bat bootRun

打包为 JAR 文件：
```
# Linux / macOS
./gradlew build -x test

# Windows
.\gradlew.bat build -x test
```
打包生成的 JAR 文件位于：build/libs/backend-1.0.0.jar。

运行 JAR 包：

java --enable-native-access=ALL-UNNAMED -jar build/libs/backend-1.0.0.jar

3. 前端配置与运行

步骤 1：安装依赖

cd frontend
npm install

步骤 2：本地开发运行

npm run dev

启动成功后，浏览器访问控制台提示地址（默认：http://localhost:5173）。

背景图片说明：欢迎页与登录界面的背景图位于 frontend/src/assets/welcome-image.png 。项目中已内置默认图片，如有需要可直接替换为你喜欢的图片。

步骤 3：生产环境打包

npm run build

打包完成后，生成的静态文件将位于 frontend/dist 目录。

Nginx 部署示例（可选）

若在生产环境使用 Nginx 托管前端并代理后端接口，可参考以下配置片段：

server {
    listen       80;
    server_name  localhost; # 替换为你的域名或服务器 IP

    # 前端静态资源托管
    location / {
        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：

sudo nginx -t
sudo systemctl reload nginx

项目结构

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 接口文档

开源许可

本项目基于 MIT License 协议开源。

11 KiB Raw Blame History Unescape Escape