1. 项目概述为什么数据源配置是Mybatis-Plus的基石搞Java后端开发尤其是和数据库打交道的Mybatis-Plus简称MP绝对是绕不开的利器。它简化了Mybatis的很多操作让CRUD变得像喝水一样简单。但不知道你有没有发现无论是官方文档还是很多入门教程往往把重点放在了Wrapper、Service、分页这些“上层建筑”上而对于最底层、最根本的数据源配置尤其是稍微复杂点的多数据源场景要么一笔带过要么语焉不详。这就导致很多新手在项目跑起来后一旦遇到多库读写、分库分表的前期准备或者仅仅是换个连接池就一头雾水到处找补丁。今天我就以一个踩过无数坑的老兵身份来和你深挖一下Mybatis-Plus的数据源配置。这不仅仅是把spring.datasource.url写进application.yml那么简单。从单数据源的内功心法连接池选型与参数调优到多数据源的实战剑招动态切换、事务管理再到那些官方文档没明说、但线上项目必须考虑的“潜规则”我都会结合真实的生产案例给你掰开揉碎了讲清楚。无论你是刚接触MP想打好基础还是正在为多数据源架构头疼这篇文章都能给你一套可直接复制、并根据自己业务微调的完整解决方案。2. 核心思路从“能用”到“好用”的数据源设计哲学在动手写配置之前我们必须先统一思想配置数据源的目标是什么仅仅是让程序能连上数据库吗不那只是“能用”。我们的目标是“好用”即在稳定、高效、可维护的前提下满足业务需求。这决定了我们接下来的每一个技术选型和参数设置。2.1 单数据源不只是连接字符串一个单数据源的配置通常包含以下几个核心维度连接池选型这是性能的基石。是选择老当益壮的HikariCP历史悠久但配置繁琐的Druid还是其他这需要根据项目特点和团队熟悉度来决定。基础连接参数url,username,password,driver-class-name。这是入门课。连接池调优参数这才是区分新手和老手的关键。比如最大连接数、最小空闲连接、连接超时时间、验证查询等这些参数直接关系到应用在高并发下的表现和稳定性。Mybatis-Plus自身配置比如mapper-locationsXML文件位置、type-aliases-package实体类别名包、configuration.map-underscore-to-camel-case是否开启驼峰映射等。这些配置决定了MP如何与Mybatis协同工作。2.2 多数据源从静态配置到动态路由当业务需要同时操作多个数据库时问题就复杂了。多数据源不是简单地在配置文件里多写几个datasource配置就完事了。它本质上是一个路由问题。我们需要思考静态多数据源在启动时就确定好每个Mapper/Service使用哪个固定的数据源。适用于数据库角色明确、很少变化的场景如一个主库用于写多个只读从库用于读。动态多数据源在运行时根据当前执行的SQL方法、甚至是传入的参数动态决定使用哪个数据源。这更灵活常用于复杂的分库分表、多租户等场景。无论静态还是动态多数据源都会引入两个核心挑战事务管理在单个数据源下Spring的Transactional注解工作得很好。但在多数据源下一个事务可能需要跨多个数据库这就涉及分布式事务如Seata的范畴复杂度陡增。很多时候我们退而求其次保证单个服务内、单个数据源下的事务而通过业务设计或最终一致性来解决跨库问题。上下文传递如何将数据源的选择逻辑比如根据当前租户ID优雅地传递到执行SQL的那一层通常我们会使用ThreadLocal来保存当前线程的数据源标识。理解了这些底层逻辑我们再看具体的配置就不会觉得是一堆莫名其妙的代码了。3. 单数据源配置详解与最佳实践让我们从最基础的开始打造一个健壮的单数据源配置。这里我以Spring Boot Mybatis-Plus 3.x 为例使用目前Spring Boot官方默认推荐的HikariCP连接池。3.1 基础YAML配置与参数解读首先在application.yml中配置spring: datasource: # 基础连接信息 url: jdbc:mysql://localhost:3306/my_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue username: root password: your_strong_password driver-class-name: com.mysql.cj.jdbc.Driver # HikariCP 连接池配置 (关键!) hikari: # 连接池名称便于监控 pool-name: MyAppHikariPool # 连接池中允许的最大连接数。默认10。计算公式connections ((core_count * 2) effective_spindle_count) # 对于普通Web应用可先设置为 (CPU核数 * 2 磁盘数)。例如4核服务器可设为10。 maximum-pool-size: 20 # 连接池中维护的最小空闲连接数。不建议设置HikariCP推荐使用固定大小的池。 # minimum-idle: 10 # 连接最大存活时间毫秒。超过此时间连接将被标记为过期并回收。默认30分钟(1800000)。建议设置为比数据库的wait_timeout少几分钟。 max-lifetime: 1740000 # 29分钟略小于MySQL默认的wait_timeout(28800秒) # 连接超时时间毫秒。客户端等待连接池分配连接的最大时长超时则抛SQLException。默认30秒(30000)。 connection-timeout: 30000 # 连接空闲超时时间毫秒。一个连接空闲多久后会被释放。默认10分钟(600000)。仅当minimum-idle小于maximum-pool-size时生效。 # idle-timeout: 600000 # 连接测试查询。用于验证从池中取出的连接是否有效。对于MySQL建议使用SELECT 1。 connection-test-query: SELECT 1 # 控制从池中获取连接时是否先进行有效性检查。建议在生产环境设为true。 connection-init-sql: SELECT 1 # 是否自动提交事务。默认true。建议根据业务在代码中显式控制此处可设为false。 auto-commit: false # Mybatis-Plus 配置 mybatis-plus: # mapper.xml文件位置如果SQL写在XML里此项必须配置 mapper-locations: classpath*:/mapper/**/*.xml # 实体类所在包配置后Mapper XML中可以直接写类名不用写全限定名 type-aliases-package: com.example.myapp.entity global-config: db-config: # 全局逻辑删除字段名若使用逻辑删除功能 logic-delete-field: is_deleted # 逻辑已删除值(默认为 1) logic-delete-value: 1 # 逻辑未删除值(默认为 0) logic-not-delete-value: 0 configuration: # 开启驼峰命名自动映射。数据库字段 user_name 会自动映射到实体属性 userName map-underscore-to-camel-case: true # 打印SQL日志到控制台开发环境使用 log-impl: org.apache.ibatis.logging.stdout.StdOutImpl注意上面的max-lifetime设置略小于数据库的wait_timeout非常重要。如果连接在数据库侧因超时被断开而连接池不知道当应用再次使用这个“僵尸连接”时就会报错。设置稍短的生命周期让连接池主动回收重建可以避免这个问题。3.2 为什么选择HikariCP连接池选型心得Spring Boot 2.x开始默认使用HikariCP这不是没有道理的。在我经历过的项目中Druid和HikariCP都用得很多简单对比一下HikariCP以“快”和“简单”著称。代码量小并发性能极高是“约定大于配置”的典范。它的监控功能需要通过JMX或Spring Boot Actuator来暴露不如Druid内置的监控页面直观但对于微服务架构和云原生环境这种“轻量”反而是优势。Druid功能强大除了连接池还内置了SQL监控、防火墙、StatViewServlet等一整套监控和防护功能。在需要深度监控SQL执行情况、防止SQL注入的场景下非常有用。但配置项繁多相对重一些。我的选择建议是如果你的项目是全新的Spring Boot 2.x/3.x项目对监控要求不是极度细致追求极简和性能直接用HikariCP配合Actuator和Prometheus做监控。如果你需要强大的、开箱即用的SQL监控和防火墙功能或者项目是从老系统迁移过来一直在用Druid那么选择Druid。但要注意Druid的Spring Boot Starter版本和Mybatis-Plus可能存在一些兼容性配置需要仔细调试。这里也给出一个Druid的快速配置片段作为参考spring: datasource: type: com.alibaba.druid.pool.DruidDataSource druid: url: jdbc:mysql://localhost:3306/my_db username: root password: your_strong_password driver-class-name: com.mysql.cj.jdbc.Driver initial-size: 5 min-idle: 5 max-active: 20 # 监控统计用的filter如果不配置druid-sql无法监控 filters: stat,wall # 启用Web监控页面访问 /druid/index.html stat-view-servlet: enabled: true login-username: admin login-password: admin # 配置监控统计拦截的filters去掉后监控界面sql无法统计 web-stat-filter: enabled: true3.3 进阶配置应对生产环境挑战基础配置能让项目跑起来但要应对生产环境的流量波动和故障还需要一些进阶配置。1. 故障转移与读写分离代理在实际生产中我们很少直接连接单一的数据库IP。通常会使用数据库中间件如MyCat、ShardingSphere-Proxy或云服务商提供的数据库代理如AWS RDS Proxy、阿里云RDS读写分离地址。这时url配置的就是代理的地址。代理层会自动处理主从切换、读写分离、故障转移等。应用层配置无需改变但需要确保连接池的**验证查询connection-test-query**足够轻量避免给代理层造成压力。2. 密码加密明文密码写在配置文件里是安全大忌。可以使用Jasypt等库进行加密配置如下spring: datasource: password: ENC(加密后的密文字符串) # 使用jasypt加密后的格式然后在启动参数或环境变量中传入加密密钥。这样即使配置文件泄露密码也不易被破解。3. 多环境配置使用Spring Profiles来区分开发、测试、生产环境。# application-dev.yml spring: datasource: url: jdbc:mysql://dev-db:3306/my_db hikari: maximum-pool-size: 10 # application-prod.yml spring: datasource: url: jdbc:mysql://prod-cluster.proxy.rds.aliyuncs.com:3306/my_db hikari: maximum-pool-size: 50 max-lifetime: 1740000通过启动命令--spring.profiles.activeprod来激活生产环境配置。4. 多数据源配置实战静态与动态方案当你的应用需要同时操作两个或以上独立的数据库时多数据源配置就派上用场了。比如一个数据库存放核心业务数据另一个数据库存放日志或报表数据。下面我介绍两种最常用的方案。4.1 方案一基于DS注解的静态多数据源推荐这是Mybatis-Plus生态中dynamic-datasource-spring-boot-starter组件提供的方案也是目前最流行、最易用的方式。它的核心思想是通过一个注解来切换数据源。第一步引入依赖dependency groupIdcom.baomidou/groupId artifactIddynamic-datasource-spring-boot-starter/artifactId version3.6.1/version !-- 请使用最新版本 -- /dependency第二步配置多个数据源在application.yml中配置从spring.datasource改为spring.datasource.dynamic。spring: datasource: dynamic: primary: master # 设置默认的数据源主数据源默认值为master strict: false # 是否启用严格模式。严格模式下未匹配到指定数据源会报错非严格模式下则使用默认数据源。 datasource: master: # 数据源名称可以自定义这里用master代表主库 url: jdbc:mysql://localhost:3306/master_db username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver hikari: maximum-pool-size: 20 slave1: # 从库1用于读操作 url: jdbc:mysql://localhost:3307/slave_db username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver hikari: maximum-pool-size: 15 connection-timeout: 10000 # 从库连接超时可以设短一点 log: # 日志库 url: jdbc:mysql://localhost:3308/log_db username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver hikari: maximum-pool-size: 5第三步使用DS注解切换数据源这个注解可以用在方法或类上。方法上的注解优先级高于类上的注解。Service public class UserServiceImpl extends ServiceImplUserMapper, User implements UserService { // 这个类默认使用主数据源master Override public User getById(Long id) { // 这个方法使用主数据源 return baseMapper.selectById(id); } DS(slave1) // 指定这个方法使用slave1数据源 Override public ListUser getAllUsers() { // 这是一个读操作我们指定它走从库 return baseMapper.selectList(null); } } DS(log) // 这个类下的所有方法默认都使用log数据源 Service public class LogServiceImpl extends ServiceImplLogMapper, Log implements LogService { Override public void saveOperationLog(Log log) { // 这个方法会自动使用log数据源 baseMapper.insert(log); } DS(master) // 即使类上指定了log这个方法也能单独切换到master public void someSpecialMethod() { // ... } }这个方案的优点非常明显配置简单几乎零侵入通过注解即可优雅切换。易于理解代码即文档一看DS(slave1)就知道这个方法要访问从库。功能完善该组件底层使用ThreadLocal和AOP处理了大多数上下文传递和基础的事务问题注意它不支持跨数据源的分布式事务只支持每个数据源内的事务。实操心得在使用DS注解时务必注意事务的传播行为。Transactional和DS注解一起使用时DS注解必须放在Transactional之前否则数据源切换可能失效。因为AOP的执行顺序是DS切面需要先确定数据源然后事务管理器才能基于这个数据源开启事务。一个常见的写法是将DS注解放在Service类或方法上而将Transactional放在需要事务管理的方法内部如果需要的话。4.2 方案二手动配置多数据源与动态路由如果你需要更精细的控制或者项目框架限制不能引入dynamic-datasource那么可以手动配置。这种方式更底层能让你透彻理解多数据源的原理。第一步手动定义多个DataSource BeanConfiguration public class DataSourceConfig { Bean(name masterDataSource) ConfigurationProperties(prefix spring.datasource.master) // 绑定配置前缀 public DataSource masterDataSource() { return DataSourceBuilder.create().type(HikariDataSource.class).build(); } Bean(name slaveDataSource) ConfigurationProperties(prefix spring.datasource.slave) ConditionalOnProperty(prefix spring.datasource.slave, name enabled, havingValue true) public DataSource slaveDataSource() { return DataSourceBuilder.create().type(HikariDataSource.class).build(); } }对应的application.yml:spring: datasource: master: url: jdbc:mysql://localhost:3306/master_db username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver hikari: maximum-pool-size: 20 slave: enabled: true # 可以通过这个开关控制是否启用从数据源 url: jdbc:mysql://localhost:3307/slave_db username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver hikari: maximum-pool-size: 15第二步创建动态数据源路由类这是核心它决定每次数据库操作使用哪个具体的DataSource。public class DynamicDataSource extends AbstractRoutingDataSource { /** * 决定当前线程使用哪个数据源的key */ Override protected Object determineCurrentLookupKey() { // 从ThreadLocal中获取数据源标识 return DataSourceContextHolder.getDataSourceKey(); } }第三步创建数据源上下文持有器基于ThreadLocalpublic class DataSourceContextHolder { // 使用ThreadLocal保证线程安全 private static final ThreadLocalString CONTEXT_HOLDER new ThreadLocal(); /** * 设置数据源key */ public static void setDataSourceKey(String key) { CONTEXT_HOLDER.set(key); } /** * 获取数据源key */ public static String getDataSourceKey() { return CONTEXT_HOLDER.get(); } /** * 清除数据源key */ public static void clearDataSourceKey() { CONTEXT_HOLDER.remove(); } }第四步将多个数据源注入到动态数据源中并设置为PrimaryConfiguration EnableTransactionManagement // 启用注解事务 public class DynamicDataSourceConfig { Bean Primary // 必须声明为Primary让Spring知道这是主要的数据源 public DataSource dynamicDataSource( Qualifier(masterDataSource) DataSource master, Qualifier(slaveDataSource) DataSource slave) { MapObject, Object targetDataSources new HashMap(); targetDataSources.put(master, master); targetDataSources.put(slave, slave); DynamicDataSource dynamicDataSource new DynamicDataSource(); dynamicDataSource.setDefaultTargetDataSource(master); // 设置默认数据源 dynamicDataSource.setTargetDataSources(targetDataSources); // 设置目标数据源Map dynamicDataSource.afterPropertiesSet(); // 初始化 return dynamicDataSource; } // 需要为动态数据源配置单独的事务管理器 Bean public PlatformTransactionManager transactionManager(DataSource dynamicDataSource) { return new DataSourceTransactionManager(dynamicDataSource); } }第五步配置Mybatis-Plus使用动态数据源Configuration MapperScan(basePackages com.example.mapper, sqlSessionTemplateRef dynamicSqlSessionTemplate) public class MybatisPlusConfig { Bean public SqlSessionFactory sqlSessionFactory(DataSource dynamicDataSource) throws Exception { MybatisSqlSessionFactoryBean factory new MybatisSqlSessionFactoryBean(); factory.setDataSource(dynamicDataSource); // 其他配置如mapperLocation, typeAliases等 factory.setMapperLocations(new PathMatchingResourcePatternResolver().getResources(classpath*:/mapper/**/*.xml)); return factory.getObject(); } Bean public SqlSessionTemplate dynamicSqlSessionTemplate(SqlSessionFactory sqlSessionFactory) { return new SqlSessionTemplate(sqlSessionFactory); } }第六步在Service层使用AOP或手动切换你可以写一个自定义注解和AOP切面在方法执行前根据注解值调用DataSourceContextHolder.setDataSourceKey(slave)。或者在需要切换数据源的地方手动调用Service public class SomeService { public void queryFromSlave() { try { DataSourceContextHolder.setDataSourceKey(slave); // ... 执行你的数据库操作 } finally { // 非常重要一定要在finally块中清理否则可能导致后续操作数据源错乱 DataSourceContextHolder.clearDataSourceKey(); } } }手动配置方案的优缺点优点完全掌控灵活性极高可以实现非常复杂的路由逻辑比如根据参数中的用户ID哈希决定分库。缺点代码侵入性强需要自己处理事务管理、资源清理等问题容易出错。避坑指南在手动方案中ThreadLocal的清理是重中之重。务必在try...finally块中或在AOP的After通知里调用clearDataSourceKey()。否则一个线程在处理完一个请求后如果线程被放回线程池复用其ThreadLocal中残留的数据源key会导致下一个请求用错数据源造成灾难性后果。这也是为什么推荐使用成熟的dynamic-datasource组件的原因之一它帮你处理了这些底层细节。5. 多数据源下的“拦路虎”事务管理难题与解决思路这是多数据源配置中最棘手的部分。Spring的Transactional注解默认是基于单个DataSource和对应的PlatformTransactionManager工作的。当我们有多个数据源时就面临两个选择1. 每个数据源独立事务非分布式事务这是dynamic-datasource-spring-boot-starter组件采用的方式也是大多数场景下的务实选择。它通过AOP在进入Transactional标记的方法前根据DS注解确定数据源然后使用该数据源对应的事务管理器开启事务。这意味着一个事务内只能操作一个数据源。如果你在一个Transactional方法里既调用了DS(master)的Mapper方法又调用了DS(slave)的Mapper方法那么只有第一个被调用的数据源会生效后续的切换可能会失效或导致错误。无法保证跨数据源的原子性。如果先更新主库成功再更新日志库时失败主库的更新不会回滚。因为这是两个独立的事务。解决方案通过业务设计规避。例如将日志记录改为异步发到消息队列或者接受最终一致性。对于强一致性的跨库更新就需要引入分布式事务。2. 分布式事务如果需要保证跨多个数据库的ACID特性就必须引入分布式事务管理器如Seata。Seata提供了AT、TCC、SAGA等模式。以最常用的AT模式为例其原理是“两阶段提交”的优化第一阶段执行业务SQL提交本地事务并生成回滚日志undo_log。第二阶段如果全局事务成功则异步删除回滚日志如果失败则根据回滚日志进行补偿。集成Seata后你只需要在全局事务的入口方法上加上GlobalTransactional注解Seata框架会帮你协调多个数据源的事务。Service public class BusinessService { Autowired private OrderService orderService; // 操作order_db Autowired private AccountService accountService; // 操作account_db GlobalTransactional // 开启Seata全局分布式事务 public void placeOrder(Order order) { // 1. 在order_db创建订单 orderService.create(order); // 2. 在account_db扣减余额 accountService.deduct(order.getUserId(), order.getAmount()); // 如果第二步失败第一步创建的订单会被Seata自动回滚 } }使用分布式事务的代价性能损耗两阶段提交、全局锁、日志记录都会带来额外的开销。复杂度提升需要部署和维护Seata ServerTC应用也需要引入客户端依赖和配置。对业务代码有侵入需要添加GlobalTransactional注解。我的经验是能不用分布式事务就尽量不要用。99%的业务场景都可以通过“最终一致性”来解决。比如上面的下单扣款例子可以拆解为1在订单库创建状态为“待支付”的订单2发送一个“扣款”消息到消息队列3账户服务消费消息扣款成功后发送“扣款成功”消息4订单服务消费消息将订单状态更新为“已支付”。任何一个步骤失败都有对应的补偿机制如重试、人工对账。这套方案虽然设计起来复杂一些但系统的整体可用性和性能会好很多。6. 生产环境配置清单与监控告警配置好了不是终点让它在生产环境稳定运行才是。这里给你一份检查清单和监控建议。配置检查清单[ ]连接池参数maximum-pool-size是否根据实际负载设置max-lifetime是否小于数据库的wait_timeout[ ]连接验证是否配置了connection-test-query或validation-query生产环境建议开启。[ ]密码加密数据库密码是否已加密[ ]多环境隔离开发、测试、生产的配置是否已通过Profiles严格分离[ ]超时设置connection-timeout、socket-timeout在JDBC URL中设置是否合理避免因网络波动导致线程长时间阻塞。[ ]防火墙与白名单数据库的安全组或防火墙是否只允许应用服务器的IP访问监控与告警关键指标活跃连接数Active Connections接近maximum-pool-size时告警可能意味着连接池大小不足或存在连接泄漏。空闲连接数Idle Connections长期为0可能意味着连接池过小长期与活跃连接数持平可能意味着连接未被正确释放。等待获取连接的线程数Threads Awaiting Connection如果这个数持续大于0说明应用在等待数据库连接是性能瓶颈的明显信号。连接创建时间Connection Creation Time创建新连接耗时过长可能表示数据库或网络有问题。SQL执行耗时与次数监控慢SQL和高频SQL。这是Druid的强项HikariCP需结合Actuator、Micrometer和外部监控系统如PrometheusGrafana来实现。对于HikariCP可以通过Spring Boot Actuator的/actuator/metrics/hikaricp.connections端点来暴露指标然后由Prometheus抓取。对于Druid其内置的监控页面/druid/index.html就非常直观。最后关于数据源配置我再分享一个真实案例的教训我们有一个服务在流量洪峰时突然出现大量数据库连接超时。排查后发现是某个背景任务在执行一个非常慢的报表查询这个查询耗时几分钟占用了连接池里大量连接导致处理用户请求的线程无法获取连接。解决方案不是一味调大连接池而是1将那个慢查询移到专门的报表数据库或数仓2在业务代码中为这种耗时长的查询使用单独的数据源和连接池与核心业务的连接池隔离避免相互影响。这个案例告诉我们数据源配置不仅是连接参数更是资源隔离和架构设计的一部分。