287 lines
14 KiB
Markdown
287 lines
14 KiB
Markdown
# tape-mybatis-generator-plugin
|
||
> MyBatis 代码生成插件
|
||
|
||
## 功能特性
|
||
|
||
本插件为 MyBatis Generator 提供了以下增强功能：
|
||
|
||
1. **TapeMybatisGeneratorPlugin** - 扩展 MyBatis Mapper，添加 `selectPrimaryKeyByExample`, `batchInsert` 方法，拓展查询分页支持
|
||
2. **TapeRepositoryGeneratorPlugin** - 为非视图表自动生成 Repository 接口和实现类，提供完整的 CRUD 和软删除功能
|
||
3. **TapeRepoviewGeneratorPlugin** - 为视图表自动生成 RepoView 接口和实现类，提供查询功能
|
||
|
||
## 插件说明
|
||
|
||
### TapeMybatisGeneratorPlugin
|
||
扩展 MyBatis Mapper，添加以下功能：
|
||
- 在 Mapper 接口中添加 `selectPrimaryKeyByExample` 方法
|
||
- 在 Mapper XML 中生成对应的 SQL 查询语句
|
||
|
||
### TapeRepositoryGeneratorPlugin
|
||
为非视图表生成 Repository 层代码：
|
||
- **接口位置**: `{facadeRepositoryPackage}.I{TableName}Repository`
|
||
- **实现类位置**: `{domainRepositoryPackage}.{TableName}RepositoryImpl`
|
||
- **视图表过滤**: 根据 `viewKeyWords` 配置自动识别并跳过视图表
|
||
|
||
**生成的方法**：
|
||
- `trashById(long id)` - 移动到回收站（单个）
|
||
- `trashAll({Example} example)` - 移动到回收站（批量）
|
||
- `deleteById(long id, boolean release)` - 删除（单个，支持物理删除）
|
||
- `deleteAll({Example} example, boolean release)` - 删除（批量，支持物理删除）
|
||
- `recoverById(long id)` - 从回收站恢复（单个）
|
||
- `recoverAll({Example} example)` - 从回收站恢复（批量）
|
||
- `findAnyById(long id)` - 查找（不区分有效/回收站）
|
||
- `findValidById(long id)` - 查找有效记录（单个）
|
||
- `findTrashById(long id)` - 查找回收站记录（单个）
|
||
- `findValidOne({Example} example)` - 查找有效记录（单个，支持条件）
|
||
- `findTrashOne({Example} example)` - 查找回收站记录（单个，支持条件）
|
||
- `getValidList({Example} example)` - 获取有效记录列表（支持分页）
|
||
- `getTrashList({Example} example)` - 获取回收站记录列表（支持分页）
|
||
- `countByValid({Example} example)` - 统计有效记录数
|
||
- `countByValidWithPage({Example} example)` - 统计分页有效记录数
|
||
- `countByTrash({Example} example)` - 统计回收站记录数
|
||
- `countByTrashWithPage({Example} example)` - 统计分页回收站记录数
|
||
- `insert({Model} record)` - 插入记录（自动生成 GUID、设置默认值）
|
||
- `batchInsert(List<{Model}> records)` - 批量插入记录（自动生成 GUID、设置默认值）
|
||
- `updateByExampleSelective({Model} record, {Example} example)` - 按条件更新记录
|
||
- `update({Model} record)` - 更新记录（支持乐观锁）
|
||
|
||
### TapeRepoviewGeneratorPlugin
|
||
为视图表生成 RepoView 层代码：
|
||
- **接口位置**: `{facadeRepoviewPackage}.I{TableName}Repo`
|
||
- **实现类位置**: `{domainRepoviewPackage}.{TableName}RepoImpl`
|
||
- **视图表识别**: 仅处理包含 `viewKeyWords` 关键字的表
|
||
|
||
**生成的方法**：
|
||
- `findOne({Example} example)` - 查找单条记录
|
||
- `getList({Example} example)` - 获取记录列表（支持分页）
|
||
- `count({Example} example)` - 统计记录数
|
||
|
||
### 其他功能
|
||
通过 `TapeMybatisGeneratorPlugin` 为所有 Example 类添加支持：
|
||
|
||
**添加的字段**：
|
||
- `offset` - 偏移量
|
||
- `rows` - 每页数量
|
||
- `startPageNum` - 最小页码（默认 1）
|
||
- `ignorePageSize` - 忽略分页数量（默认 10000）每页数量大于10000时，忽略分页
|
||
- `maxPageSize` - 最大每页数量（默认 100）
|
||
- `withBLOBs` - 是否返回BLOBs列的数据
|
||
|
||
**添加的方法**：
|
||
- `limit(int rows)` - 设置每页数量
|
||
- `limit(int offset, int rows)` - 设置偏移量和每页数量
|
||
- `usePage(int pageNum, int pageSize)` - 使用页码和每页数量（自动计算 offset）
|
||
- `setWithBLOBs(boolean withBLOBs)` - 设置是否返回BLOBs列的数据
|
||
- `isWithBLOBs()` - 是否返回BLOBs列的数据
|
||
- `getPageNum()` - 获取当前页码
|
||
- `getPageSize()` - 获取当前每页数量
|
||
- `getOffset()` - 获取当前分页limit的offset
|
||
- `getRows()` - 获取当前分页limit的rows
|
||
|
||
## 使用方法
|
||
### 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>
|
||
<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` 中配置插件
|
||
|
||
```xml
|
||
|
||
<context id="Mysql" targetRuntime="MyBatis3">
|
||
<!-- 配置属性 -->
|
||
<property name="targetProject" value="src/main/java"/>
|
||
<property name="modelPackage" value="com.iqudoo.platform.application.database.model"/>
|
||
<property name="mapperPackage" value="com.iqudoo.platform.application.database.mapper"/>
|
||
<property name="facadeRepositoryPackage" value="com.iqudoo.platform.application.facade.repository"/>
|
||
<property name="domainRepositoryPackage" value="com.iqudoo.platform.application.domain.repository"/>
|
||
<property name="facadeViewRepositoryPackage" value="com.iqudoo.platform.application.facade.repoview"/>
|
||
<property name="domainViewRepositoryPackage" value="com.iqudoo.platform.application.domain.repoview"/>
|
||
<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="true"/>
|
||
<property name="slowQueryLoggerTime" value="300"/>
|
||
<property name="slowQueryLoggerLevel" value="error"/>
|
||
<property name="priorityPrimaryKeyOffset" value="100"/>
|
||
<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.TapeRepositoryGeneratorPlugin"/>
|
||
<plugin type="com.iqudoo.framework.mybatis.TapeRepoviewGeneratorPlugin"/>
|
||
|
||
<!-- 其他配置... -->
|
||
</context>
|
||
```
|
||
|
||
### 3. 配置参数说明
|
||
|
||
| 参数名 | 说明 | 默认值 | 必需 |
|
||
|----------------------------|-------------------------------|---------------------------------------------------------|------|
|
||
| `targetProject` | 生成代码的目标项目路径 | `src/main/java` | 否 |
|
||
| `modelPackage` | Model 类的包路径 | `com.iqudoo.platform.application.database.model` | 是 |
|
||
| `mapperPackage` | Mapper 接口的包路径 | `com.iqudoo.platform.application.database.mapper` | 是 |
|
||
| `facadeRepositoryPackage` | Repository 接口的包路径 | `com.iqudoo.platform.application.facade.repository` | 否 |
|
||
| `domainRepositoryPackage` | Repository 实现类的包路径 | `com.iqudoo.platform.application.domain.repository` | 否 |
|
||
| `facadeRepoviewPackage` | RepoView 接口的包路径 | `com.iqudoo.platform.application.facade.repoview` | 否 |
|
||
| `snowflakeUtilClass` | 雪花算法ID生成工具类 | `com.iqudoo.framework.tape.modules.utils.SnowflakeUtil` | 否 |
|
||
| `snowflakeUtilGenId` | 雪花算法ID生成方法 | `SnowflakeUtil.nextId()` | 否 |
|
||
| `changeLogContextClassPackage` | 变更日志上下文包路径 | `com.iqudoo.platform.application.domain.changeLog` | 否 |
|
||
| `changeLogContextClassName` | 变更日志上下文类 | `ChangeLogContext` | 否 |
|
||
| `changeLogEnable` | 变更日志监听开关 | `false` | 否 |
|
||
| `slowQueryLoggerTime` | 慢查询日志时间阈值 | `300` | 否 |
|
||
| `slowQueryLoggerLevel` | 慢查询日志类型：error，warn，debug，info | `error` | 否 |
|
||
| `priorityPrimaryKeyOffset` | 优先查询主键偏移阈值 | `0` | 否 |
|
||
| `ignorePageSize` | 忽略分页阈值 | `10000` | 否 |
|
||
| `startPageNum` | 分页开始页码 | `1` | 否 |
|
||
| `maxPageSize` | 最大每页数量 | `100` | 否 |
|
||
|
||
## 变更日志监听
|
||
|
||
ChangeLogContext应该提供以下实现的静态方法，供Repository实现中调用
|
||
```java
|
||
public class ChangeLogContext {
|
||
|
||
/**
|
||
* 添加一条变更
|
||
*/
|
||
public static void addLog(String tableName, String eventType, Long dataGuid, Map<String, Object[]> fieldChanges) {
|
||
// your thing code
|
||
}
|
||
|
||
}
|
||
```
|
||
|
||
## 数据库表结构要求
|
||
|
||
### 标准表结构模板
|
||
|
||
为了使用完整的 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 '删除令牌',
|
||
`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,
|
||
-- UNIQUE KEY `idx_unique_key` (`you unique key`,`delete_token`) USING BTREE,
|
||
-- KEY `idx_common_query` (
|
||
-- 等值查询字段,
|
||
-- `is_hidden`,`is_delete`,
|
||
-- 其他参与排序字段,
|
||
-- `create_time` desc,
|
||
-- `guid`) USING BTREE
|
||
KEY `idx_common_query` (`is_hidden`,`is_delete`,`create_time` desc,`guid`) USING BTREE
|
||
) ENGINE = InnoDB COMMENT = '你的表格备注' ROW_FORMAT = Dynamic;
|
||
```
|
||
|
||
**必需字段说明**：
|
||
- `guid` - 主键，类型为 `bigint UNSIGNED`
|
||
- `is_hidden` - 隐藏标志，用于回收站功能
|
||
- `is_delete` - 删除标志，用于软删除功能
|
||
- `delete_token` - 删除令牌，用于标识删除状态
|
||
- `data_version` - 数据版本，用于乐观锁
|
||
- `create_time` - 创建时间，自动设置
|
||
- `update_time` - 更新时间，自动更新
|
||
|
||
### 视图表结构
|
||
|
||
视图表不需要上述标准字段，只需要包含业务字段即可。
|
||
|
||
### 在 `mybatis.generator.xml` 中配置表
|
||
|
||
```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>
|
||
|
||
<!-- 视图表配置（表名包含 VIEW_ 或 V_ 前缀，大小写不敏感） -->
|
||
<table tableName="v_your_view_name"
|
||
domainObjectName="ViewYourViewName"
|
||
enableInsert="false"
|
||
enableDeleteByPrimaryKey="false"
|
||
enableUpdateByPrimaryKey="false"
|
||
enableCountByExample="true"
|
||
enableUpdateByExample="false"
|
||
enableDeleteByExample="false"
|
||
enableSelectByExample="true"
|
||
selectByExampleQueryId="false">
|
||
<property name="useActualColumnNames" value="false"/>
|
||
<generatedKey column="guid" sqlStatement="JDBC" identity="false"/>
|
||
</table>
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **主键要求**：表必须有一个主键字段，且字段名为 `guid`，类型为 `bigint UNSIGNED`
|
||
2. **视图表识别**：视图表通过表名中的关键字识别，默认关键字为 `view_` 和 `v_` 不区分大小写
|
||
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 或更高版本 |