1. 项目概述：为什么数据源配置是Mybatis-Plus的基石

搞Java后端开发，尤其是和数据库打交道的，Mybatis-Plus（简称MP）绝对是绕不开的利器。它简化了Mybatis的很多操作，让CRUD变得像喝水一样简单。但不知道你有没有发现，无论是官方文档还是很多入门教程，往往把重点放在了Wrapper、Service、分页这些“上层建筑”上，而对于最底层、最根本的数据源配置，尤其是稍微复杂点的多数据源场景，要么一笔带过，要么语焉不详。这就导致很多新手在项目跑起来后，一旦遇到多库读写、分库分表的前期准备，或者仅仅是换个连接池，就一头雾水，到处找补丁。

今天，我就以一个踩过无数坑的老兵身份，来和你深挖一下Mybatis-Plus的数据源配置。这不仅仅是把spring.datasource.url写进application.yml那么简单。从单数据源的内功心法（连接池选型与参数调优），到多数据源的实战剑招（动态切换、事务管理），再到那些官方文档没明说、但线上项目必须考虑的“潜规则”，我都会结合真实的生产案例，给你掰开揉碎了讲清楚。无论你是刚接触MP想打好基础，还是正在为多数据源架构头疼，这篇文章都能给你一套可直接复制、并根据自己业务微调的完整解决方案。

2. 核心思路：从“能用”到“好用”的数据源设计哲学

在动手写配置之前，我们必须先统一思想：配置数据源的目标是什么？仅仅是让程序能连上数据库吗？不，那只是“能用”。我们的目标是“好用”，即在稳定、高效、可维护的前提下，满足业务需求。这决定了我们接下来的每一个技术选型和参数设置。

2.1 单数据源：不只是连接字符串

一个单数据源的配置，通常包含以下几个核心维度：

1. 连接池选型：这是性能的基石。是选择老当益壮的HikariCP，历史悠久但配置繁琐的Druid，还是其他？这需要根据项目特点和团队熟悉度来决定。
2. 基础连接参数：url,username,password,driver-class-name。这是入门课。
3. 连接池调优参数：这才是区分新手和老手的关键。比如最大连接数、最小空闲连接、连接超时时间、验证查询等，这些参数直接关系到应用在高并发下的表现和稳定性。
4. Mybatis-Plus自身配置：比如mapper-locations（XML文件位置）、type-aliases-package（实体类别名包）、configuration.map-underscore-to-camel-case（是否开启驼峰映射）等。这些配置决定了MP如何与Mybatis协同工作。

2.2 多数据源：从静态配置到动态路由

当业务需要同时操作多个数据库时，问题就复杂了。多数据源不是简单地在配置文件里多写几个datasource配置就完事了。它本质上是一个路由问题。我们需要思考：

• 静态多数据源：在启动时就确定好每个Mapper/Service使用哪个固定的数据源。适用于数据库角色明确、很少变化的场景，如一个主库用于写，多个只读从库用于读。
• 动态多数据源：在运行时，根据当前执行的SQL方法、甚至是传入的参数，动态决定使用哪个数据源。这更灵活，常用于复杂的分库分表、多租户等场景。

无论静态还是动态，多数据源都会引入两个核心挑战：

1. 事务管理：在单个数据源下，Spring的@Transactional注解工作得很好。但在多数据源下，一个事务可能需要跨多个数据库，这就涉及分布式事务（如Seata）的范畴，复杂度陡增。很多时候，我们退而求其次，保证单个服务内、单个数据源下的事务，而通过业务设计或最终一致性来解决跨库问题。
2. 上下文传递：如何将数据源的选择逻辑（比如根据当前租户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?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true 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: true

3.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.active=prod来激活生产环境配置。

4. 多数据源配置实战：静态与动态方案

当你的应用需要同时操作两个或以上独立的数据库时，多数据源配置就派上用场了。比如，一个数据库存放核心业务数据，另一个数据库存放日志或报表数据。下面我介绍两种最常用的方案。

4.1 方案一：基于@DS注解的静态多数据源（推荐）

这是Mybatis-Plus生态中dynamic-datasource-spring-boot-starter组件提供的方案，也是目前最流行、最易用的方式。它的核心思想是：通过一个注解来切换数据源。

第一步：引入依赖

<dependency> <groupId>com.baomidou</groupId> <artifactId>dynamic-datasource-spring-boot-starter</artifactId> <version>3.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 ServiceImpl<UserMapper, User> implements UserService { // 这个类默认使用主数据源（master） @Override public User getById(Long id) { // 这个方法使用主数据源 return baseMapper.selectById(id); } @DS("slave1") // 指定这个方法使用slave1数据源 @Override public List<User> getAllUsers() { // 这是一个读操作，我们指定它走从库 return baseMapper.selectList(null); } } @DS("log") // 这个类下的所有方法，默认都使用log数据源 @Service public class LogServiceImpl extends ServiceImpl<LogMapper, 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 Bean

@Configuration 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(); } }

第三步：创建数据源上下文持有器（基于ThreadLocal）

public class DataSourceContextHolder { // 使用ThreadLocal保证线程安全 private static final ThreadLocal<String> 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(); } }

第四步：将多个数据源注入到动态数据源中，并设置为Primary

@Configuration @EnableTransactionManagement // 启用注解事务 public class DynamicDataSourceConfig { @Bean @Primary // 必须声明为Primary，让Spring知道这是主要的数据源 public DataSource dynamicDataSource( @Qualifier("masterDataSource") DataSource master, @Qualifier("slaveDataSource") DataSource slave) { Map<Object, 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 Server（TC），应用也需要引入客户端依赖和配置。
• 对业务代码有侵入：需要添加@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访问？

监控与告警关键指标：

1. 活跃连接数（Active Connections）：接近maximum-pool-size时告警，可能意味着连接池大小不足或存在连接泄漏。
2. 空闲连接数（Idle Connections）：长期为0可能意味着连接池过小；长期与活跃连接数持平可能意味着连接未被正确释放。
3. 等待获取连接的线程数（Threads Awaiting Connection）：如果这个数持续大于0，说明应用在等待数据库连接，是性能瓶颈的明显信号。
4. 连接创建时间（Connection Creation Time）：创建新连接耗时过长可能表示数据库或网络有问题。
5. SQL执行耗时与次数：监控慢SQL和高频SQL。这是Druid的强项，HikariCP需结合Actuator、Micrometer和外部监控系统（如Prometheus+Grafana）来实现。

对于HikariCP，可以通过Spring Boot Actuator的/actuator/metrics/hikaricp.connections端点来暴露指标，然后由Prometheus抓取。对于Druid，其内置的监控页面/druid/index.html就非常直观。

最后，关于数据源配置，我再分享一个真实案例的教训：我们有一个服务，在流量洪峰时突然出现大量数据库连接超时。排查后发现，是某个背景任务在执行一个非常慢的报表查询，这个查询耗时几分钟，占用了连接池里大量连接，导致处理用户请求的线程无法获取连接。解决方案不是一味调大连接池，而是：1）将那个慢查询移到专门的报表数据库或数仓；2）在业务代码中，为这种耗时长的查询使用单独的数据源和连接池，与核心业务的连接池隔离，避免相互影响。这个案例告诉我们，数据源配置不仅是连接参数，更是资源隔离和架构设计的一部分。