SpringBoot 集成 MyBatis：从入门到实操的完整指南

亚当
143 阅读4分钟

一、前言

MyBatis 是一款轻量级的 ORM 框架，以灵活的 SQL 操作和低侵入性成为 Java 开发中数据持久层的主流选择。SpringBoot 凭借自动配置特性简化开发流程，本文将一步步讲解如何在 SpringBoot 项目中快速集成 MyBatis，实现数据库的增删改查操作。

二、环境准备

在开始集成前，确保你的开发环境满足以下条件：

  1. JDK 17 及以上版本
  2. Maven/Gradle 构建工具（本文以 Maven 为例）
  3. 开发工具：IntelliJ IDEA
  4. 数据库：MySQL 5.7+/8.0+（需提前创建测试数据库，如test_db）

三、核心集成步骤

步骤 1：创建 SpringBoot 项目并引入依赖

新建 SpringBoot 项目，在pom.xml中添加核心依赖（SpringBoot 父依赖 + MyBatis+MySQL 驱动）：

<!-- SpringBoot父依赖 -->
<parent>
    <groupId>org.springframework.boot</groupId> 
    <artifactId>spring-boot-starter-parent</artifactId> 
    <version>2.7.10</version> 
    <relativePath/> 
</parent> 

<dependencies> 
    <!-- SpringBoot Web依赖（非必需，用于测试接口） --> 
    <dependency> 
        <groupId>org.springframework.boot</groupId> 
        <artifactId>spring-boot-starter-web</artifactId> 
    </dependency> 
    <!-- MyBatis整合SpringBoot依赖 --> 
    <dependency> 
        <groupId>org.mybatis.spring.boot</groupId> 
        <artifactId>mybatis-spring-boot-starter</artifactId> 
        <version>2.3.0</version> 
    </dependency> 
    <!-- MySQL驱动 --> 
    <dependency> 
        <groupId>com.mysql.cj</groupId> 
        <artifactId>mysql-connector-java</artifactId> 
        <scope>runtime</scope> 
    </dependency> 
    <!-- 测试依赖 --> 
    <dependency> 
        <groupId>org.springframework.boot</groupId> 
        <artifactId>spring-boot-starter-test</artifactId> 
        <scope>test</scope> 
    </dependency> 
</dependencies>

步骤 2：配置数据库与 MyBatis 核心参数

在src/main/resources目录下的application.yml（推荐）或application.properties中，配置数据库连接和 MyBatis 关键参数：

# 数据库连接配置
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/test_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root  # 替换为你的MySQL用户名
    password: 123456  # 替换为你的MySQL密码
    driver-class-name: com.mysql.cj.jdbc.Driver

# MyBatis配置
mybatis:
  # 指定Mapper.xml文件的扫描路径（若使用注解版可省略）
  mapper-locations: classpath:mapper/*.xml
  # 实体类别名包，简化Mapper中实体类的引用
  type-aliases-package: com.example.demo.entity
  # 开启驼峰命名自动转换（如数据库user_name映射到实体类userName）
  configuration:
    map-underscore-to-camel-case: true

步骤 3：编写实体类、Mapper 接口与映射文件

（1）创建实体类

以用户表user为例，在com.example.demo.entity包下创建User.java：

package com.example.demo.entity;

public class User {
    private Long id;
    private String userName;
    private Integer age;
    private String email;

    // 无参构造、全参构造
    public User() {}
    public User(Long id, String userName, Integer age, String email) {
        this.id = id;
        this.userName = userName;
        this.age = age;
        this.email = email;
    }

    // getter/setter方法
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getUserName() { return userName; }
    public void setUserName(String userName) { this.userName = userName; }
    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }

    // toString方法
    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", userName='" + userName + ''' +
                ", age=" + age +
                ", email='" + email + ''' +
                '}';
    }
}

（2）创建 Mapper 接口

在com.example.demo.mapper包下创建UserMapper.java（MyBatis 的 Mapper 接口，需添加@Mapper注解）：

package com.example.demo.mapper;

import com.example.demo.entity.User;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Select;
import java.util.List;

// 标记为MyBatis的Mapper接口，SpringBoot会自动扫描并创建代理对象
@Mapper
public interface UserMapper {
    // 注解版：查询所有用户
    @Select("SELECT * FROM user")
    List<User> listAllUsers();

    // XML版：新增用户（具体SQL写在Mapper.xml中）
    int addUser(User user);
}

（3）创建 Mapper.xml 映射文件（可选，注解版可省略）

在src/main/resources/mapper目录下创建UserMapper.xml，编写 XML 版 SQL：

<?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">
<!-- namespace必须对应Mapper接口的全类名 -->
<mapper namespace="com.example.demo.mapper.UserMapper">
    <!-- 新增用户：id对应接口中的方法名，parameterType对应参数类型 -->
    <insert id="addUser" parameterType="User">
        INSERT INTO user (user_name, age, email)
        VALUES (#{userName}, #{age}, #{email})
    </insert>
</mapper>

步骤 4：编写 Service 与 Controller（可选，用于测试）

（1）Service 层

在com.example.demo.service包下创建UserService.java：

package com.example.demo.service;

import com.example.demo.entity.User;
import com.example.demo.mapper.UserMapper;
import org.springframework.stereotype.Service;
import javax.annotation.Resource;
import java.util.List;

@Service
public class UserService {
    // 注入Mapper接口
    @Resource
    private UserMapper userMapper;

    // 查询所有用户
    public List<User> listAllUsers() {
        return userMapper.listAllUsers();
    }

    // 新增用户
    public int addUser(User user) {
        return userMapper.addUser(user);
    }
}

（2）Controller 层

在com.example.demo.controller包下创建UserController.java：

package com.example.demo.controller;

import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
import java.util.List;

@RestController
@RequestMapping("/user")
public class UserController {
    @Resource
    private UserService userService;

    // 测试查询所有用户
    @GetMapping("/list")
    public List<User> listAllUsers() {
        return userService.listAllUsers();
    }

    // 测试新增用户
    @PostMapping("/add")
    public String addUser(@RequestBody User user) {
        int result = userService.addUser(user);
        return result > 0 ? "新增用户成功" : "新增用户失败";
    }
}

步骤 5：启动类添加扫描（可选）

若 Mapper 接口未添加@Mapper注解，需在 SpringBoot 启动类DemoApplication.java上添加@MapperScan指定 Mapper 包路径：

package com.example.demo;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

// 扫描Mapper接口所在包
@MapperScan("com.example.demo.mapper")
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

四、测试验证

  1. 启动 SpringBoot 项目，确保无报错；
  2. 方式 1：使用 Postman 调用POST http://localhost:8080/user/add，传入 JSON 参数新增用户：
{
    "userName": "张三",
    "age": 25,
    "email": "zhangsan@163.com"
}
  1. 方式 2：调用GET http://localhost:8080/user/list，可查询到新增的用户数据，验证集成成功。

五、常见问题与注意事项

  1. Mapper.xml 文件路径错误：需确保mapper-locations配置的路径与实际文件位置一致，且 XML 文件在 resources 目录下；
  2. 驼峰命名转换不生效：检查map-underscore-to-camel-case是否配置为true，且数据库字段与实体类属性命名符合驼峰规则；
  3. Mapper 接口注入失败：确保添加@Mapper注解或启动类添加@MapperScan扫描。

六、总结

SpringBoot 集成 MyBatis 的核心是「依赖引入 + 配置编写 + Mapper 映射」三步，通过自动配置特性省去了传统 SSM 框架中繁琐的 XML 配置。本文既讲解了注解版（快速开发）也讲解了 XML 版（复杂 SQL 场景），新手可根据实际需求选择，掌握后即可高效实现 SpringBoot 项目的数据库操作。

avatar
文章
阅读
粉丝