Mybatis-Plus-Join

https://github.com/yulichang/mybatis-plus-join
Admin
An enhanced toolkit of Mybatis-Plus to simplify development by providing extended multi-table query...
Tokens:354,930
Snippets:2,024
Trust Score:7.5
License:Apache-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Usage example

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/base.md

Example of using MPJBaseMapper with join wrappers to perform join queries and pagination.

```APIDOC
## Usage example

### Description
Demonstrates how to use MPJBaseMapper with MPJLambdaWrapper to perform join queries, pagination, and count.

### Code Example
```java
import com.github.yulichang.base.MPJBaseMapper;
import com.github.yulichang.wrapper.MPJLambdaWrapper;
import com.github.yulichang.toolkit.JoinWrappers;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;

public interface UserMapper extends MPJBaseMapper<UserDO> {
}

// Basic join list mapped to a DTO
MPJLambdaWrapper<UserDO> wrapper = JoinWrappers.lambda(UserDO.class)
        .selectAll(UserDO.class)
        .select(AddressDO::getTel)
        .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
        .eq(UserDO::getId, 1)
        .like(AddressDO::getTel, "1");

List<UserDTO> list = userMapper.selectJoinList(UserDTO.class, wrapper);
Page<UserDTO> page = userMapper.selectJoinPage(new Page<>(1, 10), UserDTO.class, wrapper);
Long total = userMapper.selectJoinCount(wrapper);
```
```

--------------------------------

### Usage example for MPJBaseJoin wrapper

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/interceptor.md

Shows how to use the interceptor without extra configuration. The interceptor activates on MPJBaseJoin wrappers, and the example builds a join query with selectAll, select, leftJoin, and eq conditions.

```java
// No configuration needed at call sites — the interceptor activates on MPJBaseJoin wrappers:

List<UserDTO> list = userMapper.selectJoinList(UserDTO.class,
        JoinWrappers.lambda(UserDO.class)
                .selectAll(UserDO.class)
                .select(AddressDO::getTel)
                .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
                .eq(UserDO::getId, 1));
```

--------------------------------

### Solon configuration for mybatis-plus-join-solon-plugin

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/plugins.md

Example application.yml for the Solon plugin. Sets banner, tableAlias, logicDelType, and ifExists properties.

```yaml
mybatis-plus-join:
  banner: true
  tableAlias: t
  logicDelType: ON
  ifExists: NOT_EMPTY
```

--------------------------------

### Chain Usage Examples

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/chain.md

Examples of using JoinWrappers.lambda to perform list, count, page, and map operations, including error handling when the wrapper is created without an entity class.

```APIDOC
## Chain Usage Examples

### Description
Demonstrates how to use `JoinWrappers.lambda()` to perform list, count, page, and map operations with chain wrappers.

### Method
N/A (usage examples)

### Endpoint
N/A

### Parameters
#### Methods
- **list(Class<DTO> dtoClass)** - Executes the query and returns a list of DTOs.
- **count()** - Executes a count query and returns the total count.
- **page(Page, Class)** - Executes a paginated query and returns a Page of DTOs.
- **mapFirst()** - Returns the first result as a Map.

### Request Example
```java
List<UserDTO> users = JoinWrappers.lambda(UserDO.class)
        .selectAll(UserDO.class)
        .select(AddressDO::getTel)
        .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
        .eq(UserDO::getId, 1)
        .list(UserDTO.class);
```

### Response
#### Success Response
- **list(Class<U>)** (List<U>) - List of DTOs.
- **count()** (Long) - Count of matching records.
- **page(Page, Class)** (Page<U>) - Page of DTOs.
- **mapFirst()** (Map<String, Object>) - First result as a map.

#### Response Example
N/A

### Error Handling
- Throws `IllegalArgumentException` if entityClass is null: "请使用 new MPJLambdaWrapper(主表.class) 或 JoinWrappers.lambda(主表.class) 构造方法"
- Throws `IllegalArgumentException` if mapper is not initialized: "mapper not init <EntityClass>"
- Throws `IllegalArgumentException` if mapper does not extend MPJBaseMapper: "mapper <MapperClass> not extends MPJBaseMapper"
```

--------------------------------

### JoinWrappers usage example

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/join-wrappers.md

Usage example of JoinWrappers factories for lambda queries, direct chain execution, delete joins, and update joins. Demonstrates static import of JoinWrappers.*. For delete and update, the wrapper is passed to userMapper.deleteJoin/updateJoin.

```java
import static com.github.yulichang.toolkit.JoinWrappers.*;

// Lambda join query (recommended)
MPJLambdaWrapper<UserDO> wrapper = lambda(UserDO.class)
        .selectAll(UserDO.class)
        .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
        .eq(UserDO::getId, 1);

// chain-style execution directly (see Chain)
List<UserDTO> users = lambda(UserDO.class)
        .selectAll(UserDO.class)
        .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
        .list(UserDTO.class);

// delete many-to-many style
int deleted = userMapper.deleteJoin(delete(UserDO.class)
        .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
        .eq(AddressDO::getTel, "10086"));

// update joined table
int updated = userMapper.updateJoin(new UserDO().setName("newname"),
        update(UserDO.class)
                .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
                .eq(AddressDO::getTel, "10086"));
```

--------------------------------

### Adapter and AdapterHelper default implementation

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/adapter.md

Shows the default Adapter implementation and the AdapterHelper singleton access point. Custom adapters are installed via AdapterHelper.setAdapter(...), and AdapterHelper.getAdapter() is the single access point used across the codebase (e.g. DeleteJoin, MPJBaseMethod, MPJInterceptor, UpdateJoin).

```java
public class Adapter implements IAdapter { }        // default implementation

public class AdapterHelper {
    @Getter private static IAdapter adapter = new Adapter();
    public static void setAdapter(IAdapter adapter) { AdapterHelper.adapter = adapter; }
}
```

--------------------------------

### Usage example for @Table-generated AptQueryWrapper

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/extension-apt.md

Shows how to use the generated UserCol constants with AptQueryWrapper and AptWrappers after applying @Table and @TableName. Includes a try/catch around entity-class-required operations to illustrate error handling when the wrapper lacks an entity class.

```java
// build config (Gradle)
// dependencies { annotationProcessor 'com.github.yulichang:mybatis-plus-join-processor:1.5.9' }

@Table
@TableName("user")
public class UserDO {
    @TableId private Integer id;
    private String name;
}

// generated: user.apt.UserCol with column members; use both in java:
import user.apt.UserCol;

AptQueryWrapper<UserDO> w = AptWrappers.query(UserCol.COL)
        .selectAll(UserCol.COL)
        .eq(UserCol.ID, 1);
List<UserDO> list = userMapper.selectJoinList(UserDO.class, w);

// chain + error handling: entity-class-required operations
try {
    List<UserDO> bad = AptWrappers.query(UserCol.COL) /* entity present */;
    Long count = w.count();
} catch (Exception e) {
    log.error(
```

--------------------------------

### Custom wrapper extension example

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/plugins.md

Example of a custom extension interface that adds a default method to MPJLambdaWrapper. The method sets a condition and returns the wrapper.

```java
public interface MyExt extends Ext<MPJLambdaWrapper<UserDO>> {
    default MPJLambdaWrapper<UserDO> activeOnly() {
        ((MPJLambdaWrapper<UserDO>) this).eq(UserDO::getDel, 0);
        return (MPJLambdaWrapper<UserDO>) this;
    }
}
```

--------------------------------

### AptWrappers factory class with query factory methods

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/extension-apt.md

Factory class exposing static query methods that accept a BaseColumn and optional entity. Use AptWrappers.query(UserCol.COL) to start building an AptQueryWrapper.

```java
public class AptWrappers {
    public static <T> AptQueryWrapper<T> query(BaseColumn<T> baseColumn)      // e.g. AptWrappers.query(UserCol.COL)
    public static <T> AptQueryWrapper<T> query(BaseColumn<T> baseColumn, T entity)
}
```

--------------------------------

### Error handling example

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/base.md

Example of handling errors when using DeleteJoinWrapper for join deletes.

```APIDOC
## Error handling example

### Description
Demonstrates error handling when performing join deletes with DeleteJoinWrapper, which throws MybatisPlusException for mixed physical/logical delete configurations.

### Code Example
```java
try {
    // Mixed physical/logical delete across joined tables → MybatisPlusException
    DeleteJoinWrapper<UserDO> w = JoinWrappers.delete(UserDO.class)
            .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
            .deleteAll();
    userMapper.deleteJoin(w);
} catch (Exception e) {
    // DeleteJoinWrapper.check() throws: "连表删除只适用于全部表(主表和副表)都是物理删除或全部都是逻辑删除..."
    log.error("join delete failed", e);
}
```
```

--------------------------------

### Usage examples for updateJoin and updateJoinAndNull

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/delete-update-wrappers.md

Usage examples for updateJoin and updateJoinAndNull. The first sets fixed columns and non-null entity fields; the second includes null fields. Both use JoinWrappers.update with leftJoin and eq conditions.

```java
UserMapper userMapper;

// set fixed columns + entity non-null fields
int rows = userMapper.updateJoin(
        new UserDO().setName("x"),
        JoinWrappers.update(UserDO.class)
                .set(UserDO::getName, "y")
                .setIncrBy(UserDO::getAge, 1)
                .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
                .eq(AddressDO::getTel, "10086"));

// update including null fields
int rows2 = userMapper.updateJoinAndNull(
        new UserDO().setName("x"),
        JoinWrappers.update(UserDO.class)
                .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
                .eq(UserDO::getId, 1));
```

--------------------------------

### Kotlin usage example for KtWrappers query, update, and delete

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/extension-kt.md

Demonstrates using KtWrappers to build query, update, and delete wrappers with left joins. The query selects all UserDO fields plus AddressDO.tel, filters by UserDO.id, and returns a list of UserDTO. The update sets UserDO.name and filters by AddressDO.tel. The delete is wrapped in a try-catch to handle the mixed logic/physical delete exception.

```kotlin
import com.github.yulichang.extension.kt.toolkit.KtWrappers

// query
val wrapper = KtWrappers.query(UserDO::class.java)
    .selectAll(UserDO::class.java)
    .select(AddressDO::tel)
    .leftJoin(AddressDO::class.java, AddressDO::userId, UserDO::id)
    .eq(UserDO::id, 1)

val list: List<UserDTO> = userMapper.selectJoinList(UserDTO::class.java, wrapper)

// update
val wrapper2 = KtWrappers.update(UserDO::class.java)
    .set(UserDO::name, "newName")
    .leftJoin(AddressDO::class.java, AddressDO::userId, UserDO::id)
    .eq(AddressDO::tel, "10086")
userMapper.updateJoin(UserDO().apply { name = "other" }, wrapper2)

// delete with error handling
try {
    userMapper.deleteJoin(KtWrappers.delete(UserDO::class.java)
        .leftJoin(AddressDO::class.java, AddressDO::userId, UserDO::id)
        .eq(UserDO::id, 1))
} catch (e: Exception) {
    // mixed logic/physical delete message
}
```

--------------------------------

### MPJQueryWrapper usage with and without SQL-injection protection

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/query-wrappers.md

Usage example for MPJQueryWrapper. The first block builds a wrapper with select, leftJoin, eq, and like, then executes selectJoinList. The second block shows the SQL-injection protection variant: checkSqlInjection() plus selectAll and innerJoin; a suspicious string column triggers MybatisPlusException with message "Discovering SQL injection column: ...".

```java
MPJQueryWrapper<UserDO> wrapper = JoinWrappers.<UserDO>query()
        .select("t.id", "t.name", "t1.tel")
        .leftJoin("address t1 ON t1.user_id = t.id")
        .eq("t.id", 1)
        .like("t1.tel", "1%");

List<UserDTO> list = userMapper.selectJoinList(UserDTO.class, wrapper);
```

```java
// with SQL-injection protection
MPJQueryWrapper<UserDO> safe = JoinWrappers.<UserDO>query(UserDO.class)
        .checkSqlInjection()
        .selectAll(UserDO.class, "t")
        .innerJoin("address t1 ON t1.user_id = t.id");
try {
    userMapper.selectJoinList(UserDTO.class, safe);
} catch (MybatisPlusException e) {
    // "Discovering SQL injection column: ..." if a string column is suspicious
    log.error("rejected SQL", e);
}
```

--------------------------------

### UpdateJoinWrapper<T>

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/delete-update-wrappers.md

Documentation for the UpdateJoinWrapper class, including constructors, SET-clause builders, Update interface methods, usage examples, and error handling.

```APIDOC
## UpdateJoinWrapper<T>

### Description
Wrapper class for building UPDATE statements with JOIN support in MyBatis-Plus-Join. Provides SET-clause builders and implements the Update interface for setting column values, increments, decrements, and raw SQL fragments.

### Constructors
- `UpdateJoinWrapper(Class<T> clazz)` - Recommended constructor, creates a wrapper for the given entity class.
- `UpdateJoinWrapper(T entity)` - Creates a wrapper using an entity, which can also serve as a WHERE base via `join()`.
- `UpdateJoinWrapper(Class<T> clazz, String alias)` - Creates a wrapper with a table alias.
- `UpdateJoinWrapper(T entity, String alias)` - Creates a wrapper with an entity and a table alias.

### Methods
#### setUpdateEntity
```java
public UpdateJoinWrapper<T> setUpdateEntity(Object... entity)
```
Sets entity fields (non-null only) as SET values. Throws `Assert.notNull` if any entity is null.

#### setUpdateEntityAndNull
```java
public UpdateJoinWrapper<T> setUpdateEntityAndNull(Object... entity)
```
Sets entity fields including null fields as SET values. Throws `Assert.notNull` if any entity is null.

#### set
```java
public <R> UpdateJoinWrapper<T> set(boolean condition, SFunction<R, ?> column, Object val, String mapping)
public <R, V> UpdateJoinWrapper<T> set(boolean condition, SFunction<R, ?> column, SFunction<V, ?> val, String mapping)
```
Sets a column to a value or another column's value, with optional mapping.

#### setIncrBy
```java
public <R> UpdateJoinWrapper<T> setIncrBy(boolean condition, SFunction<R, ?> column, Number val)
```
Increments a column by the given value (`column = column + val`).

#### setDecrBy
```java
public <R> UpdateJoinWrapper<T> setDecrBy(boolean condition, SFunction<R, ?> column, Number val)
```
Decrements a column by the given value (`column = column - val`).

#### setApply
```java
public Children setApply(boolean condition, String applySql, MFunction<FuncConsumer> consumerFunction, Object... values)
```
Applies raw SQL with `{0}` column placeholders resolved through `FuncConsumer`.

#### setSql
```java
public Children setSql(boolean condition, String sql)
```
Sets a raw SQL fragment for the SET clause.

#### getSqlSet
```java
public String getSqlSet()
```
Returns the accumulated SQL SET string.

### Usage Example
```java
UserMapper userMapper;

// set fixed columns + entity non-null fields
int rows = userMapper.updateJoin(
        new UserDO().setName("x"),
        JoinWrappers.update(UserDO.class)
                .set(UserDO::getName, "y")
                .setIncrBy(UserDO::getAge, 1)
                .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
                .eq(AddressDO::getTel, "10086"));

// update including null fields
int rows2 = userMapper.updateJoinAndNull(
        new UserDO().setName("x"),
        JoinWrappers.update(UserDO.class)
                .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
                .eq(UserDO::getId, 1));
```

### Errors
- `Assert.notNull(obj, "更新实体不能为空")` when passing `null` entities to `setUpdateEntity`/`setUpdateEntityAndNull`.
- Same join-content checks as `MPJLambdaWrapper` (missing main class, mixed logic delete for `deleteJoin`, etc.).
```

--------------------------------

### Custom MPJSqlInjector composition

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/sql-injector.md

Composes a custom MyBatis-Plus injector with MPJ's MPJSqlInjector, wrapping an existing injector. Required only for non-Starter setups (e.g., plain MyBatis-Plus or Solon); Spring Boot provides this bean automatically.

```java
import com.github.yulichang.injector.MPJSqlInjector;
import com.baomidou.mybatisplus.core.injector.ISqlInjector;

@Bean
public ISqlInjector mpjSqlInjector(ISqlInjector origin) {
    // wraps your existing injector; MPJ methods are appended, MP packaged methods replaced
    return new MPJSqlInjector(origin);
}
```

--------------------------------

### Configure mybatis-plus-join properties in application.yml

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/configuration.md

Configure the mybatis-plus-join starter in application.yml. All keys are optional; defaults are shown. The logic-del-type accepts ON or WHERE, and if-exists accepts NOT_NULL, NOT_EMPTY, or NOT_BLANK.

```yaml
mybatis-plus-join:
  banner: true
  table-alias: t
  sub-table-logic: true
  join-prefix: join
  logic-del-type: ON        # or WHERE
  mapping-max-count: 5
  sub-query-alias: st
  if-exists: NOT_EMPTY      # NOT_NULL | NOT_EMPTY | NOT_BLANK
```

--------------------------------

### join(String keyWord, Class<R> clazz, MConsumer<MPJLambdaWrapper<R>> table, String tableAlias, BiConsumer<JoinAbstractLambdaWrapper<T, ?>, Children> consumer)

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/mpjlambda-wrapper.md

Core join implementation that builds a join clause with a table wrapper and consumer. Marked as internal and not recommended for direct use.

```APIDOC
## join(String keyWord, Class<R> clazz, MConsumer<MPJLambdaWrapper<R>> table, String tableAlias, BiConsumer<JoinAbstractLambdaWrapper<T, ?>, Children> consumer)

### Description
Core join implementation that builds a join clause with a table wrapper and consumer. Marked as internal and not recommended for direct use.

### Method
join

### Signature
public <R> Children join(String keyWord, Class<R> clazz, MConsumer<MPJLambdaWrapper<R>> table, String tableAlias, BiConsumer<JoinAbstractLambdaWrapper<T, ?>, Children> consumer)

### Parameters
- **keyWord** (String) - Required - Join keyword (e.g., LEFT JOIN, RIGHT JOIN).
- **clazz** (Class<R>) - Required - Class of the joined table entity.
- **table** (MConsumer<MPJLambdaWrapper<R>>) - Required - Consumer to configure the joined table wrapper.
- **tableAlias** (String) - Required - Alias for the joined table.
- **consumer** (BiConsumer<JoinAbstractLambdaWrapper<T, ?>, Children>) - Required - Consumer to configure the join condition.

### Returns
- **Children** - The wrapper instance for chaining.

```

--------------------------------

### Use APT-generated columns with AptWrappers.query

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/annotations.md

Demonstrates the APT-based approach: annotate an entity with @Table and @TableName, and the annotation processor generates a UserCol class and a Tables facade member. The generated UserCol.COL is used with AptWrappers.query to create an AptQueryWrapper, and selectAll/eq methods are chained.

```java
@Table
@TableName("`user`")
public class UserDO {
    private Integer id;
    private String name;
}

// the annotation processor generates (package user.apt):
//     UserCol  (columns: ID, NAME)
// and a Tables facade member for UserDO.
// Usage:
AptQueryWrapper<UserDO> w = AptWrappers.query(UserCol.COL);   // BaseColumn<UserDO>
w.selectAll(UserCol.COL).eq(UserCol::getId, 1);
```

--------------------------------

### AptWrappers Factory Methods

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/extension-apt.md

Factory methods for creating AptQueryWrapper instances with column references.

```APIDOC
## AptWrappers.query(BaseColumn<T> baseColumn)

### Description
Creates an `AptQueryWrapper<T>` instance using a `BaseColumn<T>` reference. This is the entry point for building type-safe queries with column references.

### Method
Factory method (static)

### Parameters
- **baseColumn** (`BaseColumn<T>`) - Required - The column reference to initialize the wrapper with.

### Returns
- `AptQueryWrapper<T>` - A new query wrapper instance.

### Example
```java
AptQueryWrapper<UserDO> wrapper = AptWrappers.query(UserCol.COL);
```

## AptWrappers.query(BaseColumn<T> baseColumn, T entity)

### Description
Creates an `AptQueryWrapper<T>` instance using a `BaseColumn<T>` reference and an entity object. The entity can be used for condition building.

### Method
Factory method (static)

### Parameters
- **baseColumn** (`BaseColumn<T>`) - Required - The column reference to initialize the wrapper with.
- **entity** (`T`) - Required - The entity object to associate with the wrapper.

### Returns
- `AptQueryWrapper<T>` - A new query wrapper instance.

### Example
```java
AptQueryWrapper<UserDO> wrapper = AptWrappers.query(UserCol.COL, new UserDO());
```
```

--------------------------------

### setUpdateEntity and setUpdateEntityAndNull methods

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/delete-update-wrappers.md

SET-clause builder methods. setUpdateEntity sets non-null entity fields; setUpdateEntityAndNull includes null fields. Entities are SET values only, not WHERE conditions.

```java
public UpdateJoinWrapper<T> setUpdateEntity(Object... entity)        // entity fields -> SET (non-null only); Assert.notNull each
public UpdateJoinWrapper<T> setUpdateEntityAndNull(Object... entity) // entity fields -> SET including null fields
```

--------------------------------

### Basic MPJLambdaWrapper join query with pagination

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/mpjlambda-wrapper.md

Shows a basic join query using MPJLambdaWrapper, selecting all columns from UserDO and a specific column from AddressDO via a left join. Includes filtering with eq and like, and demonstrates both selectJoinList and selectJoinPage usage.

```java
@Resource
private UserMapper userMapper;

MPJLambdaWrapper<UserDO> wrapper = JoinWrappers.lambda(UserDO.class)
        .selectAll(UserDO.class)
        .select(AddressDO::getTel)
        .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
        .eq(UserDO::getId, 1)
        .like(AddressDO::getTel, "1");

List<UserDTO> list = userMapper.selectJoinList(UserDTO.class, wrapper);
Page<UserDTO> listPage = userMapper.selectJoinPage(new Page<>(2, 10), UserDTO.class, wrapper);
```

--------------------------------

### MPJLambdaWrapper two-level nesting example

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/resultmap.md

Use this snippet to build a two-level nested result mapping with MPJLambdaWrapper. It selects all columns from UserDO, maps a collection of AddressDTO with an associated AreaDTO, and maps a single AreaDTO association, joining AddressDO and AreaDO tables. The resulting list is obtained via userMapper.selectJoinList().

```java
public class UserDTO {
    private Integer id;
    private String name;
    private List<AddressDTO> addressListDTO;   // List element type AddressDTO
    private AreaDTO areaDTO;                   // single association
}

MPJLambdaWrapper<UserDO> wrapper = JoinWrappers.lambda(UserDO.class)
        .selectAll(UserDO.class)
        .selectCollection(AddressDO.class, UserDTO::getAddressListDTO, c -> c
                .id(AddressDO::getId, AddressDTO::getId)
                .result(AddressDO::getTel, AddressDTO::getTel)
                .association(AreaDO.class, AddressDTO::getAreaDTO))
        .selectAssociation(AreaDO.class, UserDTO::getAreaDTO)
        .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
        .leftJoin(AreaDO.class, AreaDO::getId, AddressDO::getAreaId);

List<UserDTO> list = userMapper.selectJoinList(UserDTO.class, wrapper);
```

--------------------------------

### MPJWrappers.queryJoin()

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/join-wrappers.md

Older factory methods for creating MPJQueryWrapper instances. Replaced by JoinWrappers.query().

```APIDOC
## MPJWrappers.queryJoin()

### Description
Older factory methods for creating MPJQueryWrapper instances. Replaced by JoinWrappers.query().

### Method
static factory method

### Signature
```java
public static <T> MPJQueryWrapper<T> queryJoin()
public static <T> MPJQueryWrapper<T> queryJoin(T entity)
public static <T> MPJQueryWrapper<T> queryJoin(Class<T> entityClass)
```

### Parameters
- `entity` (T) - Optional - Main-table entity instance.
- `entityClass` (Class<T>) - Optional - Main-table entity class.

### Notes
Javadoc points to `JoinWrappers` as the replacement.
```

--------------------------------

### MPJTableInfoHelper static methods

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/extension-mapping.md

Static helper methods for retrieving and initializing MPJ table metadata. getTableInfo returns null for primitives, String, and interfaces, and lazily initializes on first call; initTableInfo and initMapping are synchronized. The cache is TABLE_INFO_CACHE (ConcurrentHashMap).

```java
public static MPJTableInfo getTableInfo(Class<?> clazz)          // null for primitives/String/interface; lazy init on first call
public synchronized static void initTableInfo(Class<?> clazz, Class<?> mapperClass)
public static void initMapping(MPJTableInfo mpjTableInfo)
```

--------------------------------

### from(MFunction<MPJLambdaWrapper<T>> fromWrapper)

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/mpjlambda-wrapper.md

Adds FROM (sub-query) support.

```APIDOC
## from(MFunction<MPJLambdaWrapper<T>> fromWrapper)

### Description
Adds FROM (sub-query) support.

### Method
from

### Signature
public Children from(MFunction<MPJLambdaWrapper<T>> fromWrapper)

### Parameters
- **fromWrapper** (MFunction<MPJLambdaWrapper<T>>) - Required - Function to configure the sub-query wrapper.

### Returns
- **Children** - The wrapper instance for chaining.

```

--------------------------------

### ConfigProperties static fields

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/configuration.md

Static configuration class with public static fields for banner, sub-table logic delete, aliases, logic-delete type, mapping depth, and IfExists predicate. Defaults: banner=true, subTableLogic=true, tableAlias="t", joinPrefix="join", logicDelType=ON, mappingMaxCount=5, subQueryAlias="st", ifExists=NOT_EMPTY. Nested Convert class holds serialization-safe staging value.

```java
public class ConfigProperties {

    public static boolean banner = true;
    public static boolean subTableLogic = true;
    public static String tableAlias = "t";
    public static String joinPrefix = "join";
    public static LogicDelTypeEnum logicDelType = LogicDelTypeEnum.ON;
    public static int mappingMaxCount = 5;
    public static String subQueryAlias = "st";
    public static MBiPredicate<Object, IfExistsSqlKeyWordEnum> ifExists = (val, key) -> IfExistsEnum.NOT_EMPTY.test(val);

    public static class Convert {
        public static IfExistsEnum IfExists = IfExistsEnum.NOT_EMPTY;
    }
}
```

--------------------------------

### MybatisPlusJoinProperties configuration class

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/boot-starter.md

Configuration properties class bound to the 'mybatis-plus-join' prefix. Defaults include banner=true, tableAlias="t", subTableLogic=true, joinPrefix="join", logicDelType=ON, mappingMaxCount=5, subQueryAlias="st", and IfExists=NOT_EMPTY. Spring Boot metadata is shipped in META-INF/additional-spring-configuration-metadata.json, also documenting the legacy key mybatis-plus-join.ms-cache.

```java
@Data
@Accessors(chain = true)
@ConfigurationProperties(prefix = "mybatis-plus-join")
public class MybatisPlusJoinProperties {

    private Boolean banner = true;
    private String tableAlias = "t";
    private Boolean subTableLogic = true;
    private String joinPrefix = "join";
    private LogicDelTypeEnum logicDelType = LogicDelTypeEnum.ON;
    private int mappingMaxCount = 5;
    private String subQueryAlias = "st";
    private IfExistsEnum IfExists = IfExistsEnum.NOT_EMPTY;
}
```

--------------------------------

### MPJQueryWrapper<T>

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/query-wrappers.md

Documentation for the MPJQueryWrapper class, covering constructors, select management, join management, alias and logic delete, SQL injection filtering, lambda bridge, and comparison methods.

```APIDOC
## MPJQueryWrapper<T>

### Description
A query wrapper for MyBatis-Plus Join that supports raw SQL joins, select management, aliases, logic delete, dynamic table names, SQL injection filtering, and string-column comparison methods.

### Constructors
- `MPJQueryWrapper()` - Creates an empty wrapper.
- `MPJQueryWrapper(Class<T> clazz)` - Creates a wrapper for the given entity class.
- `MPJQueryWrapper(T entity)` - Creates a wrapper for the given entity instance.
- `MPJQueryWrapper(T entity, Class<T> entityClass, ...)` - Internal constructor for nested SQL; not public.

### Select Management
- `select(String... columns)` - Selects the specified columns.
- `select(boolean condition, List<String> columns)` - Selects columns if condition is true.
- `select(Class<T> entityClass, Predicate<TableFieldInfo> predicate)` - Selects main-table columns matching the predicate, excluding primary key.
- `selectIgnore(String... columns)` - Excludes the specified columns from the select (since 1.1.3).
- `selectAll(Class<T> clazz)` - Selects all main-table columns with the current alias.
- `selectAll(Class<?> clazz, String as)` - Selects all columns of the entity with the given alias.
- `distinct()` - Adds DISTINCT to the select.
- `getSqlSelect()` - Returns the select SQL string (removes ignored columns on first call).
- `getSelectDistinct()` - Returns whether DISTINCT is enabled.

### Join Management (Raw SQL)
- `join(String keyWord, boolean condition, String joinSql, Object... params)` - Adds a join clause.
  - `keyWord` (String) - Join keyword, e.g., "LEFT JOIN".
  - `condition` (boolean) - If false, the clause is skipped.
  - `joinSql` (String) - Full join clause, e.g., "address t1 ON t1.user_id = t.id".
  - `params` (Object...) - Positional `{0}` parameters (supports `{0,typeHandler}` syntax).
- Convenience methods from `StringJoin` interface: `leftJoin(...)`, `rightJoin(...)`, `innerJoin(...)`, `fullJoin(...)` - Each has overloads with condition and parameters, all delegate to `join`.

### Alias, Logic Delete, Dynamic Table Name
- `setAlias(String alias)` - Sets the main-table alias; must be called before `selectAll`.
- `getAlias()` - Returns the current alias.
- `disableLogicDel()` / `enableLogicDel()` - Toggles logic delete handling.
- `getLogicSql()` - Returns whether logic delete SQL is applied.
- `getSubLogicSql()` - Always returns empty string for this wrapper.
- `setTableName(Function<String, String> func)` - Sets a function to dynamically change the main-table name.
- `getTableName(String tableName)` - Applies the table name function.
- `getTableNameEnc(String tableName)` - URL-decodes then applies the function.

### SQL Injection Filter and IfExists
- `checkSqlInjection()` - Enables validation of string columns passed to `columnToString`.
- `setIfExists(BiPredicate<Object, IfExistsSqlKeyWordEnum> IfExists)` - Sets a predicate for IfExists variants.
- `setIfExists(Predicate<Object> IfExists)` - Sets a predicate for IfExists variants.
- `columnToString(String column)` - Throws `MybatisPlusException` if SQL injection is detected when `checkSqlInjection` is enabled.

### Lambda Bridge
- `lambda()` - Converts this wrapper to a `MPJLambdaQueryWrapper`, preserving state.

### Comparison Methods
String-column variants of all standard operators: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `like`, `notLike`, `likeLeft/Right`, `notLikeLeft/Right`, `between`, `notBetween`, `isNull`, `isNotNull`, `in`, `notIn`, `inSql`, `notInSql`, `gtSql`, `geSql`, `ltSql`, `leSql`, `eqSql`, plus grouping methods `and`, `or`, `nested`, `not`, and `apply`, `last`, `first`, `comment`, `around`, `exists`, `notExists`, `groupBy`, `orderByAsc/Desc`, `having`, `func`. All have `(condition, ...)` overloads; IfExists variants check the value with the configured predicate.
```

--------------------------------

### AptQueryWrapper<T>

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/extension-apt.md

The AptQueryWrapper class provides a fluent API for building type-safe queries with column references, including select, join, condition, and result mapping methods.

```APIDOC
## AptQueryWrapper<T> Class

### Description
A query wrapper that mirrors `MPJLambdaWrapper` but uses `Column`-typed references instead of `SFunction`. It provides type-safe query building with select, join, condition, and result mapping capabilities.

### Methods
- `select` - Select specific columns.
- `selectAll(BaseColumn<T>)` - Select all columns from a table.
- `selectFunc` - Select function results.
- `selectSub` - Select subquery results.
- `union` / `unionAll` - Combine query results.
- `distinct` - Apply distinct to the query.
- Join methods (via `QueryJoin`) - Perform joins.
- Condition methods (via `Compare` and `CompareIfExists`) - Add conditions like `eq`, `ne`, etc.
- Result mapping (via `QueryLabel`) - Map results to collections or associations.
- `Chain` terminal methods - Execute the query.
- `SelectWrapper` contract - For interceptor integration.

### Example
```java
AptQueryWrapper<UserDO> wrapper = AptWrappers.query(UserCol.COL)
        .selectAll(UserCol.COL)
        .select(AddressCol.TEL)
        .leftJoin(AddressCol.COL, AddressCol.USER_ID, UserCol.ID)
        .eq(UserCol.ID, 1);
List<UserDTO> users = userMapper.selectJoinList(UserDTO.class, wrapper);
```
```

--------------------------------

### JoinWrappers static factory methods

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/join-wrappers.md

Static factory methods from JoinWrappers for creating query, lambda, delete, and update wrappers. Query wrappers support raw SQL when no entity class is set; lambda wrappers accept an optional alias (default "t"), entity class, or entity instance; delete and update wrappers require an entity class.

```java
public class JoinWrappers {
```

```java
public static <T> MPJQueryWrapper<T> query()
public static <T> MPJQueryWrapper<T> query(Class<T> clazz)
public static <T> MPJQueryWrapper<T> query(T entity)
```

```java
public static <T> MPJLambdaWrapper<T> lambda()
public static <T> MPJLambdaWrapper<T> lambda(String alias)
public static <T> MPJLambdaWrapper<T> lambda(Class<T> clazz)
public static <T> MPJLambdaWrapper<T> lambda(String alias, Class<T> clazz)
public static <T> MPJLambdaWrapper<T> lambda(T entity)
public static <T> MPJLambdaWrapper<T> lambda(String alias, T entity)
```

```java
public static <T> DeleteJoinWrapper<T> delete(Class<T> clazz)
public static <T> DeleteJoinWrapper<T> delete(String alias, Class<T> clazz)
```

```java
public static <T> UpdateJoinWrapper<T> update(Class<T> clazz)
public static <T> UpdateJoinWrapper<T> update(String alias, Class<T> clazz)
```

--------------------------------

### Ext marker interface for wrapper extension

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/plugins.md

Empty marker interface implemented by JoinAbstractLambdaWrapper. Users add default methods to a sub-interface to customize their wrapper class.

```java
public interface Ext<Wrapper> {
}
```

--------------------------------

### MPJBaseServiceImpl class

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/base.md

Concrete service base class. Your service implementation extends this exactly as you would extend MyBatis-Plus ServiceImpl.

```java
public class MPJBaseServiceImpl<M extends MPJBaseMapper<T>, T> extends ServiceImpl<M, T> implements MPJBaseService<T> {

}
```

--------------------------------

### Advanced MPJLambdaWrapper with union, sub-query, and fill

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/mpjlambda-wrapper.md

Demonstrates advanced features: sub-query selection, union, fill callback, ordering, and a last limit clause. The fill callback prints fetched objects. Requires a UserMapper instance.

```java
MPJLambdaWrapper<UserDO> wrapper = JoinWrappers.lambda(UserDO.class)
        .selectAll(UserDO.class)
        .selectSub(AddressDO.class, "st", a -> a
                .select(AddressDO::getTel)
                .eq(AddressDO::getUserId, 1), UserDTO::getTel)
        .union(UserDO.class, u -> u.selectAll(UserDO.class).eq(UserDO::getId, 999))
        .addFill(obj -> System.out.println("fetched: " + obj))
        .orderByDesc(UserDO::getId)
        .last("limit 10");

List<UserDTO> list = userMapper.selectJoinList(UserDTO.class, wrapper);
```

--------------------------------

### MPJMappingConfig nested class

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/boot-starter.md

Nested configuration class that initializes mapping metadata after application ready.

```java
@Configuration @Order(Ordered.HIGHEST_PRECEDENCE)
@ConditionalOnClass({SqlSessionFactory.class, SqlSessionFactoryBean.class})
public static class MPJMappingConfig implements ApplicationListener<ApplicationReadyEvent> {
    @Override public void onApplicationEvent(ApplicationReadyEvent applicationReadyEvent) { MappingConfig.init(); }
}
```

--------------------------------

### MybatisLabel.Builder<E,T> build()

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/resultmap.md

Builds the MybatisLabel instance. If no result mappings have been added, it auto-builds all columns.

```APIDOC
## MybatisLabel.Builder<E,T> build()

### Description
Builds the MybatisLabel instance. If no result mappings have been added, it auto-builds all columns.

### Method
Builder method

### Signature
```java
public MybatisLabel<E, T> build()
```

### Returns
- **MybatisLabel<E,T>** - the built label
```

--------------------------------

### KtWrappers.query(String alias, Class<T> clazz)

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/extension-kt.md

Creates a KtLambdaWrapper for query operations with an alias for the main table.

```APIDOC
## KtWrappers.query(String alias, Class<T> clazz)

### Description
Creates a KtLambdaWrapper for query operations with an alias for the main table.

### Method
Factory method

### Endpoint
KtWrappers.query(String alias, Class<T> clazz)

### Parameters
- **alias** (String) - Required - Alias for the main table.
- **clazz** (Class<T>) - Required - The entity class to query.

### Returns
KtLambdaWrapper<T> - A query wrapper instance.

```

--------------------------------

### MybatisPlusJoinAutoConfiguration class declaration

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/boot-starter.md

Main auto-configuration class with conditions and constructor. It reads properties and resolves ifExists from consumer beans.

```java
@Configuration(proxyBeanMethods = false)
@ConditionalOnClass({SqlSessionFactory.class, SqlSessionFactoryBean.class})
@ConditionalOnSingleCandidate(DataSource.class)
@EnableConfigurationProperties(MybatisPlusJoinProperties.class)
@AutoConfigureAfter(MybatisPlusAutoConfiguration.class)
public class MybatisPlusJoinAutoConfiguration {

    public MybatisPlusJoinAutoConfiguration(MybatisPlusJoinProperties properties,
                                            ObjectProvider<MybatisPlusJoinPropertiesConsumer> propertiesConsumers,
                                            ObjectProvider<MybatisPlusJoinIfExistsConsumer> IfExistsConsumers) { ... }
```

--------------------------------

### getLogicSql()

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/mpjlambda-wrapper.md

Returns the main-table logic-delete flag.

```APIDOC
## getLogicSql()

### Description
Returns the main-table logic-delete flag.

### Method
getLogicSql

### Signature
public boolean getLogicSql()

### Returns
- **boolean** - The main-table logic-delete flag.

```

--------------------------------

### Join query with MPJLambdaWrapper

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/base.md

Shows how to use MPJBaseMapper with MPJLambdaWrapper to perform a left join query. The wrapper selects all UserDO fields plus the tel field from AddressDO, filters by user id and tel, and then the mapper methods return a list, page, and count.

```java
import com.github.yulichang.base.MPJBaseMapper;
import com.github.yulichang.wrapper.MPJLambdaWrapper;
import com.github.yulichang.toolkit.JoinWrappers;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;

public interface UserMapper extends MPJBaseMapper<UserDO> {
}

// Basic join list mapped to a DTO
MPJLambdaWrapper<UserDO> wrapper = JoinWrappers.lambda(UserDO.class)
        .selectAll(UserDO.class)
        .select(AddressDO::getTel)
        .leftJoin(AddressDO.class, AddressDO::getUserId, UserDO::getId)
        .eq(UserDO::getId, 1)
        .like(AddressDO::getTel, "1");

List<UserDTO> list = userMapper.selectJoinList(UserDTO.class, wrapper);
Page<UserDTO> page = userMapper.selectJoinPage(new Page<>(1, 10), UserDTO.class, wrapper);
Long total = userMapper.selectJoinCount(wrapper);
```

--------------------------------

### MPJBaseService interface

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/base.md

Marker interface combining MyBatis-Plus IService and JoinService. Extend this to create your service interface.

```java
public interface MPJBaseService<T> extends IService<T>, JoinService<T> {

}
```

--------------------------------

### SqlHelper.exec

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/chain.md

Static method that resolves the JoinMapper for the given entity class and executes the provided function against it. Throws exceptions if the entity class is null, the mapper is not initialized, or the mapper does not extend MPJBaseMapper.

```APIDOC
## SqlHelper.exec

### Description
Static method that resolves the JoinMapper for the given entity class and executes the provided function against it. Throws exceptions if the entity class is null, the mapper is not initialized, or the mapper does not extend MPJBaseMapper.

### Method
N/A (static method)

### Endpoint
N/A

### Parameters
#### Parameters
- **entityClass** (Class<T>) - Required - The entity class used to resolve the mapper.
- **function** (Function<JoinMapper<T>, R>) - Required - Function that receives the resolved JoinMapper and returns a result.

### Request Example
```java
SqlHelper.exec(UserDO.class, mapper -> mapper.selectList(...));
```

### Response
#### Success Response
- **R** - The result of the function applied to the JoinMapper.

#### Response Example
N/A

### Error Handling
- Throws `IllegalArgumentException` if entityClass is null: "请使用 new MPJLambdaWrapper(主表.class) 或 JoinWrappers.lambda(主表.class) 构造方法"
- Throws `IllegalArgumentException` if mapper is not initialized: "mapper not init <entityClass>"
- Throws `IllegalArgumentException` if mapper is not a JoinMapper: "mapper <mapper> not extends MPJBaseMapper"
```

--------------------------------

### MPJBaseService interface

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/base.md

Marker interface combining MyBatis-Plus IService and JoinService to provide join query capabilities.

```APIDOC
## MPJBaseService (interface)

### Description
Marker interface combining MyBatis-Plus `com.baomidou.mybatisplus.spring.service.IService` and `JoinService`.

### Interface Definition
```java
public interface MPJBaseService<T> extends IService<T>, JoinService<T> {

}
```
```

--------------------------------

### Customize MyBatis Plus Join with MPJCustomizeConfig

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/boot-starter.md

Defines a @Configuration class with two @Bean methods: one overrides the global IfExists strategy via MybatisPlusJoinIfExistsConsumer, and the other sets properties programmatically via MybatisPlusJoinPropertiesConsumer, such as table alias and sub-table logic.

```java
@Configuration
public class MPJCustomizeConfig {

    // override global IfExists strategy
    @Bean
    public MybatisPlusJoinIfExistsConsumer myIfExists() {
        return (val, keyword) -> val != null;
    }

    // override properties programmatically
    @Bean
    public MybatisPlusJoinPropertiesConsumer myProps() {
        return props -> props.setTableAlias("a").setSubTableLogic(false);
    }
}
```

--------------------------------

### addFill and doFill method signatures

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/mpjlambda-wrapper.md

addFill registers a call-back which MPJInterceptor.fill invokes on each query result object (doFill(proceed)), enabling post-processing of fetched rows.

```java
@Override public MPJLambdaWrapper<T> addFill(MConsumer<Object> consumer)
@Override public void doFill(Object obj)
```

--------------------------------

### pageByMain()

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/mpjlambda-wrapper.md

Paginates by main-table counts.

```APIDOC
## pageByMain()

### Description
Paginates by main-table counts.

### Method
pageByMain

### Signature
public Children pageByMain()

### Returns
- **Children** - The wrapper instance for chaining.

```

--------------------------------

### clear() method signature

Source: https://github.com/yulichang/mybatis-plus-join/blob/master/_autodocs/api-reference/mpjlambda-wrapper.md

Resets all state: distinct flag, sqlSelect, select columns, union SQL, result-map labels, ifExists (back to ConfigProperties.ifExists), fill list.

```java
@Override public void clear()
```
Tokens:
Raw