0
# MyBatis-Plus Extension
1

2
MyBatis-Plus Extension is an advanced toolkit that enhances MyBatis-Plus with comprehensive service layers, Kotlin extensions, SQL parsers, caching mechanisms, and various interceptors. It provides higher-level abstractions and utilities that build upon the core MyBatis-Plus functionality to significantly reduce boilerplate code and improve development productivity in enterprise Java applications.
3

4
## Package Information
5

6
- **Package Name**: mybatis-plus-extension
7
- **Package Type**: maven
8
- **Language**: Java/Kotlin
9
- **Group ID**: com.baomidou
10
- **Artifact ID**: mybatis-plus-extension
11
- **Installation**: Add to your Maven dependencies:
12

13
```xml
14
<dependency>
15
    <groupId>com.baomidou</groupId>
16
    <artifactId>mybatis-plus-extension</artifactId>
17
    <version>3.5.7</version>
18
</dependency>
19
```
20

21
Or Gradle:
22

23
```gradle
24
implementation 'com.baomidou:mybatis-plus-extension:3.5.7'
25
```
26

27
## Core Imports
28

29
```java
30
import com.baomidou.mybatisplus.extension.service.IService;
31
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
32
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
33
import com.baomidou.mybatisplus.extension.conditions.query.QueryWrapper;
34
import com.baomidou.mybatisplus.extension.toolkit.Db;
35
```
36

37
## Basic Usage
38

39
```java
40
import com.baomidou.mybatisplus.extension.service.IService;
41
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
42
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
43
import com.baomidou.mybatisplus.extension.conditions.query.QueryWrapper;
44

45
// Define a service interface
46
public interface UserService extends IService<User> {
47
    // Custom methods can be added here
48
}
49

50
// Implement the service
51
@Service
52
public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
53
    // ServiceImpl provides all CRUD operations automatically
54
}
55

56
// Use the service
57
@Autowired
58
private UserService userService;
59

60
// Basic CRUD operations
61
User user = new User("John", "john@example.com");
62
userService.save(user);
63

64
List<User> users = userService.list();
65
User foundUser = userService.getById(1L);
66

67
// Query with conditions
68
List<User> activeUsers = userService.list(
69
    new QueryWrapper<User>().eq("active", true)
70
);
71

72
// Pagination
73
Page<User> page = userService.page(new Page<>(1, 10));
74
```
75

76
## Architecture
77

78
MyBatis-Plus Extension is built around several key architectural components:
79

80
- **Service Layer**: `IService` interface and `ServiceImpl` base class providing comprehensive CRUD operations
81
- **Condition Builders**: Chain-style query and update wrappers for fluent API construction
82
- **Plugin System**: Interceptor-based architecture for cross-cutting concerns like pagination, multi-tenancy, and data permissions
83
- **Active Record**: Model base class enabling entity-level CRUD operations
84
- **Static Utilities**: `Db` class providing service-layer operations without dependency injection
85
- **Kotlin Extensions**: Type-safe Kotlin DSL wrappers for enhanced developer experience
86
- **SQL Parser Integration**: JSqlParser-based SQL manipulation and analysis capabilities
87

88
## Capabilities
89

90
### Service Layer
91

92
Comprehensive service layer with `IService` interface providing all common CRUD operations, batch processing, and method chaining. The `ServiceImpl` base class offers ready-to-use implementations.
93

94
```java { .api }
95
public interface IService<T> {
96
    int DEFAULT_BATCH_SIZE = 1000;
97
    
98
    // Save operations
99
    boolean save(T entity);
100
    boolean saveBatch(Collection<T> entityList);
101
    boolean saveBatch(Collection<T> entityList, int batchSize);
102
    boolean saveOrUpdate(T entity);
103
    boolean saveOrUpdateBatch(Collection<T> entityList);
104
    boolean saveOrUpdateBatch(Collection<T> entityList, int batchSize);
105
    
106
    // Query operations
107
    T getById(Serializable id);
108
    Optional<T> getOptById(Serializable id);
109
    List<T> list();
110
    List<T> list(Wrapper<T> queryWrapper);
111
    List<T> listByIds(Collection<? extends Serializable> idList);
112
    List<T> listByMap(Map<String, Object> columnMap);
113
    T getOne(Wrapper<T> queryWrapper);
114
    T getOne(Wrapper<T> queryWrapper, boolean throwEx);
115
    Optional<T> getOneOpt(Wrapper<T> queryWrapper);
116
    Optional<T> getOneOpt(Wrapper<T> queryWrapper, boolean throwEx);
117
    Map<String, Object> getMap(Wrapper<T> queryWrapper);
118
    <V> V getObj(Wrapper<T> queryWrapper, Function<? super Object, V> mapper);
119
    Page<T> page(IPage<T> page);
120
    <E extends IPage<T>> E page(E page, Wrapper<T> queryWrapper);
121
    long count();
122
    long count(Wrapper<T> queryWrapper);
123
    boolean exists(Wrapper<T> queryWrapper);
124
    
125
    // Update operations
126
    boolean updateById(T entity);
127
    boolean update(T entity, Wrapper<T> updateWrapper);
128
    boolean update(Wrapper<T> updateWrapper);
129
    boolean updateBatchById(Collection<T> entityList);
130
    boolean updateBatchById(Collection<T> entityList, int batchSize);
131
    
132
    // Remove operations
133
    boolean removeById(Serializable id);
134
    boolean removeById(Serializable id, boolean useFill);
135
    boolean removeById(T entity);
136
    boolean removeByIds(Collection<?> list);
137
    boolean removeByIds(Collection<?> list, boolean useFill);
138
    boolean removeByMap(Map<String, Object> columnMap);
139
    boolean remove(Wrapper<T> queryWrapper);
140
    boolean removeBatchByIds(Collection<?> list);
141
    boolean removeBatchByIds(Collection<?> list, boolean useFill);
142
    
143
    // Chain operations
144
    QueryChainWrapper<T> query();
145
    LambdaQueryChainWrapper<T> lambdaQuery();
146
    LambdaQueryChainWrapper<T> lambdaQuery(T entity);
147
    KtQueryChainWrapper<T> ktQuery();
148
    UpdateChainWrapper<T> update();
149
    LambdaUpdateChainWrapper<T> lambdaUpdate();
150
    KtUpdateChainWrapper<T> ktUpdate();
151
    
152
    // Utility methods
153
    BaseMapper<T> getBaseMapper();
154
    Class<T> getEntityClass();
155
}
156

157
public abstract class ServiceImpl<M extends BaseMapper<T>, T> implements IService<T> {
158
    @Autowired
159
    protected M baseMapper;
160
    protected final Log log;
161
    private Class<T> entityClass;
162
    private Class<M> mapperClass;
163
    private volatile SqlSessionFactory sqlSessionFactory;
164
    
165
    public M getBaseMapper();
166
    public Class<T> getEntityClass();
167
    public Class<M> getMapperClass();
168
    protected SqlSessionFactory getSqlSessionFactory();
169
}
170
```
171

172
[Service Layer](./service-layer.md)
173

174
### Condition Builders
175

176
Fluent API for building complex database queries and updates with method chaining. Supports both traditional and lambda-based property references.
177

178
```java { .api }
179
public class QueryChainWrapper<T> implements ChainQuery<T> {
180
    public QueryChainWrapper(BaseMapper<T> baseMapper);
181
    public QueryChainWrapper(Class<T> entityClass);
182
    
183
    public List<T> list();
184
    public T one();
185
    public long count();
186
    public Page<T> page(IPage<T> page);
187
}
188

189
public class UpdateChainWrapper<T> implements ChainUpdate<T> {
190
    public UpdateChainWrapper(BaseMapper<T> baseMapper);
191
    public UpdateChainWrapper(Class<T> entityClass);
192
    
193
    public boolean update();
194
    public boolean remove();
195
}
196
```
197

198
[Condition Builders](./condition-builders.md)
199

200
### Plugin System
201

202
Interceptor-based plugin architecture supporting pagination, multi-tenancy, data permissions, optimistic locking, and SQL security features.
203

204
```java { .api }
205
public class MybatisPlusInterceptor implements Interceptor {
206
    public void addInnerInterceptor(InnerInterceptor innerInterceptor);
207
    public List<InnerInterceptor> getInterceptors();
208
}
209

210
public interface InnerInterceptor {
211
    void willDoQuery(Executor executor, MappedStatement ms, Object parameter, 
212
                    RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql);
213
    void beforeQuery(Executor executor, MappedStatement ms, Object parameter, 
214
                    RowBounds rowBounds, ResultHandler resultHandler, BoundSql boundSql);
215
}
216
```
217

218
[Plugin System](./plugin-system.md)
219

220
### Pagination
221

222
Advanced pagination support with automatic total count queries and database-specific SQL dialect handling for optimal performance across different database systems.
223

224
```java { .api }
225
public class Page<T> implements IPage<T> {
226
    // Constructors
227
    public Page();
228
    public Page(long current, long size);
229
    public Page(long current, long size, long total);
230
    public Page(long current, long size, boolean searchCount);
231
    public Page(long current, long size, long total, boolean searchCount);
232
    
233
    // Core getters
234
    public List<T> getRecords();
235
    public long getTotal();
236
    public long getSize();
237
    public long getCurrent();
238
    public long getPages();
239
    public List<OrderItem> orders();
240
    
241
    // Fluent setters
242
    public Page<T> setRecords(List<T> records);
243
    public Page<T> setTotal(long total);
244
    public Page<T> setSize(long size);
245
    public Page<T> setCurrent(long current);
246
    public Page<T> addOrder(OrderItem... items);
247
    public Page<T> addOrder(List<OrderItem> items);
248
    
249
    // Pagination utilities
250
    public boolean hasPrevious();
251
    public boolean hasNext();
252
    public boolean searchCount();
253
    public boolean optimizeCountSql();
254
    public Page<T> setSearchCount(boolean searchCount);
255
    public Page<T> setOptimizeCountSql(boolean optimizeCountSql);
256
    
257
    // Static factory methods
258
    public static <T> Page<T> of(long current, long size);
259
    public static <T> Page<T> of(long current, long size, long total);
260
    public static <T> Page<T> of(long current, long size, boolean searchCount);
261
    public static <T> Page<T> of(long current, long size, long total, boolean searchCount);
262
}
263
```
264

265
[Pagination](./pagination.md)
266

267
### Active Record Pattern
268

269
Base `Model` class enabling entity objects to perform their own database operations, following the Active Record pattern for simplified data access.
270

271
```java { .api }
272
public abstract class Model<T extends Model<?>> implements Serializable {
273
    public boolean insert();
274
    public boolean deleteById();
275
    public boolean updateById();
276
    public T selectById();
277
    public List<T> selectAll();
278
    public Page<T> selectPage(IPage<T> page, Wrapper<T> queryWrapper);
279
}
280
```
281

282
[Active Record](./active-record.md)
283

284
### Static Database Utilities
285

286
`Db` utility class providing static methods for direct database operations without requiring service layer dependency injection, ideal for utility classes and static contexts.
287

288
```java { .api }
289
public class Db {
290
    // Save operations
291
    public static <T> boolean save(T entity);
292
    public static <T> boolean saveBatch(Collection<T> entityList);
293
    public static <T> boolean saveBatch(Collection<T> entityList, int batchSize);
294
    public static <T> boolean saveOrUpdate(T entity);
295
    public static <T> boolean saveOrUpdateBatch(Collection<T> entityList);
296
    public static <T> boolean saveOrUpdateBatch(Collection<T> entityList, int batchSize);
297
    
298
    // Query operations
299
    public static <T> T getById(Serializable id, Class<T> entityClass);
300
    public static <T> List<T> list(Class<T> entityClass);
301
    public static <T> List<T> list(Class<T> entityClass, Wrapper<T> queryWrapper);
302
    public static <T> List<T> listByIds(Collection<? extends Serializable> idList, Class<T> entityClass);
303
    public static <T> List<T> listByMap(Map<String, Object> columnMap, Class<T> entityClass);
304
    public static <T> T getOne(Class<T> entityClass, Wrapper<T> queryWrapper);
305
    public static <T> Map<String, Object> getMap(Class<T> entityClass, Wrapper<T> queryWrapper);
306
    public static <T> <V> V getObj(Class<T> entityClass, Wrapper<T> queryWrapper, Function<? super Object, V> mapper);
307
    public static <T> long count(Class<T> entityClass);
308
    public static <T> long count(Class<T> entityClass, Wrapper<T> queryWrapper);
309
    public static <T> boolean exists(Class<T> entityClass, Wrapper<T> queryWrapper);
310
    
311
    // Update operations
312
    public static <T> boolean updateById(T entity);
313
    public static <T> boolean update(T entity, Wrapper<T> updateWrapper);
314
    public static <T> boolean update(Class<T> entityClass, Wrapper<T> updateWrapper);
315
    public static <T> boolean updateBatchById(Collection<T> entityList);
316
    public static <T> boolean updateBatchById(Collection<T> entityList, int batchSize);
317
    
318
    // Remove operations
319
    public static <T> boolean removeById(Serializable id, Class<T> entityClass);
320
    public static <T> boolean removeByIds(Collection<? extends Serializable> idList, Class<T> entityClass);
321
    public static <T> boolean removeByMap(Map<String, Object> columnMap, Class<T> entityClass);
322
    public static <T> boolean remove(Class<T> entityClass, Wrapper<T> queryWrapper);
323
    
324
    // Pagination operations
325
    public static <T, E extends IPage<T>> E page(E page, Class<T> entityClass);
326
    public static <T, E extends IPage<T>> E page(E page, Class<T> entityClass, Wrapper<T> queryWrapper);
327
    public static <E extends IPage<Map<String, Object>>> E pageMaps(E page, Class<?> entityClass, Wrapper<?> queryWrapper);
328
    
329
    // Chain operations
330
    public static <T> QueryChainWrapper<T> query(Class<T> entityClass);
331
    public static <T> LambdaQueryChainWrapper<T> lambdaQuery(Class<T> entityClass);
332
    public static <T> KtQueryChainWrapper<T> ktQuery(Class<T> entityClass);
333
    public static <T> UpdateChainWrapper<T> update(Class<T> entityClass);
334
    public static <T> LambdaUpdateChainWrapper<T> lambdaUpdate(Class<T> entityClass);
335
    public static <T> KtUpdateChainWrapper<T> ktUpdate(Class<T> entityClass);
336
}
337
```
338

339
[Static Database Utilities](./static-utilities.md)
340

341
### Kotlin Extensions
342

343
Type-safe Kotlin DSL providing enhanced developer experience with property-based query building and Kotlin-specific language features.
344

345
```kotlin { .api }
346
class KtQueryWrapper<T>(entity: T? = null) : AbstractKtWrapper<T, KtQueryWrapper<T>>() {
347
    fun select(vararg columns: KProperty<*>): KtQueryWrapper<T>
348
    fun getSqlSelect(): String
349
}
350

351
class KtUpdateWrapper<T>(entity: T? = null) : AbstractKtWrapper<T, KtUpdateWrapper<T>>()
352
```
353

354
[Kotlin Extensions](./kotlin-extensions.md)
355

356
## Core Types
357

358
```java { .api }
359
// Base service interface providing CRUD operations
360
public interface IService<T> {
361
    int DEFAULT_BATCH_SIZE = 1000;
362
}
363

364
// Base service implementation
365
public abstract class ServiceImpl<M extends BaseMapper<T>, T> implements IService<T> {
366
    @Autowired
367
    protected M baseMapper;
368
    protected final Log log;
369
    private Class<T> entityClass;
370
    private Class<M> mapperClass;
371
    private volatile SqlSessionFactory sqlSessionFactory;
372
}
373

374
// Pagination container
375
public class Page<T> implements IPage<T> {
376
    protected List<T> records;
377
    protected long total;
378
    protected long size;
379
    protected long current;
380
    protected List<OrderItem> orders;
381
    protected boolean optimizeCountSql = true;
382
    protected boolean searchCount = true;
383
    protected boolean optimizeJoinOfCountSql = true;
384
    protected Long maxLimit;
385
    protected String countId;
386
}
387

388
// Active Record base class
389
public abstract class Model<T extends Model<?>> implements Serializable {
390
    protected Serializable pkVal();
391
}
392

393
// Main interceptor coordinator
394
public class MybatisPlusInterceptor implements Interceptor {
395
    private List<InnerInterceptor> interceptors;
396
}
397
```