1. 项目背景与技术选型
最近在搭建新项目的技术框架时，我选择了Spring Boot 3.4这个最新版本作为基础。这个版本在性能优化和功能增强方面都有不少亮点，特别是在响应式编程支持和GraalVM原生镜像兼容性上做了很多改进。不过在实际集成过程中发现，由于Spring Boot 3.x系列对Jakarta EE 9+的全面支持，很多传统组件的集成方式都需要相应调整。
Swagger作为API文档生成工具，在前后端分离开发中几乎是必备组件。而MyBatis-Plus则是国内Java开发者最喜爱的ORM增强工具之一，它的代码生成器和Wrapper查询构造器能极大提升开发效率。本文将详细介绍如何在Spring Boot 3.4环境下正确整合这两个核心组件。
2. 环境准备与基础配置
2.1 项目初始化
首先通过Spring Initializr创建基础项目，我选择的依赖包括：
- Spring Web (用于构建RESTful API)
- Lombok (简化实体类编写)
- MySQL Driver (数据库连接)
xml复制<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.4.0</version>
</parent>
2.2 关键依赖版本选择
对于Swagger的集成，Spring Boot 3.x之后官方不再维护springfox，推荐使用springdoc-openapi。这里需要特别注意版本兼容性：
xml复制<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.5.0</version>
</dependency>
MyBatis-Plus的集成相对简单，直接使用最新稳定版即可：
xml复制<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
<version>3.5.6</version>
</dependency>
注意：Spring Boot 3.x要求JDK 17+，如果使用较低版本JDK会导致编译失败。这也是很多开发者升级时遇到的第一个坑。
3. Swagger集成详解
3.1 基础配置类
在Spring Boot 3.4中配置Swagger需要创建一个OpenAPI的Bean：
java复制@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("API文档")
.description("Spring Boot 3.4项目接口文档")
.version("v1.0")
.license(new License().name("Apache 2.0")))
.externalDocs(new ExternalDocumentation()
.description("项目Wiki")
.url("https://github.com/yourrepo/wiki"));
}
}
3.2 接口文档分组配置
对于大型项目，我们通常需要按模块分组展示API：
java复制@Bean
@Profile("dev")
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("user-service")
.pathsToMatch("/api/user/**")
.build();
}
3.3 常见问题解决
-
Swagger UI无法访问：检查是否添加了springdoc-openapi-starter-webmvc-ui依赖，默认访问路径是
/swagger-ui.html -
接口文档不显示：确保Controller类上有
@RestController注解，方法上有@Operation注解 -
参数说明缺失：在DTO字段上添加
@Schema注解描述字段含义
java复制@Data
public class UserDTO {
@Schema(description = "用户ID", example = "1001")
private Long id;
@Schema(description = "用户名", example = "admin")
private String username;
}
4. MyBatis-Plus深度集成
4.1 基础配置
在application.yml中添加数据库和MyBatis-Plus配置：
yaml复制spring:
datasource:
url: jdbc:mysql://localhost:3306/demo?useSSL=false
username: root
password: 123456
driver-class-name: com.mysql.cj.jdbc.Driver
mybatis-plus:
configuration:
log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
global-config:
db-config:
id-type: auto
logic-delete-field: deleted
logic-not-delete-value: 0
logic-delete-value: 1
4.2 代码生成器配置
MyBatis-Plus的代码生成器可以极大提升开发效率：
java复制public class CodeGenerator {
public static void main(String[] args) {
FastAutoGenerator.create("jdbc:mysql://localhost:3306/demo", "root", "123456")
.globalConfig(builder -> {
builder.author("yourname")
.outputDir(System.getProperty("user.dir") + "/src/main/java");
})
.packageConfig(builder -> {
builder.parent("com.example.demo")
.moduleName("system");
})
.strategyConfig(builder -> {
builder.addInclude("user", "role")
.entityBuilder()
.enableLombok()
.controllerBuilder()
.enableRestStyle();
})
.execute();
}
}
4.3 高级特性使用
- 分页插件配置：
java复制@Configuration
public class MybatisPlusConfig {
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
return interceptor;
}
}
- Wrapper条件构造器示例：
java复制public List<User> queryUsers(String username, Integer status) {
return userMapper.selectList(new QueryWrapper<User>()
.like(StringUtils.isNotBlank(username), "username", username)
.eq(status != null, "status", status)
.orderByDesc("create_time"));
}
5. 整合过程中的坑与解决方案
5.1 版本兼容性问题
-
Spring Boot 3.x与MyBatis-Plus的兼容性：
- 确保使用MyBatis-Plus 3.5.x版本
- 如果遇到
java.lang.NoClassDefFoundError: jakarta/servlet/Filter错误，需要检查是否引入了正确的servlet-api依赖
-
Swagger与Spring Security整合：
如果项目使用了Spring Security，需要放行Swagger相关路径：
java复制@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http.authorizeHttpRequests(auth -> auth
.requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()
.anyRequest().authenticated()
);
return http.build();
}
5.2 性能优化建议
- 生产环境关闭Swagger：
通过Profile控制Swagger只在开发环境启用：
java复制@Profile({"dev", "test"})
@Configuration
public class SwaggerConfig {
// 配置内容
}
- MyBatis-Plus二级缓存配置：
对于读多写少的场景可以启用二级缓存：
yaml复制mybatis-plus:
configuration:
cache-enabled: true
6. 完整项目结构参考
一个标准的整合项目结构如下：
code复制src/main/java
├── com.example.demo
│ ├── config
│ │ ├── MybatisPlusConfig.java
│ │ └── SwaggerConfig.java
│ ├── controller
│ │ └── UserController.java
│ ├── entity
│ │ └── User.java
│ ├── mapper
│ │ └── UserMapper.java
│ ├── service
│ │ ├── impl
│ │ │ └── UserServiceImpl.java
│ │ └── UserService.java
│ └── DemoApplication.java
src/main/resources
├── application.yml
└── mapper
└── UserMapper.xml
在实际开发中，我发现Spring Boot 3.4与这两个组件的整合整体上比较平滑，主要需要注意版本兼容性和配置方式的调整。特别是在从Spring Boot 2.x升级到3.x的项目中，需要仔细检查所有涉及javax包导入的地方，全部替换为jakarta包。