# springboot-template

**Repository Path**: XingXuan-Sivan/springboot-template

## Basic Information

- **Project Name**: springboot-template
- **Description**: SpringBoot + Mybatis Plus 后端项目模板
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpringBoot + Mybatis Plus 后端项目模板

一个标准的 Spring Boot + MyBatis-Plus + MySQL 模板项目，采用经典三层架构（Controller → Service → Mapper），提供完整的 RESTful API 示例，适合学习和实际开发使用。

## 技术栈


| 技术         | 版本   | 说明                |
| ------------ | ------ | ------------------- |
| Spring Boot  | 3.2.5  | 基础框架            |
| MyBatis-Plus | 3.5.5  | ORM 增强工具        |
| MySQL        | 8.0    | 关系型数据库        |
| Lombok       | -      | 简化 POJO 代码      |
| Validation   | -      | 参数校验（JSR-303） |
| Maven        | 3.x    | 项目构建与依赖管理  |
| JDK          | 17     | Java 运行环境       |
| JWT (jjwt)   | 0.12.5 | Token 鉴权          |

## 项目结构

```
springboot-template/
├── sql/
│   └── init.sql                        # 数据库初始化脚本（建库 + 建表 + 示例数据）
├── src/main/
│   ├── java/com/example/demo/
│   │   ├── DemoApplication.java        # Spring Boot 启动类
│   │   ├── common/                     # 通用模块
│   │   │   ├── Result.java             # 统一 API 响应体
│   │   │   ├── ResultCode.java         # 响应状态码枚举
│   │   │   ├── BusinessException.java  # 自定义业务异常
│   │   │   ├── GlobalExceptionHandler.java  # 全局异常处理器
│   │   │   ├── JwtUtil.java             # JWT 工具类
│   │   │   └── JwtInterceptor.java      # JWT 认证拦截器
│   │   ├── config/                     # 配置模块
│   │   │   ├── MyBatisPlusConfig.java  # MyBatis-Plus 分页插件配置
│   │   │   ├── CorsConfig.java         # 跨域配置
│   │   │   └── WebConfig.java          # JWT 拦截器注册
│   │   ├── controller/                 # 表现层（Controller）
│   │   │   ├── AuthController.java     # 认证接口（登录）
│   │   │   └── UserController.java     # 用户接口
│   │   ├── service/                    # 业务逻辑层（Service）
│   │   │   ├── UserService.java        # 用户服务接口
│   │   │   └── impl/
│   │   │       └── UserServiceImpl.java  # 用户服务实现
│   │   ├── mapper/                     # 数据访问层（Mapper）
│   │   │   └── UserMapper.java         # 用户 Mapper
│   │   ├── entity/                     # 实体类
│   │   │   └── User.java               # 用户实体
│   │   └── dto/                        # 数据传输对象
│   │       ├── UserCreateDTO.java      # 创建用户 DTO
│   │       ├── UserUpdateDTO.java      # 更新用户 DTO
│   │       └── UserQueryDTO.java       # 查询用户 DTO
│   └── resources/
│       ├── application.yml             # 主配置文件
│       ├── application-dev.yml         # 开发环境配置
│       └── application-prod.yml        # 生产环境配置
├── .gitignore
├── pom.xml
└── README.md
```

## 三层架构说明

```
┌────────────────────────────────────────────┐
│                  Controller 层              │
│  (接收请求、参数校验、返回响应)              │
│  使用 @RestController + @RequestMapping    │
└──────────────────┬─────────────────────────┘
                   │ 调用
┌──────────────────▼─────────────────────────┐
│                  Service 层                 │
│  (业务逻辑处理、事务管理)                    │
│  接口 + 实现类，使用 @Service               │
└──────────────────┬─────────────────────────┘
                   │ 调用
┌──────────────────▼─────────────────────────┐
│                  Mapper 层                  │
│  (数据访问、SQL 执行)                       │
│  继承 BaseMapper，使用 @Mapper              │
└──────────────────┬─────────────────────────┘
                   │ 操作
┌──────────────────▼─────────────────────────┐
│                   MySQL 数据库              │
└────────────────────────────────────────────┘
```

**DTO（数据传输对象）**：用于接收前端请求参数，与实体分离，避免直接暴露数据库结构。

**Entity（实体类）**：与数据库表一一对应，使用 MyBatis-Plus 注解进行 ORM 映射。

## 快速开始

### 1. 环境准备


| 工具       | 版本          | 说明                | 下载地址                                                                                                     |
| ---------- | ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
| JDK        | 17            | Java 运行与编译环境 | [Adoptium](https://adoptium.net/) / [Oracle JDK](https://www.oracle.com/java/technologies/downloads/#java17) |
| Maven      | 3.x           | 项目构建与依赖管理  | [Maven 官网](https://maven.apache.org/download.cgi)                                                          |
| MySQL      | 8.0           | 关系型数据库        | [MySQL 官网](https://dev.mysql.com/downloads/mysql/8.0.html)                                                 |
| IDE (推荐) | IntelliJ IDEA | Java 集成开发环境   | [IDEA 官网](https://www.jetbrains.com/idea/download/)（Community 版免费）                                    |

> **提示**：JDK 17 推荐使用 [Eclipse Adoptium](https://adoptium.net/) 提供的 OpenJDK 发行版，免费且长期支持。
>
> 安装完成后，在终端执行 `java -version` 和 `mvn -version` 确认版本正确。

### 2. 导入 IDE（IntelliJ IDEA）

1. 打开 IntelliJ IDEA，点击 **File → Open**
2. 选择 `SpringBoot-template` 目录
3. IDEA 会自动识别 Maven 项目，等待依赖下载完成
4. 找到 `DemoApplication.java`，右键 → **Run** 即可启动

### 3. 初始化数据库

在 MySQL 中执行 `sql/init.sql` 脚本：

```bash
mysql -u root -p < sql/init.sql
```

该脚本会创建 `springboot_demo` 数据库、`user` 表，并插入 3 条示例数据。

### 4. 修改数据库连接

编辑 `src/main/resources/application-dev.yml`，将数据库用户名和密码修改为你本机的配置：

```yaml
spring:
  datasource:
    username: root       # 修改为你的 MySQL 用户名
    password: 123456     # 修改为你的 MySQL 密码
```

### 5. 启动项目

```bash
# 编译并启动
mvn clean spring-boot:run

# 或者先打包再运行
mvn clean package -DskipTests
java -jar target/springboot-template-1.0.0.jar
```

启动成功后访问: http://localhost:8080

### 6. 指定环境启动

```bash
# 使用生产环境配置
java -jar target/springboot-template-1.0.0.jar --spring.profiles.active=prod
```

## API 接口文档

### 统一响应格式

所有接口返回格式如下：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

### 认证接口


| 方法 | URL             | 说明     | 请求体          |
| ---- | --------------- | -------- | --------------- |
| POST | /api/auth/login | 用户登录 | JSON (LoginDTO) |

#### POST /api/auth/login —— 用户登录

请求示例：

```json
{
  "username": "admin",
  "password": "123456"
}
```

响应示例：

```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "userId": 1,
    "username": "admin"
  }
}
```

> 登录成功后，后续请求需在 Header 中携带 `Authorization: Bearer <token>`。
> 测试账号：admin / 123456

### 用户管理接口


| 方法   | URL             | 说明           | 请求体               |
| ------ | --------------- | -------------- | -------------------- |
| GET    | /api/users      | 分页查询用户   | Query 参数           |
| GET    | /api/users/{id} | 根据ID查询用户 | -                    |
| POST   | /api/users      | 新增用户       | JSON (UserCreateDTO) |
| PUT    | /api/users/{id} | 更新用户       | JSON (UserUpdateDTO) |
| DELETE | /api/users/{id} | 删除用户(逻辑) | -                    |

#### GET /api/users —— 分页查询

请求示例：

```
GET /api/users?pageNum=1&pageSize=10&username=admin
```

响应示例：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com",
        "phone": "13800000001",
        "status": 1,
        "createTime": "2026-04-28T10:00:00",
        "updateTime": "2026-04-28T10:00:00"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "pages": 1
  }
}
```

#### POST /api/users —— 新增用户

请求示例：

```json
{
  "username": "newuser",
  "password": "123456",
  "email": "newuser@example.com",
  "phone": "13800000004",
  "status": 1
}
```

响应示例：

```json
{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 1750000000000000001,
    "username": "newuser",
    "email": "newuser@example.com",
    "phone": "13800000004",
    "status": 1
  }
}
```

#### 错误响应示例

```json
{
  "code": 404,
  "message": "用户不存在，ID: 999"
}
```

```json
{
  "code": 400,
  "message": "用户名不能为空"
}
```

## 通用模块说明

### Result<T> —— 统一响应体

所有 Controller 接口使用 `Result<T>` 封装返回值，提供一致的响应格式：

```java
Result.success(data)              // 成功返回数据
Result.success("操作成功", data)   // 成功返回消息+数据
Result.fail("参数错误")            // 失败返回消息
Result.fail(ResultCode.NOT_FOUND)  // 失败使用预定义状态码
```

### GlobalExceptionHandler —— 全局异常处理

自动拦截以下异常并转换为标准响应：

- `BusinessException` —— 业务异常
- `MethodArgumentNotValidException` —— 参数校验失败
- `BindException` —— 参数绑定失败
- `DuplicateKeyException` —— 数据唯一键冲突
- `Exception` —— 兜底处理

### MyBatis-Plus 内置功能

本项目使用 MyBatis-Plus 提供的开箱即用功能：

- **自动 CRUD**：继承 `BaseMapper<T>` 即可获得 17 种内置方法
- **分页插件**：使用 `Page<T>` 即可实现物理分页
- **逻辑删除**：`@TableLogic` 注解实现软删除
- **主键策略**：`IdType.ASSIGN_ID` 使用雪花算法生成 ID

## 开发建议

1. **新增业务模块**：按照 `entity → dto → mapper → service → controller` 的顺序创建
2. **复杂 SQL**：在 `resources/mapper/` 下创建 XML 文件编写自定义 SQL
3. **密码加密**：实际项目中应使用 `BCryptPasswordEncoder` 对密码加密存储
4. **事务管理**：Service 层方法上使用 `@Transactional` 注解管理事务
5. **生产部署**：使用 `application-prod.yml` 配置，敏感信息通过环境变量注入

## 配套前端项目

本项目配套了 [Vue 3 + Element Plus 前端管理后台](https://gitee.com/XingXuan-Sivan/vue3-template)。

前端项目包含登录鉴权、管理后台布局、用户管理 CRUD 页面，通过 Vite 代理与后端联调。

> 如需获取前后端完整代码，请访问全栈仓库：[fullstack-template](https://gitee.com/XingXuan-Sivan/fullstack-template)