最开始接到这个需求时我以为只是给 MyBatis 的databaseId写个配置模板真正动手才发现Spring Boot MyBatis Plus 项目里要把DatabaseId用好涉及的细节远比想象中多自动装配、XML 加载机制、动态上下文变量、分页与方言的边界……哪一个没搞透都会在生产环境给你埋雷。这篇文章不打算写成 API 文档的复述而是从一个真实遇到过的问题出发同一套系统要在 MySQL 和 PostgreSQL 上部署BaseMapper 的自带 CRUD 完全没问题分页插件也能自动处理但自定义 SQL 里那句LIMIT #{offset}, #{size}在 PG 环境直接翻车。我花了一个下午排查最后把眼光落到了 MyBatis 的 DatabaseId 机制上。如果你也在做多数据库兼容或者正在从单数据库迁移到另一种数据库这篇文章应该能帮你少走不少弯路。1. DatabaseId 解决了什么问题一段先踩坑的经历1.1 从一条分页 SQL 说起项目是一个典型的 Spring Boot MyBatis Plus 单体服务开发阶段一直跑在 MySQL 8 上。某个客户要求部署到 PostgreSQL 环境我本以为 MyBatis Plus 的分页插件已经做了方言适配换库只是改个数据源配置的事。结果客户环境一启动跑批任务只处理了前十条数据就“正常结束”了。查日志发现某个自定义 Mapper 方法里写的是select idselectPendingOrders resultTypecom.example.entity.Order SELECT * FROM t_order WHERE status PENDING ORDER BY create_time LIMIT #{offset}, #{size} /select在 MySQL 里LIMIT 20, 10表示跳过 20 条取 10 条但在 PostgreSQL 里LIMIT后面只能跟一个参数实现“取多少条”“跳过多少条”必须用OFFSET。于是LIMIT 20, 10在 PG 中变成了“取 20 条后忽略 10 条”实际只返回 10 条跑批任务以为处理完了后续的数据全被漏掉。这个 bug 不报错、不警告只在数据量超过分页阈值后静默出错是最难排查的那一类问题。1.2 我试过的几种方案问题确认后我列了几种候选方案挨个评估改代码适配把所有自定义 SQL 里的分页语法改成兼容写法。听上去简单但项目里类似 SQL 有几十处而且 MySQL 和 PG 的日期函数、序列、树形查询都有差异改一处漏一处。按环境加载不同 Mapper XML用 Spring Profile 控制扫描不同目录下的 XML。能解决问题但同一个方法要维护两份 XML公共部分无法复用改字段时要同步改多处维护成本高。用 MyBatis 的 DatabaseId同一个statement id下根据当前数据库自动选择对应 SQL 片段。这套机制是 MyBatis 原生的不依赖 Spring也不需要额外引入依赖。我当然选了第三种也因为这条路踩了几个坑才把整个机制彻底翻了一遍。1.3 MyBatis 为什么会设计 DatabaseId简单说Mapper 接口的方法名相当于一个“查询接口”SQL 是它的“实现”。当同一个接口需要在不同数据库上给出不同实现时MyBatis 希望你能在statement上标注一个databaseId属性运行环境是什么数据库就加载哪条 SQL。这就好比同一把钥匙要能开不同锁芯的锁钥匙的齿形不同但拿钥匙的手是同一个。它和单纯的“多环境配置”最大的区别是数据库 ID 不是靠 Spring Profile 事先写死的而是 MyBatis 在运行时主动检查当前DataSource的DatabaseMetaData.getDatabaseProductName()再通过DatabaseIdProvider映射成一个短 ID。这意味着同一套代码、同一个配置包在 MySQL、PostgreSQL 上部署时能自动选择对应的 SQL 分支不需要改任何外部配置。2. Spring Boot MyBatis Plus 中配置 DatabaseIdProvider2.1 注册 DatabaseIdProvider BeanMyBatis 提供了一个具体的实现类VendorDatabaseIdProvider它负责读取数据库产品名再跟自定义映射表做比对输出一个我们约定的短 ID。Spring Boot 环境下只需要在配置类里声明一个 Beanpackage com.example.config; import org.apache.ibatis.mapping.DatabaseIdProvider; import org.apache.ibatis.mapping.VendorDatabaseIdProvider; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import java.util.Properties; Configuration public class MybatisDatabaseIdConfig { Bean public DatabaseIdProvider databaseIdProvider() { VendorDatabaseIdProvider provider new VendorDatabaseIdProvider(); Properties props new Properties(); props.setProperty(MySQL, mysql); props.setProperty(Oracle, oracle); props.setProperty(PostgreSQL, postgresql); props.setProperty(Microsoft SQL Server, sqlserver); props.setProperty(H2, h2); props.setProperty(SQLite, sqlite); provider.setProperties(props); return provider; } }这里的 key 是数据库产品名也就是DatabaseMetaData.getDatabaseProductName()返回的原始值value 是我们希望 MyBatis 使用的短 ID。以后在 XML 里写databaseIdmysql还是databaseIdpostgresql都以这里的 value 为准。有人会问VendorDatabaseIdProvider不是自带默认映射吗为什么还要自己配置因为默认映射在不同 MyBatis 版本里有差别比如 SQL Server 在旧版本里映射成ms-sql新版本又可能是sqlserver与其依赖版本行为不如显式声明至少在团队内部能形成一个统一约定。2.2 它是怎么被自动装配的如果你用的是mybatis-plus-boot-starterMyBatis Plus 的自动配置类在创建SqlSessionFactory时会从 Spring 容器里找DatabaseIdProvider类型的 Bean找到后调用factory.setDatabaseIdProvider(...)注入进去。所以上面的Bean声明完之后理论上不需要再写别的代码。这个“理论上”有个前提你没有手动创建自定义的SqlSessionFactoryBean。如果你因为某些特殊需求自己写了一个Bean SqlSessionFactory那就得手动调用factory.setDatabaseIdProvider(databaseIdProvider())否则自动配置的逻辑会被整个覆盖掉。这也是我后来在一个老项目里排查半天才发现的隐藏问题。2.3 如何快速确认配置生效配置完成后第一步不是急着写 SQL而是先确认Configuration里的databaseId被正确赋值。最简单的办法是写一个集成测试打印出来SpringBootTest class DatabaseIdVerificationTest { Autowired private SqlSessionFactory sqlSessionFactory; Test void printCurrentDatabaseId() { String databaseId sqlSessionFactory.getConfiguration().getDatabaseId(); System.out.println(current databaseId databaseId); } }如果输出的是mysql、postgresql这样的值说明 Provider 装配成功如果输出null哪怕 XML 里写了databaseId属性对应 SQL 也根本不会被加载。这个“输出为 null”的情况我在后面第五节会详细讲是一个很容易踩的坑。3. XML SQL 中 databaseId 的两种用法3.1 独立分支同一个 statement id 按数据库区分最直观的用法是在同一条select上写两个不同的databaseIdselect idselectPendingOrders resultTypecom.example.entity.Order databaseIdmysql SELECT * FROM t_order WHERE status PENDING ORDER BY create_time LIMIT #{offset}, #{size} /select select idselectPendingOrders resultTypecom.example.entity.Order databaseIdpostgresql SELECT * FROM t_order WHERE status PENDING ORDER BY create_time LIMIT #{size} OFFSET #{offset} /select调用方依然是orderMapper.selectPendingOrders(page, size)完全感知不到底层有两个 SQL 分支。MyBatis 在解析 XML 时会按当前环境筛选当前是 MySQL就加载databaseIdmysql的语句当前是 PG就加载databaseIdpostgresql的语句其他分支会被直接丢弃。这样就实现了“同一接口多数据库实现”代码层零侵入。这种写法的好处是每个分支的 SQL 都很纯粹不容易因为动态判断造成 SQL 拼接顺序混乱坏处则是复制量大如果 SQL 有 50 行两个分支就是 100 行后续调整字段时很容易漏改其中一个分支。3.2 合并写法用动态上下文变量 _databaseId 判断如果两个数据库的 SQL 整体结构一致只有某个局部语法不同那么更推荐用 MyBatis 提供的上下文变量_databaseId做局部动态判断select idselectPendingOrders resultTypecom.example.entity.Order SELECT * FROM t_order WHERE status PENDING ORDER BY create_time choose when test_databaseId mysql LIMIT #{offset}, #{size} /when when test_databaseId postgresql LIMIT #{size} OFFSET #{offset} /when otherwise LIMIT #{offset}, #{size} /otherwise /choose /select_databaseId是 MyBatis 在配置DatabaseIdProvider后注入到上下文里的一个隐藏变量可以直接在 OGNL 表达式中访问。这里要注意它的值必须和VendorDatabaseIdProvider里配置的 value 完全一致大小写也要一致。这种写法的核心优势是“增量式差异”先写一个默认版本再在分歧点做微调而不是把整个 SQL 复制一份。项目里如果多数据库支持会越来越多我一般更倾向于这种写法因为它在代码阅读时一眼就能看出不同数据库之间的差异点到底在哪。3.3 两种写法的取舍以及注解 SQL 的边界选择标准其实不难差异点多、每个分支的 SQL 差异很大时用独立分支90% 相同、只有一两句方言不同时用_databaseId。我的经验法则是一段 SQL 超过 30 行就尽量用独立分支否则动态判断嵌套太多OGNL 表达式反而变成了可读性杀手。另外注意注解 SQL比如Select(...)本身不支持声明databaseId属性。如果想在注解场景做方言分支只能通过SelectProvider的方式在 Provider 类里根据当前环境手动拼 SQL。但这里有两个麻烦一是 Provider 方法里拿_databaseId不方便二是字符串拼接 SQL 可读性远不如 XML。所以我的建议很直接凡是涉及方言分支的 SQL一律放到 XML 里写注解 SQL 只处理那些“各数据库写法一致”的简单查询。4. 实际项目中的多数据库兼容设计分页、主键、日期与树形4.1 分页差异不要把方言写死在 SQL 里分页是方言差异的重灾区。除了文章开头提到的 MySQL 和 PG 的LIMIT/OFFSET差异Oracle 12c 之前用ROWNUM包三层子查询12c 之后可以用FETCH FIRSTSQL Server 则是TOPROW_NUMBER()。如果每个库都自己写一套完整分页维护量会非常大。更合理的做法是把分页参数交给 MyBatis Plus 的分页插件让PaginationInnerInterceptor根据方言统一包装 SQL。你在 XML 里只写WHERE和ORDER BY不要自己写LIMITselect idselectPendingOrders resultTypecom.example.entity.Order SELECT * FROM t_order WHERE status PENDING ORDER BY create_time /selectMapper 方法接收IPage参数分页插件会在执行前自动帮你在 SQL 尾部追加对应方言的分页语法。这样MySQL、PG、Oracle、SQL Server 的物理分页全部交给拦截器databaseId只需要处理那些“分页插件管不到”的方言问题。但要特别提醒如果你的自定义 SQL 里已经手动写了LIMIT又同时配置了分页插件插件会在外层再包一层分页结果就是出现“分页套分页”的诡异 SQL数据量一大就会出现重复或丢失。所以用 MyBatis Plus 的分页能力时SQL 里就不要自己写分页关键字这是团队代码规范里必须写明的一条。4.2 插入主键生成自增与序列的典型写法自增主键和序列的差异也是多数据库兼容里绕不开的问题。MySQL 依赖AUTO_INCREMENTOracle 和 PostgreSQL 早期版本依赖序列对象。使用databaseId可以优雅地区分insert idinsertOrder parameterTypecom.example.entity.Order useGeneratedKeystrue keyPropertyid databaseIdmysql INSERT INTO t_order(order_no, amount, status) VALUES (#{orderNo}, #{amount}, #{status}) /insert insert idinsertOrder parameterTypecom.example.entity.Order databaseIdoracle selectKey keyPropertyid orderBEFORE resultTypejava.lang.Long SELECT SEQ_ORDER_ID.NEXTVAL FROM DUAL /selectKey INSERT INTO t_order(id, order_no, amount, status) VALUES (#{id}, #{orderNo}, #{amount}, #{status}) /insert注意selectKey的order属性Oracle 需要在插入前先取序列值所以orderBEFOREMySQL 需要在插入后通过LAST_INSERT_ID()拿自增主键所以交给useGeneratedKeys处理。这些细节如果不用databaseId区分就只能通过代码里冗长的if判断来处理非常不优雅。4.3 日期函数与树形查询的差别日期获取函数在不同数据库里差异也很大MySQL 是NOW()Oracle 是SYSDATEPostgreSQL 是CURRENT_TIMESTAMPSQL Server 是GETDATE()。如果 SQL 里要取当前时间做判断建议优先通过 Java 层统一传入时间参数而不是在 SQL 里写数据库特有函数这样能从源头上减少方言分支。实在要在 SQL 里获取当前时间时可以借助_databaseId做局部判断select idselectTodayOrders resultTypecom.example.entity.Order SELECT * FROM t_order WHERE create_time ![CDATA[ ]] choose when test_databaseId mysqlNOW()/when when test_databaseId oracleSYSDATE/when when test_databaseId postgresqlCURRENT_TIMESTAMP/when otherwiseNOW()/otherwise /choose /select树形查询更是方言差异的重灾区。Oracle 有CONNECT BY PRIORMySQL 8 可以用WITH RECURSIVE但老版本 MySQL 只能靠递归存储过程或者程序递归。这种场景很难用统一的 SQL 表达用databaseId独立分支是最实际的方案——因为每个分支的 SQL 结构完全不同硬要合并成一个动态 SQL反而会让代码没法看。4.4 与 MyBatis Plus 分页插件的边界最后要把这条边界划清楚MyBatis Plus 的分页插件解决的是“物理分页语法”问题databaseId解决的是“SQL 本身在不同数据库上的方言差异”问题。两者不冲突但也不能互相替代。分页插件处理的是最终 SQL 的包装它不知道你 SQL 里的GROUP_CONCAT、CONNECT BY、序列取值这些方言写法是否兼容目标数据库。所以我的项目分工是能用BaseMapper和LambdaQueryWrapper解决的查询绝不写自定义 SQL必须写自定义 SQL 时先思考分页是否交给插件再思考哪些局部语法需要databaseId分支最后考虑这段 SQL 是不是差异太大直接拆成独立分支更清晰。5. databaseId 的加载匹配逻辑与最容易踩的坑5.1 源码里的判断逻辑排查问题的过程中我翻了一下 MyBatis 解析 Mapper XML 的源码发现它对databaseId的处理逻辑大致是这样的从 XML 节点上读取databaseId属性。如果Configuration.getDatabaseId()不为 null说明 Provider 装配成功那么只有满足“databaseId属性为空”或“databaseId属性等于当前值”的语句才会被加载。如果Configuration.getDatabaseId()为 null说明 Provider 没装配上那么带有databaseId属性的语句会被直接跳过不带databaseId的语句正常加载。这个逻辑解释了一个非常容易踩的坑在 XML 里写了databaseIdmysql但容器里没有注册DatabaseIdProvider那么这条 SQL 不会被加载运行时会报Invalid bound statement (not found)。我当时排查时第一反应是 Mapper XML 没扫到检查了半天扫描路径最后才发现是 Provider 没生效。5.2 坑Bean 注册了但没有生效DatabaseIdProviderBean 注册了但Configuration.getDatabaseId()仍然是 null这种情况我遇到过几次原因通常是这三个之一第一项目里自定义了SqlSessionFactoryBean把自动配置的注入逻辑覆盖掉了。这种情况需要在自定义工厂里手动setDatabaseIdProvider。第二用了老版本 MyBatis Plus自动配置类不支持读取DatabaseIdProvider。升级到较新的 3.5.x 版本或者自己手动加工厂配置。第三多数据源场景下某个SqlSessionFactory绑定的是代理数据源产品名可能被代理包装掩盖导致获取不到真实的数据库产品名。动态数据源项目里最好确认一下DatabaseMetaData拿到的产品名是目标库的而不是连接池代理层返回的。5.3 坑大小写与 SQL Server 的别名databaseId的值是大小写敏感的。_databaseId MySQL和_databaseId mysql完全是两个概念。我习惯在配置里统一用小写短 ID团队代码规范里也明确要求小写避免后面一群人各自写各自的大小写。另一个细节是 SQL Server 的映射。VendorDatabaseIdProvider的默认映射在不同版本里不一样曾经有一段时期默认输出是ms-sql而不是sqlserver。如果你不显式配置映射表而是依赖默认行为那么在 XML 里写databaseIdsqlserver就永远匹配不上。解决办法就是我在第二节里写的不要依赖默认映射显式声明 properties让团队内部 ID 统一可控。5.4 坑不要把 databaseId 用在公共 sql 片段上我在项目里习惯把公共查询字段抽成sql idBaseColumnList一开始想当然地给sql片段也加了databaseId属性结果发现加载行为很奇怪部分语句能用部分报错。排查后确认databaseId最好只用在select/insert/update/delete这些最终语句节点上用在sql片段上时各版本解析行为不完全一致容易产生“片段被跳过但引用者还在”的状态。稳妥做法是sql片段只抽那些“所有数据库写法一致”的内容一旦片段本身存在方言差异就不要抽出来了直接在最终分支里分别写。5.5 坑公共 SQL 想省事用了不兼容的函数最后一个坑不是配置上的而是写 SQL 时的惯性思维。比如 MySQL 的GROUP_CONCAT、DATE_FORMAT在 PG 里对应的是STRING_AGG、TO_CHAR写法完全不同。如果你在一个没有databaseId分支的 SQL 里使用了这类函数换库之后要么直接报错要么返回错误结果。这类问题属于“代码审查死区”因为开发环境永远是 MySQL只有到了客户环境才暴露。我现在的做法是涉及这类函数时即使只有一个数据库在用也要把这段 SQL 设计成带databaseId的可扩展结构并预留另一分支的占位实现逼着自己思考兼容性问题。6. 我的几点实操体会这套机制完整跑通后回头再看有几点体会比较深。第一不要等客户环境出问题再配置DatabaseId。如果项目定位是“可能多数据库部署”在项目第一天就应该把DatabaseIdProviderBean 配上哪怕所有 XML 暂时都不写databaseId也不会产生任何副作用但后续需要分支时直接就能用。第二_databaseId和独立分支不是二选一可以混用。我的原则是局部方言差异用_databaseId整体 SQL 结构差异大就用独立分支。两种方式共存并不冲突关键是团队规范里要写明“什么场景用哪种”。第三多数据库兼容的最终保障是集成测试。我在项目里搭了一个测试配置用 H2 模拟一部分 MySQL 行为再单独建一个 PostgreSQL 测试实例CI 里会同时跑一遍完整 Mapper 的集成测试。只有自动化测试能防止“改了一边忘了另一边”的低级错误。最后分享一个小技巧如果你只是某个复杂报表 SQL 需要多库分支又不想全局注册DatabaseIdProvider可以先不启用databaseId在Mapper.xml里用${databaseType}这种自定义变量来代替。但这种方式需要手动在参数里传入数据库类型不够透明所以我最终仍然选择了全局 Provider因为从长期维护角度看让 MyBatis 自己感知数据库类型才是最省心的方案。