1. 项目概述为什么“SpringBootMybatis整合”仍是Java后端开发绕不开的第一课你打开任何一家中型以上公司的Java岗位JD几乎都会看到“熟悉SpringBoot、Mybatis框架”这一条。不是SpringCloud不是Redis集群更不是K8s编排——而是这两个基础组合。我带过十几期后端训练营观察到一个非常稳定的规律92%的新人在真正写出第一个可运行的增删改查接口前卡点都出在SpringBoot和Mybatis的“握手环节”——不是不会写SQL也不是不懂Controller怎么写而是XML配置路径不对、Mapper扫描失败、事务不生效、甚至连启动日志里那句“Mapped statement not found”的报错都看不懂。这根本不是能力问题而是框架整合过程中的“隐性契约”没被显性化。所谓“整合”本质是让两个设计哲学不同的框架在类加载、Bean生命周期、SQL执行链路上达成一致节奏。SpringBoot用自动装配简化了Spring容器初始化Mybatis则用SqlSessionFactory作为核心枢纽调度SQL执行二者交汇处恰恰是最容易出错的“胶水层”。这篇文章不讲抽象原理只拆解真实项目里你马上会遇到的5个关键断点依赖版本如何对齐、Mapper接口与XML如何精准绑定、MapperScan该扫哪、为什么加了Transactional却没回滚、以及最常被忽略的——Mybatis的TypeHandler在字段映射时如何悄悄改变你的数据类型。这些不是面试八股而是你明天上午十点就要提交给导师/组长的第一个可运行Demo里必须踩实的五个台阶。2. 整体设计思路与方案选型逻辑为什么不用Mybatis-Plus为什么坚持XML很多新人看到标题里的“入门一”就下意识想跳过觉得“都2024年了还手写XML直接上Mybatis-Plus不香吗”——这个想法很真实但恰恰暴露了对框架演进逻辑的误读。我参与过3个从零搭建的中后台系统其中2个初期强行用Mybatis-Plus结果在第3个月全部回退到原生Mybatis少量自定义Starter。原因很具体Mybatis-Plus的“约定大于配置”在复杂业务场景下会变成“约束大于自由”。比如某次需要根据动态条件拼接嵌套子查询MP的QueryWrapper写出来像俄罗斯套娃而原生XML里一个 标签加两行SQL就搞定再比如分页插件MP的IPage在多表关联时默认只对主表分页要改源码或重写Interceptor而Mybatis原生分页插件PageHelper的count查询逻辑完全可控。所以本系列坚持用原生Mybatis不是守旧而是把“控制权”交还给开发者。至于SpringBoot版本我们锁定2.7.18Spring Framework 5.3.31这是SpringBoot 2.x最后一个长期支持版也是企业级项目最广泛采用的稳定基线——它避开了3.x的Jakarta EE迁移阵痛又比2.5.x多了对JDK17的完整支持。依赖管理采用Maven BOMBill of Materials模式所有Spring生态组件版本由spring-boot-dependencies统一仲裁杜绝mybatis-spring-boot-starter 2.2.x和mybatis 3.4.x这种经典版本错配。这种“保守选型”背后是血泪教训曾有个项目因升级到SpringBoot 3.0导致所有自定义TypeHandler失效排查了整整两天才发现是jakarta.persistence包路径变更引发的反射异常。2.1 依赖坐标与版本对齐的底层逻辑Maven依赖不是简单复制粘贴每个坐标背后都有明确的职责边界。我们逐个拆解pom.xml中必须出现的三个核心依赖!-- SpringBoot Web基础 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Mybatis与SpringBoot的官方桥接器 -- dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version2.2.2/version /dependency !-- 数据库驱动以MySQL为例 -- dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency重点看第二个依赖mybatis-spring-boot-starter它的作用不是提供Mybatis核心功能而是实现SpringBoot的AutoConfiguration机制与Mybatis生命周期的深度绑定。当你引入它时SpringBoot会自动触发MybatisAutoConfiguration类这个类内部做了三件关键事第一创建SqlSessionFactoryBean并注入数据源第二扫描标注了Mapper的接口并注册为Spring Bean第三配置SqlSessionTemplate作为线程安全的SqlSession代理。这里埋着第一个坑如果你手动创建了SqlSessionFactoryBean又没排除自动配置就会触发Bean定义冲突。解决方案是在SpringBootApplication上添加EnableAutoConfiguration(exclude {MybatisAutoConfiguration.class})但除非你有特殊定制需求否则绝不建议这么做——官方自动配置经过了千万级生产环境验证自己重写反而容易出错。2.2 XML vs 注解为什么在入门阶段必须手写XMLMybatis支持两种SQL定义方式Mapper接口方法上的Select注解或独立的XML文件。新手常问“哪个更简单”答案是XML在入门阶段更简单因为错误反馈更直接。举个例子你在注解里写Select(SELECT * FROM user WHERE id #{id})如果表名user拼错成uers运行时抛出Table db.uers doesnt exist你能立刻定位到SQL问题但如果用XMLIDEA会直接在XML编辑器里标红select idgetUser resultTypeUser这一行提示“Cannot resolve symbol User”因为resultType指向的实体类未被识别。这种静态检查能拦截80%的低级错误。更重要的是XML天然支持动态SQL的复杂结构 标签自动处理AND/OR前置空格 遍历集合生成IN语句 实现类似switch的条件分支——这些在注解里需要用字符串拼接极易引发SQL注入风险。我见过最典型的案例某开发者为图省事在注解里写Select(SELECT * FROM order WHERE status ${status})用${}直接拼接参数结果测试环境被注入了1 OR 11订单列表全崩。而XML里强制要求用#{}, Mybatis会自动做预编译参数化从根源上规避这类问题。所以本系列所有SQL均采用XML方式不是排斥注解而是让初学者先建立“SQL与Java对象严格分离”的工程直觉。3. 核心细节解析与实操要点从零开始搭建可运行环境搭建过程看似简单但每个步骤都藏着决定成败的细节。我用一台刚重装系统的MacBook ProM1芯片JDK17实测了三遍记录下所有关键操作节点和验证方法。整个流程分为四个不可跳过的阶段环境准备→项目初始化→数据库建模→框架整合验证。跳过任一环节后续都会出现“明明代码一样却跑不通”的玄学问题。3.1 环境准备JDK与Maven的隐形陷阱很多人以为装好JDK和Maven就万事大吉但实际开发中JDK版本与SpringBoot的兼容性、Maven本地仓库的权限问题才是最常被忽视的拦路虎。SpringBoot 2.7.x要求JDK8-17但JDK17的模块化特性会导致某些老版本依赖如HikariCP 3.4.x启动失败。解决方案是使用JDK17.0.1并在pom.xml中显式声明HikariCP版本properties java.version17/java.version hikari.version4.0.3/hikari.version /properties dependencies dependency groupIdcom.zaxxer/groupId artifactIdHikariCP/artifactId version${hikari.version}/version /dependency /dependenciesMaven本地仓库默认~/.m2/repository的权限问题更隐蔽。在Mac/Linux系统中如果之前用sudo执行过mvn命令会导致部分jar包文件属主变为root后续普通用户构建时会因权限不足无法覆盖表现为“依赖下载一半卡住”或“ClassNotFoundException”。验证方法执行ls -la ~/.m2/repository/org/springframework/boot/查看spring-boot-starter-web目录下文件是否全为当前用户所有。若存在root属主文件执行sudo chown -R $USER:$GROUP ~/.m2/repository修复。这个操作耗时不到10秒却能避免后续3小时无意义排查。3.2 项目初始化Spring Initializr的正确打开方式虽然可以用IDEA内置的Spring Initializr向导但手动配置依赖坐标比图形界面更可靠。原因在于向导生成的pom.xml可能包含冗余依赖如spring-boot-starter-aop而实际整合Mybatis时并不需要更重要的是向导默认勾选的Lombok依赖其版本可能与SpringBoot 2.7.x不兼容Lombok 1.18.26才完全支持JDK17。因此我推荐纯手工创建pom.xml只保留最精简的核心依赖。以下是经过验证的最小可行配置?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent groupIdcom.example/groupId artifactIddemo-mybatis/artifactId version0.0.1-SNAPSHOT/version namedemo-mybatis/name descriptionDemo project for Spring Boot Mybatis/description properties java.version17/java.version mybatis.version2.2.2/mybatis.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version${mybatis.version}/version /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency !-- Lombok需单独指定兼容版本 -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId configuration excludes exclude groupIdorg.projectlombok/groupId artifactIdlombok/artifactId /exclude /excludes /configuration /plugin /plugins /build /project关键点解析parent标签指定了SpringBoot父POM它内部已定义了所有Spring生态组件的版本号因此mybatis-spring-boot-starter无需声明版本也能正确解析optionaltrue/optional用于Lombok表示该依赖仅在编译期生效不打包进最终jar包避免运行时冲突excludes配置确保Lombok不会被包含在可执行jar中这是生产环境最佳实践。3.3 数据库建模从ER图到建表语句的精确转换很多教程直接给出建表SQL却不说清楚字段设计背后的业务含义。我们以“用户管理”模块为例构建一个符合真实业务逻辑的最小数据模型。ER图核心关系是一个用户user属于一个部门department可拥有多个角色role角色与权限permission是多对多关系。但入门阶段我们只实现user表其他表留作后续扩展-- 创建数据库 CREATE DATABASE IF NOT EXISTS demo_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- 切换数据库 USE demo_db; -- 用户表 CREATE TABLE user ( id bigint NOT NULL AUTO_INCREMENT COMMENT 主键ID, username varchar(50) NOT NULL COMMENT 用户名唯一索引, password varchar(100) NOT NULL COMMENT 密码BCrypt加密, email varchar(100) DEFAULT NULL COMMENT 邮箱, status tinyint NOT NULL DEFAULT 1 COMMENT 状态0-禁用1-启用, created_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT 创建时间, updated_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新时间, PRIMARY KEY (id), UNIQUE KEY uk_username (username), KEY idx_status (status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT用户基本信息表;这里有几个必须强调的设计细节第一id类型用bigint而非int因为互联网系统用户量轻松破千万int最大值21亿虽够用但bigint预留了更长生命周期第二password字段长度设为100因为BCrypt加密后的密文长度固定为60字符留40位余量应对未来算法升级第三created_time和updated_time采用DEFAULT CURRENT_TIMESTAMP和ON UPDATE CURRENT_TIMESTAMP由数据库自动维护避免Java层手动赋值导致的时间不一致第四status用tinyint而不用enum因为MySQL的enum类型在JDBC驱动中映射为字符串增加序列化开销且修改枚举值需DDL操作不够灵活。这些细节看似微小但在高并发场景下会成为性能瓶颈或维护噩梦。4. 实操过程与核心环节实现手把手完成第一个CRUD现在进入最核心的实操环节。我们将用最朴素的方式不借助任何代码生成器从零编写Mapper接口、XML映射文件、Service层和Controller每一步都附带验证方法和常见错误提示。整个过程遵循“写一行测一行”的原则确保每个环节都处于可控状态。4.1 Mapper接口与XML文件的物理绑定这是整合过程中最容易出错的环节。很多新人把Mapper接口放在com.example.demo.mapper包下XML文件却放在resources/mapper/UserMapper.xml结果启动时报Invalid bound statement (not found)。根本原因是Mybatis默认只扫描classpath:mapper/*.xml路径而SpringBoot的mybatis.mapper-locations配置未生效。解决方案分三步第一步确认XML文件存放位置必须将UserMapper.xml放在src/main/resources/mapper/目录下注意是resources不是java。IDEA中右键resources目录→New→Directory→输入mapper确保路径为src/main/resources/mapper/UserMapper.xml。第二步配置application.yml显式声明扫描路径mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.demo.entity这里type-aliases-package指定实体类包路径让Mybatis能自动识别resultTypeUser中的User类无需写全限定名。第三步Mapper接口添加Mapper注解或全局扫描推荐使用全局扫描避免每个接口都加注解。在SpringBoot主类上添加SpringBootApplication MapperScan(com.example.demo.mapper) public class DemoMybatisApplication { public static void main(String[] args) { SpringApplication.run(DemoMybatisApplication.class, args); } }此时com.example.demo.mapper包下的所有接口都会被自动注册为Mapper Bean。验证方法启动应用后查看控制台日志搜索Mapped statement应看到类似Mapped statement com.example.demo.mapper.UserMapper.getUser的日志证明XML已成功加载。4.2 编写UserMapper接口与XML映射接口定义遵循Mybatis规范方法名必须与XML中select标签的id属性完全一致参数类型用Param注解明确命名避免单参数时的模糊匹配// src/main/java/com/example/demo/mapper/UserMapper.java package com.example.demo.mapper; import com.example.demo.entity.User; import org.apache.ibatis.annotations.Param; public interface UserMapper { /** * 根据ID查询用户 */ User getUser(Param(id) Long id); /** * 插入新用户 */ int insertUser(User user); /** * 更新用户信息 */ int updateUser(User user); /** * 删除用户 */ int deleteUser(Param(id) Long id); }对应的XML文件内容如下注意namespace必须是接口全限定名!-- 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 namespacecom.example.demo.mapper.UserMapper !-- 结果映射定义数据库字段与Java属性的对应关系 -- resultMap idUserResultMap typecom.example.demo.entity.User id propertyid columnid/ result propertyusername columnusername/ result propertypassword columnpassword/ result propertyemail columnemail/ result propertystatus columnstatus/ result propertycreatedTime columncreated_time/ result propertyupdatedTime columnupdated_time/ /resultMap !-- 查询语句 -- select idgetUser resultMapUserResultMap SELECT id, username, password, email, status, created_time, updated_time FROM user WHERE id #{id} /select !-- 插入语句useGeneratedKeystrue让Mybatis获取自增主键 -- insert idinsertUser useGeneratedKeystrue keyPropertyid INSERT INTO user (username, password, email, status, created_time, updated_time) VALUES (#{username}, #{password}, #{email}, #{status}, NOW(), NOW()) /insert !-- 更新语句动态SQL避免更新null值 -- update idupdateUser UPDATE user set if testusername ! null and username ! username #{username},/if if testpassword ! null and password ! password #{password},/if if testemail ! null and email ! email #{email},/if if teststatus ! nullstatus #{status},/if updated_time NOW() /set WHERE id #{id} /update !-- 删除语句 -- delete iddeleteUser DELETE FROM user WHERE id #{id} /delete /mapper关键细节说明resultMap中的property必须与Java实体类的getter/setter方法名匹配如getCreatedTime()对应createdTimecolumn必须与数据库字段名一致注意下划线命名转驼峰insert标签的useGeneratedKeystrue和keyPropertyid组合确保插入后user.getId()能返回数据库生成的主键值update中的set标签会自动去除末尾逗号if标签实现空值安全更新——这些是Mybatis动态SQL的精髓比硬编码SQL健壮得多。4.3 Service层实现与事务控制Service层是业务逻辑的承载体也是事务管理的关键位置。我们创建UserService接口及其实现类重点演示Transactional的正确用法// src/main/java/com/example/demo/service/UserService.java package com.example.demo.service; import com.example.demo.entity.User; public interface UserService { User getUserById(Long id); int createUser(User user); int updateUser(User user); int deleteUser(Long id); } // src/main/java/com/example/demo/service/impl/UserServiceImpl.java package com.example.demo.service.impl; import com.example.demo.entity.User; import com.example.demo.mapper.UserMapper; import com.example.demo.service.UserService; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; Service public class UserServiceImpl implements UserService { Autowired private UserMapper userMapper; Override public User getUserById(Long id) { return userMapper.getUser(id); } Override Transactional(rollbackFor Exception.class) public int createUser(User user) { // 模拟业务校验用户名不能重复 if (userMapper.getUserByUsername(user.getUsername()) ! null) { throw new RuntimeException(用户名已存在); } return userMapper.insertUser(user); } Override Transactional(rollbackFor Exception.class) public int updateUser(User user) { return userMapper.updateUser(user); } Override Transactional(rollbackFor Exception.class) public int deleteUser(Long id) { return userMapper.deleteUser(id); } }这里有两个致命误区必须避开第一Transactional必须加在public方法上加在private或protected方法上无效因为Spring的AOP代理基于JDK动态代理或CGLIB只能拦截public调用第二rollbackFor参数必须显式指定为Exception.class因为Spring默认只对RuntimeException及其子类回滚而Exception的其他子类如IOException不会触发回滚。实测案例某次上传头像文件时捕获IOException但未配置rollbackFor导致用户创建成功但文件上传失败数据状态不一致。此外createUser方法中调用userMapper.getUserByUsername()需要在UserMapper中新增方法这引出了另一个重要原则Mapper接口方法应与业务场景强相关而不是机械对应数据库操作。因此我们在UserMapper中补充// 在UserMapper.java中添加 User getUserByUsername(Param(username) String username);对应XML中添加select idgetUserByUsername resultMapUserResultMap SELECT id, username, password, email, status, created_time, updated_time FROM user WHERE username #{username} /select4.4 Controller层与接口验证最后编写RESTful风格的Controller用Postman或curl进行端到端验证// src/main/java/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.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/api/users) public class UserController { Autowired private UserService userService; GetMapping(/{id}) public User getUser(PathVariable Long id) { return userService.getUserById(id); } PostMapping public User createUser(RequestBody User user) { userService.createUser(user); return user; // 返回已填充主键的user对象 } PutMapping public int updateUser(RequestBody User user) { return userService.updateUser(user); } DeleteMapping(/{id}) public int deleteUser(PathVariable Long id) { return userService.deleteUser(id); } }启动应用后执行以下curl命令验证# 1. 创建用户 curl -X POST http://localhost:8080/api/users \ -H Content-Type: application/json \ -d {username:zhangsan,password:123456,email:zhangsanexample.com,status:1} # 2. 查询用户假设返回id为1 curl http://localhost:8080/api/users/1 # 3. 更新用户 curl -X PUT http://localhost:8080/api/users \ -H Content-Type: application/json \ -d {id:1,username:zhangsan,password:newpass,email:zhangsannew.com,status:1} # 4. 删除用户 curl -X DELETE http://localhost:8080/api/users/1验证通过的标准是每步返回HTTP 200状态码且数据库user表数据与请求参数完全一致。特别注意第1步返回的JSON中应包含id:1或其他自增ID证明useGeneratedKeys配置生效第3步更新后数据库updated_time字段时间戳应更新为当前时间证明update中的NOW()函数被正确执行。5. 常见问题与排查技巧实录那些让你抓狂的“灵异事件”在真实项目中90%的整合问题并非技术难点而是环境、配置、认知偏差导致的“假性故障”。我把过去三年收集的27个高频问题浓缩为5类典型场景并给出可立即执行的排查指令。这些问题的答案往往藏在启动日志的第3行或第158行而不是Stack Overflow的第7页。5.1 启动失败类问题从日志第3行开始读问题现象启动时报Caused by: java.lang.IllegalArgumentException: Property sqlSessionFactory or sqlSessionTemplate are required根本原因mybatis-spring-boot-starter依赖未正确引入或版本与SpringBoot不兼容。排查指令执行mvn dependency:tree | grep mybatis确认输出中包含org.mybatis.spring.boot:mybatis-spring-boot-starter:jar:2.2.2若显示omitted for cycle说明存在依赖循环需检查是否有其他starter间接引入了旧版mybatis强制指定版本在pom.xml中添加exclusions排除冲突依赖问题现象控制台无任何Mybatis相关日志Mapped statement字样完全不出现根本原因mybatis.mapper-locations配置路径错误或XML文件未编译到target/classes目录排查指令启动后检查target/classes/mapper/目录是否存在若不存在说明Maven未将resources下的文件复制过去在IDEA中右键项目→Maven→Reimport强制刷新依赖手动执行mvn clean compile观察[INFO] Copying 1 resource日志是否出现5.2 SQL执行类问题为什么查不到数据问题现象getUser(id)返回null但数据库确认存在该记录根本原因resultMap中property与Java实体类字段名不匹配或数据库字段名与column属性不一致排查指令在User实体类中添加Data注解Lombok确保getter/setter生成正确执行SELECT * FROM user WHERE id 1确认返回字段名为created_time而非createdTime在XML中将result propertycreatedTime columncreated_time/改为result propertycreatedTime columncreated_time/注意大小写问题现象插入操作后user.getId()返回null根本原因insert标签缺少useGeneratedKeystrue或keyProperty值错误排查指令检查XML中insert标签是否包含useGeneratedKeystrue keyPropertyid确认数据库user表id字段设置为AUTO_INCREMENT在MySQL中执行SHOW CREATE TABLE user验证引擎为InnoDBMyISAM不支持事务和自增主键5.3 事务失效类问题为什么加了Transactional却不回滚问题现象createUser方法中抛出RuntimeException但数据库user表仍插入了一条记录根本原因Transactional注解所在类未被Spring容器管理或调用发生在同一个类的内部方法中排查指令在UserServiceImpl类上添加Service注解确认启动日志中有Creating shared instance of singleton bean userServiceImpl检查调用链必须是Controller→Service→Mapper不能是Service内部方法A调用方法B此时AOP代理失效在application.yml中添加logging.level.org.springframework.transactionDEBUG观察日志中是否有Creating new transaction字样5.4 动态SQL类问题为什么 标签不生效问题现象updateUser方法中即使传入emailnullSQL仍执行email null根本原因if标签的test表达式语法错误或Java实体类中email字段为基本类型如String但getter返回空字符串排查指令将test表达式改为if testemail ! null and !email.equals()避免空字符串干扰在Service方法中添加日志log.info(Email value: [{}], length: {}, user.getEmail(), user.getEmail() null ? null : user.getEmail().length())使用trim标签替代set手动控制前后缀trim prefixSET suffixOverrides,5.5 性能类问题为什么第一次查询特别慢问题现象首次调用getUser耗时800ms后续调用仅5ms根本原因Mybatis首次加载XML时需解析DOM树并缓存MappedStatement同时JVM类加载和JIT编译带来额外开销优化方案在application.yml中添加mybatis.configuration.cache-enabledtrue开启二级缓存添加SelectKey注解预热在Mapper接口中添加SelectKey(statementSELECT 1, keyPropertyid, beforefalse, resultTypeLong.class)生产环境启动时执行一次空查询curl -X GET http://localhost:8080/api/users/0 2/dev/nullID为0的记录不存在但会触发Mybatis初始化提示所有排查指令均经过MacOS/Linux/Windows三端实测复制粘贴即可执行。记住一个铁律95%的“框架bug”其实是配置错误而配置错误的根源80%来自对默认行为的误解。比如Mybatis默认不开启二级缓存SpringBoot默认不扫描mapper包——这些“不作为”恰恰是框架设计者留给开发者的决策空间。6. 实操心得与避坑指南十年踩坑总结的7条军规作为经历过从SSH到SpringBoot再到云原生架构迭代的开发者我把整合Mybatis过程中最痛的教训凝练成7条可立即执行的军规。这些不是教科书理论而是我在凌晨三点服务器告警时用咖啡和黑眼圈换来的经验。军规1永远用mvn clean compile代替IDEA的Build ProjectIDEA的增量编译有时会残留旧class文件导致“代码改了但效果没变”的诡异现象。某次我修改了XML中的SQL反复重启应用仍执行旧逻辑最后发现target/classes/mapper/UserMapper.xml里还是旧内容。执行mvn clean compile后问题消失。从此我的终端里永远开着一个窗口里面只有这行命令。军规2数据库字段名必须用下划线Java属性名必须用驼峰中间靠resultMap翻译不要试图用Mybatis的mapUnderscoreToCamelCasetrue配置自动转换这会在复杂查询如多表JOIN中导致字段映射错乱。明确写出result propertycreatedTime columncreated_time/虽然多写几行但换来的是100%的可预测性。军规3Param注解不是可选项是必选项即使方法只有一个参数也必须加Param(id)。因为Mybatis 3.4版本中单参数方法在字节码层面丢失了参数名不加注解会导致#{id}无法解析。这个坑让我在客户现场调试了2小时最后发现是JDK编译参数-parameters未开启。军规4application.yml中的mybatis配置项必须顶格写不能缩进YAML对空格极其敏感。mybatis:前面多一个空格整个配置就失效。我见过最离谱的案例配置写成mybatis:两个空格导致mapper-locations不生效日志里连Mapped statement都不打印。用VS Code的YAML插件开启“Indentation Guide”让空格无所遁形。军规5实体类必须实现Serializable接口且添加private static final long serialVersionUID 1L;这不是为了序列化存储而是为了Mybatis的ResultHandler和二级缓存机制。某次在分布式环境下不同节点的JVM加载同一实体类时因serialVersionUID不一致导致反序列化失败缓存命中率暴跌至5%。军规6select标签必须指定resultMap或resultType二者不可兼得我曾在一个项目中误写select idgetUser resultMapUserResultMap resultTypeUserMybatis静默忽略resultType但resultMap未定义导致返回null。Mybatis的容错机制有时过于宽容反而掩盖了错误。军规7永远在Transactional方法内用try-catch包裹业务代码并在catch块中显式throw new RuntimeException(e)不要用catch(Exception e)吞掉异常也不要return false。Spring的事务切面只捕获
