一、前言
很多人学到 Spring Boot + MyBatis 时，会卡在一个点：
配置都写了 Mapper 也写了 项目也能启动 但就是查不出数据 ❌原因很简单：
❗ MyBatis 真正难的不是写代码，而是“配置 + 路径 + 映射关系”
这篇文章我带你从 0 到 1：
👉跑通一个查询接口（100% 可落地）
👉并帮你避开最常见的坑
二、最终目标
我们要实现：
浏览器访问： http://localhost:8080/user/1返回：
{ "id": 1, "username": "test", "password": "123456", "createTime": "2026-04-16T..." }三、准备数据库（第一步）
1️⃣ 创建数据库
CREATE DATABASE user_center;2️⃣ 创建表
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️⃣ 插入数据（必须）
INSERT INTO user (username, password) VALUES ('test', '123456');四、引入依赖（第二步）
pom.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（第三步）
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@Data public class User { private Long id; private String username; private String password; private LocalDateTime createTime; }七、创建 Mapper 接口（第五步）
路径：
mapper/UserMapper.java@Mapper public interface UserMapper { User selectById(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="org.example.arkbackend.mapper.UserMapper"> <select id="selectById" resultType="User"> select id, username, password, create_time from user where id = #{id} </select> </mapper>九、创建 Service（第七步）
@Service @RequiredArgsConstructor public class UserService { private final UserMapper userMapper; public User getById(Long id) { return userMapper.selectById(id); } }十、创建 Controller（第八步）
@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_timeJava：
createTime👉 一般 MyBatis 会自动转（前提配置正确）
十三、完整链路总结
浏览器请求 ↓ Controller ↓ Service ↓ Mapper（代理对象） ↓ XML SQL ↓ MySQL ↓ 返回对象十四、一句话总结
❗ MyBatis 的核心不是 Mapper，而是：
接口 + XML + 映射关系必须完全一致
十五、写在最后
如果你能跑通这一篇，你就完成了：
从 0 → 能真正访问数据库这一步非常关键。
十六、下一篇预告
👉 《Spring Boot 用户注册接口（含事务 + 参数校验）》
（完）
