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

A modern full-stack starter template / demo project based on Spring Boot 4 (Kotlin + WebFlux) and Vue 3 (Vite + TypeScript + Element Plus).

Long may the Student Pack

简体中文 / 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

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

2. Backend Setup & Run

Step 1: Database Initialization

Create a MySQL database named kotlin_springboot (recommended charset: utf8mb4).
Import the initial SQL script: 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

Navigate to the backend directory:
```
cd backend
```
Create application.yaml based on the example: Copy 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:

# Linux / macOS
./gradlew bootRun

# Windows
.\gradlew.bat bootRun

Build Executable JAR:

# 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:

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

3. Frontend Setup & Run

Step 1: Install Dependencies

cd frontend
npm install

Step 2: Development Server

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. A default image is already provided; replace it with your own image if desired.

Step 3: Production Build

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:

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:

sudo nginx -t
sudo systemctl reload nginx

Project Structure

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

License

This project is licensed under the MIT License.

11 KiB Raw Blame History