Spring Boot + MySQL + MyBatis：一次从零到一的搭建完整搭建记录

凌晨两点，我盯着屏幕上的搭建红色报错——数据库连接超时。这不是搭建第一次了，但每次排查到最后，搭建多半是搭建配置文件的坑。今天直接把搭建过程完整写下来，搭建从建工程到跑通第一个查询，搭建每一步都踩过雷，搭建你照着做能省至少半天时间。搭建

先说工具版本。搭建JDK 1.8，搭建Spring Boot 2.7.14，搭建MySQL 8.0.33，搭建MyBatis 3.5.13。搭建别用太新的搭建版本，网上资料少，出了问题难搜。我见过有人用Spring Boot 3.x配MyBatis，结果starter包名都变了，折腾一晚上没跑通。

第一步，去Spring Initializr生成基础工程。选Web、MySQL Driver、MyBatis Framework这三个依赖。注意，这里别选JDBC API，MyBatis自己会处理。生成后解压，用IDEA打开，等Maven下载依赖——这个过程可能要几分钟，取决于你的网速。

接着配置application.yml。这是最容易出错的地方。我习惯把连接信息放这里，而不是用properties文件，因为YAML缩进更清晰。核心配置就这几行：

spring: datasource: url: jdbc:mysql://localhost:3306/test_db?useSSL=false&serverTimezone=Asia/Shanghai username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.entity

URL里的serverTimezone必须加，否则会报时区错误。useSSL=false是为了避免本地连接时的证书警告。这两个参数我每次写都要翻笔记，今天直接贴这儿了。

数据库这边，先建库建表。用Navicat或者命令行都行，执行几句简单的SQL：

CREATE DATABASE test_db DEFAULT CHARACTER SET utf8mb4; USE test_db; CREATE TABLE user ( id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(50) NOT NULL, age INT DEFAULT 0 );

utf8mb4比utf8好，能存emoji和生僻字。表结构简单点，先跑通最重要。

实体类User.java，字段对应表结构，加个Lombok的@Data注解省去写getter/setter。如果你没用Lombok，就手动写，别偷懒。

Mapper接口写两个方法——findById和insert。接口就放com.example.mapper包下。然后重点来了，XML文件必须放在resources/mapper目录，文件名和接口名一致：UserMapper.xml。namespace写接口全路径，resultType写实体类全路径。我最初犯过错，把XML放java包里，结果扫描不到，报绑定异常。折腾两小时才反应过来是路径问题。

Service层和Controller层简单写。Controller暴露一个GET接口返回用户，一个POST接口新增用户。启动类不用改，Spring Boot自动扫描同包及子包的组件。

跑起来后，用Postman或浏览器访问http://localhost:8080/user/1。第一次我遇到404，检查发现Controller的@RequestMapping路径写错了，多加了个斜杠。第二次遇到500，看日志是SQL语句里的表名写错。这些低级错误，多试几次就记住了。

整个搭建过程其实不超过半小时，但前提是版本匹配、路径正确、配置无遗漏。如果中途报错，优先看控制台第一行异常，别被后面的堆栈信息带偏。有一次我盯着NoSuchBeanDefinitionException看了十分钟，最后发现是Mapper接口忘了加@Mapper注解——这个注解不加也能扫到，前提是在启动类上加@MapperScan。两种方式选一种就行，我推荐@MapperScan，省得每个接口都加注解。

数据库连接池默认用HikariCP，性能不错，不用额外配置。如果连接数多，可以在配置里加maximum-pool-size参数，默认10够用。至于MyBatis的驼峰映射，如果数据库字段用下划线，实体类用驼峰，记得在配置里加map-underscore-to-camel-case: true。这个参数我漏过好几次，查出来的对象属性全是null。

最后说个调试技巧。在application.yml里加logging.level.com.example.mapper=debug，就能在控制台看到MyBatis执行的SQL语句和参数。排查问题的时候这个开关特别有用，比猜来猜去强多了。

跑通第一个接口后，后面的分页、动态SQL、多表查询都是在这个基础上加。基础打牢了，后面就不会因为环境问题卡壳。如果你照着做还报错，把报错信息直接复制到搜索引擎，多半能搜到解决方案——毕竟这些坑，前人早就踩过了。