# tape-mybatis-generator-plugin

> MyBatis 代码生成插件

## 功能特性

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

1. **TapeMybatisGeneratorPlugin** - 扩展 MyBatis Mapper，添加 `selectPrimaryKeyByExample`, `batchInsert` 方法，拓展查询分页支持
2. **TapeTableRepositoryGeneratorPlugin** - 为非视图表自动生成 Repository 接口和实现类，提供完整的 CRUD 和软删除功能
3. **TapeViewRepositoryGeneratorPlugin** - 为视图表自动生成 ViewRepository 接口和实现类，提供查询功能

## 插件说明

### TapeMybatisGeneratorPlugin

扩展 MyBatis Mapper，添加以下功能：

- 在 Mapper 接口中添加 `selectPrimaryKeyByExample` 方法
- 在 Mapper XML 中生成对应的 SQL 查询语句

### TapeTableRepositoryGeneratorPlugin

为非视图表生成 Repository 层代码：

- **接口位置**: `{facadeRepositoryPackage}.I{TableName}Repository`
- **实现类位置**: `{domainRepositoryPackage}.{TableName}RepositoryImpl`

**生成的方法**：

- `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)` - 更新记录（支持乐观锁）

### TapeViewRepositoryGeneratorPlugin

为视图表生成 RepoView 层代码：

- **接口位置**: `{facadeViewRepositoryPackage}.I{TableName}Repo`
- **实现类位置**: `{domainViewRepositoryPackage}.{TableName}RepoImpl`

**生成的方法**：

- `findOne({Example} example)` - 查找单条记录
- `getList({Example} example)` - 获取记录列表（支持分页）
- `count({Example} example)` - 统计记录数

### 其他功能

通过 `TapeMybatisGeneratorPlugin` 为所有 Example 类添加支持：

**添加的字段**：

- `offset` - 偏移量
- `rows` - 每页数量
- `startPageNum` - 最小页码（默认 1）
- `ignorePageSize` - 忽略分页数量（默认 10000）每页数量大于10000时，忽略分页
- `maxPageSize` - 最大每页数量（默认 100）
- `withBLOBs` - 是否返回BLOBs列的数据
- `resultType` - 返回数据格式：any, trash, valid（默认）

**添加的方法**：

- `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

## 使用方法

### 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="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`         | 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`                                                   | 否  |

### 3. TABLE级配置
> 当存在table配置时，以table配置优先，未配置时使用全局配置，目前支持的table属性如下

| 参数名                    |
|------------------------|
| `changeLogEnable`      | 
| `slowQueryLoggerTime`  |
| `slowQueryLoggerLevel` |
| `optimisticLockEnable` |
| `ignorePageSize`       | 
| `startPageNum`         |
| `maxPageSize`          |

示例：

```xml
<!-- your table -->
<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>
```

## 变更日志监听

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,
    KEY `idx_common_query` (`is_hidden`, `is_delete`, `create_time` desc, `guid`) USING BTREE
) ENGINE = InnoDB COMMENT = '你的表格备注'
  ROW_FORMAT = Dynamic;
```

### 索引优化指南

唯一键索引：

```sql
UNIQUE KEY `idx_your_unique_key` (
    `you unique key`,
    `delete_token`
) USING BTREE
```

查询索引：

```sql
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` - 更新时间，自动更新

### 视图表结构

视图表不需要上述标准字段，只需要包含业务字段即可。

### 在 `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>
```

## 非视图表注意事项

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 或更高版本