数据库切换到底怎么玩同一个项目要同时兼容 MySQL 和 OracleMapper 里的 SQL 写着写着就变成了“两份代码两个世界”。这个问题我踩过不少坑最后靠 MyBatis 原生提供的 DatabaseId 机制把两套 SQL 收了回来。今天这篇就围绕 Spring Boot MyBatis Plus 项目里 DatabaseId 的实际使用把配置、写法、坑和排查思路完整捋一遍适合正在做多数据库兼容、或者准备接手这种项目的同学参考。先说结论DatabaseId 不是 MyBatis Plus 的私有功能它是 MyBatis 自带的“数据库方言识别”机制。MyBatis Plus 因为底层还是 MyBatis 的会话工厂所以天然支持只是自动装配层面需要我们多补一个 Bean。它的核心价值在于同一个 Mapper XML 里可以写多套相同 ID 的 SQL 片段每套用databaseId标记属于哪个数据库应用启动时MyBatis 通过DatabaseIdProvider检测当前连接的是哪类数据库只加载匹配的那一套 SQL。这样代码仓库里只有一套 Mapper 接口部署到不同数据库环境的客户现场时不需要改代码、不需要替换 XML启动即适配。1. DatabaseId 到底在解决什么问题1.1 数据库方言差异与多环境部署的痛点做过传统企业项目交付的人应该都有这种经历开发阶段全员 MySQL功能验证没问题到了客户现场生产环境是 Oracle 或者 SQL Server于是一大堆 SQL 开始冒红。最常见的就是分页、日期格式化、字符串拼接、空值处理这些点。比如 MySQL 分页写LIMIT #{start}, #{limit}换成 Oracle 就得套三层子查询或者用OFFSET ... FETCH日期格式化一个用DATE_FORMAT一个用TO_CHAR。如果项目里只有两三条这种 SQL硬着头皮改还能忍但几十上百条的时候就完全不是一回事了。更麻烦的是这种差异往往不是一个客户环境独有。这个项目要部署到 A 客户那个项目要部署到 B 客户两边数据库不同你就得维护两套 XML 或者两套分支代码。改了一个逻辑另一套可能漏改功能上线前要在两套数据库环境分别回归。这种“通过判断代码路径来切 SQL”的方案我早期做过维护成本高到让人怀疑人生。后面我用过根据环境变量动态加载不同 mapper-locations 的路子也算能跑但配置繁琐而且 MyBatis 解析时机、多模块打包、测试环境切换都不够清爽。真正解决这个问题还得回到 MyBatis 自己提供的 DatabaseIdProvider 机制。1.2 DatabaseIdProvider 的工作链路MyBatis 在构建Configuration的时候会调用配置好的DatabaseIdProvider从当前数据源连接里读取DatabaseMetaData.getDatabaseProductName()拿到数据库产品名比如 MySQL 返回MySQLOracle 返回OraclePostgreSQL 返回PostgreSQL。这个产品名经过VendorDatabaseIdProvider的Properties映射变成我们自定义的短字符串比如mysql、oracle最终存在Configuration.databaseId字段上。紧接着MyBatis 解析 Mapper XML 中的每个语句节点时会检查databaseId属性。这里有三个关键动作如果语句节点显式写了databaseIdoracle那么只有当当前配置的 databaseId 也是oracle时才会加载这个语句如果语句节点没写databaseId属性MyBatis 会把当前配置的 databaseId 当作这个语句的 databaseId 来绑定只要配置了 provider所有不匹配当前数据库的语句都会被跳过。这个“加载时过滤”的设计非常关键它意味着 MySQL 环境和 Oracle 环境虽然读的是同一个 XML 文件但最终实际注册进配置的 MappedStatement 只有当前数据库匹配的那一套。你不需要在代码里写if (isOracle) doSomething()数据库类型判断在 SqlSessionFactory 构建阶段就完成了。我个人的理解是DatabaseId 解决的是“同一套代码部署到不同数据库环境”的静态适配问题。它不解决运行中频繁切换库的问题这一点后面讲坑的时候还会重点提。2. 基础工程搭建Spring Boot MyBatis Plus 环境准备2.1 依赖与版本选型我用得比较稳的组合是 Spring Boot 2.7.18 MyBatis Plus 3.5.3.2。如果项目已经升级到 Spring Boot 3需要注意 MyBatis Plus 要换用mybatis-plus-spring-boot3-starter因为 Spring Boot 3 用的是jakarta.*命名空间老包会直接报类找不到。pom.xml 里核心依赖就这几样parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.2/version /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies这里放 H2 依赖不是因为正事要连它而是给“本地没有 Oracle 环境但想验证 DatabaseId 链路”的同学一条活路。后面实战部分我会专门演示怎么用 H2 模拟不同数据库分支。2.2 基础配置与 Mapper 扫描application.yml 先保持最简配置spring: datasource: url: jdbc:mysql://localhost:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver mybatis-plus: mapper-locations: classpath*:/mapper/**/*.xml type-aliases-package: com.example.demo.entity configuration: map-underscore-to-camel-case: true启动类上记得加MapperScan让 Mapper 接口能被扫描注册。这里有个容易被新手忽略的点MyBatis Plus 的 mapper-locations 默认路径是classpath*:/mapper/**/*.xml如果你把 XML 放在别的目录记得在配置里显式改掉否则运行时会报 “Invalid bound statement (not found)”。实体类用一个简单的SysUser演示字段就是id、name、status、createTimeData TableName(sys_user) public class SysUser { private Long id; private String name; private Integer status; private LocalDateTime createTime; }工程能起来、能连上库跑通一个基础查询之后我们再往里面加 DatabaseId 相关的东西。3. 核心配置让 MyBatis Plus 识别当前数据库类型3.1 注册 DatabaseIdProvider Bean这一步是整个链路里最容易被忽略的。很多同学在 XML 里写好了databaseIdmysql结果启动直接报 SQL 重复定义原因就是容器里压根没有DatabaseIdProviderMyBatis 把它当成“未启用多数据库支持”把 XML 里的所有语句都原样加载了一遍带 databaseId 和不带 databaseId 的同名语句自然就撞上了。正确做法是手动注册一个 provider。MyBatis 官方提供了现成的实现VendorDatabaseIdProvider我们只需要把它声明成 Spring Bean 并配置好数据库产品名和自定义 ID 的映射Configuration public class DatabaseIdConfig { Bean public DatabaseIdProvider databaseIdProvider() { VendorDatabaseIdProvider provider new VendorDatabaseIdProvider(); Properties properties new Properties(); properties.setProperty(MySQL, mysql); properties.setProperty(Oracle, oracle); properties.setProperty(PostgreSQL, postgresql); properties.setProperty(H2, h2); provider.setProperties(properties); return provider; } }这里特别提醒一个细节VendorDatabaseIdProvider的Properties的 key 是 JDBC 驱动返回的原始数据库产品名大小写是敏感的。MySQL 驱动返回的是MySQL而不是mysqlOracle 驱动返回的是Oracle而不是oracle。如果你只写了properties.setProperty(mysql, mysql)检测结果会直接落空Configuration.getDatabaseId()拿到的可能是个不匹配的值。如果不确定驱动返回什么产品名可以在启动时临时打印一下Component public class DatabaseIdRunner implements ApplicationRunner { Resource private DataSource dataSource; Override public void run(ApplicationArguments args) throws Exception { try (Connection connection dataSource.getConnection()) { System.out.println(DatabaseProductName: connection.getMetaData().getDatabaseProductName()); } } }我第一次写这个映射的时候就把大小写写错了结果 provider 返回的是 null_databaseId怎么判断都不走分支排查了半天才发现是 properties 的 key 没对上。3.2 MyBatis Plus 会把 provider 自动塞给 SqlSessionFactory注册完 Bean 之后MyBatis Plus 的自动配置会检查容器里有没有DatabaseIdProvider有的话就设置到MybatisSqlSessionFactoryBean上。这块不需要我们额外写代码Spring Boot 的自动装配帮我们处理掉了。但有个前提MybatisPlusAutoConfiguration扫描到DatabaseIdProviderBean 的方式是Autowired(required false)如果你的项目里有多个 SqlSessionFactory比如多数据源场景每个 factory 都需要单独设置 provider自动配置只会照顾到默认的哪一个。这个等我讲到常见坑的时候再展开。验证 provider 是否生效最直接的一招是在ApplicationRunner里取一次SqlSessionFactoryComponent public class DatabaseIdCheckRunner implements ApplicationRunner { Resource private SqlSessionFactory sqlSessionFactory; Override public void run(ApplicationArguments args) { System.out.println([databaseId] current sqlSessionFactory.getConfiguration().getDatabaseId()); } }如果启动日志打印出[databaseId] current mysql说明整条链路已经通了。后面所有 XML 里的_databaseId判断才有意义。4. 在 Mapper XML 里按数据库写 SQL 的两种实战姿势4.1 姿势 A一个 statementId 配多套 databaseId 语句这是 DatabaseId 最直白的用法。同一个select节点ID 保持一样databaseId属性不同MyBatis 启动时只会加载当前数据库匹配的那一个。以用户列表查询为例select idselectUserListByStatus resultTypecom.example.demo.entity.SysUser SELECT id, name, status, create_time FROM sys_user WHERE status #{status} if test_databaseId oracle ORDER BY id OFFSET #{start} ROWS FETCH NEXT #{limit} ROWS ONLY /if if test_databaseId mysql ORDER BY id LIMIT #{start}, #{limit} /if /select这里我用的是_databaseId条件分支但如果要演示显式databaseId属性写法可以改成两套同 ID 的完整节点select idselectUserListByStatus resultTypecom.example.demo.entity.SysUser databaseIdmysql SELECT id, name, status, create_time FROM sys_user WHERE status #{status} ORDER BY id LIMIT #{start}, #{limit} /select select idselectUserListByStatus resultTypecom.example.demo.entity.SysUser databaseIdoracle SELECT id, name, status, create_time FROM sys_user WHERE status #{status} ORDER BY id OFFSET #{start} ROWS FETCH NEXT #{limit} ROWS ONLY /select这种写法适合整套 SQL 差异很大、几乎等于重写的情况。例如某个复杂统计查询Oracle 里要用ROW_NUMBER() OVER (PARTITION BY ...)MySQL 里要变着法子用变量或者窗口函数替代两套 SQL 结构完全不同。硬塞进一个choose里会让 XML 变得又长又乱不如直接按照databaseId拆成两个节点职责清晰。需要注意使用姿势 A 时要么所有环境都用显式databaseId标记要么只在 XML 里保留一套默认语句不要混着写“一套不带 databaseId 的默认 SQL 一套带 databaseId 的特化 SQL”。因为配置了 provider 之后不带 databaseId 的语句也会被绑定上当前数据库 ID此时如果再出现一个显式声明同 ID 的语句MyBatis 会直接报 “Mapped Statements collection already contains value”具体现象和原因我放在最后的排查表里详细说。4.2 姿势 B一个语句内用 _databaseId 做分支当两套 SQL 差异只集中在少量片段的时候我更推荐用_databaseId参数配合if或choose在同一个语句里处理。_databaseId是 MyBatis 动态 SQL 内置的一个参数它的值就是Configuration.getDatabaseId()也就是我们前面通过 provider 设置好的当前数据库标识。举个例子用户列表查询同时要对时间字段做格式化、分页、按状态过滤。不同数据库的日期函数不同分页语法不同但整体 SQL 骨架一样这种情况下把它拆成两个 statement 反而阅读起来费劲。用一个 statement _databaseId分支差异点就在眼皮子底下select idselectUserListByStatus resultTypejava.util.Map SELECT id, name, choose when test_databaseId oracle TO_CHAR(create_time, YYYY-MM-DD HH24:MI:SS) AS create_time /when otherwise DATE_FORMAT(create_time, %Y-%m-%d %H:%i:%s) AS create_time /otherwise /choose FROM sys_user WHERE status #{status} choose when test_databaseId oracle ORDER BY id OFFSET #{start} ROWS FETCH NEXT #{limit} ROWS ONLY /when otherwise ORDER BY id LIMIT #{start}, #{limit} /otherwise /choose /select运行时MyBatis 会把_databaseId解析成当前的数据库标识选择对应的 SQL 片段组装出来。这种写法最大的好处是“差异在同一个语句里集中暴露”后续维护时只要看这一个节点就能知道自己维护的库走了哪条逻辑。不过它也有缺点如果差异点很多choose和if嵌套多了XML 的可读性会快速下降。我自己大概是这么取舍的差异片段不超过 SQL 总量的三分之一用姿势 B改到跟重写差不多用姿势 A。4.3 两种姿势的对比与选择建议为了让大家决策得更快我把两种方式的适用场景整理成了表格对比维度姿势 A多套 databaseId 语句姿势 B_databaseId 分支SQL 差异程度差异大基本两套结构差异小局部片段不同XML 可读性每套完整 SQL结构清晰分支多了会显得臃肿维护成本两套都要维护容易漏改差异点在一个语句里一目了然启动加载只加载匹配当前库的语句加载一个语句运行时分段选择适合场景复杂报表、特殊数据库专属写法分页、函数差异、条件拼接实际做项目我一般两种混着用整体查询骨架一致的用姿势 B某几个特别复杂的报表查询用姿势 A。DatabaseId 机制没有限制你在同一个 XML 里只能选一种怎么顺手怎么来。5. 实战一套用户列表查询接口适配 MySQL 与 Oracle5.1 业务需求与 SQL 差异分析假设我们有个用户管理页面要按状态分页查询用户列表并且列表里展示的create_time需要格式化到秒。这个需求在 MySQL 和 Oracle 上有两个明显差异分页语法MySQL 用LIMIT #{start}, #{limit}Oracle 12c 以上可以用OFFSET #{start} ROWS FETCH NEXT #{limit} ROWS ONLY比老套的ROWNUM两层子查询干净得多。日期格式化MySQL 的DATE_FORMAT占位符是%Y-%m-%d %H:%i:%sOracle 的TO_CHAR格式串是YYYY-MM-DD HH24:MI:SS。这个场景用姿势 B 最合适因为整个 SQL 的骨架都是SELECT ... FROM sys_user WHERE status ? ORDER BY id ...只有中间一小段函数和最后的分页段需要切换。5.2 Mapper 接口与 XML 完整实现Mapper 接口没什么特殊的多个参数记得用Param显式命名public interface SysUserMapper extends BaseMapperSysUser { ListMapString, Object selectUserListByStatus( Param(status) Integer status, Param(start) Integer start, Param(limit) Integer limit); }XML 放在resources/mapper目录下?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.demo.mapper.SysUserMapper select idselectUserListByStatus resultTypejava.util.Map SELECT id, name, choose when test_databaseId oracle TO_CHAR(create_time, YYYY-MM-DD HH24:MI:SS) AS create_time /when otherwise DATE_FORMAT(create_time, %Y-%m-%d %H:%i:%s) AS create_time /otherwise /choose FROM sys_user WHERE status #{status} choose when test_databaseId oracle ORDER BY id OFFSET #{start} ROWS FETCH NEXT #{limit} ROWS ONLY /when otherwise ORDER BY id LIMIT #{start}, #{limit} /otherwise /choose /select /mapper特别注意XML 里如果 SQL 片段中出现、、这些特殊字符必须使用转义形式比如lt;代表小于号或者用![CDATA[ ... ]]包裹。上面的例子刻意避开了写成ROWNUM lt; #{limit}这种老写法直接用OFFSET ... FETCH省去转义的麻烦也更贴近现代 Oracle 的最佳实践。接口调用时传status 1, start 0, limit 10MySQL 环境会执行SELECT id, name, DATE_FORMAT(create_time, %Y-%m-%d %H:%i:%s) AS create_time FROM sys_user WHERE status 1 ORDER BY id LIMIT 0, 10Oracle 环境会执行SELECT id, name, TO_CHAR(create_time, YYYY-MM-DD HH24:MI:SS) AS create_time FROM sys_user WHERE status 1 ORDER BY id OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY两者的返回字段结构一致前端完全无感。5.3 本地没有 Oracle怎么验证分支逻辑很多项目本地根本没装 Oracle验证多数据库适配总不能每次跑到客户现场。我的做法是用 H2 数据库的兼容模式去模拟成本极低效果足够验证链路。H2 的DatabaseMetaData.getDatabaseProductName()固定返回H2所以我们需要在 provider 的映射里加一行properties.setProperty(H2, oracle)让 H2 连接在检测时被当成 Oracle 来对待。这样我们可以用同一套代码、同一套 XML切换数据源 URL 就能分别走 MySQL 分支和 Oracle 分支。MySQL 环境连接串spring: datasource: url: jdbc:mysql://localhost:3306/demo driver-class-name: com.mysql.cj.jdbc.Driver模拟 Oracle 环境时把数据源切到 H2 的 Oracle 兼容模式spring: datasource: url: jdbc:h2:mem:demo;MODEOracle;DATABASE_TO_LOWERTRUE;DB_CLOSE_DELAY-1 driver-class-name: org.h2.Driver username: sa password:H2 的 Oracle 模式支持TO_CHAR和OFFSET ... FETCH这些语法足以验证 SQL 分支是否真的切换成功。如果你手头有可用的 MySQL 环境建议真实跑一遍 MySQL 分支Oracle 分支用 H2 模拟这样的组合能覆盖大多数开发场景。6. 高频问题与排查技巧速查6.1 启动报 “Mapped Statements collection already contains value”这个问题我在前面已经预告过。最常见的原因就是XML 里同时存在“不带 databaseId 的默认语句”和“带 databaseId 的语句”而两者 ID 完全相同。配置了DatabaseIdProvider之后不带 databaseId 的语句也会被绑定当前数据库的 ID于是 MyBatis 发现两个同 ID 同 databaseId 的 MappedStatement自然就冲突了。顺着这个思路就能排查检查所有同 ID 的 select/update/insert/delete 节点要么全部去掉 databaseId 属性要么每个环境都显式把 databaseId 写全不要让“默认 特化”混在一起。我在项目里用姿势 B_databaseId分支之后这类问题几乎绝迹。6.2 _databaseId 一直是 null或者分支永远走不对先确认容器里到底有没有注册DatabaseIdProviderBean。没有 provider 时Configuration.getDatabaseId()为 null动态 SQL 里_databaseId oracle永远为 false所有分支都会走otherwise或直接漏掉。再检查VendorDatabaseIdProvider的 Properties 映射 key 是否和驱动返回的DatabaseProductName大小写一致。MySQL 驱动返回MySQL不是你随手写的mysqlSQL Server 驱动返回Microsoft SQL Server中间还有空格。拿不准就直接打印DatabaseProductName看一眼。还有一种情况是数据源没被正确检测。如果项目用了动态数据源provider 在构建 SqlSessionFactory 时连接的是主数据源而实际业务跑在另一个库上_databaseId检测的结果和真实执行库可能对不上需要确认检测数据源与实际业务数据源的关系。6.3 部署到多数据源环境DatabaseId 为什么不动态切换这是很多人最容易产生误解的地方。Configuration.getDatabaseId()是在 SqlSessionFactory 初始化阶段通过 provider 检测数据源后一次性写入的。也就是说DatabaseId 是“部署时确定”的静态值不是“运行中随数据源切换”的动态值。如果项目里用动态数据源方案比如一个 MySQL 库、一个 Oracle 库运行过程中通过DS注解切换数据源此时底层只有一个 SqlSessionFactory它的 databaseId 仍然是初始化时检测到的那个值_databaseId不会跟随切换而变化。这种情况不要指望 DatabaseId 来区分正确做法是每个数据源单独构建 SqlSessionFactory并且为每个 factory 设置对应的DatabaseIdProvider或者在 Mapper 层把多数据库差异抽象成独立接口按数据源类型加载不同的 Mapper 实现。我早期在这上面栽过跟头以为动态数据源 DatabaseId 是万能组合结果切换后 SQL 一直走错分支排查了很久才意识到 databaseId 根本不感知运行时切换。6.4 与 MyBatis Plus 分页插件的协同使用MyBatis Plus 自带的分页插件PaginationInnerInterceptor是另一个维度的方言适配。它负责在 SQL 执行前拦截并改写分页语句本身需要指定数据库方言类型比如new PaginationInnerInterceptor(DbType.MYSQL)。如果你已经用分页插件处理了分页那么 DatabaseId 就不需要再操心LIMIT和OFFSET这些分页差异了只处理函数、语法层面的差异比如前面示例里的日期格式化。两层职责一拆XML 能比上面写的还干净select idselectUserListByStatus resultTypejava.util.Map SELECT id, name, choose when test_databaseId oracle TO_CHAR(create_time, YYYY-MM-DD HH24:MI:SS) AS create_time /when otherwise DATE_FORMAT(create_time, %Y-%m-%d %H:%i:%s) AS create_time /otherwise /choose FROM sys_user WHERE status #{status} ORDER BY id /select分页插件在拦截器层统一处理方言DatabaseId 只管 SQL 片段差异两者互不干扰配合起来很顺。要注意的是如果连接的是动态数据源分页插件的DbType也需要按数据源区分固定写死DbType.MYSQL而在 Oracle 数据源上执行同样会出问题这一点和 DatabaseId 的“静态检测”问题同宗同源。6.5 排查建议把 databaseId 打印进启动日志最后分享一个我自己的小习惯项目启动时一定会把当前 databaseId 打印出来。写法很简单一个ApplicationRunner就够Component public class DatabaseIdStartupLogger implements ApplicationRunner { Resource private SqlSessionFactory sqlSessionFactory; Override public void run(ApplicationArguments args) { System.out.println([databaseId] current databaseId sqlSessionFactory.getConfiguration().getDatabaseId()); } }这样每次部署环境变了、数据源改了第一眼就能确认 MyBatis 到底识别成了什么数据库而不是等到接口调用才发现 SQL 分支不对。这个习惯帮我节省了大量“看起来正常但实则走了错误分支”的排查时间。项目里如果真的同时面对 MySQL、Oracle、PostgreSQL 这类多数据库交付场景DatabaseId 是我目前用下来最顺手的方案。SQL 差异小就塞进_databaseId分支差异大就拆成多套databaseId语句部署到哪里检测到哪里代码仓库里始终只有一套 Mapper。暂时没条件装真实 Oracle 数据库的H2 兼容模式加上映射配置也能把链路跑通本地验证足够了。
数据库切换到底怎么玩同一个项目要同时兼容 MySQL 和 OracleMapper 里的 SQL 写着写着就变成了“两份代码两个世界”。这个问题我踩过不少坑最后靠 MyBatis 原生提供的 DatabaseId 机制把两套 SQL 收了回来。今天这篇就围绕 Spring Boot MyBatis Plus 项目里 DatabaseId 的实际使用把配置、写法、坑和排查思路完整捋一遍适合正在做多数据库兼容、或者准备接手这种项目的同学参考。先说结论DatabaseId 不是 MyBatis Plus 的私有功能它是 MyBatis 自带的“数据库方言识别”机制。MyBatis Plus 因为底层还是 MyBatis 的会话工厂所以天然支持只是自动装配层面需要我们多补一个 Bean。它的核心价值在于同一个 Mapper XML 里可以写多套相同 ID 的 SQL 片段每套用databaseId标记属于哪个数据库应用启动时MyBatis 通过DatabaseIdProvider检测当前连接的是哪类数据库只加载匹配的那一套 SQL。这样代码仓库里只有一套 Mapper 接口部署到不同数据库环境的客户现场时不需要改代码、不需要替换 XML启动即适配。1. DatabaseId 到底在解决什么问题1.1 数据库方言差异与多环境部署的痛点做过传统企业项目交付的人应该都有这种经历开发阶段全员 MySQL功能验证没问题到了客户现场生产环境是 Oracle 或者 SQL Server于是一大堆 SQL 开始冒红。最常见的就是分页、日期格式化、字符串拼接、空值处理这些点。比如 MySQL 分页写LIMIT #{start}, #{limit}换成 Oracle 就得套三层子查询或者用OFFSET ... FETCH日期格式化一个用DATE_FORMAT一个用TO_CHAR。如果项目里只有两三条这种 SQL硬着头皮改还能忍但几十上百条的时候就完全不是一回事了。更麻烦的是这种差异往往不是一个客户环境独有。这个项目要部署到 A 客户那个项目要部署到 B 客户两边数据库不同你就得维护两套 XML 或者两套分支代码。改了一个逻辑另一套可能漏改功能上线前要在两套数据库环境分别回归。这种“通过判断代码路径来切 SQL”的方案我早期做过维护成本高到让人怀疑人生。后面我用过根据环境变量动态加载不同 mapper-locations 的路子也算能跑但配置繁琐而且 MyBatis 解析时机、多模块打包、测试环境切换都不够清爽。真正解决这个问题还得回到 MyBatis 自己提供的 DatabaseIdProvider 机制。1.2 DatabaseIdProvider 的工作链路MyBatis 在构建Configuration的时候会调用配置好的DatabaseIdProvider从当前数据源连接里读取DatabaseMetaData.getDatabaseProductName()拿到数据库产品名比如 MySQL 返回MySQLOracle 返回OraclePostgreSQL 返回PostgreSQL。这个产品名经过VendorDatabaseIdProvider的Properties映射变成我们自定义的短字符串比如mysql、oracle最终存在Configuration.databaseId字段上。紧接着MyBatis 解析 Mapper XML 中的每个语句节点时会检查databaseId属性。这里有三个关键动作如果语句节点显式写了databaseIdoracle那么只有当当前配置的 databaseId 也是oracle时才会加载这个语句如果语句节点没写databaseId属性MyBatis 会把当前配置的 databaseId 当作这个语句的 databaseId 来绑定只要配置了 provider所有不匹配当前数据库的语句都会被跳过。这个“加载时过滤”的设计非常关键它意味着 MySQL 环境和 Oracle 环境虽然读的是同一个 XML 文件但最终实际注册进配置的 MappedStatement 只有当前数据库匹配的那一套。你不需要在代码里写if (isOracle) doSomething()数据库类型判断在 SqlSessionFactory 构建阶段就完成了。我个人的理解是DatabaseId 解决的是“同一套代码部署到不同数据库环境”的静态适配问题。它不解决运行中频繁切换库的问题这一点后面讲坑的时候还会重点提。2. 基础工程搭建Spring Boot MyBatis Plus 环境准备2.1 依赖与版本选型我用得比较稳的组合是 Spring Boot 2.7.18 MyBatis Plus 3.5.3.2。如果项目已经升级到 Spring Boot 3需要注意 MyBatis Plus 要换用mybatis-plus-spring-boot3-starter因为 Spring Boot 3 用的是jakarta.*命名空间老包会直接报类找不到。pom.xml 里核心依赖就这几样parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.2/version /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency dependency groupIdcom.h2database/groupId artifactIdh2/artifactId scoperuntime/scope /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies这里放 H2 依赖不是因为正事要连它而是给“本地没有 Oracle 环境但想验证 DatabaseId 链路”的同学一条活路。后面实战部分我会专门演示怎么用 H2 模拟不同数据库分支。2.2 基础配置与 Mapper 扫描application.yml 先保持最简配置spring: datasource: url: jdbc:mysql://localhost:3306/demo?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: root driver-class-name: com.mysql.cj.jdbc.Driver mybatis-plus: mapper-locations: classpath*:/mapper/**/*.xml type-aliases-package: com.example.demo.entity configuration: map-underscore-to-camel-case: true启动类上记得加MapperScan让 Mapper 接口能被扫描注册。这里有个容易被新手忽略的点MyBatis Plus 的 mapper-locations 默认路径是classpath*:/mapper/**/*.xml如果你把 XML 放在别的目录记得在配置里显式改掉否则运行时会报 “Invalid bound statement (not found)”。实体类用一个简单的SysUser演示字段就是id、name、status、createTimeData TableName(sys_user) public class SysUser { private Long id; private String name; private Integer status; private LocalDateTime createTime; }工程能起来、能连上库跑通一个基础查询之后我们再往里面加 DatabaseId 相关的东西。3. 核心配置让 MyBatis Plus 识别当前数据库类型3.1 注册 DatabaseIdProvider Bean这一步是整个链路里最容易被忽略的。很多同学在 XML 里写好了databaseIdmysql结果启动直接报 SQL 重复定义原因就是容器里压根没有DatabaseIdProviderMyBatis 把它当成“未启用多数据库支持”把 XML 里的所有语句都原样加载了一遍带 databaseId 和不带 databaseId 的同名语句自然就撞上了。正确做法是手动注册一个 provider。MyBatis 官方提供了现成的实现VendorDatabaseIdProvider我们只需要把它声明成 Spring Bean 并配置好数据库产品名和自定义 ID 的映射Configuration public class DatabaseIdConfig { Bean public DatabaseIdProvider databaseIdProvider() { VendorDatabaseIdProvider provider new VendorDatabaseIdProvider(); Properties properties new Properties(); properties.setProperty(MySQL, mysql); properties.setProperty(Oracle, oracle); properties.setProperty(PostgreSQL, postgresql); properties.setProperty(H2, h2); provider.setProperties(properties); return provider; } }这里特别提醒一个细节VendorDatabaseIdProvider的Properties的 key 是 JDBC 驱动返回的原始数据库产品名大小写是敏感的。MySQL 驱动返回的是MySQL而不是mysqlOracle 驱动返回的是Oracle而不是oracle。如果你只写了properties.setProperty(mysql, mysql)检测结果会直接落空Configuration.getDatabaseId()拿到的可能是个不匹配的值。如果不确定驱动返回什么产品名可以在启动时临时打印一下Component public class DatabaseIdRunner implements ApplicationRunner { Resource private DataSource dataSource; Override public void run(ApplicationArguments args) throws Exception { try (Connection connection dataSource.getConnection()) { System.out.println(DatabaseProductName: connection.getMetaData().getDatabaseProductName()); } } }我第一次写这个映射的时候就把大小写写错了结果 provider 返回的是 null_databaseId怎么判断都不走分支排查了半天才发现是 properties 的 key 没对上。3.2 MyBatis Plus 会把 provider 自动塞给 SqlSessionFactory注册完 Bean 之后MyBatis Plus 的自动配置会检查容器里有没有DatabaseIdProvider有的话就设置到MybatisSqlSessionFactoryBean上。这块不需要我们额外写代码Spring Boot 的自动装配帮我们处理掉了。但有个前提MybatisPlusAutoConfiguration扫描到DatabaseIdProviderBean 的方式是Autowired(required false)如果你的项目里有多个 SqlSessionFactory比如多数据源场景每个 factory 都需要单独设置 provider自动配置只会照顾到默认的哪一个。这个等我讲到常见坑的时候再展开。验证 provider 是否生效最直接的一招是在ApplicationRunner里取一次SqlSessionFactoryComponent public class DatabaseIdCheckRunner implements ApplicationRunner { Resource private SqlSessionFactory sqlSessionFactory; Override public void run(ApplicationArguments args) { System.out.println([databaseId] current sqlSessionFactory.getConfiguration().getDatabaseId()); } }如果启动日志打印出[databaseId] current mysql说明整条链路已经通了。后面所有 XML 里的_databaseId判断才有意义。4. 在 Mapper XML 里按数据库写 SQL 的两种实战姿势4.1 姿势 A一个 statementId 配多套 databaseId 语句这是 DatabaseId 最直白的用法。同一个select节点ID 保持一样databaseId属性不同MyBatis 启动时只会加载当前数据库匹配的那一个。以用户列表查询为例select idselectUserListByStatus resultTypecom.example.demo.entity.SysUser SELECT id, name, status, create_time FROM sys_user WHERE status #{status} if test_databaseId oracle ORDER BY id OFFSET #{start} ROWS FETCH NEXT #{limit} ROWS ONLY /if if test_databaseId mysql ORDER BY id LIMIT #{start}, #{limit} /if /select这里我用的是_databaseId条件分支但如果要演示显式databaseId属性写法可以改成两套同 ID 的完整节点select idselectUserListByStatus resultTypecom.example.demo.entity.SysUser databaseIdmysql SELECT id, name, status, create_time FROM sys_user WHERE status #{status} ORDER BY id LIMIT #{start}, #{limit} /select select idselectUserListByStatus resultTypecom.example.demo.entity.SysUser databaseIdoracle SELECT id, name, status, create_time FROM sys_user WHERE status #{status} ORDER BY id OFFSET #{start} ROWS FETCH NEXT #{limit} ROWS ONLY /select这种写法适合整套 SQL 差异很大、几乎等于重写的情况。例如某个复杂统计查询Oracle 里要用ROW_NUMBER() OVER (PARTITION BY ...)MySQL 里要变着法子用变量或者窗口函数替代两套 SQL 结构完全不同。硬塞进一个choose里会让 XML 变得又长又乱不如直接按照databaseId拆成两个节点职责清晰。需要注意使用姿势 A 时要么所有环境都用显式databaseId标记要么只在 XML 里保留一套默认语句不要混着写“一套不带 databaseId 的默认 SQL 一套带 databaseId 的特化 SQL”。因为配置了 provider 之后不带 databaseId 的语句也会被绑定上当前数据库 ID此时如果再出现一个显式声明同 ID 的语句MyBatis 会直接报 “Mapped Statements collection already contains value”具体现象和原因我放在最后的排查表里详细说。4.2 姿势 B一个语句内用 _databaseId 做分支当两套 SQL 差异只集中在少量片段的时候我更推荐用_databaseId参数配合if或choose在同一个语句里处理。_databaseId是 MyBatis 动态 SQL 内置的一个参数它的值就是Configuration.getDatabaseId()也就是我们前面通过 provider 设置好的当前数据库标识。举个例子用户列表查询同时要对时间字段做格式化、分页、按状态过滤。不同数据库的日期函数不同分页语法不同但整体 SQL 骨架一样这种情况下把它拆成两个 statement 反而阅读起来费劲。用一个 statement _databaseId分支差异点就在眼皮子底下select idselectUserListByStatus resultTypejava.util.Map SELECT id, name, choose when test_databaseId oracle TO_CHAR(create_time, YYYY-MM-DD HH24:MI:SS) AS create_time /when otherwise DATE_FORMAT(create_time, %Y-%m-%d %H:%i:%s) AS create_time /otherwise /choose FROM sys_user WHERE status #{status} choose when test_databaseId oracle ORDER BY id OFFSET #{start} ROWS FETCH NEXT #{limit} ROWS ONLY /when otherwise ORDER BY id LIMIT #{start}, #{limit} /otherwise /choose /select运行时MyBatis 会把_databaseId解析成当前的数据库标识选择对应的 SQL 片段组装出来。这种写法最大的好处是“差异在同一个语句里集中暴露”后续维护时只要看这一个节点就能知道自己维护的库走了哪条逻辑。不过它也有缺点如果差异点很多choose和if嵌套多了XML 的可读性会快速下降。我自己大概是这么取舍的差异片段不超过 SQL 总量的三分之一用姿势 B改到跟重写差不多用姿势 A。4.3 两种姿势的对比与选择建议为了让大家决策得更快我把两种方式的适用场景整理成了表格对比维度姿势 A多套 databaseId 语句姿势 B_databaseId 分支SQL 差异程度差异大基本两套结构差异小局部片段不同XML 可读性每套完整 SQL结构清晰分支多了会显得臃肿维护成本两套都要维护容易漏改差异点在一个语句里一目了然启动加载只加载匹配当前库的语句加载一个语句运行时分段选择适合场景复杂报表、特殊数据库专属写法分页、函数差异、条件拼接实际做项目我一般两种混着用整体查询骨架一致的用姿势 B某几个特别复杂的报表查询用姿势 A。DatabaseId 机制没有限制你在同一个 XML 里只能选一种怎么顺手怎么来。5. 实战一套用户列表查询接口适配 MySQL 与 Oracle5.1 业务需求与 SQL 差异分析假设我们有个用户管理页面要按状态分页查询用户列表并且列表里展示的create_time需要格式化到秒。这个需求在 MySQL 和 Oracle 上有两个明显差异分页语法MySQL 用LIMIT #{start}, #{limit}Oracle 12c 以上可以用OFFSET #{start} ROWS FETCH NEXT #{limit} ROWS ONLY比老套的ROWNUM两层子查询干净得多。日期格式化MySQL 的DATE_FORMAT占位符是%Y-%m-%d %H:%i:%sOracle 的TO_CHAR格式串是YYYY-MM-DD HH24:MI:SS。这个场景用姿势 B 最合适因为整个 SQL 的骨架都是SELECT ... FROM sys_user WHERE status ? ORDER BY id ...只有中间一小段函数和最后的分页段需要切换。5.2 Mapper 接口与 XML 完整实现Mapper 接口没什么特殊的多个参数记得用Param显式命名public interface SysUserMapper extends BaseMapperSysUser { ListMapString, Object selectUserListByStatus( Param(status) Integer status, Param(start) Integer start, Param(limit) Integer limit); }XML 放在resources/mapper目录下?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.demo.mapper.SysUserMapper select idselectUserListByStatus resultTypejava.util.Map SELECT id, name, choose when test_databaseId oracle TO_CHAR(create_time, YYYY-MM-DD HH24:MI:SS) AS create_time /when otherwise DATE_FORMAT(create_time, %Y-%m-%d %H:%i:%s) AS create_time /otherwise /choose FROM sys_user WHERE status #{status} choose when test_databaseId oracle ORDER BY id OFFSET #{start} ROWS FETCH NEXT #{limit} ROWS ONLY /when otherwise ORDER BY id LIMIT #{start}, #{limit} /otherwise /choose /select /mapper特别注意XML 里如果 SQL 片段中出现、、这些特殊字符必须使用转义形式比如lt;代表小于号或者用![CDATA[ ... ]]包裹。上面的例子刻意避开了写成ROWNUM lt; #{limit}这种老写法直接用OFFSET ... FETCH省去转义的麻烦也更贴近现代 Oracle 的最佳实践。接口调用时传status 1, start 0, limit 10MySQL 环境会执行SELECT id, name, DATE_FORMAT(create_time, %Y-%m-%d %H:%i:%s) AS create_time FROM sys_user WHERE status 1 ORDER BY id LIMIT 0, 10Oracle 环境会执行SELECT id, name, TO_CHAR(create_time, YYYY-MM-DD HH24:MI:SS) AS create_time FROM sys_user WHERE status 1 ORDER BY id OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY两者的返回字段结构一致前端完全无感。5.3 本地没有 Oracle怎么验证分支逻辑很多项目本地根本没装 Oracle验证多数据库适配总不能每次跑到客户现场。我的做法是用 H2 数据库的兼容模式去模拟成本极低效果足够验证链路。H2 的DatabaseMetaData.getDatabaseProductName()固定返回H2所以我们需要在 provider 的映射里加一行properties.setProperty(H2, oracle)让 H2 连接在检测时被当成 Oracle 来对待。这样我们可以用同一套代码、同一套 XML切换数据源 URL 就能分别走 MySQL 分支和 Oracle 分支。MySQL 环境连接串spring: datasource: url: jdbc:mysql://localhost:3306/demo driver-class-name: com.mysql.cj.jdbc.Driver模拟 Oracle 环境时把数据源切到 H2 的 Oracle 兼容模式spring: datasource: url: jdbc:h2:mem:demo;MODEOracle;DATABASE_TO_LOWERTRUE;DB_CLOSE_DELAY-1 driver-class-name: org.h2.Driver username: sa password:H2 的 Oracle 模式支持TO_CHAR和OFFSET ... FETCH这些语法足以验证 SQL 分支是否真的切换成功。如果你手头有可用的 MySQL 环境建议真实跑一遍 MySQL 分支Oracle 分支用 H2 模拟这样的组合能覆盖大多数开发场景。6. 高频问题与排查技巧速查6.1 启动报 “Mapped Statements collection already contains value”这个问题我在前面已经预告过。最常见的原因就是XML 里同时存在“不带 databaseId 的默认语句”和“带 databaseId 的语句”而两者 ID 完全相同。配置了DatabaseIdProvider之后不带 databaseId 的语句也会被绑定当前数据库的 ID于是 MyBatis 发现两个同 ID 同 databaseId 的 MappedStatement自然就冲突了。顺着这个思路就能排查检查所有同 ID 的 select/update/insert/delete 节点要么全部去掉 databaseId 属性要么每个环境都显式把 databaseId 写全不要让“默认 特化”混在一起。我在项目里用姿势 B_databaseId分支之后这类问题几乎绝迹。6.2 _databaseId 一直是 null或者分支永远走不对先确认容器里到底有没有注册DatabaseIdProviderBean。没有 provider 时Configuration.getDatabaseId()为 null动态 SQL 里_databaseId oracle永远为 false所有分支都会走otherwise或直接漏掉。再检查VendorDatabaseIdProvider的 Properties 映射 key 是否和驱动返回的DatabaseProductName大小写一致。MySQL 驱动返回MySQL不是你随手写的mysqlSQL Server 驱动返回Microsoft SQL Server中间还有空格。拿不准就直接打印DatabaseProductName看一眼。还有一种情况是数据源没被正确检测。如果项目用了动态数据源provider 在构建 SqlSessionFactory 时连接的是主数据源而实际业务跑在另一个库上_databaseId检测的结果和真实执行库可能对不上需要确认检测数据源与实际业务数据源的关系。6.3 部署到多数据源环境DatabaseId 为什么不动态切换这是很多人最容易产生误解的地方。Configuration.getDatabaseId()是在 SqlSessionFactory 初始化阶段通过 provider 检测数据源后一次性写入的。也就是说DatabaseId 是“部署时确定”的静态值不是“运行中随数据源切换”的动态值。如果项目里用动态数据源方案比如一个 MySQL 库、一个 Oracle 库运行过程中通过DS注解切换数据源此时底层只有一个 SqlSessionFactory它的 databaseId 仍然是初始化时检测到的那个值_databaseId不会跟随切换而变化。这种情况不要指望 DatabaseId 来区分正确做法是每个数据源单独构建 SqlSessionFactory并且为每个 factory 设置对应的DatabaseIdProvider或者在 Mapper 层把多数据库差异抽象成独立接口按数据源类型加载不同的 Mapper 实现。我早期在这上面栽过跟头以为动态数据源 DatabaseId 是万能组合结果切换后 SQL 一直走错分支排查了很久才意识到 databaseId 根本不感知运行时切换。6.4 与 MyBatis Plus 分页插件的协同使用MyBatis Plus 自带的分页插件PaginationInnerInterceptor是另一个维度的方言适配。它负责在 SQL 执行前拦截并改写分页语句本身需要指定数据库方言类型比如new PaginationInnerInterceptor(DbType.MYSQL)。如果你已经用分页插件处理了分页那么 DatabaseId 就不需要再操心LIMIT和OFFSET这些分页差异了只处理函数、语法层面的差异比如前面示例里的日期格式化。两层职责一拆XML 能比上面写的还干净select idselectUserListByStatus resultTypejava.util.Map SELECT id, name, choose when test_databaseId oracle TO_CHAR(create_time, YYYY-MM-DD HH24:MI:SS) AS create_time /when otherwise DATE_FORMAT(create_time, %Y-%m-%d %H:%i:%s) AS create_time /otherwise /choose FROM sys_user WHERE status #{status} ORDER BY id /select分页插件在拦截器层统一处理方言DatabaseId 只管 SQL 片段差异两者互不干扰配合起来很顺。要注意的是如果连接的是动态数据源分页插件的DbType也需要按数据源区分固定写死DbType.MYSQL而在 Oracle 数据源上执行同样会出问题这一点和 DatabaseId 的“静态检测”问题同宗同源。6.5 排查建议把 databaseId 打印进启动日志最后分享一个我自己的小习惯项目启动时一定会把当前 databaseId 打印出来。写法很简单一个ApplicationRunner就够Component public class DatabaseIdStartupLogger implements ApplicationRunner { Resource private SqlSessionFactory sqlSessionFactory; Override public void run(ApplicationArguments args) { System.out.println([databaseId] current databaseId sqlSessionFactory.getConfiguration().getDatabaseId()); } }这样每次部署环境变了、数据源改了第一眼就能确认 MyBatis 到底识别成了什么数据库而不是等到接口调用才发现 SQL 分支不对。这个习惯帮我节省了大量“看起来正常但实则走了错误分支”的排查时间。项目里如果真的同时面对 MySQL、Oracle、PostgreSQL 这类多数据库交付场景DatabaseId 是我目前用下来最顺手的方案。SQL 差异小就塞进_databaseId分支差异大就拆成多套databaseId语句部署到哪里检测到哪里代码仓库里始终只有一套 Mapper。暂时没条件装真实 Oracle 数据库的H2 兼容模式加上映射配置也能把链路跑通本地验证足够了。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
