Spring Boot 3.4整合MyBatis-Plus与Swagger实战指南-代码聚汇网

Spring Boot 3.4整合MyBatis-Plus与Swagger实战指南

戈玄白今天要做题

1. 项目背景与技术选型

最近在搭建一个企业级后台管理系统时，我选择了Spring Boot 3.4作为基础框架。这个版本在性能优化和功能扩展方面都有显著提升，特别是在响应式编程支持和原生镜像构建方面做了很多改进。考虑到项目需要快速开发迭代，我决定整合Swagger和MyBatis-Plus这两个开发利器。

Swagger作为API文档工具，可以自动生成接口文档，极大减少了前后端联调时的沟通成本。而MyBatis-Plus作为MyBatis的增强工具，提供了丰富的CRUD操作封装，让数据库操作变得异常简单。这两个组件的组合，可以让我们在保证开发效率的同时，也能维护良好的代码规范和文档体系。

2. 环境准备与基础配置

2.1 创建Spring Boot项目

首先使用Spring Initializr创建一个基础项目，选择以下依赖：

Spring Web
Lombok
MySQL Driver

然后手动添加以下依赖到pom.xml：

xml复制<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.3.1</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

注意：Spring Boot 3.x对Jakarta EE有严格要求，确保所有依赖都兼容Jakarta命名空间。

2.2 数据库配置

在application.yml中配置数据库连接：

yaml复制spring:
  datasource:
    url: jdbc:mysql://localhost:3306/your_db?useSSL=false&serverTimezone=UTC
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver

3. MyBatis-Plus整合详解

3.1 实体类与Mapper配置

创建一个简单的用户实体类：

java复制@Data
@TableName("sys_user")
public class User {
    @TableId(type = IdType.AUTO)
    private Long id;
    private String username;
    private String password;
    private Integer status;
    private LocalDateTime createTime;
}

创建对应的Mapper接口：

java复制public interface UserMapper extends BaseMapper<User> {
}

3.2 分页插件配置

MyBatis-Plus的分页功能需要配置拦截器：

java复制@Configuration
public class MybatisPlusConfig {
    
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

3.3 常见问题解决

字段映射问题：如果数据库字段使用下划线命名，而实体类使用驼峰命名，需要确保开启驼峰映射：

yaml复制mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true

逻辑删除：如果需要逻辑删除功能，可以在实体类字段上添加注解：

java复制@TableLogic
private Integer deleted;

4. Swagger3整合与优化

4.1 基础配置

创建Swagger配置类：

java复制@Configuration
@EnableOpenApi
public class SwaggerConfig {
    
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.package"))
                .paths(PathSelectors.any())
                .build();
    }
    
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("Spring Boot 3.4整合Swagger和MyBatis-Plus")
                .version("1.0")
                .build();
    }
}

4.2 接口文档增强

为Controller添加Swagger注解：

java复制@RestController
@RequestMapping("/user")
@Api(tags = "用户管理")
public class UserController {
    
    @Autowired
    private UserMapper userMapper;
    
    @GetMapping("/list")
    @ApiOperation("获取用户列表")
    public List<User> list() {
        return userMapper.selectList(null);
    }
    
    @PostMapping("/add")
    @ApiOperation("添加用户")
    public boolean add(@RequestBody User user) {
        return userMapper.insert(user) > 0;
    }
}

4.3 常见问题解决

Spring Boot 3.x兼容性问题：如果遇到jakarta包冲突，可以尝试以下解决方案：

xml复制<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>jakarta.servlet</groupId>
            <artifactId>jakarta.servlet-api</artifactId>
        </exclusion>
    </exclusions>
</dependency>

文档不显示问题：确保访问路径为/swagger-ui/index.html，Spring Boot 3.x的静态资源路径有所变化。

5. 高级功能实现

5.1 自动填充功能

MyBatis-Plus提供了自动填充功能，非常适合处理创建时间、更新时间等字段：

java复制@Component
public class MyMetaObjectHandler implements MetaObjectHandler {
    
    @Override
    public void insertFill(MetaObject metaObject) {
        this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());
    }
    
    @Override
    public void updateFill(MetaObject metaObject) {
        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
    }
}

5.2 多数据源配置

对于需要连接多个数据库的场景，可以配置多数据源：

java复制@Configuration
@MapperScan(basePackages = "com.your.mapper1", sqlSessionTemplateRef = "db1SqlSessionTemplate")
public class DataSource1Config {
    
    @Bean
    @ConfigurationProperties(prefix = "spring.datasource.db1")
    public DataSource db1DataSource() {
        return DataSourceBuilder.create().build();
    }
    
    @Bean
    public SqlSessionFactory db1SqlSessionFactory(@Qualifier("db1DataSource") DataSource dataSource) throws Exception {
        MybatisSqlSessionFactoryBean factoryBean = new MybatisSqlSessionFactoryBean();
        factoryBean.setDataSource(dataSource);
        return factoryBean.getObject();
    }
    
    @Bean
    public SqlSessionTemplate db1SqlSessionTemplate(@Qualifier("db1SqlSessionFactory") SqlSessionFactory sqlSessionFactory) {
        return new SqlSessionTemplate(sqlSessionFactory);
    }
}

5.3 接口权限控制

结合Spring Security实现接口权限控制：

java复制@Configuration
@EnableWebSecurity
public class SecurityConfig {
    
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/swagger-ui/**").permitAll()
                .requestMatchers("/v3/api-docs/**").permitAll()
                .anyRequest().authenticated()
            )
            .formLogin(withDefaults());
        return http.build();
    }
}

6. 性能优化与最佳实践

6.1 MyBatis-Plus性能优化

批量操作：使用saveBatch方法进行批量插入：

java复制userService.saveBatch(userList, 1000); // 每1000条提交一次

SQL打印优化：生产环境建议关闭SQL打印：

yaml复制mybatis-plus:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 开发环境
    # log-impl: org.apache.ibatis.logging.nologging.NoLoggingImpl # 生产环境

6.2 Swagger文档优化

分组展示：大型项目可以按模块分组展示API：

java复制@Bean
public Docket userApi() {
    return new Docket(DocumentationType.OAS_30)
            .groupName("用户模块")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.your.user"))
            .build();
}

接口缓存：生产环境可以启用文档缓存：

java复制@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.OAS_30)
            .enable(true) // 生产环境可以设为false
            // 其他配置...
}

7. 项目部署与测试

7.1 打包部署

使用Maven打包：

bash复制mvn clean package -DskipTests

然后运行生成的jar文件：

bash复制java -jar your-project.jar

7.2 接口测试

访问Swagger UI界面：http://localhost:8080/swagger-ui/index.html
测试MyBatis-Plus的CRUD接口
验证分页查询功能

7.3 性能测试

使用JMeter或Postman进行压力测试，重点关注：

数据库查询性能
接口响应时间
系统资源占用情况

8. 常见问题解决方案

8.1 版本冲突问题

Spring Boot 3.4与某些库可能存在版本冲突，解决方案：

检查依赖树：mvn dependency:tree
排除冲突依赖
使用兼容版本

8.2 日期格式问题

处理日期类型时常见问题：

前端传参格式不一致
数据库存储时区问题
返回给前端的格式化问题

解决方案：

java复制@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
private LocalDateTime createTime;

8.3 跨域问题

开发阶段可能会遇到跨域问题，解决方案：

java复制@Configuration
public class CorsConfig implements WebMvcConfigurer {
    
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("*")
                .allowedHeaders("*");
    }
}

9. 项目结构建议

一个良好的项目结构可以提高维护性：

code复制src/main/java
├── com.your.project
│   ├── config       # 配置类
│   ├── controller   # 控制器
│   ├── entity       # 实体类
│   ├── mapper       # Mapper接口
│   ├── service      # 服务层
│   │   ├── impl     # 服务实现
│   ├── util         # 工具类
│   └── vo           # 视图对象
src/main/resources
├── application.yml  # 主配置文件
├── application-dev.yml # 开发环境配置
├── application-prod.yml # 生产环境配置

10. 扩展思考

在实际项目中，我们还可以考虑以下扩展方向：

接口幂等性：防止重复提交
分布式锁：解决并发问题
数据权限：实现行级数据过滤
审计日志：记录关键操作
接口版本控制：支持多版本API

这些扩展功能都可以基于现有的Spring Boot + MyBatis-Plus + Swagger技术栈实现，为项目提供更完善的企业级支持。