Skip to content

starter-mybatis ​

1. 职责 ​

把 Spring Boot 应用接到关系库上,并把 MyBatis-Plus 的用法收敛成一套项目规范:统一父类 BaseDO、统一 Mapper 基类 BaseMapperX、统一查询 Wrapper、统一类型处理器与批量方法。

它额外做两件「启动期」的事:按主数据源 URL 推断数据库类型(DbType),自动把 mybatis-plus.global-config.db-config.id-type=NONE 改写成 AUTO 或 INPUT;顺带把 Quartz 的 driverDelegateClass 也按数据库类型填好。

它不解决:多租户 SQL 条件(biz-tenant)、数据权限条件(biz-data-permission)、读写分离本身(由 dynamic-datasource 提供,本 starter 只读它的配置推断类型)、分页结果的 VO 转换(业务自己做)。

本节路径均省略公共前缀 framework/pmforge-spring-boot-starter-mybatis/src/main/java/com/pmforge/framework/。

2. 关键类 ​

类作用路径
BaseDO所有 DO 的父类:createTime、updateTime、creator、updater、deleted(@TableLogic);实现 TransPojo 以支持 easy-transmybatis/core/dataobject/BaseDO.java
DefaultDBFieldHandlerMetaObjectHandler:插入补 4 个字段,更新补 updateTime/updater;creator/updater 取当前登录用户mybatis/core/handler/DefaultDBFieldHandler.java
BaseMapperX<T>Mapper 基类:selectPage(PageParam, Wrapper)、selectJoinPage、selectOne、selectList、insertBatch、updateBatch、deleteBatchmybatis/core/mapper/BaseMapperX.java
LambdaQueryWrapperX / QueryWrapperX / MPJLambdaWrapperXxxxIfPresent 系列,参数为空时自动跳过该条件mybatis/core/query/
EncryptTypeHandlerAES 字段加解密,密钥读 mybatis-plus.encryptor.passwordmybatis/core/type/EncryptTypeHandler.java
LongListTypeHandler / IntegerListTypeHandler / StringListTypeHandler / LongSetTypeHandler逗号分隔字符串 ↔ 集合(对应 MySQL 的「多值字段」)mybatis/core/type/
JdbcUtilsJDBC URL → DbType;MyBatisUtils 负责拦截器注册、表名与列名解析mybatis/core/util/
DbTypeEnumDbType 与中文数据库名的映射mybatis/core/enums/DbTypeEnum.java
PmforgeDataSourceAutoConfiguration事务管理(proxyTargetClass=true)+ Druid 广告过滤datasource/config/PmforgeDataSourceAutoConfiguration.java
DruidAdRemoveFilter把 /druid/js/common.js 响应替换为去掉广告的脚本datasource/core/filter/DruidAdRemoveFilter.java
DataSourceEnumMASTER / SLAVE 数据源名常量datasource/core/enums/DataSourceEnum.java
TranslateUtilseasy-trans 的静态入口,init(TransService) 由自动配置调用translate/core/TranslateUtils.java
IdTypeEnvironmentPostProcessor启动最早期推断 DbType、改写 id-type、填 Quartz delegatemybatis/config/IdTypeEnvironmentPostProcessor.java

3. 自动配置 ​

配置类生效条件注册了什么
PmforgeDataSourceAutoConfiguration始终装配(依赖容器里已有 DataSource/Druid)@EnableTransactionManagement(proxyTargetClass = true);FilterRegistrationBean<DruidAdRemoveFilter>,仅当 spring.datasource.druid.stat-view-servlet.enabled=true
PmforgeMybatisAutoConfiguration@AutoConfiguration(before = MybatisPlusAutoConfiguration.class),避免 @MapperScan 先扫到 Mapper 打 warn@MapperScan(value="${pmforge.info.base-package}", annotationClass=Mapper.class);MybatisPlusInterceptor(只加分页);MetaObjectHandler = DefaultDBFieldHandler;IKeyGenerator(仅 id-type=INPUT);给 JacksonTypeHandler 注入主 ObjectMapper
PmforgeTranslateAutoConfiguration@ConditionalOnBean(TransService.class)TranslateUtils.init(transService),翻译能力就绪
IdTypeEnvironmentPostProcessor通过 META-INF/spring.factories 注册,早于容器刷新推断 DbType → 改写 id-type;写 Quartz jobStore.driverDelegateClass

启动期改写规则(postProcessEnvironment):先读 spring.datasource.dynamic.primary 与其 .url,推不出 DbType 就直接返回;再看 id-type,不是 NONE 就不动;是 NONE 时 Oracle/PostgreSQL/Kingbase/DB2/H2 → INPUT,其余(MySQL、达梦等自增库)→ AUTO。

4. 配置项 ​

前缀键默认值说明
mybatis-plus.global-config.db-configid-typeNONE(示例配置)框架约定的「智能」值:启动时由 EPP 改写为 AUTO/INPUT
mybatis-plus.global-config.db-configlogic-delete-value / logic-not-delete-value1 / 0逻辑删除值
mybatis-plus.configurationmap-underscore-to-camel-casetrue下划线转驼峰
mybatis-plustype-aliases-package${pmforge.info.base-package}.module.*.dal.dataobjectDO 别名包
mybatis-plusencryptor.passwordXDV71a+xqStEA3WH(示例值,生产必须换)EncryptTypeHandler 的 AES 密钥
mybatislazy-initializationfalse透传给 @MapperScan(lazyInitialization=...)
pmforge.infobase-packagecom.pmforgeMapper 扫描根包,改包名只改这一处
spring.datasource.dynamicprimarymasterEPP 推断数据库类型的主数据源名
spring.datasource.druid.stat-view-servletenabledtrue(示例)关掉后不再注册 Druid 广告过滤

5. 扩展点 ​

  • Mapper 写法:interface XxxMapper extends BaseMapperX<XxxDO>,直接获得分页与批量;只要 BaseMapper 就得自己拼 Page。
  • 条件构造:用 LambdaQueryWrapperX 的 eqIfPresent/likeIfPresent,避免 if (str != null) 铺满 Service。
  • 字段加密:DO 字段标 @TableField(typeHandler = EncryptTypeHandler.class);已有密文无法用新密钥解开,换密钥前必须迁移数据。
  • 日期/JSON/集合字段:JSON 用 MyBatis-Plus 的 JacksonTypeHandler(框架已注入主 ObjectMapper),集合用本模块的 *ListTypeHandler。
  • 新增拦截器:业务侧建 MybatisPlusInterceptor 时注意顺序——租户与数据权限插件都以 MyBatisUtils.addInterceptor(interceptor, inner, 0) 抢占第 0 位(必须早于分页),自己追加请复制同样的顺序约定。
  • 翻译字段:VO 加 easy-trans 的 @Trans,并实现 TransService Bean,TranslateUtils 会由 PmforgeTranslateAutoConfiguration 初始化。

6. 常见坑 ​

  1. 主键策略被「智能改写」是有前提的:EPP 只认 spring.datasource.dynamic.primary + datasource.<primary>.url。手工写 spring.datasource.url 时推不出 DbType,id-type 会保持 NONE,插入报「主键未设置」。
  2. BlockAttackInnerInterceptor 被注释掉了(PmforgeMybatisAutoConfiguration 中)——注释写明它会「影响 updateBatch」,代价是无条件 update/delete 全表不会被拦。
  3. DefaultDBFieldHandler 依赖登录上下文:creator/updater 来自 SecurityFrameworkUtils.getLoginUserId(),在定时任务、MQ 消费、@Async 线程里为 null,字段若 NOT NULL 会插入失败——这正是 mybatis 反向依赖 security 的原因。
  4. Quartz 的 delegate 是「猜」出来的,且只认 5 种库:setJobStoreDriverIfPresent 依次匹配 POSTGRE_SQL、ORACLE/ORACLE_12C、SQL_SERVER/SQL_SERVER2005、DM/KINGBASE_ES,MySQL 等不匹配的库保持 Quartz 默认;写入位置是 environment.getSystemProperties().put(...)(systemProperties property source,不是 spring.quartz.* 配置),并且该键已有值时直接 return——想在 yaml 里覆盖它,必须自己写 spring.quartz.properties.org.quartz.jobStore.driverDelegateClass。
  5. EncryptTypeHandler 的注释与实现不一致:类注释说「可通过 jasypt.encryptor.password 配置」,实际读的是 mybatis-plus.encryptor.password。
  6. 启动时 JsqlParserGlobal.setJsqlParseCache(...) 设置的是全局静态解析缓存(1024 条 / 5 秒过期),影响所有用 JSqlParser 的插件(租户、数据权限)。

7. 关联页面 ​