keyfil/文档/基础组件/mybatis/20250526-engine-starter-mybatis-plus-2.0.0.md

<!-- Space: qifu -->
<!-- Parent: 后端技术&知识&规范 -->
<!-- Parent: 技术方案 -->
<!-- Parent: 基建 -->
<!-- Parent: 00-基础组件 -->
<!-- Parent: 00-EngineStarterMybatisPlus使用指南 -->
<!-- Title: 20250526-engine-starter-mybatis-plus-2.0.0 -->

<!-- Macro: :anchor\((.*)\):
     Template: ac:anchor
     Anchor: ${1} -->
<!-- Macro: \!\[.*\]\((.+)\)\<\!\-\- width=(.*) \-\-\>
     Template: ac:image
     Url: ${1}
     Width: ${2} -->
<!-- Macro: \<\!\-\- :toc: \-\-\>
     Template: ac:toc
     Printable: 'false'
     MinLevel: 2 
     MaxLevel: 4 -->
<!-- Include: 杂项/声明文件.md -->

<!-- :toc: -->

# engine-starter-mybatis-plus 使用教程

> 基于 mybatis-plus 的各种工具封装   
> 具体使用可参考 [engine-sample > engine-sample-starter-mybatis-plus](../engine-sample/engine-sample-starter-mybatis-plus)

## 功能特性

- [X] `YmMybatisPlusUtils`: MybatisPlus工具类
- [X] `YmBaseMapper`: Mapper扩展父类
  - Mapper 添加删除操作源数据自动填充方法
- [X] `YmBaseService`: Service扩展父类
- [X] `YmBaseServiceImpl`: Service扩展父类实现
- [X] `YmJsonTypeHandler`: 字段处理合并
  - 可以处理 `Map, JSONObject, JSONArray, List<JSONObject>, List<Integer>`, 其余的 Collection 对象需要实现继承该类，实现 `collectionType` 方法
  - 内置 `YmLongListTypeHandler`
  - 内置 `YmStringListTypeHandler`
- [X] `YmMetaObjectHandler`: 源数据填充
  - `YmCreateEntity` 插入数据填充
  - `YmUpdateEntity` 更新数据填充
- [X] `YmBaseEntity` 实体基类
  - `YmTenantBaseEntity` 实体基类（带tenantId）
- [X] `YmTenantLineHandler`: tenantId 填充

-------

## 快速使用

- **注意：** `qifu-saas-parent >= 1.1.1-SNAPSHOT`
- **注意：** `pom.xml` 中 `engine-starter-mybatis-plus` 和 `data-mybatis-plus` 不兼容
- **注意：** 兼容 `engine-starter-mybatis-plus` 和 `data-mybatis-plus` 需要添加依赖 `engine-starter-compatible`
- **注意：** 启动类 `@ComponentScan` 需要变更为如下形式
- ```java
  @ComponentScan(value = "com.yuanmeng.*",
          excludeFilters = {
                  @ComponentScan.Filter(type = FilterType.CUSTOM, classes = TypeExcludeFilter.class),
                  @ComponentScan.Filter(type = FilterType.CUSTOM, classes = AutoConfigurationExcludeFilter.class)
          })
  @SpringBootApplication
  public class SampleStarterWebApplication {
  
      public static void main(String[] args) {
          SpringApplication.run(SampleStarterWebApplication.class, args);
      }
  
  }
  ```

### 添加依赖

```xml

<dependency>
    <groupId>com.yuanmeng.engine</groupId>
    <artifactId>engine-starter-mybatis-plus</artifactId>
</dependency>
```

### 添加兼容包（可选）

- 项目中存在 `data-mybatis-plus` 时需要添加兼容包

```xml

<dependency>
    <groupId>com.yuanmeng.engine</groupId>
    <artifactId>engine-starter-compatible-mybatis-plus</artifactId>
</dependency>
```

---- 

## 使用工具

### 开启插入时填充更新数据（默认关闭）
```yaml
yuanmeng:
  mybatis-plus:
    meta-inject:
      enable: true
      fill-update-on-insert: false
```

### 自定义List字段序列化反序列化
```java
public class YmUserInfoTypeHandler extends YmJsonTypeHandler {

  public YmUserInfoTypeHandler(Class<?> type) {
    super(type);
  }

  @Override
  protected Class<?> collectionItemType() {
    return UserInfo.class;
  }

}

@Data
@EqualsAndHashCode(callSuper = false)
@TableName(value = "test_no_tenant_id_ignore", autoResultMap = true)
public class TestNoTenantIdIgnore extends YmBaseEntity<Long> {
    
  @TableField(typeHandler = YmJsonTypeHandler.class)
  private UserInfo customObject;

  @TableField(typeHandler = YmJsonTypeHandler.class)
  private JSONArray customJsonArray;

  @TableField(typeHandler = YmUserInfoTypeHandler.class)
  private List<UserInfo> customListObject;

  @TableField(typeHandler = YmLongListTypeHandler.class)
  private List<Long> customListIntObject;
}
```

### 开启雪花算法Id生成（对默认基类不生效，默认关闭）
```yaml
yuanmeng:
  mybatis-plus:
    enable-identifier-generator: false
```

------

## 完整默认配置文件

```yaml
yuanmeng:
  mybatis-plus:
    #- 开启 starter-mybatis-plus。默认开启
    enable: true
    #- 开启 雪花id 生成。默认关闭
    enable-identifier-generator: false
    #- 开启父类增强扩展。默认开启
    enable-sql-inject: true
    #- 拦截器配置
    interceptor:
      #- 开启拦截器配置。默认开启
      enable: true
      #- 开启乐观锁。默认关闭
      enable-optimistic-locker: false
      #- 开启恶意sql拦截。默认开启
      enable-block-attack: true
      #- 开启分页处理。默认开启
      enable-pagination: true
      #- 多租户处理
      tenant-line:
        #- 开启全局多租户处理。默认开启
        enable: true
        #- 开启包含模式。默认排除模式
        include-mode: false
        #- 需要处理的表格
        tenant-line-tables:
          - test_no_tenant_id
        #- 需要处理的表格前缀
        tenant-line-prefix-tables:
          - test_no
    #- 源数据填充
    meta-inject:
      #- 开启源数据填充。默认开启
      enable: true
      #- 插入时填充更新数据。默认关闭
      fill-update-on-insert: false
```