为什么会有这个系列文章
- 在项目开发中，大多项目依旧沿用的是 JDK 8 + Spring Boot 2.x 系列的技术栈，没有Spring Boot 3.x 的上手实践机会。
- 在个人学习探索 Spring Boot 3.x 的过程中，遇到多数第三方框架集成和问题排查的技术问题，搜索到都是零碎的、没有直接结果的回答，所以以此系列记录在 Spring Boot 3.x项目探索过程，搭建一个 web 项目的基础脚手架，供其他用到类似技术的同学参考。
技术选型
因为项目目前定义为单体且以简单易上手为主，所以采用的技术栈相对通用、易用，有其他需求的同学可留言，在有能力的情况下会进行集成 Demo.
| 技术栈 | 版本 |
|---|---|
| JDK | 21 |
| Spring Boot | 3.2.5 |
| PostgreSQL | 16 |
| MyBatis Plus（ORM 框架） | 3.5.7 |
| Redis（外置缓存） | 7 |
| Redisson （Redis 高级客户端） | 3.25.0 |
| SaToken（轻量鉴权框架） | 1.38.0 |
| MapStruct（实体映射工具，非必需） | 1.5.5.Final |
项目初始化
根据个人习惯，用生成器或 IDE 工具初始化项目，或创建 Maven 工程后手动添加依赖。
Spring 官方项目初始化工具 start.spring.io ，阿里云初始化工具 start.aliyun.com，网络环境不佳的同学可选择阿里云工具创建。
Spring 官方初始化工具示例
阿里云初始化工具示例
阿里云应用脚手架对每一项描述较为清晰，不多复述
IDE 工具示例（以 IDEA 为例）
项目结构
不同工具初始化目录结构可能略有差异
├─src
│├─main
│ ├─java
│ │ └─com
│ │ └─bootemp
│ │ └─boot3
│ │ └─Boot3Application.java---- // 项目启动类
│ └─resources
│ └─application.properties--------- // 项目默认配置文件
└─test------------------------------- // 单元测试
└─pom.xml------------------------------ // Maven 工程文件
项目配置
项目结构规划
合适的项目结构有利于项目后期的维护，不同的项目结构适合不同的开发团队和开发习惯，仅个人习惯。
├─.gitignore
├─docs------------------------------ // 项目文档，如SQL、项目部署文档，UML等
├─pom.xml
└─src
└─main
└─java
└─cn
└─yiyanc
├─common------------------ // 项目通用组件（工具类，常量等）
├─config------------------ // 项目配置
├─service------------------ // 业务逻辑处理
├─infrastructur---------- // 项目基础设施，如ORM、缓存服务、消息队列等基础组件
├─MainApplication.java---- // 项目启动类
└─trigger----------------- // 项目入口
├─common
├─http------------------ // http请求
├─job------------------- // 任务
└─listener-------------- // 事件监听
依赖版本配置
不同的项目初始化方式，支持、生成的依赖版本各有不同，在进行项目配置前，先统一版本信息。
编辑 pom.xml 文件
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.bootemp</groupId>
<artifactId>boot3</artifactId>
<version>0.0.1</version>
<name>boot3</name>
<packaging>jar</packaging>
<description>从零搭建SpringBoot 3.x项目脚手架</description>
<properties>
<!-- 定义项目基础 -->
<java.version>21</java.version>
<maven.compiler.source>21</maven.compiler.source>
<maven.compiler.target>21</maven.compiler.target>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<!-- 定义SpringBoot依赖版本 -->
<spring-boot.version>3.2.5</spring-boot.version>
<!-- 定义项目依赖版本 -->
<mybatis-plus.version>3.5.4.1</mybatis-plus.version>
<redisson.version>3.25.0</redisson.version>
<sa-token.version>1.38.0</sa-token.version>
<hutool.version>5.8.25</hutool.version>
</properties>
<dependencyManagement>
<dependencies>
<!-- 以依赖管理的方式管理SpringBoot依赖版本 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<!-- 引入项目依赖 -->
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<!-- 指定构建后的Jar包名 -->
<finalName>app</finalName>
<plugins>
<!-- Maven编译配置 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>21</source>
<target>21</target>
<encoding>UTF-8</encoding>
<compilerArgs>
<arg>-parameters</arg>
</compilerArgs>
</configuration>
</plugin>
<!-- SpringBoot配置 -->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<!-- 指定构建时指定启动文件 -->
<mainClass>com.bootemp.boot3.MainApplication</mainClass>
<excludes>
<exclude>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</exclude>
</excludes>
</configuration>
<executions>
<execution>
<id>repackage</id>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
项目参数配置
spring boot 默认配置文件为 application.properties, 个人习惯使用 yml 格式。
配置文件规划：
application.yml- 系统通用配置文件，用于引导加载不同环境配置application-local.yml- 本地开发环境配置文件，一般在.gitignore添加忽略，避免个人使用习惯“污染”项目配置application-dev.yml- 开发环境配置文件application-prod- 生产环境配置文件
当前为演示项目，仅配置application.yml和application-local.yml文件，项目只进行最简配置，对特定参数如数据库连接池参数有要求等，请自行添加。
如环境配置中存在与
application.yml相同配置会覆盖配置
application. yml
server:
port: 8080
servlet:
context-path: /boot3
shutdown: graceful
logging:
file:
path: ./logs
level:
com.bootemp: debug
spring:
application:
name: boot3
mvc:
pathmatch:
matching-strategy: ant_path_matcher
main:
banner-mode: off
application-local. yml
spring:
datasource:
# 数据库驱动
driver-class-name: org.postgresql.Driver
# 数据库连接地址
url: jdbc:postgresql://127.0.0.1:5432/boot3
# 数据库用户名
username: postgres
# 数据库密码
password: postgres
测试 Controller
package com.bootemp.boot3.trigger.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class HelloController {
@GetMapping("/")
public String hello() {
return "Hello, SpringBoot 3.2.5!";
}
}
启动项目，基础配置完成
访问测试接口
最后项目结构
├─logs
├─pom.xml
└─src
├─main
│ ├─java
│ │ └─com
│ │ └─bootemp
│ │ └─boot3
│ │ ├─common
│ │ ├─config
│ │ ├─infrastructur
│ │ ├─MainApplication.java
│ │ ├─service
│ │ └─trigger
│ │ ├─controller
│ │ │ └─HelloController.java
│ │ ├─job
│ │ └─listener
│ └─resources
│ ├─application-local.yml
│ └─application.yml
└─test
