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️⃣ 创建数据库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.xmldependencies !-- Spring Boot Web -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- MyBatis 核心 -- dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version3.0.3/version /dependency !-- MySQL 驱动 -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId /dependency !-- Lombok可选但推荐 -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId /dependency /dependencies五、配置 application.yaml第三步spring: datasource: url: jdbc:mysql://localhost:3306/user_center?useSSLfalseserverTimezoneAsia/ShanghaicharacterEncodingutf-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.javaData public class User { private Long id; private String username; private String password; private LocalDateTime createTime; }七、创建 Mapper 接口第五步路径mapper/UserMapper.javaMapper public interface UserMapper { User selectById(Long id); }八、编写 XML第六步重点路径必须是src/main/resources/mapper/UserMapper.xml内容?xml version1.0 encodingUTF-8 ? !DOCTYPE mapper PUBLIC -//mybatis.org//DTD Mapper 3.0//EN http://mybatis.org/dtd/mybatis-3-mapper.dtd mapper namespaceorg.example.arkbackend.mapper.UserMapper select idselectById resultTypeUser 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十二、常见踩坑重点❌ 坑1Mapper 找不到报错No qualifying bean of type UserMapper 原因没加Mapper或没加MapperScan❌ 坑2SQL 找不到报错Invalid bound statement 原因namespace 不一致id 不一致❌ 坑3XML 没加载 原因mapper-locations 写错 ❌❌ 坑4路径错误最常见XML 必须放 resources/mapper/不是java/mapper ❌❌ 坑5字段映射问题数据库create_timeJavacreateTime 一般 MyBatis 会自动转前提配置正确十三、完整链路总结浏览器请求 ↓ Controller ↓ Service ↓ Mapper代理对象 ↓ XML SQL ↓ MySQL ↓ 返回对象十四、一句话总结❗ MyBatis 的核心不是 Mapper而是接口 XML 映射关系必须完全一致十五、写在最后如果你能跑通这一篇你就完成了从 0 → 能真正访问数据库这一步非常关键。十六、下一篇预告 《Spring Boot 用户注册接口含事务 参数校验》完