为什么会有这个系列文章

1. 在项目开发中，大多项目依旧沿用的是 JDK 8 + Spring Boot 2.x 系列的技术栈，没有Spring Boot 3.x 的上手实践机会。
2. 在个人学习探索 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