SpringBoot整合MySQL与MyBatis实战指南

1. 项目概述作为一名Java开发者我经常需要在本地开发环境中搭建SpringBoot项目并连接MySQL数据库。最近在指导新人时发现虽然网上有很多相关教程但大多比较零散缺乏系统性和实操细节。本文将完整记录从零开始搭建SpringBoot项目并连接MySQL数据库的全过程包含我在实际开发中积累的经验技巧。这个教程适合以下人群刚接触SpringBoot和MySQL的Java开发者需要快速搭建本地开发环境的程序员想了解MyBatis和SpringBoot整合的初学者2. 环境准备与数据库创建2.1 开发环境要求在开始之前请确保你的开发环境满足以下要求JDK 17或更高版本推荐使用OpenJDKMySQL 8.0社区版即可IntelliJ IDEA或Eclipse IDEMaven 3.6提示建议使用Docker安装MySQL可以避免很多环境配置问题。如果使用原生安装记得配置好环境变量。2.2 创建MySQL数据库首先我们需要在本地MySQL中创建数据库和表。以下是详细步骤登录MySQL命令行mysql -u root -p创建数据库这里以blog_system为例CREATE DATABASE blog_system CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;选择刚创建的数据库USE blog_system;创建用户表CREATE TABLE users ( id INT AUTO_INCREMENT PRIMARY KEY, username VARCHAR(50) NOT NULL UNIQUE, password VARCHAR(100) NOT NULL, email VARCHAR(100) NOT NULL UNIQUE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP );经验分享utf8mb4字符集支持完整的Unicode字符包括emoji比传统的utf8更推荐使用。TIMESTAMP字段的自动更新功能可以省去手动维护更新时间的工作。3. SpringBoot项目初始化3.1 创建SpringBoot项目使用Spring Initializr创建项目以IntelliJ IDEA为例选择File → New → Project → Spring Initializr配置项目基本信息Group: com.exampleArtifact: blog-systemType: MavenJava: 17添加依赖Spring WebMyBatis FrameworkMySQL DriverLombok推荐3.2 项目结构说明创建完成后项目基本结构如下blog-system ├── src/main/java │ └── com/example/blog │ ├── BlogApplication.java │ ├── config │ ├── controller │ ├── model │ ├── mapper │ └── service ├── src/main/resources │ ├── application.properties │ └── mapper └── src/test注意这是Maven标准结构不要随意修改目录位置否则可能导致构建失败。4. 数据库连接配置4.1 配置数据库连接在application.properties中添加以下配置# 数据库连接配置 spring.datasource.urljdbc:mysql://localhost:3306/blog_system?useUnicodetruecharacterEncodingUTF-8useSSLfalseserverTimezoneAsia/Shanghai spring.datasource.usernameroot spring.datasource.passwordyourpassword spring.datasource.driver-class-namecom.mysql.cj.jdbc.Driver # MyBatis配置 mybatis.mapper-locationsclasspath:mapper/*.xml mybatis.type-aliases-packagecom.example.blog.model重要提示useSSLfalse仅适用于开发环境生产环境应该使用true并配置证书。serverTimezone设置可以避免时区问题。4.2 测试数据库连接创建一个简单的测试类验证连接是否成功SpringBootTest class DatabaseConnectionTest { Autowired private DataSource dataSource; Test void testConnection() throws SQLException { try (Connection conn dataSource.getConnection()) { assertNotNull(conn); System.out.println(数据库连接成功 conn.getMetaData().getDatabaseProductName()); } } }5. 模型层与Mapper实现5.1 创建实体类使用Lombok简化代码Data NoArgsConstructor AllArgsConstructor TableName(users) public class User { TableId(type IdType.AUTO) private Integer id; private String username; private String password; private String email; TableField(fill FieldFill.INSERT) private LocalDateTime createdAt; TableField(fill FieldFill.INSERT_UPDATE) private LocalDateTime updatedAt; }技巧TableField的fill属性可以自动填充字段值需要在配置类中配置MetaObjectHandler。5.2 创建Mapper接口基础Mapper接口Mapper public interface UserMapper extends BaseMapperUser { Select(SELECT * FROM users WHERE username #{username}) User selectByUsername(Param(username) String username); Select(SELECT EXISTS(SELECT 1 FROM users WHERE username #{username})) boolean existsByUsername(Param(username) String username); }5.3 XML映射文件在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.blog.mapper.UserMapper resultMap idBaseResultMap typecom.example.blog.model.User id columnid propertyid / result columnusername propertyusername / result columnpassword propertypassword / result columnemail propertyemail / result columncreated_at propertycreatedAt / result columnupdated_at propertyupdatedAt / /resultMap sql idBase_Column_List id, username, password, email, created_at, updated_at /sql select idselectByEmail resultMapBaseResultMap SELECT include refidBase_Column_List / FROM users WHERE email #{email} /select /mapper6. 业务逻辑与控制器实现6.1 创建Service层用户服务接口和实现public interface UserService { User getUserById(Integer id); User getUserByUsername(String username); boolean createUser(User user); } Service RequiredArgsConstructor public class UserServiceImpl implements UserService { private final UserMapper userMapper; Override public User getUserById(Integer id) { return userMapper.selectById(id); } Override public User getUserByUsername(String username) { return userMapper.selectByUsername(username); } Override Transactional public boolean createUser(User user) { if (userMapper.existsByUsername(user.getUsername())) { throw new RuntimeException(用户名已存在); } return userMapper.insert(user) 0; } }6.2 创建Controller用户控制器RestController RequestMapping(/api/users) RequiredArgsConstructor public class UserController { private final UserService userService; GetMapping(/{id}) public ResponseEntityUser getUserById(PathVariable Integer id) { return ResponseEntity.ok(userService.getUserById(id)); } PostMapping public ResponseEntityVoid createUser(RequestBody User user) { userService.createUser(user); return ResponseEntity.status(HttpStatus.CREATED).build(); } }7. 常见问题与解决方案7.1 连接失败问题排查Access denied for user检查用户名密码是否正确确认用户有访问该数据库的权限尝试在MySQL命令行中直接连接测试Communications link failure检查MySQL服务是否启动确认端口号是否正确默认3306检查防火墙设置是否阻止了连接7.2 MyBatis映射问题Invalid bound statement (not found)检查mapper.xml文件是否在正确目录下确认application.properties中配置了mapper-locations检查namespace是否与Mapper接口全限定名一致字段映射失败确认数据库字段名与实体类属性名一致使用TableField注解指定映射关系检查是否有getter/setter方法7.3 性能优化建议使用连接池如HikariCPspring.datasource.hikari.maximum-pool-size10 spring.datasource.hikari.minimum-idle5启用MyBatis二级缓存CacheNamespace public interface UserMapper extends BaseMapperUser { // ... }批量操作使用批处理模式Transactional public void batchInsert(ListUser users) { users.forEach(userMapper::insert); }8. 进阶配置与最佳实践8.1 多环境配置创建不同环境的配置文件application-dev.properties开发环境application-test.properties测试环境application-prod.properties生产环境通过启动参数指定环境java -jar blog-system.jar --spring.profiles.activeprod8.2 数据库迁移工具推荐使用Flyway管理数据库变更添加依赖dependency groupIdorg.flywaydb/groupId artifactIdflyway-core/artifactId /dependency创建迁移脚本src/main/resources/db/migration/V1__Create_user_table.sql8.3 监控与健康检查添加Spring Boot Actuatormanagement.endpoints.web.exposure.includehealth,info,metrics management.endpoint.health.show-detailsalways访问/actuator/health可以查看数据库连接状态。在实际项目中我发现合理的项目结构和清晰的层次划分可以大幅提高开发效率。特别是在团队协作时统一的编码规范和技术选型非常重要。对于数据库操作建议尽量使用MyBatis-Plus提供的基础方法减少手写SQL的机会这样可以降低出错概率。