# 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` 中配置插件

```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` 中配置插件

```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` | 单页最大条数 |

示例：

```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"/>
    <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`。使用方需提供如下静态方法：

```java
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 功能（软删除、回收站、乐观锁）时，表需包含以下标准字段：

```mysql
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` 以支持回收站后重建）：

```sql
UNIQUE KEY `idx_your_unique_key` (
    `your_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` | 回收站标志（`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"
       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 列。