tools/tape-springboot-mybatis-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix

Browse Source
This commit is contained in:
iqudoo
2026-05-23 19:39:11 +08:00
parent c27a2433be
commit 45f5300e42
1 changed files with 165 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

304
README.md
View File

@@ -1,106 +1,126 @@
# tape-mybatis-generator-plugin
> MyBatis 代码生成插件
> MyBatis 代码生成插件（基于 MyBatis Generator **1.4.1** 开发，Maven 插件建议使用 **1.4.0+**）
## 功能特性
本插件为 MyBatis Generator 提供了以下增强功能：
1. **TapeMybatisGeneratorPlugin** - 扩展 MyBatis Mapper，添加 `selectPrimaryKeyByExample`, `batchInsert` 方法，拓展查询分页支持
2. **TapeTableRepositoryGeneratorPlugin** - 为非视图表自动生成 Repository 接口和实现类，提供完整的 CRUD 和软删除功能
3. **TapeViewRepositoryGeneratorPlugin** - 为视图表自动生成 ViewRepository 接口和实现类，提供查询功能
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，添加以下功能：
扩展 MyBatis Mapper 与 Example 类：
- 在 Mapper 接口中添加 `selectPrimaryKeyByExample` 方法
- 在 Mapper XML 中生成对应的 SQL 查询语句
**Mapper 接口 / XML**
- `selectPrimaryKeyByExample(Example)` — 按条件查询主键列表（支持 Example 分页 `limit`）
- `batchInsert(List<Model>)` — 批量插入，返回影响行数
**Mapper XML 动态 SQL**
- 为 `selectByExample`、`selectByExampleWithBLOBs`、`selectAll` 等查询追加 `limit` 片段（`rows` / `offset`）
### TapeTableRepositoryGeneratorPlugin
为非视图表生成 Repository 层代码：
为非视图表生成 Repository（类名后缀由 `domainRepositoryType` 控制，默认 `Repository`）：
- **接口位置**: `{facadeRepositoryPackage}.I{TableName}Repository`
- **实现类位置**: `{domainRepositoryPackage}.{TableName}RepositoryImpl`
- **接口**：`{facadeRepositoryPackage}.I{TableName}{domainRepositoryType}`
- **实现**：`{domainRepositoryPackage}.{TableName}{domainRepositoryType}Impl`
**生成的方法**：
示例（默认后缀）：`IYourTableNameRepository`、`YourTableNameRepositoryImpl`
- `trashById(long id)` - 移动到回收站（单个）
- `trashAll({Example} example)` - 移动到回收站（批量）
- `deleteById(long id, boolean release)` - 删除（单个，支持物理删除）
- `deleteAll({Example} example, boolean release)` - 删除（批量，支持物理删除）
- `recoverById(long id)` - 从回收站恢复（单个）
- `recoverAll({Example} example)` - 从回收站恢复（批量）
- `findById(long id)` - 根据主键查询数据
- `findOne({Example} example)` - 查找单条数据
- `getList({Example} example)` - 获取多条数据
- `count({Example} example)` - 统计记录数
- `countByWithPage({Example} example)` - 统计分页记录数
- `insert({Model} record)` - 插入记录（自动生成 GUID、设置默认值）
- `batchInsert(List<{Model}> records)` - 批量插入记录（自动生成 GUID、设置默认值）
- `updateByExampleSelective({Model} record, {Example} example)` - 按条件更新记录
- `update({Model} record)` - 更新记录（支持乐观锁）
**生成的方法**（均声明 `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
为视图表生成 RepoView 层代码：
为视图表生成 View Repository（类名后缀由 `domainViewRepositoryType` 控制，默认 `Repository`）：
- **接口位置**: `{facadeViewRepositoryPackage}.I{TableName}Repo`
- **实现类位置**: `{domainViewRepositoryPackage}.{TableName}RepoImpl`
- **接口**：`{facadeViewRepositoryPackage}.I{TableName}{domainViewRepositoryType}`
- **实现**：`{domainViewRepositoryPackage}.{TableName}{domainViewRepositoryType}Impl`
**生成的方法**：
示例（默认后缀）：`IYourTableNameRepository`、`YourTableNameRepositoryImpl`
- `findOne({Example} example)` - 查找单条记录
- `getList({Example} example)` - 获取记录列表（支持分页）
- `count({Example} example)` - 统计记录数
**生成的方法**（均声明 `throws Throwable`）：
### 其他功能
| 方法 | 说明 |
|------|------|
| `findOne(Example)` → `Model` | 单条 |
| `getList(Example)` → `List<Model>` | 列表（支持 Example 分页；含 BLOB 时按 `withBLOBs` 选择查询方法） |
| `count(Example)` → `long` | 计数 |
| `countWithPage(Example)` → `long` | 行为同表 Repository |
通过 `TapeMybatisGeneratorPlugin` 为所有 Example 类添加支持：
### Example 类增强（TapeMybatisGeneratorPlugin）
**添加的字段**：
**所有表/视图共有的字段与方法**：
- `offset` - 偏移量
- `rows` - 每页数量
- `startPageNum` - 最小页码（默认 1）
- `ignorePageSize` - 忽略分页数量（默认 10000）每页数量大于10000时，忽略分页
- `maxPageSize` - 最大每页数量（默认 100）
- `withBLOBs` - 是否返回BLOBs列的数据
- `resultType` - 返回数据格式：any, trash, valid（默认）
| 字段 / 方法 | 说明 |
|------------|------|
| `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` | 分页参数读写 |
**添加的方法**：
**仅非视图表额外支持**：
- `limit(int rows)` - 设置每页数量
- `limit(int offset, int rows)` - 设置偏移量和每页数量
- `usePage(int pageNum, int pageSize)` - 使用页码和每页数量（自动计算 offset）
- `setWithBLOBs(boolean withBLOBs)` - 设置是否返回BLOBs列的数据
- `isWithBLOBs()` - 是否返回BLOBs列的数据
- `setResultType(String type)` - 设置返回值的类型
- `resultAny()` - 不区分
- `isResultAny()` - 查询不区分
- `resultTrash()` - 回收站
- `isResultTrash()` - 查询回收站
- `resultValid()` - 有效数据
- `isResultValid()` - 查询有效数据
- `getPageNum()` - 获取当前页码
- `getPageSize()` - 获取当前每页数量
- `getOffset()` - 获取当前分页limit的offset
- `getRows()` - 获取当前分页limit的rows
| 字段 / 方法 | 说明 |
|------------|------|
| `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` 中配置插件
```xml
<build>
<finalName>application</finalName>
<plugins>
<!-- your other plugins -->
<!-- add mybatis plugin -->
<plugin>
<groupId>org.mybatis.generator</groupId>
<artifactId>mybatis-generator-maven-plugin</artifactId>
@@ -142,9 +162,7 @@
### 2. 在 `mybatis.generator.xml` 中配置插件
```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"/>
@@ -166,12 +184,10 @@
<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"/>
@@ -182,47 +198,47 @@
### 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` | RepoView 名称后缀 | `Repository` | 否 |
| `facadeViewRepositoryPackage` | RepoView 接口的包路径 | `com.iqudoo.platform.application.facade.repoview` | 否 |
| `domainViewRepositoryPackage` | RepoView 实现类的包路径 | `com.iqudoo.platform.application.domain.repoview` | 否 |
| `domainViewRepositoryType` | RepoView 名称后缀 | `Repository` | 否 |
| `guidGeneratorClass` | GUID生成工具类 | `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` | 忽略分页阈值 | `10000` | 否 |
| `startPageNum` | 分页开始页码 | `1` | 否 |
| `maxPageSize` | 最大每页数量 | `100` | 否 |
| 参数名 | 说明 | 默认值 | 必需 |
|--------|------|--------|------|
| `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` | 否 |
### 3. TABLE级配置
> 当存在table配置时，以table配置优先，未配置时使用全局配置，目前支持的table属性如下
### 4. TABLE 级配置
| 参数名 |
|------------------------|
| `changeLogEnable` |
| `slowQueryLoggerTime` |
| `slowQueryLoggerLevel` |
| `optimisticLockEnable` |
| `ignorePageSize` |
| `startPageNum` |
| `maxPageSize` |
表级 `<property>` 优先于全局 `<property>`，未配置时回退到全局值。
| 参数名 | 说明 |
|--------|------|
| `changeLogEnable` | 变更日志开关 |
| `slowQueryLoggerTime` | 慢查询阈值（毫秒） |
| `slowQueryLoggerLevel` | 慢查询日志级别 |
| `optimisticLockEnable` | 乐观锁开关 |
| `ignorePageSize` | 取消分页阈值 |
| `startPageNum` | 起始页码 |
| `maxPageSize` | 单页最大条数 |
示例：
```xml
<!-- your table -->
<table tableName="your table name"
<table tableName="your_table_name"
domainObjectName="YourTableName"
enableInsert="true"
enableDeleteByPrimaryKey="true"
@@ -245,34 +261,46 @@
## 变更日志监听
ChangeLogContext应该提供以下实现的静态方法，供Repository实现中调用
`changeLogEnable=true` 时，Repository 实现会调用 `ChangeLogContext.addLog`。使用方需提供如下静态方法：
```java
public class ChangeLogContext {
/**
* 添加一条变更
*/
public static void addLog(String tableName, String eventType, Long dataGuid, Map<String, Object[]> fieldChanges) {
// your thing code
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 功能（软删除、回收站等），表结构需要包含以下标准字段：
使用完整 Repository 功能（软删除、回收站、乐观锁）时，表需包含以下标准字段：
```mysql
DROP TABLE IF EXISTS `your_table_name`;
CREATE TABLE `your_table_name` (
`guid` bigint(0) UNSIGNED NOT NULL DEFAULT 0 COMMENT 'GUID',
-- ----------------------------
-- add your table other table field
-- ----------------------------
-- 业务字段
`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 '删除令牌',
@@ -287,11 +315,11 @@ CREATE TABLE `your_table_name` (
### 索引优化指南
唯一键索引：
唯一键索引（含 `delete_token` 以支持回收站后重建）：
```sql
UNIQUE KEY `idx_your_unique_key` (
`you unique key`,
`your_unique_key`,
`delete_token`
) USING BTREE
```
@@ -299,33 +327,31 @@ UNIQUE KEY `idx_your_unique_key` (
查询索引：
```sql
KEY `idx_your_query_case` (
/* 等值查询字段 */
`is_hidden`,`is_delete`,
/* 其他参与排序字段 */
KEY `idx_your_query_case` (
`is_hidden`, `is_delete`,
`create_time` desc,
`guid`
) USING BTREE
```
**必需字段说明**：
**标准字段说明**：
- `guid` - 主键，类型为 `bigint UNSIGNED`
- `is_hidden` - 隐藏标志，用于回收站功能
- `is_delete` - 删除标志，用于软删除功能
- `delete_token` - 删除令牌，用于标识删除状态
- `data_version` - 数据版本，用于乐观锁
- `create_time` - 创建时间，自动设置
- `update_time` - 更新时间，自动更新
| 字段 | 说明 |
|------|------|
| `guid` | 主键，`bigint UNSIGNED` |
| `is_hidden` | 回收站标志（`1` = 在回收站） |
| `is_delete` | 软删除标志 |
| `delete_token` | 删除令牌（有效数据为 `VALID`，进回收站后变更） |
| `data_version` | 乐观锁版本号 |
| `create_time` / `update_time` | 插入时自动设置 |
### 视图表结构
### 视图表
视图表不需要上述标准字段，只需要包含业务字段即可。
视图表无需上述标准字段，仅需业务列；由 `TapeViewRepositoryGeneratorPlugin` 生成只读 Repository。
### 在 `mybatis.generator.xml` 中配置表
```xml
<!-- 标准表配置 -->
<table tableName="your_table_name"
domainObjectName="YourTableName"
enableInsert="true"
@@ -342,12 +368,12 @@ KEY `idx_your_query_case` (
## 非视图表注意事项
1. **主键要求**：表必须有一个主键字段，且字段名为 `guid`，类型为 `bigint UNSIGNED`
3. **分页功能**：所有 Example 类都自动包含分页功能，可通过 `usePage()` 方法使用
4. **乐观锁**：更新操作使用 `data_version` 字段实现乐观锁，更新时需要传入正确的版本号
5. **软删除**：删除操作默认是软删除（设置 `is_delete` 标志），可通过 `release=true` 参数执行物理删除
6. **回收站**：通过 `is_hidden` 字段实现回收站功能，`trash` 方法将记录移动到回收站，`recover` 方法恢复记录
7. **自动字段**：插入记录时，插件会自动设置 `guid`
（使用雪花算法）、`is_delete`、`is_hidden`、`delete_token`、`data_version`、`create_time`、`update_time` 等字段
8. **BLOB 字段支持**：如果表包含 BLOB 字段，插件会自动使用 `selectByExampleWithBLOBs` 和 `updateByExampleWithBLOBs` 方法
9. **MyBatis Generator 版本**：本插件基于 MyBatis Generator 1.4.1 开发，建议使用 1.4.0 或更高版本
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 列。