Spring Boot 3.0 + MyBatis-Plus 全家桶实战

原创已于 2025-09-26 14:28:27 修改 · 1.9k 阅读

14 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

Java

Spring/Springboot

于 2025-09-26 14:27:12 首次发布

概要

从依赖、配置、实体/Mapper、分页、常用插件（逻辑删除、乐观锁）、以及简单的示例接口讲起。代码可直接复制到项目里跑通。文中引用 MyBatis-Plus 官方与社区资料以保证兼容性与最佳实践。

文章结构

项目说明与目标
快速依赖（Maven）
配置文件（application.yml）
实体、Mapper、Mapper XML（或注解）示例
Service + Controller 快速 CRUD 示例
分页、条件构造器（QueryWrapper / Lambda）示例
常见插件配置：逻辑删除、乐观锁、分页插件
常见问题与调试技巧
总结与扩展阅读

1. 项目说明与目标

目标：在 Spring Boot 3.0 项目中集成 MyBatis-Plus，实现标准的增删改查、分页与常见插件（逻辑删除、乐观锁），并演示一个可运行的示例接口供快速上手。MyBatis-Plus 官方提供 Spring Boot 3 的 starter，且社区维护活跃

2. 快速依赖（Maven）

pom.xml 关键依赖（只展示最重要的部分）：

<properties>
    <java.version>17</java.version>
    <spring-boot.version>3.0.8</spring-boot.version> <!-- 任选 Spring Boot 3.0.x -->
    <mybatis-plus.version>3.5.12</mybatis-plus.version> <!-- 官方 Maven 中央库示例版本 -->
</properties>

<dependencies>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Spring Boot Starter JDBC / DataSource -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-jdbc</artifactId>
    </dependency>

    <!-- MyBatis-Plus Spring Boot 3 starter -->
    <dependency>
        <groupId>com.baomidou</groupId>
        <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
        <version>${mybatis-plus.version}</version>
    </dependency>

    <!-- 数据库驱动（示例用 MySQL） -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>

    <!-- 可选：Lombok (简化实体) -->
    <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>

注：使用 mybatis-plus-spring-boot3-starter 是推荐方式，官方/中央仓库有发布包可用。

3. 配置文件 application.yml

示例（MySQL）：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo?useUnicode=true&characterEncoding=utf8&serverTimezone=UTC
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver

mybatis-plus:
  configuration:
    # 驼峰映射：数据库 user_name -> Java userName
    map-underscore-to-camel-case: true
  global-config:
    db-config:
      logic-delete-field: deleted     # 逻辑删除字段名（可选）
      logic-delete-value: 1
      logic-not-delete-value: 0
  # mapper xml 路径（若使用 xml）
  mapper-locations: classpath:/mapper/**/*.xml
  type-aliases-package: com.example.demo.entity

解释：

map-underscore-to-camel-case：开启下划线->驼峰映射；
mapper-locations：若使用 XML 映射文件需要设置路径；
global-config.db-config.logic-delete-field：配置逻辑删除字段（如果你使用逻辑删除插件/注解）。

4. 实体、Mapper、Mapper XML（或注解）

4.1 数据库表（示例）

CREATE TABLE user (
  id BIGINT AUTO_INCREMENT PRIMARY KEY,
  username VARCHAR(100),
  email VARCHAR(200),
  age INT,
  version INT DEFAULT 0,
  deleted TINYINT DEFAULT 0,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

4.2 实体类 User.java

package com.example.demo.entity;

import com.baomidou.mybatisplus.annotation.*;
import lombok.Data;
import java.time.LocalDateTime;

@Data
@TableName("user")
public class User {
    @TableId(type = IdType.AUTO)
    private Long id;

    private String username;
    private String email;
    private Integer age;

    @Version
    private Integer version; // 乐观锁字段，@Version 标注

    @TableLogic
    private Integer deleted; // 逻辑删除，0 未删除，1 已删除

    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createdAt;

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updatedAt;
}

说明：

@TableId：主键策略；
@Version：开启乐观锁支持（需配合插件）；
@TableLogic：逻辑删除字段（MyBatis-Plus 会在 DELETE 时改写成更新已删除标志）。

4.3 Mapper 接口 UserMapper.java

package com.example.demo.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.example.demo.entity.User;
import org.apache.ibatis.annotations.Mapper;

@Mapper
public interface UserMapper extends BaseMapper<User> {
    // BaseMapper 已经包含常见 CRUD 方法（insert, deleteById, updateById, selectById, selectList...）
    // 可扩展自定义方法
}

MyBatis-Plus 提供 BaseMapper<T>，大幅减少重复 DAO 代码。

5. Service + Controller 快速 CRUD 示例

5.1 Service（直接使用 MP 的 Service 接口）

如果你喜欢 Service 层抽象，可以使用 MyBatis-Plus 的 IService 与 ServiceImpl：

package com.example.demo.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.example.demo.entity.User;

public interface IUserService extends IService<User> {
    // 自定义业务方法可以在这里扩展
}

实现类：

package com.example.demo.service.impl;

import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.example.demo.entity.User;
import com.example.demo.mapper.UserMapper;
import com.example.demo.service.IUserService;
import org.springframework.stereotype.Service;

@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements IUserService {
    // 使用内置的 save/update/getById/list 等方法
}

5.2 Controller 示例

package com.example.demo.controller;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.example.demo.entity.User;
import com.example.demo.service.IUserService;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;
import java.util.List;

@RestController
@RequestMapping("/users")
public class UserController {
    @Resource
    private IUserService userService;

    @GetMapping("/{id}")
    public User get(@PathVariable Long id) {
        return userService.getById(id);
    }

    @GetMapping
    public Page<User> list(@RequestParam(defaultValue = "1") long page,
                           @RequestParam(defaultValue = "10") long size,
                           @RequestParam(required = false) String name) {
        Page<User> p = new Page<>(page, size);
        LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
        if (name != null && !name.isEmpty()) {
            wrapper.like(User::getUsername, name);
        }
        return userService.page(p, wrapper);
    }

    @PostMapping
    public boolean create(@RequestBody User user) {
        return userService.save(user);
    }

    @PutMapping("/{id}")
    public boolean update(@PathVariable Long id, @RequestBody User user) {
        user.setId(id);
        return userService.updateById(user);
    }

    @DeleteMapping("/{id}")
    public boolean delete(@PathVariable Long id) {
        // 若启用了逻辑删除，则会被标记为已删除
        return userService.removeById(id);
    }
}

说明：

userService.page(page, wrapper)：内置分页接口，配合分页插件使用；
LambdaQueryWrapper：类型安全的条件构造器（避免写错字段名）。

6. 分页与条件构造器重点说明

MyBatis-Plus 的分页是插件驱动：需要配置分页插件（下一节会展示）。分页查询只要传入 Page 对象即可自动分页并返回 IPage/Page 对象。
QueryWrapper 和 LambdaQueryWrapper 是常用的条件构造器，Lambda 方式优点是重命名/重构字段更安全。
示例（复合条件）：

LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
wrapper.ge(User::getAge, 18)
       .le(User::getAge, 40)
       .like(User::getUsername, "张");

7. 常见插件配置（分页 / 乐观锁 / 逻辑删除 / 自动填充）

在 Spring Boot 的配置类中注册插件。

package com.example.demo.config;

import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor;
import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor;
import com.baomidou.mybatisplus.extension.plugins.inner.OptimisticLockerInnerInterceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class MybatisPlusConfig {

    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 分页（针对 MySQL）
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor());
        // 乐观锁
        interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
        // 其他插件（如防止全表更新等）可在此追加
        return interceptor;
    }
}

说明要点：

PaginationInnerInterceptor：负责分页拦截；
OptimisticLockerInnerInterceptor：启用 @Version 乐观锁注解支持；
逻辑删除在实体上加 @TableLogic，并在 application.yml 做对齐配置（见上文）。
官方文档对这些功能有说明，建议参考官方快速入门与配置章节。

8. 常见问题与调试技巧

1. SQL 不打印？

配置日志级别（application.yml）：

logging:
  level:
    com.baomidou.mybatisplus: debug
    org.mybatis: debug
    com.example.demo: debug

或使用 mybatis-plus.configuration.log-impl 指定 Slf4jImpl（部分版本需要）。查看日志可以帮助定位 SQL 与参数

2. 分页不起作用

确认注册了 MybatisPlusInterceptor 与 PaginationInnerInterceptor。
确认调用 page(new Page<>(page, size), wrapper) 而不是自己写 limit。

3. 乐观锁失败却无异常

需要在实体上标注 @Version 并在更新时使用 updateById / update，MP 会自动带上版本条件（WHERE version = ?），如果更新条数为 0表示冲突。

4. 逻辑删除仍能被查询到

确认实体字段有 @TableLogic，同时 global-config.db-config 的logic-delete-field/值是否对应。MP 会在查询时自动过滤被标记的行。

5. Mapper XML 与注解混用

若使用 XML，确保 mapperLocations 指向 XML 路径，且 @MapperScan 或 @Mapper 在 mapper
接口上生效。

9. 小结（为什么选 MyBatis-Plus）

MyBatis-Plus 在 MyBatis 基础上做了大量“零侵入”增强，提供了 BaseMapper、条件构造器、分页、代码生成器等常用工具，大幅减少模板 CRUD 代码。官方和社区对 Spring Boot 3 有专门的 starter，方便集成

10. 参考 & 延伸阅读

MyBatis-Plus 官方文档（快速开始 / 插件 / 分页 / 代码生成等）。
MyBatis-Plus 在 Maven 中央仓库的 artifact 列表（查看可用版本）。
GitHub 源码和示例仓库（官方/社区）。
Baeldung 的 MyBatis-Plus 入门文章（英文参考）

标签

#spring boot #mybatis #后端