
<p align="center" >
    <img src="https://developer.qcloudimg.com/http-save/yehe-10363848/adcb27f1c9933702b93331d6df340132.png"  width="200px"   alt=""/>
</p>

<p align="center">
  <strong>标准CRUD + 高效SELECT查询</strong>
</p>  

<p align="center">
    <img src="https://developer.qcloudimg.com/http-save/yehe-10363848/5b577536f7d6384a1f9d3557e6386ffa.svg" />
    <img src="https://developer.qcloudimg.com/http-save/yehe-10363848/ac8a9f76adbcfcbd44f72a24e0419b03.svg" />
    <img src="https://developer.qcloudimg.com/http-save/yehe-10363848/448391e411293a0489ef36d52731dbbf.svg" />
    <img src="https://developer.qcloudimg.com/http-save/yehe-10363848/3f0070c8bf2eab0a1779b26226f2eb12.svg" />
</p>

# MyBatis JPA Extra

**MyBatis JPA Extra**对MyBatis扩展JPA功能，融合JPA的标准化和MyBatis灵活性

1.JPA 注解支持：支持 `@Entity`、`@Table`、`@Column` 等注解，简化实体类的定义；  

2.**标准化CRUD操作**，通过JPA 注释和接口，减少传统MyBatis中大量的XML配置和SQL编写工作;
    
3.高效**SELECT分页**查询，优化了分页查询的实现方式，提供更高效、更灵活的分页功能;
    
4.**链式**Query查询条件构造器；支持Lambda 形式调用，方便编写各类查询条件；

5.**findByXxx**解析方法名自动生成查询；

6.@Encrypted注解轻松实现字段数据加密和解密;

7.字段数据自动填充功能;

8.数据库支持

|  数据库        |  支持 |
| ---           | ---   |
|  MySQL        | ✅    |
|  PostgreSQL   | ✅    |
|  Oracle       | ✅    |
|  SqlServer    | ✅    |
|  DB2          | ✅    |
|  Mariadb      | ✅    |

代码托管  

|  <a href="https://gitcode.com/dromara/mybatis-jpa-extra/overview" target="_blank"><b>GitCode</b></a>        |  <a href="https://gitee.com/dromara/mybatis-jpa-extra" target="_blank"><b>Gitee</b></a>  |<a href="https://github.com/dromara/mybatis-jpa-extra" target="_blank"><b>GitHub</b></a>  |

## 1、JPA 注释

## 1.1、注释

| 注释      | 作用    |功能描述 |
| :-----        | :----   | :----   |
| @Entity          | class  |  标识一个类为JPA实体  | 
| @Table           | class  |  指定实体类对应的数据库表名  | 
| @Column          | field  |  定义字段与数据库列的映射关系，支持自定义列名、是否可为空等属性  | 
| @Id              | field  |  标识主键字段  | 
| @GeneratedValue  | field  |  定义主键生成策略，支持AUTO、SEQUENCE和IDENTITY  | 
| @Encrypted       | field  |  标记加密的字段，支持加密算法(如SM4、AES、DES、DESede)  | 
| @PartitionKey    | field  |  分库分表，多租户区分  | 
| @SoftDelete      | field  |  标记逻辑删除字段。当执行删除操作时，该字段会被更新为标记值（如 y/1） | 
| @ColumnDefault   | field  |  字段设置默认值，避免手动初始化  | 
| @Transient       | field  |  标识字段不映射到数据库列  |


## 1.2、主键策略

支持3种主键Id策略

| 策略      |   支持  |
| :-----        | :----   |
| AUTO          | 主键自动填充策略<br>snowflakeid(雪花ID-默认)<br>ulid<br>uuid(UUID) | 
| SEQUENCE      | 数据库序列生成，generator值为数据库序列名 | 
| IDENTITY      | 数据库表自增主键  |


## 2、基本操作

## 2.1、CURD

```java
    //新增数据
    @Test
    void insert() throws Exception{
        Students student = new Students();
        student.setStdNo("10024");
        student.setStdGender("M");
        student.setStdName("司马昭");
        student.setStdAge(20);
        student.setStdMajor("政治");
        student.setStdClass("4");
        service.insert(student);
    }
    //查询数据实体并更新
    @Test
    void update() throws Exception{
        Students student = service.get("1");
        student.setStdMajor("政治");
        service.update(student);
        //service.merge(student);
    }
    //根据ID查询
    @Test
    void get() throws Exception{
        Students student = service.get("2");
    }
    //根据实体查询
    @Test
    void query() throws Exception{
        Students student = new Students();
        student.setStdGender("M");
        List<Students> listStudents = service.query(student);
    }
    //查询所有记录
    @Test
    void findAll() throws Exception{
        List<Students> listStudents = service.findAll();
    }
    //根据ID删除
    @Test
    void delete() throws Exception{
        service.delete("3");
    }
    //根据ID集合批量删除
    @Test
    void batchDelete() throws Exception{
        List<String> idList = new ArrayList<String>();
        idList.add("4");
        //...
        service.deleteBatch(idList);
    }
```
## 2.2、逻辑删除
```java    
    //根据IDS批量逻辑删除
    @Test
    void softDelete() throws Exception{
        //逻辑删除
        service.softDelete("5");

        //批量逻辑删除    
        List<String> idList=new ArrayList<String>();
        idList.add("6");
        idList.add("7");
        //...
        service.softDelete(idList);
    }
```

## 2.3、Find查询和Qruey构造器

```java
    //SpringJDBC的查询方式 where StdNo = '10024' or StdNo = '10004'
    @Test
    void find() throws Exception{
        List<Students> listStudents = service.find(" StdNo = ? or StdNo = ?  ",
                            new Object[]{"10024","10004"},
                            new int[]{Types.VARCHAR,Types.INTEGER}
                        );
    }
    //根据链式条件构造器查询
    //WHERE (stdMajor = '政治' and STDAGE > 30 and stdMajor in ( '政治' , '化学' )  or  ( stdname = '周瑜' or stdname = '吕蒙' ) )
    @Test
    void queryByCondition() throws Exception{
        List<Students> listStudents = service.query(
                new Query().eq("stdMajor", "政治")
                .and().gt("STDAGE", 30)
                .and().in("stdMajor", new Object[]{"政治","化学"})
                .or(new Query().eq("stdname", "周瑜").or().eq("stdname", "吕蒙")));
    }
```

## 2.4、单表分页查询

```java
    //根据实体分页查询
    @Test
    void fetch() throws Exception{
         JpaPage page = new JpaPage(1);
         Students student = new Students();
         student.setStdGender("M");
         JpaPageResults<Students>  results = service.fetch(page,student);
    }
    //根据Query条件分页查询 where stdMajor = '政治' and STDAGE > 30
    @Test
    void fetchByCondition() throws Exception{
         JpaPage page = new JpaPage(1,20);
         Query condition = new Query().eq("stdMajor", "政治").and().gt("STDAGE", 30);
         JpaPageResults<Students>  results = service.fetch(page,condition);
    }
```

## 2.5、多表关联分页查询，根据mapper的xml分页查询

```java
    //根据Mapper xml配置fetchPageResults分页查询
    @Test
    void fetchPageResults() throws Exception{
         Students student = new Students();
         student.setStdGender("M");
         student.setPageNumber(1);
         JpaPageResults<Students>  results = service.fetchPageResults(student);
    }
    //根据Mapper xml id分页查询,fetchPageResults1在mapper的xml中配置
    @Test
    void fetchPageResultsByMapperId() throws Exception{
         Students student = new Students();
         student.setStdGender("M");
         student.setPageNumber(1);
         JpaPageResults<Students> results = service.fetchPageResults("fetchPageResults1",student);
    }
```


## 2.6、 Lambda查询
```java

    //根据Lambda链式条件构造器查询
    //WHERE (stdMajor = '政治' and STDAGE > 30 and stdMajor in ( '政治' , '化学' )  or  ( stdname = '周瑜' or stdname = '吕蒙' ) )
    service.query(new LambdaQuery<Students>()
                    .eq(Students::getStdMajor, "政治")
                    .and().gt(Students::getStdAge, Integer.valueOf(30))
                    .and().in(Students::getStdMajor, new Object[]{"政治","化学"})
                    .or( new LambdaQuery<Students>()
                            .eq(Students::getStdName, "周瑜")
                            .or().eq(Students::getStdName, "吕蒙"))
                );

    //根据Lambda链式条件构造器分页查询
    //where stdMajor = '政治' and stdAge > 30
    JpaPage page = new JpaPage(1,20);
    LambdaQuery<Students> lambdaQuery =new LambdaQuery<>();
    lambdaQuery.eq(Students::getStdMajor, "政治").and().gt(Students::getStdAge, Integer.valueOf(30));
    JpaPageResults<Students>  results = service.fetch(page,lambdaQuery);

    ...

```

## 2.6、 UpdateWrapper更新
```java
    //根据UpdateWrapper更新数据
    UpdateWrapper updateWrapper = new UpdateWrapper();
    updateWrapper.set("StdMajor", "历史").eq("StdName", "周瑜").or().eq("StdName", "吕蒙");   
    service.update(updateWrapper);

    //更新LambdaUpdateWrapper更新数据，带多重LambdaUpdateWrapper
    List<String> majorList = new ArrayList<>(Arrays.asList("政治","化学"));
    LambdaUpdateWrapper<Students> updateWrapper = new LambdaUpdateWrapper<>();
    updateWrapper.set(Students::getStdMajor, "历史")
                 .eq(Students::getStdMajor, "政治")
                 .and().gt(Students::getStdAge, Integer.valueOf(30))
                 .and().in(Students::getStdMajor, majorList)
                 .or(new LambdaUpdateWrapper<Students>()
                        .eq(Students::getStdName, "周瑜")
                        .or()
                        .eq(Students::getStdName, "吕蒙"));
        
    service.update(updateWrapper);

```

## 2.8、FindBy查询

`@Select({})` 标识findBy，实现spring data jpa的findBy功能

```java
    //Mapper接口定义
    //where x.stdNo = ?1
    @Select({})
    public List<Students> findByStdNo(String stdNo);
    //where x.stdNo = ?1
    @Select({})
    public List<Students> findByStdNoIs(String stdNo);
    //where x.stdNo = ?1
    @Select({})
    public List<Students> findByStdNoEquals(String stdNo);
    //where x.stdAge between ?1 and ?2
    @Select({})
    public List<Students> findByStdAgeBetween(int ageStart,int ageEnd);
    //where x.stdAge < ?1
    @Select({})
    public List<Students> findByStdAgeLessThan(int ageLessThan);
    //where x.stdAge <= ?1
    @Select({})
    public List<Students> findByStdAgeLessThanEqual(int ageLessThanEqual);
    //where x.stdAge > ?1
    @Select({})
    public List<Students> findByStdAgeAfter(int ageAfter);
    //where x.stdAge < ?1
    @Select({})
    public List<Students> findByStdAgeBefore(int ageBefore);
    //where x.images is null
    @Select({})
    public List<Students> findByImagesNull();
    //where x.images is null
    @Select({})
    public List<Students> findByImagesIsNull();
    //where x.images is not null
    @Select({})
    public List<Students> findByImagesIsNotNull();
    //where x.images is not null
    @Select({})
    public List<Students> findByImagesNotNull();
    //where x.stdName like ?1
    @Select({})
    public List<Students> findByStdNameLike(String stdName);
    //where x.stdName not like ?1
    @Select({})
    public List<Students> findByStdNameNotLike(String stdName);
    //where x.stdName like ?1 (parameter bound with appended %)
    @Select({})
    public List<Students> findByStdNameStartingWith(String stdName);
    //where x.stdName like ?1 (parameter bound with prepended %)
    @Select({})
    public List<Students> findByStdNameEndingWith(String stdName);
    //where x.stdName like ?1 (parameter bound wrapped in %)
    @Select({})
    public List<Students> findByStdNameContaining(String stdName);
    //where x.stdGender = ?1 order by x.stdAge desc
    @Select({})
    public List<Students> findByStdGenderOrderByStdAge(String stdGender);
    //where x.stdGender = ?1 order by x.stdAge desc
    @Select({})
    public List<Students> findByStdGenderIsOrderByStdAge(String stdGender);
    //where x.stdMajors in ?1
    @Select({})
    public List<Students> findByStdMajorIn(String... stdMajors) ;
    //where x.stdMajors not in ?1
    @Select({})
    public List<Students> findByStdMajorNotIn(List<String> stdMajors);
    //where x.deleted = true
    @Select({})
    public List<Students> findByDeletedTrue();
    //where x.deleted = false
    @Select({})
    public List<Students> findByDeletedFalse();
    //where UPPER(x.stdGender) = UPPER(?1)
    @Select({})
    public List<Students> findByStdGenderIgnoreCase(String stdGender);
    //where x.stdNo <> ?1
    @Select({})
    public List<Students> findByStdNoNot(String stdNo);
    //where x.lastname = ?1 and x.firstname = ?2
    @Select({})
    public List<Students> findByStdMajorAndStdClass(String stdMajor,String stdClass);
```

## 2.9、默认数据自动填充

继承FieldAutoFillHandler，实现insertFill和updateFill函数，可以完成租户字段，创建人、创建时间、修改人、修改时间等默认字段的填充

```java
public class MxkFieldAutoFillHandler  extends FieldAutoFillHandler{
    //插入
    @Override
    public void insertFill(MetaObject metaObject) {
        this.setFieldValue(metaObject , "stdNo", "AutoFill_Insert");
    }
    //更新
    @Override
    public void updateFill(MetaObject metaObject) {
        this.setFieldValue(metaObject , "stdNo", "AutoFill_Update");
    }
}
```

## 3、 使用方法

### 3.1、实体类定义

```java
@Entity
@Table(name = "STUDENTS")  
public class Students extends JpaEntity implements Serializable{
    @Id
    @Column
    @GeneratedValue
    private String id;
    @Column
    private String stdNo;
    @Column
    @Encrypted
    private String password;
    @Column
    private String stdName;
    @Column
    @ColumnDefault("'M'")
    private String stdGender;
    @Column(insertable = false)
    @GeneratedValue
    private LocalDateTime modifyDate;
    @SoftDelete
    @Column(name ="is_deleted")
    private String isDeleted;
    //...
    //getter setter
}
```

### 3.2、Mapper定义

```java
@Mapper
public interface StudentsMapper extends IJpaMapper<Students,String> {

    //根据mapper.xml的fetchPageResults语句分页查询
    public List<Students> fetchPageResults(Students entity);

    //根据mapper.xml的fetchPageResults1语句自定义分页查询
    public List<Students> fetchPageResults1(Students entity);

    //根据mapper.xml的fetchPageResultsVo语句自定返回类型分页查询，返回类型JpaPageResults<StudentVo>
    public List<StudentVo> fetchPageResultsVo(StudentQueryDto entity);

    //实现JPA findBy功能，无需写SQL
    @Select({})
    public List<Students> findByStdNo(String stdNo);

}
```

### 3.3、Service接口

```java
public interface StudentsService extends IJpaService<Students,String>{

    //fetchPageResults/fetchPageResults1无需定义接口

    public JpaPageResults<StudentVo> fetchPageResultsVo(StudentQueryDto entity) ;

    public List<Students> findByStdNo(String stdNo);
}
```

### 3.4、Service实现

```java
public class StudentsServiceImpl extends AbstractJpaRepository<StudentsMapper,Students,String> implements StudentsService{
    
    //fetchPageResults/fetchPageResults1无需定义实现

    //自定义返回类型JpaPageResults<StudentVo>
    @SuppressWarnings("unchecked")
    public JpaPageResults<StudentVo> fetchPageResultsVo(StudentQueryDto entity) {
        entity.build();
        return (JpaPageResults<StudentVo>) this.buildPageResults(entity, getMapper().fetchPageResultsVo(entity));
    }
    
    //mapper findBy调用
    public List<Students> findByStdNo(String stdNo) {
        return getMapper().findByStdNo(stdNo);
    }
}
```

### 3.5、mapper配置

```xml
<mapper namespace="org.apache.mybatis.jpa.test.dao.persistence.StudentsMapper" >
    <sql id="sql_condition">
        WHERE   1   =   1
        <if test="id != null">
            AND ID  =   '${id}'
        </if>
        <if test="stdName != null  and stdName != '' ">
            AND STDNAME like '%${stdName}%'
        </if>
        <if test="stdGender != null  and stdGender != '' ">
            AND STDGENDER   =   #{stdGender}
        </if>
        <if test="stdMajor != null">
            <![CDATA[AND    STDMAJOR    = #{stdMajor}]]>
        </if>
    </sql>
    
    <select id="fetchPageResults" parameterType="Students" resultType="Students">
        SELECT 
            id , stdno , stdname ,stdgender , stdage , stdmajor , stdclass 
        FROM STUDENTS 
        <include refid="sql_condition"/>
    </select>
 
     <select id="fetchPageResults1" parameterType="Students" resultType="Students">
        SELECT 
            id , stdno , stdname ,stdgender , stdage , stdmajor , stdclass 
        FROM STUDENTS 
        <include refid="sql_condition"/>
    </select>
       
     <select id="queryBy" parameterType="Students" resultType="Students">
        SELECT 
            id , stdno , stdname ,stdgender , stdage , stdmajor , stdclass 
        FROM ROLES 
        <include refid="sql_condition"/>
    </select>

```

###  3.6、SpringBoot配置

```properties
#
spring.datasource.type=com.alibaba.druid.pool.DruidDataSource
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.url=jdbc:mysql://localhost/test?autoReconnect=true&characterEncoding=UTF-8&serverTimezone=UTC
spring.datasource.username=root
spring.datasource.password=maxkey

mybatis.dialect=mysql
mybatis.type-aliases-package=org.apache.mybatis.jpa.test.entity
mybatis.mapper-locations=classpath*:/org/apache/mybatis/jpa/test/dao/persistence/xml/${mybatis.dialect}/*.xml
#定界符，默认 false
#mybatis.table-column-escape=false
#表、字段等定界符
#mybatis.table-column-escape-char=`
#驼峰与下划线转换配置，默认 false
#mybatis.configuration.map-underscore-to-camel-case=true
```

###  3.7、依赖引用
例如依赖版本`3.4.4`配置如下
### 3.7.1 Maven依赖
```xml
<dependency>
    <groupId>org.dromara.mybatis-jpa-extra</groupId>
    <artifactId>mybatis-jpa-extra</artifactId>
    <version>3.4.4</version>
</dependency>
<dependency>
    <groupId>org.dromara.mybatis-jpa-extra</groupId>
    <artifactId>mybatis-jpa-extra-spring</artifactId>
    <version>3.4.4</version>
</dependency>
<dependency>
    <groupId>org.dromara.mybatis-jpa-extra</groupId>
    <artifactId>mybatis-jpa-extra-spring-boot-starter</artifactId>
    <version>3.4.4</version>
</dependency>
```

### 3.7.2 Gradle依赖
```gradle
implementation group: 'org.dromara.mybatis-jpa-extra', name: 'mybatis-jpa-extra', version: '3.4.4'
implementation group: 'org.dromara.mybatis-jpa-extra', name: 'mybatis-jpa-extra-spring', version: '3.4.4'
implementation group: 'org.dromara.mybatis-jpa-extra', name: 'mybatis-jpa-extra-spring-boot-starter', version: '3.4.4'
```
> [提示]
> 当前版本支持springboot v4+， springboot v3 请参考`3.3`分支



MyBatis JPA Extra对MyBatis扩展JPA功能，融合JPA的标准化和MyBatis灵活性

MyBatis JPA Extra 3.4.x 全功能介绍，融合JPA，支持Springboot4+

架构师

数据库

后端

开发工具

MyBatisJPAExtra扩展MyBatis支持JPA注解，简化CRUD操作，提供高效分页查询和链式条件构造器。支持字段加密、逻辑删除、自动填充等功能，兼容MySQL/PostgreSQL/Oracle等主流数据库，提升开发效率。

数据加密

PostgreSQL

GitHub

MySQL

2026新春采购季

tencentdb-catalog

腾讯云数据库特惠，新用户首单0.5折起


postgres

coding

cloudhsm

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

MyBatis JPA Extra 3.4.x 全功能介绍，融合JPA，支持Springboot4+-腾讯云开发者社区-腾讯云

MyBatis JPA Extra 3.4.x 全功能介绍，融合JPA，支持Springboot4+

MyBatis JPA Extra 3.4.x 全功能介绍，融合JPA，支持Springboot4+

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐