tape-mybatis-generator-plugin

MyBatis 代码生成插件（基于 MyBatis Generator 1.4.1 开发，Maven 插件建议使用 1.4.0+）

功能特性

本插件为 MyBatis Generator 提供了以下增强功能：

1. TapeMybatisGeneratorPlugin — 扩展 Mapper（selectPrimaryKeyByExample、batchInsert）与 Example（分页、回收站筛选等）
2. TapeTableRepositoryGeneratorPlugin — 为非视图表生成 Repository 接口与实现，提供 CRUD、软删除与回收站
3. TapeViewRepositoryGeneratorPlugin — 为视图表生成 View Repository 接口与实现，提供只读查询

视图表识别：通过 JDBC 元数据 tableType == "VIEW" 判断；非视图表与视图表由不同插件分别生成代码。

运行时依赖：生成的 Repository 使用 Spring @Repository、@Resource 及 SLF4J，使用方项目需引入对应依赖。

插件说明

TapeMybatisGeneratorPlugin

扩展 MyBatis Mapper 与 Example 类：

Mapper 接口 / XML

• selectPrimaryKeyByExample(Example) — 按条件查询主键列表（支持 Example 分页 limit）
• batchInsert(List<Model>) — 批量插入，返回影响行数

Mapper XML 动态 SQL

• 为 selectByExample、selectByExampleWithBLOBs、selectAll 等查询追加 limit 片段（rows / offset）

TapeTableRepositoryGeneratorPlugin

为非视图表生成 Repository（类名后缀由 domainRepositoryType 控制，默认 Repository）：

• 接口：{facadeRepositoryPackage}.I{TableName}{domainRepositoryType}
• 实现：{domainRepositoryPackage}.{TableName}{domainRepositoryType}Impl

示例（默认后缀）：IYourTableNameRepository、YourTableNameRepositoryImpl

生成的方法（均声明 throws Throwable）：

方法	说明
trashById(long id) → int	移入回收站（is_hidden=1）
trashAll(Example) → int	批量移入回收站；自动限定 is_delete=0 且 is_hidden=0
deleteById(long id, boolean release) → int	release=false 软删；release=true 物理删除
deleteAll(Example, boolean release) → int	release=false 仅软删回收站中记录（is_hidden=1）；release=true 直接 deleteByExample
recoverById(long id) → int	从回收站恢复
recoverAll(Example) → int	批量恢复；自动限定 is_delete=0 且 is_hidden=1
findAnyById(long id) → Model	未删除（is_delete=0），不区分是否在回收站
findValidById(long id) → Model	有效数据（is_hidden=0 且 is_delete=0）
findTrashById(long id) → Model	回收站数据（is_hidden=1 且 is_delete=0）
findOne(Example) → Model	单条（内部 usePage(1,1)）
getList(Example) → List<Model>	列表；按 resultType 过滤；含 BLOB 且分页时先查主键再查详情
count(Example) → long	计数（含 resultType 过滤）
countWithPage(Example) → long	仅当 offset、rows 均已设置时调用 count，否则返回 0
insert(Model) → Model	插入并返回带 GUID 的记录
batchInsert(List<Model>) → List<Model>	批量插入并返回记录列表
update(Model) → int	按主键更新（支持乐观锁）
updateByExampleSelective(Model, Example) → int	按条件选择性更新

TapeViewRepositoryGeneratorPlugin

为视图表生成 View Repository（类名后缀由 domainViewRepositoryType 控制，默认 Repository）：

• 接口：{facadeViewRepositoryPackage}.I{TableName}{domainViewRepositoryType}
• 实现：{domainViewRepositoryPackage}.{TableName}{domainViewRepositoryType}Impl

示例（默认后缀）：IYourTableNameRepository、YourTableNameRepositoryImpl

生成的方法（均声明 throws Throwable）：

方法	说明
findOne(Example) → Model	单条
getList(Example) → List<Model>	列表（支持 Example 分页；含 BLOB 时按 withBLOBs 选择查询方法）
count(Example) → long	计数
countWithPage(Example) → long	行为同表 Repository

Example 类增强（TapeMybatisGeneratorPlugin）

所有表/视图共有的字段与方法：

字段 / 方法	说明
offset、rows	分页偏移与条数
startPageNum	起始页码（默认 1，表级可覆盖）
ignorePageSize	usePage 时若 pageSize >= 该值则取消分页（默认 10000）
maxPageSize	usePage 时每页上限（默认 100）
limit(rows) / limit(offset, rows)	设置分页
limitOffset(offset, rows)	设置 offset，rows 置为极大值（仅偏移）
usePage(pageNum, pageSize)	按页码计算 offset/rows
getPageNum() / getPageSize() / getOffset() / getRows()	读取分页状态；未设 rows 时 getPageSize() 返回 ignorePageSize
getLimitString() / getWhereString()	调试用 limit/where 字符串
cloneExample()	克隆条件与分页状态
get/setMaxPageSize、get/setIgnorePageSize、get/setStartPageNum	分页参数读写

仅非视图表额外支持：

字段 / 方法	说明
resultType	null（默认，等同有效数据）、any、trash、valid
setResultType / resultAny / resultTrash / resultValid	设置筛选类型
isResultAny / isResultTrash / isResultValid	isResultValid 在既非 any 也非 trash 时为 true（含 resultType==null）

仅含 BLOB 列的表/视图：

字段 / 方法	说明
withBLOBs	默认 true
setWithBLOBs / isWithBLOBs	是否查询 BLOB 列

getList / count 在表 Repository 中会根据 resultType 自动附加 is_hidden、is_delete 条件。

使用方法

1. 在 pom.xml 中配置插件

<build>
    <finalName>application</finalName>
    <plugins>
        <plugin>
            <groupId>org.mybatis.generator</groupId>
            <artifactId>mybatis-generator-maven-plugin</artifactId>
            <version>1.4.0</version>
            <configuration>
                <configurationFile>src/main/resources/mybatis.generator.xml</configurationFile>
                <overwrite>true</overwrite>
                <verbose>true</verbose>
            </configuration>
            <executions>
                <execution>
                    <id>Generate MyBatis Artifacts</id>
                    <phase>deploy</phase>
                    <goals>
                        <goal>generate</goal>
                    </goals>
                </execution>
            </executions>
            <dependencies>
                <dependency>
                    <groupId>mysql</groupId>
                    <artifactId>mysql-connector-java</artifactId>
                    <scope>runtime</scope>
                    <version>8.0.33</version>
                </dependency>
                <dependency>
                    <groupId>com.iqudoo.framework</groupId>
                    <artifactId>tape-mybatis-generator-plugin</artifactId>
                    <version>1.0-SNAPSHOT</version>
                    <systemPath>${project.basedir}/src/lib/tape-mybatis-generator-plugin-1.0-SNAPSHOT.jar</systemPath>
                    <scope>system</scope>
                </dependency>
            </dependencies>
        </plugin>
    </plugins>
</build>

2. 在 mybatis.generator.xml 中配置插件

<context id="Mysql" targetRuntime="MyBatis3">
   <property name="targetProject" value="src/main/java"/>
   <property name="mapperPackage" value="com.iqudoo.platform.application.database.mapper"/>
   <property name="modelPackage" value="com.iqudoo.platform.application.database.model"/>
   <property name="facadeRepositoryPackage" value="com.iqudoo.platform.application.facade.repository"/>
   <property name="domainRepositoryPackage" value="com.iqudoo.platform.application.domain.repository"/>
   <property name="domainRepositoryType" value="Repository"/>
   <property name="facadeViewRepositoryPackage" value="com.iqudoo.platform.application.facade.repoview"/>
   <property name="domainViewRepositoryPackage" value="com.iqudoo.platform.application.domain.repoview"/>
   <property name="domainViewRepositoryType" value="Repository"/>
   <property name="guidGeneratorClass" value="com.iqudoo.framework.tape.modules.utils.SnowflakeUtil"/>
   <property name="guidGeneratorCode" value="SnowflakeUtil.nextId()"/>
   <property name="changeLogContextClassPackage" value="com.iqudoo.platform.application.domain.changeLog"/>
   <property name="changeLogContextClassName" value="ChangeLogContext"/>
   <property name="changeLogEnable" value="false"/>
   <property name="slowQueryLoggerTime" value="300"/>
   <property name="slowQueryLoggerLevel" value="error"/>
   <property name="optimisticLockEnable" value="true"/>
   <property name="ignorePageSize" value="10000"/>
   <property name="startPageNum" value="1"/>
   <property name="maxPageSize" value="100"/>

   <plugin type="com.iqudoo.framework.mybatis.TapeMybatisGeneratorPlugin"/>
   <plugin type="com.iqudoo.framework.mybatis.TapeTableRepositoryGeneratorPlugin"/>
   <plugin type="com.iqudoo.framework.mybatis.TapeViewRepositoryGeneratorPlugin"/>

   <plugin type="org.mybatis.generator.plugins.SerializablePlugin"/>
   <plugin type="org.mybatis.generator.plugins.ToStringPlugin"/>
   <plugin type="org.mybatis.generator.plugins.UnmergeableXmlMappersPlugin"/>

   <!-- 其他配置... -->
</context>

3. 全局配置参数说明

参数名	说明	默认值	必需
targetProject	生成代码的目标项目路径	src/main/java	否
mapperPackage	Mapper 接口包路径	com.iqudoo.platform.application.database.mapper	是
modelPackage	Model 类包路径	com.iqudoo.platform.application.database.model	是
facadeRepositoryPackage	表 Repository 接口包路径	com.iqudoo.platform.application.facade.repository	否
domainRepositoryPackage	表 Repository 实现类包路径	com.iqudoo.platform.application.domain.repository	否
domainRepositoryType	表 Repository 类名后缀	Repository	否
facadeViewRepositoryPackage	视图 Repository 接口包路径	com.iqudoo.platform.application.facade.repoview	否
domainViewRepositoryPackage	视图 Repository 实现类包路径	com.iqudoo.platform.application.domain.repoview	否
domainViewRepositoryType	视图 Repository 类名后缀	Repository	否
guidGeneratorClass	GUID 生成工具类（需 import）	com.iqudoo.framework.tape.modules.utils.SnowflakeUtil	否
guidGeneratorCode	GUID 生成表达式（写入生成代码）	SnowflakeUtil.nextId()	否
changeLogContextClassPackage	变更日志上下文包路径	com.iqudoo.platform.application.domain.changeLog	否
changeLogContextClassName	变更日志上下文类名	ChangeLogContext	否
changeLogEnable	变更日志开关	false	否
slowQueryLoggerTime	慢查询阈值（毫秒）	300	否
slowQueryLoggerLevel	慢查询日志级别：error / warn / debug / info	error	否
optimisticLockEnable	乐观锁开关	true	否
ignorePageSize	usePage 取消分页的 pageSize 阈值	10000	否
startPageNum	分页起始页码	1	否
maxPageSize	单页最大条数	100	否

4. TABLE 级配置

表级 <property> 优先于全局 <property>，未配置时回退到全局值。

参数名	说明
changeLogEnable	变更日志开关
slowQueryLoggerTime	慢查询阈值（毫秒）
slowQueryLoggerLevel	慢查询日志级别
optimisticLockEnable	乐观锁开关
ignorePageSize	取消分页阈值
startPageNum	起始页码
maxPageSize	单页最大条数

示例：

<table tableName="your_table_name"
       domainObjectName="YourTableName"
       enableInsert="true"
       enableDeleteByPrimaryKey="true"
       enableUpdateByPrimaryKey="true"
       enableCountByExample="true"
       enableUpdateByExample="true"
       enableDeleteByExample="true"
       enableSelectByExample="true"
       selectByExampleQueryId="false">
    <property name="useActualColumnNames" value="false"/>
    <property name="changeLogEnable" value="false"/>
    <property name="slowQueryLoggerTime" value="200"/>
    <property name="slowQueryLoggerLevel" value="warn"/>
    <property name="optimisticLockEnable" value="false"/>
    <property name="ignorePageSize" value="10000"/>
    <property name="startPageNum" value="1"/>
    <property name="maxPageSize" value="100"/>
</table>

变更日志监听

changeLogEnable=true 时，Repository 实现会调用 ChangeLogContext.addLog。使用方需提供如下静态方法：

public class ChangeLogContext {

    public static void addLog(String tableName, String eventType, Long dataGuid,
                              Map<String, Object[]> fieldChanges) {
        // 自行实现
    }
}

eventType 取值：

eventType	触发操作
insert	insert
batchInsert	batchInsert
update	update
updateByExampleSelective	updateByExampleSelective
deleteById	deleteById（软删）
deleteAll	deleteAll（软删）
trashById	trashById
trashAll	trashAll
recoverById	recoverById
recoverAll	recoverAll

fieldChanges 中 Object[] 为 [旧值, 新值]；插入/删除类事件通常为空 Map。

数据库表结构要求

标准表结构模板

使用完整 Repository 功能（软删除、回收站、乐观锁）时，表需包含以下标准字段：

DROP TABLE IF EXISTS `your_table_name`;
CREATE TABLE `your_table_name` (
    `guid`         bigint(0) UNSIGNED NOT NULL DEFAULT 0 COMMENT 'GUID',
    -- 业务字段
    `is_hidden`    int(0)             NOT NULL DEFAULT 0 COMMENT '隐藏标志',
    `is_delete`    int(0)             NOT NULL DEFAULT 0 COMMENT '删除标志',
    `delete_token` varchar(32)        NULL     DEFAULT '' COMMENT '删除令牌',
    `data_version` int(0)             NOT NULL DEFAULT 0 COMMENT '数据版本',
    `create_time`  datetime(0)        NOT NULL DEFAULT CURRENT_TIMESTAMP(0) COMMENT '创建时间',
    `update_time`  datetime(0)        NOT NULL DEFAULT CURRENT_TIMESTAMP(0) COMMENT '更新时间',
    PRIMARY KEY (`guid`) USING BTREE,
    KEY `idx_common_query` (`is_hidden`, `is_delete`, `create_time` desc, `guid`) USING BTREE
) ENGINE = InnoDB COMMENT = '你的表格备注'
  ROW_FORMAT = Dynamic;

索引优化指南

唯一键索引（含 delete_token 以支持回收站后重建）：

UNIQUE KEY `idx_your_unique_key` (
    `your_unique_key`,
    `delete_token`
) USING BTREE

查询索引：

KEY `idx_your_query_case` (
    `is_hidden`, `is_delete`,
    `create_time` desc,
    `guid`
) USING BTREE

标准字段说明：

字段	说明
guid	主键，bigint UNSIGNED
is_hidden	回收站标志（1 = 在回收站）
is_delete	软删除标志
delete_token	删除令牌（有效数据为 VALID，进回收站后变更）
data_version	乐观锁版本号
create_time / update_time	插入时自动设置

视图表

视图表无需上述标准字段，仅需业务列；由 TapeViewRepositoryGeneratorPlugin 生成只读 Repository。

在 mybatis.generator.xml 中配置表

<table tableName="your_table_name"
       domainObjectName="YourTableName"
       enableInsert="true"
       enableDeleteByPrimaryKey="true"
       enableUpdateByPrimaryKey="true"
       enableCountByExample="true"
       enableUpdateByExample="true"
       enableDeleteByExample="true"
       enableSelectByExample="true"
       selectByExampleQueryId="false">
    <property name="useActualColumnNames" value="false"/>
</table>

非视图表注意事项

1. 主键：必须有名为 guid 的主键，类型 bigint UNSIGNED。
2. 视图表判定：JDBC tableType 为 VIEW 时不会生成表 Repository，改由视图插件处理。
3. 分页：Example 支持 usePage() / limit()；pageSize >= ignorePageSize 时不加分页。
4. 乐观锁：update 使用 data_version；optimisticLockEnable=false 时不校验版本。
5. 软删除：deleteById / deleteAll 默认软删（is_delete=1）；release=true 为物理删除。
6. 回收站：trash* 设置 is_hidden=1；recover* 恢复为 is_hidden=0、delete_token=VALID。
7. 批量删除：deleteAll(release=false) 仅作用于已在回收站的记录。
8. 自动字段：insert / batchInsert 自动设置 guid（guidGeneratorCode）、is_delete=0、is_hidden=0、delete_token=VALID、data_version=1、时间戳等。
9. BLOB：含 BLOB 列时，getList 分页查询先 selectPrimaryKeyByExample 再按 GUID 拉取详情；可通过 withBLOBs 控制是否查询 BLOB 列。