Spring Boot + MyBatis-Plus 快速连接 MySQL：从配置到排错全链路指南

搞技术的人看到“Spring Boot + MyBatis-Plus 快速连接 MySQL”这个标题，第一反应大概都是：这不就是个配置一把梭的事儿？但我在技术社区里见过太多人卡在同一个地方——代码照抄了，依赖也加了，启动还是报红；或者好不容易启动起来，一查数据又给你来个时区错乱、公钥检索失败。

说到底，“快速连接”四个字的重点是链路理解，不是配置长度。只要搞明白 Spring Boot 的自动配置是怎么把数据源、连接池、Mapper接口串起来的，再回头看我下面写的这些步骤，你会觉得所有配置其实都顺理成章。

这篇文章我不会只贴一份能跑通的配置就完事。我会把数据库侧的准备、Spring Boot 不同版本下的依赖差异、配置文件里每个字段背后的意义、最小可运行示例、以及我实际踩过的排错链路全部梳理一遍。不管你是刚学 Spring Boot 的初学者，还是从传统 SSM 项目转过来的老开发，这篇文章都能帮你少走弯路。

1. 这套“三件套”解决什么问题：为什么是 MyBatis-Plus 而不是 JPA 或原生 MyBatis

很多新人在选数据库访问层的时候会犹豫。一边是 Spring Data JPA，号称极简；一边是原生 MyBatis，SQL 控制力强；中间夹着一个 MyBatis-Plus，常被人调侃是“增强工具”。我在早期项目里三种都试过，如果目标是“快速连接 MySQL 并完成业务开发”，我的选择很明确：MyBatis-Plus。下面讲清楚它的价值边界，以及为什么它和 Spring Boot 是天生一对。

1.1 单表 CRUD 的代码量对比，省下来的不只是模板代码

我们先看一个最普通的用户表。传统 MyBatis 要实现一个根据 ID 查询、插入用户、更新用户信息，你得做这些事：

• 在 UserMapper.xml 里写 <select>、<insert>、<update> 标签
• 在接口里定义对应方法
• 处理参数映射和结果映射，稍微偷懒少写个字段，运行期就给你报错

而 MyBatis-Plus 内置了 BaseMapper<T>，直接给你提供 selectById、insert、updateById、deleteById 这些现成方法。比如查询用户：

java复制User user = userMapper.selectById(1L);

插入用户：

java复制User user = new User();
user.setName("张三");
user.setAge(25);
userMapper.insert(user);

两条语句就完成了单表 CRUD 里最核心的两个动作。如果是带条件的分页查询，MyBatis-Plus 用条件构造器也能搞定，不用写 XML。这里的关键价值不只是代码行数变少，而是少了一整个“维护 SQL 映射文件”的心智负担。

这一点和 JPA 比也不一样。JPA 的问题是封装得太抽象，遇到多表关联、复杂查询，要么写 JPQL，要么写原生 SQL，和 Java 实体之间的映射在调试时比较绕。MyBatis-Plus 的定位更务实：单表操作足够简单，复杂场景保留 MyBatis 原生 XML 能力，后退一步是 SQL，前进一步是 CRUD，不会把 SQL 能力给锁死。

1.2 一条完整的调用链路：从 Controller 到 MySQL 到底经过了什么

“连接”这两个字不能只理解成 TCP 握手。一次正常的数据请求，实际链路是这样的：

text复制HTTP 请求
  -> Spring MVC Controller
    -> Service 层
      -> Mapper 接口（继承 BaseMapper）
        -> MyBatis-Plus 内部生成 SQL
          -> MyBatis 会话
            -> JDBC 驱动
              -> HikariCP 连接池
                -> MySQL 服务器

如果你只是想跑通一个 Demo，这个链路不用全记住，但你至少要知道两件事：

第一，Spring Boot 启动时会通过 DataSourceAutoConfiguration 读取 spring.datasource 配置，创建数据源。数据源本质上是一个连接池工厂，负责管理到 MySQL 的物理连接，避免每次请求都重新建立 TCP 连接。

第二，我们写的 Mapper 接口之所以能直接注入使用，是因为 MyBatis 在启动时扫描到了它，为它生成代理对象。代理对象内部把方法调用转换为对 SQL 的执行。MyBatis-Plus 的启动流程更激进，它继承了 MyBatis 的扫描逻辑，还额外处理了实体类与数据库表之间的映射关系。

把这条链路放在脑子里以后，再去排查启动报错就有方向了。启动时如果报数据源相关错误，问题大概率出在配置阶段；请求时报 SQL 错误，问题才可能出在 SQL 语句或映射关系上。

2. 数据库侧准备：我踩过的 MySQL 安装与连接参数的那些坑

Spring Boot 项目里配数据库，十次连接失败有八次问题不是出在 Java 代码，而是出在 MySQL 这边。这里我把 Windows 和 Linux 环境下最实用的做法拆开讲，都是我自己反复踩过的点。

2.1 Windows 下安装 MySQL 8 时最容易忽略的认证插件选项

如果你在 Windows 上用 MySQL Installer 安装，走到认证方式选择那一步，默认是 caching_sha2_password，不建议来回切换。这个认证插件是 MySQL 8 的默认选项，安全性更高。

问题出在它和旧版本 JDBC 驱动的兼容性上。如果你项目里的 mysql-connector-java 还停留在 5.x 时代，连接时大概率会看到这样一句报错：

text复制Public Key Retrieval is not allowed

很多老教程会让你把 JDBC URL 改成这样来规避：

text复制jdbc:mysql://localhost:3306/demo?allowPublicKeyRetrieval=true&useSSL=false

如果你的 MySQL 是 8.x 版本，我的建议是直接用 com.mysql.cj.jdbc.Driver，也就是 MySQL Connector/J 8.x，这属于官方驱动的新类名。Spring Boot 2.7 和 3.x 默认管理的驱动版本已经是 8.x 了，正常引入依赖时不会碰到这个问题。但如果你在整合一些老项目，发现驱动被覆盖成 5.x，就要注意 URL 里补上 allowPublicKeyRetrieval=true，并且尽量升级驱动的 Maven 坐标。

2.2 用 Docker 跑 MySQL 8 的推荐命令与参数

个人开发时我强烈建议用 Docker 跑 MySQL。不要觉得这是多此一举，Docker 方式最大的好处是“用完即弃”，不污染宿主机环境，版本切换也方便。这里给一条我平时用的命令：

bash复制docker run -d \
  --name mysql8 \
  -p 3306:3306 \
  -e MYSQL_ROOT_PASSWORD=root123456 \
  -e TZ=Asia/Shanghai \
  -v mysql-data:/var/lib/mysql \
  mysql:8.0

注意几个细节：

• -p 3306:3306 把容器的 3306 端口映射到宿主机，保证 Java 程序能通过 localhost 访问。
• MYSQL_ROOT_PASSWORD 是初始化时设置的 root 密码，只在第一次启动时生效。如果你把容器删了再用同一条命令跑，卷数据还在，密码不会重置。
• TZ=Asia/Shanghai 设置容器时区，避免后面 Java 程序写入的时间戳差了 8 小时。
• -v mysql-data:/var/lib/mysql 是数据卷挂载，容器删了数据也不丢。做实验的时候一旦发现问题，可以直接删容器重建，非常省心。

容器启动后，可以进入容器内部验证数据库状态：

bash复制docker exec -it mysql8 mysql -uroot -p

输入密码后能进到 MySQL 命令行就算成功。

2.3 JDBC URL 里每个参数的真实含义

很多人直接复制网上的 jdbc:mysql://localhost:3306/quick_start?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true，并不清楚后面挂的参数是什么意思。这里逐一解释，你以后就知道怎么取舍了：

如果只是本地学习，useSSL=false 可以帮你减少很多没必要的告警；生产环境如果数据库和应用的网络链路不安全，则需要评估启用 SSL。serverTimezone 这个参数最有迷惑性，因为你用 Navicat 连 MySQL 不会遇到问题，但 JDBC 连接时如果没有指定时区，驱动会拿 JVM 默认时区和数据库会话时区做转换，日期数据很容易出现偏移。

3. Spring Boot 3 还是 2.x：一个版本选择决定你整个依赖坐标

写 Spring Boot 项目，版本选择是第一关。很多人喜欢盲搜最新教程，结果教程用的是 Spring Boot 3.2，自己的环境还是 JDK 8，抄完代码项目直接起不来。这一章我们先把版本矩阵讲清楚。

3.1 MyBatis-Plus 的 starter 坐标差异

MyBatis-Plus 官方对 Spring Boot 3 的适配方式是单独出了一个新的 starter 坐标，这一点最容易踩坑。

如果你的项目是 Spring Boot 2.x，使用：

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

如果你的项目是 Spring Boot 3.x，必须使用：

xml复制<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-spring-boot3-starter</artifactId>
    <version>3.5.3.1</version>
</dependency>

为什么会有两个坐标？因为 Spring Boot 3 从 Java EE 迁移到了 Jakarta EE 规范，包名从 javax.* 变成了 jakarta.*，MyBatis-Plus 需要针对新的 API 重新编译适配。你用错坐标的典型报错是：

text复制ClassNotFoundException: jakarta.servlet.ServletException

或者更隐蔽的，项目启动时没有报错，但某些和 Servlet 相关的自动配置没生效。排查方法就是先看你的 Spring Boot 大版本，再对照上面两个坐标选择。

3.2 JDK 版本和编译器配置

Spring Boot 3.x 默认要求 Java 17 及以上。如果你的开发机只有 JDK 8，硬上 Spring Boot 3 是行不通的。这时候两条路：

• 升级 JDK 到 17 或 21，使用 Spring Boot 3.x
• 保留 JDK 8，使用 Spring Boot 2.7.x，并选择对应的 mybatis-plus-boot-starter

我的建议是，如果是新项目，尽量用 Spring Boot 3.x + JDK 17。JDK 17 是 LTS 版本，各种新特性支持也稳定。Spring Boot 2.7 已经停止免费商业支持，长期看不是新项目的首选。

如果你用 Maven，pom.xml 里需要保证编译器级别正确：

xml复制<properties>
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

加上 spring-boot-starter-parent 后，默认的 java.version 属性会强制编译级别。你可以单独配置覆盖。

3.3 Lombok 与多模块项目的联动细节

实体类里写 getter/setter 是最折磨人的环节，所以 Lombok 几乎是标配。在 pom.xml 中引入：

xml复制<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

IDEA 里要确保安装了 Lombok 插件，并且在 Settings 中开启 Annotation Processing，否则注解不生效。多模块项目里，Lombok 依赖建议只在需要写实体的模块引入，或者统一在父 POM 的 dependencyManagement 中管理版本，避免各模块版本不一致。

我遇到最多的问题是：IDEA 里编译正常，但 Maven 打包时报“找不到符号 getter”。这通常是因为某个子模块没引入 Lombok 依赖，或者编译时没有使用注解处理器。检查模块自身 pom.xml 而不是父 POM。

4. 配置文件里的“为什么”：每个字段我都给你拆开讲

搞定依赖后，接下来就是写配置。我见过不少人把 application.yml 里几十行配置原样复制，项目跑起来就庆幸，跑不起来就四处乱改。配置文件里的每一项都在告诉 Spring Boot 一个关键信息，理解之后，你完全可以按需裁剪。

4.1 spring.datasource 配置逐项拆解

一份基础配置文件长这样：

yaml复制spring:
  datasource:
    url: jdbc:mysql://localhost:3306/quick_start?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
    username: root
    password: root123456
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      minimum-idle: 5
      maximum-pool-size: 10
      connection-timeout: 30000

先问一个问题：driver-class-name 到底要不要写？

如果你用的数据库是 MySQL，版本在 MySQL Connector/J 8.x，Spring Boot 会根据 URL 自动推断驱动类名。我通常不写，因为少写一个配置项就少一个配置不一致的风险。但有些内网环境有多个 MySQL 驱动包，或数据库类型特殊，建议显式指定。

然后是 url 后面那一长串参数，前面已经解释过，这里不再重复。username 和 password 是数据库账号密码，没有太多花样，但记住一点：如果你 MySQL 的 root 账号密码里有特殊字符比如 @ 或 #，在 YAML 里要加引号，例如：

yaml复制password: "root#123456"

不加引号 YAML 解析时可能报错，这个坑很隐蔽但非常常见。

4.2 连接池参数 HikariCP 的推荐值

Spring Boot 2.x 之后默认的数据库连接池是 HikariCP，它的性能很好，不需要做太多调优。但你至少要知道这几个参数：

• maximum-pool-size：连接池最大连接数。不是说越大越好，MySQL 默认最大连接数是 151，你配 100 个数据库连接会直接把数据库拖垮。小型应用 10～20 足够了，大型应用要根据 QPS 压测来定。
• minimum-idle：最小空闲连接数。为了应对突发流量，让它至少保留几个空闲连接。和核心业务并发量匹配即可，默认等于最大连接数也没问题。
• connection-timeout：获取连接的超时时间（毫秒）。默认 30000 已经比较合适，如果业务侧经常报连接超时，不建议直接调大，要先检查是不是连接池不够用或数据库慢查询太多。

我见过很多人在网上抄一个特别大的连接池参数，比如 maximum-pool-size: 100，还开着多个微服务实例，结果 MySQL 直接拒绝连接。这里给个经验公式：连接数最终受限于数据库性能，单实例数据库 20 个连接左右已经能支撑不小的单机应用。

4.3 MyBatis-Plus 专属配置的字段意义

除了数据源，MyBatis-Plus 在配置文件里也有专属配置块：

yaml复制mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
  global-config:
    db-config:
      id-type: auto
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0
  mapper-locations:
    - classpath*:/mapper/**/*.xml

逐项看：

• map-underscore-to-camel-case：把数据库下划线字段映射为 Java 驼峰属性。数据库里叫 user_name，Java 实体里叫 userName，靠这个配置自动转换。
• log-impl：SQL 日志输出到控制台。开发阶段强烈建议开启，能直接看到 MyBatis-Plus 生成的 SQL 语句。
• id-type: auto：主键策略为数据库自增。如果你的表主键不是自增而是雪花ID、UUID，需要对应调整。
• logic-delete-field：逻辑删除字段。这也是很多人理解不透的概念，简单说就是删除不是真的 DELETE，而是 UPDATE 一个标记位。MyBatis-Plus 在初始化时会自动识别这个字段。
• mapper-locations：指定 XML 映射文件的路径。如果项目里完全不需要 XML 文件，可以省略；一旦写了自定义 SQL 的 XML，就必须配置这个路径，否则启动时不会加载。

这里要特别说下逻辑删除的甜头和苦头。MyBatis-Plus 这个能力很实用，当你调用 userMapper.deleteById(1L) 时，它会在底层把 SQL 改写成 UPDATE user SET deleted = 1 WHERE id = 1 AND deleted = 0。但如果配置了逻辑删除，所有查询都会自动追加 AND deleted = 0 条件。好处是不丢失数据，坏处是如果哪天你要真正物理删除数据，得用自定义 SQL 绕过 MP 的逻辑删除机制。所以设计表结构时，如果确认某些表不需要逻辑删除，在实体类上不要加逻辑删除字段注解。

4.4 密码别硬编码到配置文件里

即便是在写个人项目，我也建议不要把数据库密码明文直接写在 application.yml 里并提交到代码仓库。一种轻量做法是利用环境变量：

yaml复制spring:
  datasource:
    password: ${DB_PASSWORD:root123456}

本地开发环境不配置 DB_PASSWORD 就使用默认密码；部署到服务器时通过环境变量注入真实密码。这比硬编码安全得多，而且几乎不增加任何使用成本。再往上的方案是配置中心或 Jasypt 加密，生产环境建议引入。

5. 最小可运行示例：从建表到查出数据全流程走一遍

光说不练假把式。这一节我带你从零建一张表，写一个能跑的 Spring Boot Demo，完整跑通 CRUD。

5.1 建表语句与实体类注解

先用一段 SQL 在数据库里建一张用户表：

sql复制CREATE TABLE `user` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `name` VARCHAR(30) DEFAULT NULL COMMENT '姓名',
  `age` INT DEFAULT NULL COMMENT '年龄',
  `email` VARCHAR(50) DEFAULT NULL COMMENT '邮箱',
  `deleted` TINYINT DEFAULT 0 COMMENT '逻辑删除标记，0未删除，1已删除',
  `create_time` DATETIME DEFAULT NULL COMMENT '创建时间',
  `update_time` DATETIME DEFAULT NULL COMMENT '更新时间',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';

注意这里我把表名直接命名为 user，在 MySQL 里它虽然不是保留字，但在某些 SQL 模式中容易引发问题。实体类的 @TableName 注解会帮你做映射，这里为了避免转义麻烦，建议加注解：

java复制@Data
@TableName("user")
public class User {

    @TableId(type = IdType.AUTO)
    private Long id;

    private String name;

    private Integer age;

    private String email;

    @TableLogic
    private Integer deleted;

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

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

看看这些注解分别做了什么：

• @TableName("user")：指定实体类对应的数据库表名。
• @TableId(type = IdType.AUTO)：声明主键字段，并指定主键生成策略是数据库自增。如果数据库表主键是雪花 ID，就用 IdType.ASSIGN_ID。
• @TableLogic：逻辑删除字段注解。加了它之后，MyBatis-Plus 会自动在 CRUD 操作里注入逻辑删除条件。
• @TableField(fill = ...)：配合自动填充功能，在插入和更新时自动写入时间字段。要让它生效，还需要一个 MetaObjectHandler 的 Bean，我们后面讲。

5.2 Mapper 接口与 Service 层的“零 SQL”实现

创建 Mapper 接口：

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

没有方法定义，没有 XML 文件，就这一个接口，MyBatis-Plus 在启动时会自动扫描到它，并注入 CRUD 功能。

推荐在启动类上使用 @MapperScan 注解，一次性扫描 Mapper 包：

java复制@SpringBootApplication
@MapperScan("com.example.demo.mapper")
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

使用 @MapperScan 的好处是不用在每个 Mapper 接口上都加 @Mapper 注解，尤其是 Mapper 接口多了以后特别方便。就算你已经在启动类上加了扫描，某个 Mapper 上再加 @Mapper 也不会报错，但没必要。

Service 层可以继承 MyBatis-Plus 的 ServiceImpl：

java复制@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
}

然后定义接口：

java复制public interface UserService extends IService<User> {
}

这样你立刻拥有 save、list、getById、page 等一批现成方法。如果你的业务里不需要 Service 层，直接在 Controller 里注入 Mapper 也是能跑的，但为了后续业务扩展，我不建议跳过 Service 层。

5.3 控制器里的 CRUD 实操与条件构造器用法

写一个简单的 Controller 演示查询接口：

java复制@RestController
@RequestMapping("/users")
public class UserController {

    @Resource
    private UserMapper userMapper;

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

    @GetMapping("/list")
    public List<User> list(String name, Integer age) {
        LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
        wrapper.eq(StringUtils.hasText(name), User::getName, name)
               .eq(age != null, User::getAge, age)
               .orderByDesc(User::getId);
        return userMapper.selectList(wrapper);
    }

    @PostMapping
    public User add(@RequestBody User user) {
        userMapper.insert(user);
        return user;
    }
}

这段代码里最值得展开的是 LambdaQueryWrapper。它解决的核心问题是“动态 SQL 拼接”的重复劳动。传统 MyBatis 里你要在 XML 里写 <if test="name != null">，而 LambdaQueryWrapper 在 Java 代码里直接使用 lambda 表达式引用实体字段，还会自动判断条件是否成立。

比如这一行：

java复制wrapper.eq(StringUtils.hasText(name), User::getName, name);

如果 name 是空字符串或 null，这个条件就自动不生效。如果业务参数非空，就生成 WHERE name = ?。

为什么不建议使用普通的 QueryWrapper？因为 QueryWrapper 传的是字符串列名：

java复制wrapper.eq("name", name);

一旦你把字段名拼错，编译期不会发现，运行期才会报错。LambdaQueryWrapper 用 User::getName 这种写法，字段名如果改了，编译期就能感知到，重构时心里踏实很多。

插入成功后，MyBatis-Plus 还会把数据库生成的自增主键回填到实体对象里。所以上面的 add 方法在 userMapper.insert(user) 执行完后，user.getId() 就已经是数据库生成的新 ID 了，直接返回对象给前端正好。

6. 连接失败不可怕：一套从启动日志到数据库端的排查方法

即使前面每一步都照做了，开发过程中依然大概率会碰到连接问题。这里我总结出一套排查思路，按这条链路走，大部分问题都能在几分钟内定位。

6.1 连接期报错的快速定位入口

我按错误关键词把它们分成了四类，对应不同的故障面：

先记住一个原则：报错信息只看第一行是不够的。Spring Boot 的异常堆栈会把根因放在最下面的 Caused by 里。比如一个典型的堆栈，前面一坨都是框架内部调用链，真正的错误是最后这句 Caused by: java.net.ConnectException: Connection refused。下次看到满屏红色，先瞄一眼最底部的 Caused by。

6.2 一次“Communications link failure”的完整排查过程

我之前帮朋友排查一次启动连接失败，应用日志里第一屏全是 HikariPool-1 - Exception during pool initialization，看起来很像 HikariCP 的初始化问题。如果照着连接池参数方向改，肯定走弯路。

接着往下拉，看到关键线索：

text复制Caused by: java.net.ConnectException: Connection refused: connect

这说明连接根本没到 MySQL 那一步，方向直接切换成网络问题。我的排查步骤是：

第一，确认 MySQL 进程还活着。

bash复制ps -ef | grep mysqld

如果是 Docker 安装的：

bash复制docker ps | grep mysql

第二，确认端口监听情况。在 MySQL 所在机器上执行：

bash复制netstat -tlnp | grep 3306

如果结果显示 0.0.0.0:3306，说明 MySQL 监听在所有网卡上。如果只显示 127.0.0.1:3306，说明它只接受本机连接，Java 应用部署在别的机器或 Docker 容器里就连接不上。

第三步，检查 Java 应用这一侧的数据库地址。这里有个经典问题：Java 应用和 MySQL 都跑在 Docker 容器里时，url 里的 localhost 指向的是应用容器自身，不是宿主机。正确写法是把 localhost 换成宿主机实际 IP，或者使用 Docker Compose 中的服务名。

第四步，确认防火墙有没有拦截。Linux 下临时验证：

bash复制telnet 192.168.x.x 3306

如果提示 Connection refused，要么 MySQL 没监听对应网卡，要么防火墙拦截。这一步可以直接帮你缩小范围。

那次问题最后定位到 MySQL 容器的端口映射失效，重建容器后解决。整个排查过程不到十分钟，关键点就是顺着 Caused by 一层层往下找。

6.3 启动日志里看到的悲观锁和表锁问题不要慌

连接一旦成功，另一个高频出现的坑是 MySQL 的锁问题。开发环境的 SQL 执行日志里，偶尔能看到 Lock wait timeout exceeded; try restarting transaction 这类的报错，很多人第一反应是自己写的 SQL 死锁了。

排查方法很简单。在 MySQL 里执行：

sql复制SHOW PROCESSLIST;

这个命令能看到当前所有数据库连接正在执行的 SQL。如果有大量 Waiting for table metadata lock 状态，说明有长事务一直占着表没提交。最常见的原因是你的代码在开启事务后没有正确提交，或者某个事务里执行了一段特别耗时的外部调用。

我处理过的一个案例是一个定时任务里调用了第三方 HTTP 接口后再批量更新数据库，外部接口超时导致事务长时间不提交，最终拖垮了同一张表的其他写入操作。解决办法很简单：事务边界内不要做远程调用，先查完外部数据再开事务。

7. 从“连上”到“用好”：分页插件、自动填充与代码生成器

连接跑通只是开始，真正做业务时需要一些更高级的配套。这一章我挑 MyBatis-Plus 日常使用频率最高的三个能力展开。

7.1 MyBatis-Plus 分页插件配置与物理分页原理

直接告诉你结论：如果你不去配置分页插件，MyBatis-Plus 里调用 selectPage 时，分页功能是不完整的。更早版本里会直接查询全部数据然后在内存里分页，数据量一大就出问题。

正确做法是新建一个配置类：

java复制@Configuration
public class MybatisPlusConfig {

    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        return interceptor;
    }
}

PaginationInnerInterceptor 是专门做物理分页的拦截器。它会在你执行分页查询时，自动在 SQL 后面追加 LIMIT, 并生成一条 SELECT COUNT 语句来查总数。

实际业务中你没有必要手动拼接 LIMIT，直接用 MP 的 Page 对象：

java复制Page<User> page = new Page<>(1, 10);
LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
wrapper.orderByDesc(User::getId);
Page<User> userPage = userMapper.selectPage(page, wrapper);

List<User> records = userPage.getRecords();
long total = userPage.getTotal();

接口返回给前端时，把 records 和 total 一起返回，前端渲染翻页组件就够了。注意 Page 的页码从 1 开始，不是 0。

7.2 时间字段自动填充与逻辑删除组合使用

之前实体类里有 createTime 和 updateTime 两个字段，我加了 @TableField(fill = ...) 注解，但它并不是加了注解就自动填充，还需要实现 MetaObjectHandler 接口：

java复制@Component
public class MyMetaObjectHandler implements MetaObjectHandler {

    @Override
    public void insertFill(MetaObject metaObject) {
        this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());
        this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
    }

    @Override
    public void updateFill(MetaObject metaObject) {
        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
    }
}

这样做的好处是：插入数据时不需要手动给 createTime 赋值，更新时也不需要手动维护 updateTime，所有写操作统一由 MyBatis-Plus 在底层完成。

需要注意的是 strictInsertFill 方法只在字段值为空时才填充。如果你在代码里故意给某个字段设置了值，它就不会覆盖你设置的值。

7.3 用代码生成器批量生成 entity/mapper/service

每次建一张表都要手写实体类、Mapper、Service、Controller，看起来还行，但当你有二三十张表时，这套重复劳动很消耗耐心。MyBatis-Plus 官方提供了代码生成器，基于数据库表反向生成代码。

新版推荐使用 FastAutoGenerator，它链式配置很简洁：

java复制FastAutoGenerator.create("jdbc:mysql://localhost:3306/quick_start?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false",
                "root", "root123456")
        .globalConfig(builder -> builder.author("你的名字").outputDir("/Users/me/code"))
        .packageConfig(builder -> builder.parent("com.example.demo"))
        .strategyConfig(builder -> builder.addInclude("user"))
        .execute();

这段代码会连接数据库读取表结构，自动生成完整项目结构。生成后的实体类里已经包含 @TableName、@TableId 这些注解，Mapper 也继承了 BaseMapper，几乎可以直接使用。

我的实际体验是：代码生成器对单表 CRUD 的帮助是实打实的，能让项目启动后立刻进入业务开发阶段。但也要注意，生成代码只是骨架，复杂业务查询还是需要手写 XML 或方法。如果哪张表结构发生变化，重新生成时可能会覆盖你手改过的代码，所以用代码生成器前最好把代码目录提交到 Git，生成后对比差异再合并。

7.4 接上 Actuator，让数据库连接状态可观察

热词里两次出现 micrometer + spring boot actuator，Spring Boot 2.x 之后 Actuator 的底层监控就是基于 Micrometer 的。引入依赖：

xml复制<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

配置暴露健康检查端点：

yaml复制management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics

启动后访问 http://localhost:8080/actuator/health，你会看到：

json复制{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP"
    }
  }
}

db 组件的状态就是数据源健康检查的结果，它内部会尝试获取一个数据库连接并执行校验查询。如果 MySQL 挂了或连接池耗尽，状态会变成 DOWN，这个端点可以被监控系统直接采集。数据库连接这种事，重点不是在出问题时到处翻日志，而是提前暴露在健康检查里。

8. 写在实操之后：关于“快速连接”真正重要的一件事

每次带新人做 Spring Boot 项目，我都会强调：连接 MySQL 本身花不了多少时间，真正影响效率的是你是否理解配的每个参数、每条依赖在链路中的角色。spring.datasource 决定连接池怎么创建，@MapperScan 决定代理对象从哪来，LambdaQueryWrapper 决定 SQL 的拼接方式，配置类决定分页是否真正生效——这些点串起来，才构成完整的“连接”。

我个人项目里的固定套路是：Docker 里跑 MySQL 8，Spring Boot 3 + JDK 17 + mybatis-plus-spring-boot3-starter，开发环境开着 SQL 日志，启动类上写 @MapperScan，实体类统一使用 Lombok 和自动填充。这套组合帮我省掉了大量 CRUD 模板代码，也让团队新人上手速度明显加快。如果你还在用 Spring Boot 2.x，照着文中的逻辑换成对应坐标即可，原理完全是相通的。

希望这篇偏实战的梳理能帮你把连接阶段的时间压缩到最短，把省下的精力真正投入到业务本身。数据库连接这件事，搞透一次，以后就再也不会被绊住了。