主题
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-trans | mybatis/core/dataobject/BaseDO.java |
DefaultDBFieldHandler | MetaObjectHandler:插入补 4 个字段,更新补 updateTime/updater;creator/updater 取当前登录用户 | mybatis/core/handler/DefaultDBFieldHandler.java |
BaseMapperX<T> | Mapper 基类:selectPage(PageParam, Wrapper)、selectJoinPage、selectOne、selectList、insertBatch、updateBatch、deleteBatch | mybatis/core/mapper/BaseMapperX.java |
LambdaQueryWrapperX / QueryWrapperX / MPJLambdaWrapperX | xxxIfPresent 系列,参数为空时自动跳过该条件 | mybatis/core/query/ |
EncryptTypeHandler | AES 字段加解密,密钥读 mybatis-plus.encryptor.password | mybatis/core/type/EncryptTypeHandler.java |
LongListTypeHandler / IntegerListTypeHandler / StringListTypeHandler / LongSetTypeHandler | 逗号分隔字符串 ↔ 集合(对应 MySQL 的「多值字段」) | mybatis/core/type/ |
JdbcUtils | JDBC URL → DbType;MyBatisUtils 负责拦截器注册、表名与列名解析 | mybatis/core/util/ |
DbTypeEnum | DbType 与中文数据库名的映射 | mybatis/core/enums/DbTypeEnum.java |
PmforgeDataSourceAutoConfiguration | 事务管理(proxyTargetClass=true)+ Druid 广告过滤 | datasource/config/PmforgeDataSourceAutoConfiguration.java |
DruidAdRemoveFilter | 把 /druid/js/common.js 响应替换为去掉广告的脚本 | datasource/core/filter/DruidAdRemoveFilter.java |
DataSourceEnum | MASTER / SLAVE 数据源名常量 | datasource/core/enums/DataSourceEnum.java |
TranslateUtils | easy-trans 的静态入口,init(TransService) 由自动配置调用 | translate/core/TranslateUtils.java |
IdTypeEnvironmentPostProcessor | 启动最早期推断 DbType、改写 id-type、填 Quartz delegate | mybatis/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-config | id-type | NONE(示例配置) | 框架约定的「智能」值:启动时由 EPP 改写为 AUTO/INPUT |
mybatis-plus.global-config.db-config | logic-delete-value / logic-not-delete-value | 1 / 0 | 逻辑删除值 |
mybatis-plus.configuration | map-underscore-to-camel-case | true | 下划线转驼峰 |
mybatis-plus | type-aliases-package | ${pmforge.info.base-package}.module.*.dal.dataobject | DO 别名包 |
mybatis-plus | encryptor.password | XDV71a+xqStEA3WH(示例值,生产必须换) | EncryptTypeHandler 的 AES 密钥 |
mybatis | lazy-initialization | false | 透传给 @MapperScan(lazyInitialization=...) |
pmforge.info | base-package | com.pmforge | Mapper 扫描根包,改包名只改这一处 |
spring.datasource.dynamic | primary | master | EPP 推断数据库类型的主数据源名 |
spring.datasource.druid.stat-view-servlet | enabled | true(示例) | 关掉后不再注册 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,并实现TransServiceBean,TranslateUtils会由PmforgeTranslateAutoConfiguration初始化。
6. 常见坑
- 主键策略被「智能改写」是有前提的:
EPP只认spring.datasource.dynamic.primary+datasource.<primary>.url。手工写spring.datasource.url时推不出DbType,id-type会保持NONE,插入报「主键未设置」。 BlockAttackInnerInterceptor被注释掉了(PmforgeMybatisAutoConfiguration中)——注释写明它会「影响 updateBatch」,代价是无条件update/delete全表不会被拦。DefaultDBFieldHandler依赖登录上下文:creator/updater来自SecurityFrameworkUtils.getLoginUserId(),在定时任务、MQ 消费、@Async线程里为null,字段若NOT NULL会插入失败——这正是 mybatis 反向依赖 security 的原因。- Quartz 的 delegate 是「猜」出来的,且只认 5 种库:
setJobStoreDriverIfPresent依次匹配POSTGRE_SQL、ORACLE/ORACLE_12C、SQL_SERVER/SQL_SERVER2005、DM/KINGBASE_ES,MySQL 等不匹配的库保持 Quartz 默认;写入位置是environment.getSystemProperties().put(...)(systemPropertiesproperty source,不是spring.quartz.*配置),并且该键已有值时直接 return——想在 yaml 里覆盖它,必须自己写spring.quartz.properties.org.quartz.jobStore.driverDelegateClass。 EncryptTypeHandler的注释与实现不一致:类注释说「可通过jasypt.encryptor.password配置」,实际读的是mybatis-plus.encryptor.password。- 启动时
JsqlParserGlobal.setJsqlParseCache(...)设置的是全局静态解析缓存(1024 条 / 5 秒过期),影响所有用 JSqlParser 的插件(租户、数据权限)。
7. 关联页面
- pmforge-common:
PageParam/PageResult/ServiceException - starter-test:
BaseDbUnitTest直接@Import本模块的自动配置 - starter-biz-tenant:
TenantLineInnerInterceptor挂在第 0 位 - starter-biz-data-permission:基于 JSqlParser 的 WHERE 条件
- 横切机制、数据源与多库、代码生成