Spring Boot + MyBatis 数据库连接配置指南

记录在 Spring Cloud 项目中用 MyBatis 连接 MySQL 的完整配置，以及踩过的坑。

一、需要引入的依赖

放在 service 的公共父节点 module/pom.xml 里（所有 service 都能继承）：

<!-- MySQL 驱动 -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- MyBatis 与 Spring Boot 集成 -->
<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>4.0.0</version>
</dependency>

版本号要和你的 Spring Boot 大版本对上（Boot 4.x → mybatis-spring-boot-starter 4.0.x）。

二、配置文件（application.yml）

放在 src/main/resources/application.yml：

server:
  port: 8081

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://主机:端口/数据库名?useSSL=false&serverTimezone=Asia/Shanghai
    username: 用户名
    password: 密码

mybatis:
  mapper-locations: classpath:mapper/*.xml
  configuration:
    map-underscore-to-camel-case: true

各部分说明

关于 mapper-locations：可以配，也可以不配

推荐显式配置：

mybatis:
  mapper-locations: classpath:mapper/*.xml

直观、规范，XML 统一放 resources/mapper/ 下，别人一看就知道在哪。

不配置也能生效的情况（默认约定）：
当 XML 文件在 resources/ 下的包路径和 Mapper 接口的包路径完全一致，且文件名和接口同名时，MyBatis 会自动扫描到，不用写 mapper-locations。例如：

resources/com/example/user/mapper/UserMapper.xml   ↔  com.example.user.mapper.UserMapper

结论： 虽然不配也能靠「接口同包」自动找到，但推荐显式配置，结构更可控。

三、三种 MyBatis 用法

方式 A：注解 SQL（入门简单）

@Mapper
public interface UserMapper {
    @Select("SELECT * FROM user WHERE id = #{id}")
    UserEntity getUserById(@Param("id") Long id);
}

方式 B：XML 写 SQL（企业主流）

Mapper 接口（只写方法签名）：

@Mapper
public interface UserMapper {
    UserEntity getUserById(@Param("id") Long id);
}

XML 文件 src/main/resources/mapper/UserMapper.xml：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.example.user.mapper.UserMapper">

    <select id="getUserById" resultType="com.example.user.entity.UserEntity">
        SELECT * FROM user WHERE id = #{id}
    </select>

</mapper>

方式 C：启动类扫包（不用每个接口写 @Mapper）

@SpringBootApplication
@MapperScan("com.example.user.mapper")
public class UserServiceApplication { ... }

四、Mapper 与 XML 的对应关系（关键）

五、分层结构（规范）

UserController  →  UserService(接口)  →  UserServiceImpl  →  UserMapper(接口)  →  XML

com.example.user
├── UserServiceApplication.java   (启动类)
├── controller/UserController.java
├── service/UserService.java      (接口)
├── service/UserServiceImpl.java  (实现)
├── mapper/UserMapper.java        (接口)
├── entity/UserEntity.java        (实体)
└── resources/mapper/UserMapper.xml

六、踩坑记录

七、验证是否连上

1. 确认 application.yml 里 mybatis 配置块已加
2. 刷新 Maven 让依赖生效
3. 启动应用，访问 Controller 接口
4. 日志里看到 HikariPool-1 - Starting 表示开始连数据库；若无报错即连接成功

常见失败：UnknownHostException（域名不存在/地址错）、Access denied（账号密码错）、Connection refused（端口错/数据库没启动）。