Spring Boot + MyBatis 从 0 到 1 跑通查询接口（含全部踩坑）

一、前言

很多人学到 Spring Boot + MyBatis 时，会卡在一个点：

复制代码

配置都写了
Mapper 也写了
项目也能启动
但就是查不出数据 ❌

原因很简单：

❗ MyBatis 真正难的不是写代码，而是"配置 + 路径 + 映射关系"

这篇文章我带你从 0 到 1：

👉 跑通一个查询接口（100% 可落地）

👉 并帮你避开最常见的坑

二、最终目标

我们要实现：

复制代码

浏览器访问：
http://localhost:8080/user/1

复制代码

{
  "id": 1,
  "username": "test",
  "password": "123456",
  "createTime": "2026-04-16T..."
}

三、准备数据库（第一步）

1️⃣ 创建数据库

sql 复制代码

CREATE DATABASE user_center;

2️⃣ 创建表

sql 复制代码

CREATE TABLE user (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    username VARCHAR(64) NOT NULL,
    password VARCHAR(128) NOT NULL,
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP
);

3️⃣ 插入数据（必须）

sql 复制代码

INSERT INTO user (username, password)
VALUES ('test', '123456');

四、引入依赖（第二步）

pom.xml：

XML 复制代码

<dependencies>

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

    <!-- MyBatis 核心 -->
    <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>3.0.3</version>
    </dependency>

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

    <!-- Lombok（可选但推荐） -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </dependency>

</dependencies>

五、配置 application.yaml（第三步）

XML 复制代码

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/user_center?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf-8
    username: root
    password:
    driver-class-name: com.mysql.cj.jdbc.Driver

server:
  port: 8080

mybatis:
  mapper-locations: classpath:mapper/*.xml
  type-aliases-package: org.example.arkbackend.entity

logging:
  level:
    org.example.arkbackend: debug

六、创建实体类（第四步）

路径：

复制代码

entity/User.java

java 复制代码

@Data
public class User {
    private Long id;
    private String username;
    private String password;
    private LocalDateTime createTime;
}

七、创建 Mapper 接口（第五步）

路径：

复制代码

mapper/UserMapper.java

java 复制代码

@Mapper
public interface UserMapper {

    User selectById(Long id);

}

八、编写 XML（第六步，重点）

路径必须是：

复制代码

src/main/resources/mapper/UserMapper.xml

内容：

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="org.example.arkbackend.mapper.UserMapper">

    <select id="selectById" resultType="User">
        select id, username, password, create_time
        from user
        where id = #{id}
    </select>

</mapper>

九、创建 Service（第七步）

java 复制代码

@Service
@RequiredArgsConstructor
public class UserService {

    private final UserMapper userMapper;

    public User getById(Long id) {
        return userMapper.selectById(id);
    }
}

十、创建 Controller（第八步）

java 复制代码

@RestController
@RequestMapping("/user")
@RequiredArgsConstructor
public class UserController {

    private final UserService userService;

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

十一、启动测试（第九步）

访问：

复制代码

http://localhost:8080/user/1

十二、常见踩坑（重点）

❌ 坑1：Mapper 找不到

报错：

复制代码

No qualifying bean of type 'UserMapper'

👉 原因：

没加 @Mapper
或没加 @MapperScan

❌ 坑2：SQL 找不到

报错：

复制代码

Invalid bound statement

👉 原因：

namespace 不一致
id 不一致

❌ 坑3：XML 没加载

👉 原因：

复制代码

mapper-locations 写错 ❌

❌ 坑4：路径错误（最常见）

复制代码

XML 必须放：
resources/mapper/

不是：

复制代码

java/mapper ❌

❌ 坑5：字段映射问题

数据库：

复制代码

create_time

Java：

复制代码

createTime

👉 一般 MyBatis 会自动转（前提配置正确）

十三、完整链路总结

复制代码

浏览器请求
    ↓
Controller
    ↓
Service
    ↓
Mapper（代理对象）
    ↓
XML SQL
    ↓
MySQL
    ↓
返回对象

十四、一句话总结

❗ MyBatis 的核心不是 Mapper，而是：
接口 + XML + 映射关系必须完全一致

十五、写在最后

如果你能跑通这一篇，你就完成了：

复制代码

从 0 → 能真正访问数据库

这一步非常关键。

十六、下一篇预告

👉 《Spring Boot 用户注册接口（含事务 + 参数校验）》