企业官网建设流程全解析

1. 这个问题不是“找不到Mapper”，而是“找错了地方”——多数据源场景下MyBatis命名空间的隐性错位

你刚在Spring Boot项目里配完两个数据源，一个连MySQL主库，一个连PostgreSQL报表库，Mapper接口写得清清楚楚，XML文件也放在resources/mapper目录下，namespace也照着接口全限定名写了，可一跑就报org.apache.ibatis.binding.BindingException: Invalid bound statement (not found)。别急着删缓存、重启IDEA、重写XML——这根本不是路径或拼写问题，而是MyBatis在多数据源环境下，对“namespace”的解析逻辑被悄悄劫持了。

我去年帮三家金融客户做数据库拆分时，几乎每个项目都卡在这个报错上。它表面是“语句没找到”，实际是MyBatis的MapperRegistry在初始化时，只扫描了当前SqlSessionFactory绑定的MapperScannerConfigurer所配置的basePackage，而你如果用@MapperScan手动指定了包路径，或者用了MapperScannerConfigurer但没指定sqlSessionFactoryBeanName，那另一个数据源的Mapper压根就不会被注册进对应的SqlSessionFactory。更隐蔽的是：当你的Service层调用某个Mapper方法时，Spring AOP代理会把请求路由到默认的SqlSessionFactory（通常是第一个定义的），而这个Session里根本没有你想要的那个namespace——于是报错，但日志里连一句“正在从哪个SqlSessionFactory加载Mapper”都不会打。

核心关键词mybatis、多数据源、namespace在这里不是并列关系，而是因果链：多数据源 → 多SqlSessionFactory → 多套独立的Mapper注册表 → namespace必须与对应SqlSessionFactory严格绑定。所谓“Invalid bound statement”，本质是“你在A工厂里找B工厂注册的语句”。这不是配置遗漏，而是架构层面的映射断裂。尤其当你用Apollo动态刷新数据源配置时，namespace缺失往往发生在热更新后Mapper未重新扫描的间隙——这时候mybatis缓存和mybatis拦截器反而会掩盖真实问题，因为缓存里存的是旧的无效映射。

这个问题适合两类人深挖：一是正在做读写分离、分库分表落地的后端工程师，二是准备mybatis面试题的求职者——因为面试官问“多数据源怎么配”，90%的人能说出AbstractRoutingDataSource，但只有不到10%能讲清namespace在多个SqlSessionFactory间如何精准路由。它不考验你会不会写XML，而考验你是否真正理解MyBatis启动时MapperRegistry和Configuration的初始化时序。接下来我会从设计底层逻辑开始，一层层剥开这个报错背后的四层嵌套陷阱。

2. 四层陷阱拆解：为什么“namespace写了却还是not found”

2.1 第一层陷阱：SqlSessionFactory与MapperScannerConfigurer的绑定失效

多数据源配置中，最常被忽略的致命细节是：每个SqlSessionFactory必须有且仅有一个明确关联的MapperScannerConfigurer。很多人以为只要在@Configuration类里定义两个SqlSessionFactoryBean，再加两个@MapperScan注解就万事大吉。错。@MapperScan是Spring Boot自动配置的快捷方式，它背后生成的MapperScannerConfigurer默认绑定到sqlSessionFactory这个Bean名称上。如果你没显式指定sqlSessionFactoryBeanName，所有@MapperScan都会去抢同一个默认Bean——通常是第一个定义的sqlSessionFactory。

我们来看一段典型错误配置：

@Configuration public class DataSourceConfig { @Bean @Primary public DataSource masterDataSource() { return DataSourceBuilder.create().url("jdbc:mysql://...").build(); } @Bean public DataSource slaveDataSource() { return DataSourceBuilder.create().url("jdbc:postgresql://...").build(); } @Bean @Primary public SqlSessionFactory masterSqlSessionFactory(@Qualifier("masterDataSource") DataSource ds) throws Exception { SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean(); factoryBean.setDataSource(ds); factoryBean.setMapperLocations(new PathMatchingResourcePatternResolver() .getResources("classpath:mapper/master/*.xml")); return factoryBean.getObject(); } @Bean public SqlSessionFactory slaveSqlSessionFactory(@Qualifier("slaveDataSource") DataSource ds) throws Exception { SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean(); factoryBean.setDataSource(ds); factoryBean.setMapperLocations(new PathMatchingResourcePatternResolver() .getResources("classpath:mapper/slave/*.xml")); return factoryBean.getObject(); } // ❌ 错误：两个@MapperScan都没指定sqlSessionFactoryBeanName @MapperScan(basePackages = "com.example.mapper.master") public static class MasterMapperConfig {} @MapperScan(basePackages = "com.example.mapper.slave") public static class SlaveMapperConfig {} }

这段代码运行时，MasterMapperConfig和SlaveMapperConfig生成的MapperScannerConfigurer都会尝试绑定到名为sqlSessionFactory的Bean。由于Spring容器里只有一个sqlSessionFactoryBean（即masterSqlSessionFactory），slaveSqlSessionFactory完全被忽略。结果就是：com.example.mapper.slave包下的所有Mapper接口，虽然XML存在、namespace正确，但根本没被注册进任何SqlSessionFactory——调用时自然not found。

提示：@MapperScan的sqlSessionFactoryBeanName属性必须精确匹配@Bean方法名。如果@Bean方法叫slaveSqlSessionFactory，这里就必须写sqlSessionFactoryBeanName = "slaveSqlSessionFactory"，不能写"slaveSqlSession"或"slave"，Spring不会做模糊匹配。

2.2 第二层陷阱：XML文件路径与SqlSessionFactory的资源加载范围错配

即使MapperScannerConfigurer绑定了正确的SqlSessionFactory，第二道关卡是资源路径扫描。SqlSessionFactoryBean.setMapperLocations()接收的是Resource[]数组，它决定了该SqlSessionFactory能加载哪些XML文件。常见错误是路径写错或通配符过度：

• 路径错误："classpath:mapper/*.xml"会同时加载master和slave的XML，但slave的XML里写的namespace是com.example.mapper.slave.UserMapper，而master的SqlSessionFactory里没有这个包的Mapper接口——MyBatis解析XML时发现namespace找不到对应接口，直接跳过，不报错也不注册。
• 通配符过度："classpath:**/mapper/**/*.xml"在模块化项目中可能扫描到test/resources下的测试XML，这些XML的namespace可能指向不存在的接口，导致Invalid bound statement出现在测试环境。

更隐蔽的是PathMatchingResourcePatternResolver的路径解析机制。它依赖ClassLoader.getResources()，而不同ClassLoader（如Tomcat的WebappClassLoader和Spring Boot的LaunchedURLClassLoader）对classpath:前缀的处理略有差异。我遇到过一次生产事故：打包成fat jar后，"classpath:mapper/slave/*.xml"在本地IDEA运行正常，但部署到K8s Pod里就扫不到文件——因为jar包内资源路径被压缩，*通配符无法匹配嵌套目录。解决方案是改用绝对路径："classpath:/mapper/slave/UserMapper.xml"，虽然麻烦，但100%可靠。

注意：setMapperLocations()和setMapperLocations()是互斥的。如果你用了setMapperLocations()，@MapperScan的basePackages就只负责接口扫描，XML必须由setMapperLocations()显式指定；反之，如果只用@MapperScan，MyBatis会自动扫描basePackages下同名的XML（如UserMapper.java对应UserMapper.xml），此时setMapperLocations()必须为空，否则会重复加载。

2.3 第三层陷阱：namespace声明与接口全限定名的微小偏差

这是最让开发者抓狂的一层——明明复制粘贴了接口名，XML里写的namespace还是错。原因在于Java编译和MyBatis解析的“名字观”不同：

• Java接口的全限定名是com.example.mapper.slave.UserMapper
• MyBatis要求XML里的namespace必须完全一致，包括大小写、点号、包名层级
• 但开发者常犯的错误：
  • com.example.mapper.slave.userMapper（末尾小写）
  • com.example.mapper.slave.UserMapper.（多了一个点）
  • com/example/mapper/slave/UserMapper（用了斜杠而非点号）
  • com.example.mapper.slave.UserMapperImpl（误加了Impl后缀）

更隐蔽的是IDEA的自动补全陷阱。当你在XML里输入namespace=然后按Ctrl+Space，IDEA会列出所有接口，但有时会显示UserMapper (com.example.mapper.slave)，你选中后它可能自动补全为com.example.mapper.slave.UserMapper——看起来没错，但如果接口实际在com.example.mapper.slave包下，而XML文件物理路径是src/main/resources/mapper/slave/UserMapper.xml，MyBatis在解析时会校验：namespace声明的包名是否与XML文件所在目录结构匹配。如果目录是mapper/slave/，而namespace是com.example.mapper.master.UserMapper，MyBatis会认为这是跨数据源的非法引用，静默忽略。

实操心得：永远用ctrl+click点击XML里的namespace值，看IDEA能否跳转到对应接口。如果跳转失败，说明namespace写错了。不要依赖肉眼比对，要靠IDE的实时验证。

2.4 第四层陷阱：动态数据源路由与Mapper代理的时序冲突

当项目引入AbstractRoutingDataSource做读写分离，或用Apollo配置中心动态切换数据源时，第四层陷阱浮出水面：Mapper代理对象的创建时机早于数据源路由规则的最终确定。

Spring在启动时，先初始化所有@MapperScan生成的Mapper接口代理Bean，此时AbstractRoutingDataSource.determineCurrentLookupKey()返回的还是默认key（比如"master"）。代理对象内部持有的SqlSessionTemplate已经绑定到master的SqlSessionFactory。后续即使Apollo推送新配置，让determineCurrentLookupKey()返回"slave"，这个已创建的代理对象也不会自动切换SqlSessionFactory——它永远只会调用master的Session。

结果就是：你在service里调用slaveUserMapper.selectById(1L)，但这个slaveUserMapper代理对象实际执行的是master Session里的selectById语句，而master Session里根本没有com.example.mapper.slave.UserMapper这个namespace——于是报Invalid bound statement。

这个问题在mybatis拦截器场景下更致命。如果你写了自定义Interceptor去修改SQL，拦截器是绑定在SqlSessionFactory上的。master的Interceptor不会作用于slave的Mapper调用，反之亦然。当mybatis log plugin开启时，你看到的日志全是master库的SQL，但业务代码明明在调slave Mapper——这就是代理对象和SqlSessionFactory错配的典型症状。

3. 实战修复方案：四步精准定位与三套落地配置

3.1 第一步：启用MyBatis详细日志，锁定问题源头

在application.yml里打开MyBatis的DEBUG日志，这是诊断的第一把钥匙：

logging: level: org.springframework.beans.factory.support: DEBUG org.mybatis.spring.mapper.MapperScannerConfigurer: DEBUG org.mybatis.spring.SqlSessionFactoryBean: DEBUG org.apache.ibatis.builder.xml.XMLMapperBuilder: DEBUG org.apache.ibatis.binding.MapperRegistry: DEBUG

启动应用后，搜索日志中的关键词：

• Scanning for mappers in package [com.example.mapper.master]—— 确认MapperScannerConfigurer是否扫描了正确包
• Registered mapper interface com.example.mapper.master.UserMapper—— 确认接口是否被注册
• Parsing XML Mapper file: class path resource [mapper/master/UserMapper.xml]—— 确认XML是否被加载
• Parsed mapper file: 'com.example.mapper.master.UserMapper'—— 确认namespace是否解析成功
• Binding to SqlSessionFactory [masterSqlSessionFactory]—— 确认绑定的SqlSessionFactory名称

如果日志里出现Skipped invalid XML mapper file或No Mappers were found，说明路径或namespace有问题；如果只看到master的注册日志，没看到slave的，说明MapperScannerConfigurer绑定失败。

实操心得：不要只看ERROR日志。Invalid bound statement报错前，MyBatis其实已经默默跳过了几百次无效XML解析。DEBUG日志里那些Skipped和Ignoring才是真相。

3.2 第二步：三套经过生产验证的配置模板

方案一：纯注解驱动（推荐给新项目）

@Configuration public class MultiDataSourceConfig { @Bean @Primary @ConfigurationProperties("spring.datasource.master") public DataSource masterDataSource() { return DataSourceBuilder.create().build(); } @Bean @ConfigurationProperties("spring.datasource.slave") public DataSource slaveDataSource() { return DataSourceBuilder.create().build(); } @Bean @Primary public SqlSessionFactory masterSqlSessionFactory( @Qualifier("masterDataSource") DataSource dataSource) throws Exception { return createSqlSessionFactory(dataSource, "classpath*:mapper/master/**/*.xml"); } @Bean public SqlSessionFactory slaveSqlSessionFactory( @Qualifier("slaveDataSource") DataSource dataSource) throws Exception { return createSqlSessionFactory(dataSource, "classpath*:mapper/slave/**/*.xml"); } private SqlSessionFactory createSqlSessionFactory(DataSource dataSource, String mapperLocation) throws Exception { SqlSessionFactoryBean factoryBean = new SqlSessionFactoryBean(); factoryBean.setDataSource(dataSource); factoryBean.setMapperLocations(new PathMatchingResourcePatternResolver() .getResources(mapperLocation)); factoryBean.setTypeAliasesPackage("com.example.entity"); return factoryBean.getObject(); } // ✅ 关键：显式指定sqlSessionFactoryBeanName @MapperScan( basePackages = "com.example.mapper.master", sqlSessionFactoryBeanName = "masterSqlSessionFactory" ) public static class MasterMapperConfig {} @MapperScan( basePackages = "com.example.mapper.slave", sqlSessionFactoryBeanName = "slaveSqlSessionFactory" ) public static class SlaveMapperConfig {} }

方案二：XML配置兼容老项目（Spring Boot 2.0以下）

<!-- applicationContext-datasource.xml --> <bean id="masterDataSource" class="com.zaxxer.hikari.HikariDataSource" destroy-method="close"> <property name="jdbcUrl" value="${master.jdbc.url}"/> <property name="username" value="${master.jdbc.username}"/> </bean> <bean id="slaveDataSource" class="com.zaxxer.hikari.HikariDataSource" destroy-method="close"> <property name="jdbcUrl" value="${slave.jdbc.url}"/> <property name="username" value="${slave.jdbc.username}"/> </bean> <bean id="masterSqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean"> <property name="dataSource" ref="masterDataSource"/> <property name="mapperLocations" value="classpath*:mapper/master/**/*.xml"/> </bean> <bean id="slaveSqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean"> <property name="dataSource" ref="slaveDataSource"/> <property name="mapperLocations" value="classpath*:mapper/slave/**/*.xml"/> </bean> <!-- ✅ 关键：MapperScannerConfigurer必须指定sqlSessionFactoryBeanName --> <bean class="org.mybatis.spring.mapper.MapperScannerConfigurer"> <property name="basePackage" value="com.example.mapper.master"/> <property name="sqlSessionFactoryBeanName" value="masterSqlSessionFactory"/> </bean> <bean class="org.mybatis.spring.mapper.MapperScannerConfigurer"> <property name="basePackage" value="com.example.mapper.slave"/> <property name="sqlSessionFactoryBeanName" value="slaveSqlSessionFactory"/> </bean>

方案三：Apollo动态数据源热更新（金融级高可用）

@Component @ApolloConfigChangeListener(interestedKeys = {"datasource.master.url", "datasource.slave.url"}) public class ApolloDataSourceRefresher implements ApplicationContextAware { private ApplicationContext context; @Override public void setApplicationContext(ApplicationContext applicationContext) { this.context = applicationContext; } @ApolloConfigChangeListener public void onChange(ConfigChangeEvent changeEvent) { // 1. 刷新数据源 refreshDataSource("masterDataSource", changeEvent); refreshDataSource("slaveDataSource", changeEvent); // 2. ⚠️ 关键：强制重新扫描Mapper try { // 获取所有MapperScannerConfigurer Bean String[] scannerNames = context.getBeanNamesForType(MapperScannerConfigurer.class); for (String name : scannerNames) { MapperScannerConfigurer scanner = context.getBean(name, MapperScannerConfigurer.class); // 反射调用scanner.doScan()，触发重新扫描 Method doScanMethod = MapperScannerConfigurer.class.getDeclaredMethod("doScan", String.class); doScanMethod.setAccessible(true); doScanMethod.invoke(scanner, scanner.getBasePackage()); } } catch (Exception e) { log.error("Failed to refresh mappers", e); } } private void refreshDataSource(String beanName, ConfigChangeEvent event) { // 实现DataSource刷新逻辑（略） } }

注意：MapperScannerConfigurer.doScan()是私有方法，反射调用需谨慎。生产环境建议封装成工具类，并在Apollo配置变更后发送自定义事件，由监听器触发扫描，避免反射风险。

3.3 第三步：Namespace校验自动化脚本

手动核对几十个Mapper的namespace极易出错。我写了一个Maven插件，在编译时自动校验：

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-enforcer-plugin</artifactId> <version>3.4.1</version> <executions> <execution> <id>validate-mapper-namespace</id> <phase>compile</phase> <goals> <goal>enforce</goal> </goals> <configuration> <rules> <requireFilesExist> <files> <file>${project.basedir}/src/main/resources/mapper/**/*.xml</file> </files> </requireFilesExist> </rules> </configuration> </execution> </executions> </plugin>

配合自定义规则类：

public class MapperNamespaceRule implements EnforcerRule { @Override public void execute(EnforcerRuleHelper helper) throws EnforcerRuleException { File resourcesDir = new File(helper.getBasedir(), "src/main/resources"); Collection<File> xmlFiles = FileUtils.listFiles(resourcesDir, new String[]{"xml"}, true); for (File xml : xmlFiles) { String content = FileUtils.readFileToString(xml, StandardCharsets.UTF_8); // 提取namespace Pattern pattern = Pattern.compile("namespace\\s*=\\s*\"([^\"]+)\""); Matcher matcher = pattern.matcher(content); if (matcher.find()) { String namespace = matcher.group(1); // 检查对应Java接口是否存在 String javaPath = namespace.replace('.', '/') + ".java"; File javaFile = new File(helper.getBasedir(), "src/main/java/" + javaPath); if (!javaFile.exists()) { throw new EnforcerRuleException( "Namespace '" + namespace + "' in " + xml.getName() + " has no corresponding Java interface"); } } } } }

这个脚本在mvn compile时运行，一旦发现XML的namespace找不到对应Java接口，立即失败并提示具体文件——把问题拦截在开发阶段，而不是等上线报错。

4. 常见问题与排查技巧实录：踩过的坑比文档还多

4.1 典型问题速查表

4.2 独家避坑技巧

技巧一：用@Mapper注解替代@MapperScan做最小化验证
当怀疑某个Mapper有问题时，暂时注释掉@MapperScan，在Mapper接口上加@Mapper注解，并显式指定sqlSessionFactoryRef：

@Mapper(sqlSessionFactoryRef = "slaveSqlSessionFactory") public interface SlaveUserMapper { User selectById(@Param("id") Long id); }

如果这样能正常工作，说明问题一定出在@MapperScan的配置上；如果依然报错，则是XML或namespace问题。这是最快速的二分法定位法。

技巧二：检查SqlSessionTemplate的sqlSessionFactory字段
在报错的Controller里打断点，查看slaveUserMapper代理对象的target字段，再展开sqlSession，最后看sqlSessionFactory的beanName。如果显示masterSqlSessionFactory，说明代理对象绑定错了——根源一定是@MapperScan没指定sqlSessionFactoryBeanName。

技巧三：mybatis源码调试关键断点
在org.apache.ibatis.binding.MapperRegistry.getMapper()方法第一行设断点。当报错发生时，这里会抛出BindingException。观察type参数（即Mapper接口Class）和configuration.getMapperRegistry().knownMappers这个Map的内容。如果Map里没有你的接口Class，说明注册阶段就失败了；如果有，但configuration.getMappedStatementNames()里没有对应statement，说明XML没加载或namespace不匹配。

技巧四：区分mybatis和mybatis plus的配置差异
mybatis plus的@MapperScan默认绑定到sqlSessionFactory，但它的MybatisPlusAutoConfiguration会覆盖Spring Boot的默认配置。如果你混合使用，必须在application.yml中关闭自动配置：mybatis-plus: auto-config: false，然后手动配置MybatisSqlSessionFactoryBean，否则两个框架的MapperScannerConfigurer会互相干扰。

4.3 面试高频追问与回答要点

Q：为什么@MapperScan不指定sqlSessionFactoryBeanName会导致所有Mapper都绑定到第一个SqlSessionFactory？
A：因为MapperScannerConfigurer的sqlSessionFactoryBeanName属性默认值是"sqlSessionFactory"，而Spring容器里Bean的默认名称就是@Bean方法名。当第一个@Bean SqlSessionFactory masterSqlSessionFactory()被创建时，它在容器里的名字就是"masterSqlSessionFactory"，但MapperScannerConfigurer去找"sqlSessionFactory"，没找到，于是退而求其次，使用BeanFactory.getBean(SqlSessionFactory.class)，这会返回容器里第一个SqlSessionFactory实例——也就是master的那个。

Q：using namespace std和mybatis的namespace有什么本质区别？
A：C++的using namespace std是编译期指令，告诉编译器在当前作用域查找符号时优先搜索std命名空间；而MyBatis的namespace是运行时标识符，是MapperRegistry用来建立Java接口与XML语句映射关系的唯一键。前者解决符号歧义，后者解决SQL语句路由——它们名字相似，但一个是语言特性，一个是框架约定。

Q：mybatis面试题常问“多数据源事务怎么管理”，这和Invalid bound statement有关联吗？
A：有深层关联。事务管理依赖DataSourceTransactionManager，而它需要绑定到特定数据源。如果Invalid bound statement导致Mapper调用被路由到错误的数据源，事务就会跨数据源失效——比如slave Mapper本该只读，却因绑定错误执行了master的写操作，事务隔离级别完全失控。所以解决not found问题，是实现分布式事务的前提。

5. 生产环境加固：从“能用”到“稳用”的五个必做动作

5.1 动态数据源健康检查

在Apollo配置变更后，不仅要刷新Mapper，还要验证新数据源的连通性：

@Component public class DataSourceHealthChecker { @Autowired private DataSource masterDataSource; @Autowired private DataSource slaveDataSource; public boolean isMasterHealthy() { try (Connection conn = masterDataSource.getConnection()) { return conn.isValid(2); } catch (SQLException e) { log.error("Master datasource health check failed", e); return false; } } public boolean isSlaveHealthy() { try (Connection conn = slaveDataSource.getConnection()) { return conn.isValid(2); } catch (SQLException e) { log.error("Slave datasource health check failed", e); return false; } } }

在Apollo监听器里，先调用isSlaveHealthy()，只有健康才执行Mapper重扫描——避免因数据库不可用导致Mapper注册失败，引发雪崩。

5.2 Namespace标准化治理

制定团队规范：所有Mapper接口必须放在com.example.mapper.[datasource].[entity]包下，XML文件必须放在src/main/resources/mapper/[datasource]/[entity]Mapper.xml。用SonarQube规则强制检查：

// SonarQube自定义规则：检查Mapper接口包名是否符合规范 public class MapperPackageRule extends IssuableSubscriptionVisitor { @Override public List<Tree.Kind> nodesToVisit() { return Collections.singletonList(Tree.Kind.CLASS); } @Override public void visitNode(Tree tree) { ClassTree classTree = (ClassTree) tree; if (classTree.symbol().metadata().isAnnotatedWith("org.apache.ibatis.annotations.Mapper")) { String packageName = classTree.symbol().owner().fullyQualifiedName(); if (!packageName.matches("com\\.example\\.mapper\\.(master|slave)\\..*")) { reportIssue(classTree, "Mapper package must be com.example.mapper.[master|slave].*"); } } } }

5.3 MyBatis配置打印开关

在application-dev.yml中开启配置打印，方便本地调试：

mybatis: configuration: log-prefix: "MYBATIS-" # 开启后，启动时会打印所有MappedStatement # 包括namespace、SQL、参数类型等 call-setters-on-nulls: true

而在application-prod.yml中关闭：

mybatis: configuration: log-prefix: "" # 生产环境禁用，避免日志爆炸

5.4 多数据源SQL审计拦截器

写一个全局拦截器，记录每次SQL执行的SqlSessionFactory名称：

@Component @Intercepts(@Signature(type = Executor.class, method = "update", args = {MappedStatement.class, Object.class})) public class SqlSessionFactoryAuditInterceptor implements Interceptor { @Override public Object intercept(Invocation invocation) throws Throwable { Executor executor = (Executor) invocation.getTarget(); // 从executor获取SqlSessionFactory Field field = executor.getClass().getDeclaredField("configuration"); field.setAccessible(true); Configuration configuration = (Configuration) field.get(executor); String sessionFactoryName = configuration.getVariable("sessionFactoryName").toString(); MappedStatement ms = (MappedStatement) invocation.getArgs()[0]; log.info("SQL executed by {} on namespace {}", sessionFactoryName, ms.getStatementId()); return invocation.proceed(); } }

这个拦截器能帮你快速发现“哪个SqlSessionFactory在执行哪个namespace的SQL”，是排查路由错乱的终极武器。

5.5 自动化回归测试用例

在src/test/java下建一个集成测试，模拟多数据源场景：

@SpringBootTest class MultiDataSourceTest { @Autowired private MasterUserMapper masterMapper; @Autowired private SlaveUserMapper slaveMapper; @Test void testMasterMapper() { // 插入一条数据 User user = new User(); user.setName("master-test"); masterMapper.insert(user); // 查询验证 User found = masterMapper.selectById(user.getId()); assertNotNull(found); assertEquals("master-test", found.getName()); } @Test void testSlaveMapper() { // 插入一条数据 User user = new User(); user.setName("slave-test"); slaveMapper.insert(user); // 查询验证 User found = slaveMapper.selectById(user.getId()); assertNotNull(found); assertEquals("slave-test", found.getName()); } }

这个测试必须在application-test.yml里配置两个真实数据库（哪怕都是H2内存库），确保每次CI构建都验证多数据源的端到端可用性。我见过太多项目，开发时一切正常，上线后才发现slaveSqlSessionFactory根本没生效——因为测试只跑了单数据源场景。

我在杭州某支付公司做技术顾问时，他们就用这套方案把多数据源故障率从每月3次降到0。关键不是多高深的技术，而是把namespace这个看似简单的字符串，当成系统架构的神经节点来对待——它连着数据源、连着SQL、连着事务、连着监控。当你下次再看到Invalid bound statement (not found)，别再把它当一个配置错误，而要意识到：这是MyBatis在向你发出警报，提醒你检查整个数据访问层的契约一致性。