# lucy-jpa

**Repository Path**: lboot/lucy-jpa

## Basic Information

- **Project Name**: lucy-jpa
- **Description**: lucy JPA核心依赖，自定义审计，快速构建查询
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-03-24
- **Last Updated**: 2024-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java, ORM

## README

<p align="center">
	<a href="https://lucy.apisev.cn/"><img src="https://s1.ax1x.com/2023/04/10/ppqZQjf.png" width="15%"></a>
</p>
<p align="center">
	<strong>Lucy</strong>
</p>
<p align="center">
	<strong>不断迭代的技术解决方案</strong>
</p>

---

<p align="center">
	<strong>lucy-jpa</strong>
</p>




![](https://img.shields.io/badge/build-passing-green)	![](https://img.shields.io/badge/license-MIT-blue)

## 简介

`lucy-jpa`是基于`lucy-spring-boot-starter`的`ORM`核心包，自定义构建数据库查询方式。

最小版本依赖关系:

| lucy-jpa | lucy-spring-boot-starter |
| -------- | ------------------------ |
| 1.0.8    | 1.1.2                    |

## 准备

在引入任何 `Lucy`系列依赖之前，需要完成`jitpack`镜像仓库的配置。

```xml
<repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://www.jitpack.io</url>
        </repository>
</repositories>
```

## 集成

### 引入

在`pom`中引入，版本号与发行版一致。

```xml
<dependency>
        <groupId>com.gitee.lboot</groupId>
        <artifactId>lucy-jpa</artifactId>
        <version>1.0.8</version>
</dependency>
```

### 配置

- 配置`JPA`审计

  1. 在启动类上配置开启审计功能

  ```java
  @EnableJpaAuditing
  @SpringBootApplication
  public class DemoApplication {
  }
  ```

  2. 拓展实现`JPA`审计接口

  ```java
  @Configuration
  public class AuditorConfig implements AuditorAware<String> {
      /**
       * 返回操作人员ID
       */
      @Override
      public Optional<String> getCurrentAuditor() {
          // 根据自己使用的鉴权方案，实现代码不同
          // SaToken 鉴权方案例
          return Optional.of(StpUtil.getLoginIdAsString());
      }
  }
  
  ```

## 使用

通过完整流程介绍本`ORM `库的功能特性

### 1. 定义实体类

```java
@EqualsAndHashCode(callSuper = true)
@Data
@Entity
@Table(name = "sys_user")
@ApiModel(value = "用户信息实体",description = "用户实体信息管理")
public class SysUser extends LongBaseEntity implements Serializable {

}
```

通过继承不同的父类，实现对实体类的初始字段定义，可选父类列表如下:

| 父类                      | ID类型 | ID策略 | 自动审计操作人员 | 自动审计操作日期 | 备注                   |
| ------------------------- | ------ | ------ | ---------------- | ---------------- | ---------------------- |
| BaseEntity                | String | 雪花ID | √                | √                |                        |
| LongBaseEntity            | Long   | 自增   | √                | √                |                        |
| DateAuditBaseEntity       | String | 雪花ID | ×                | √                | 无审计人字段           |
| DateAuditLongBaseEntity   | Long   | 自增   | ×                | √                | 无审计人字段           |
| CustomAuditBaseEntity     | String | 雪花ID | ×                | ×                | 审计信息手动赋值       |
| CustomAuditLongBaseEntity | Long   | 自增   | ×                | ×                | 审计信息手动赋值       |
| NoAuditBaseEntity         | String | 雪花ID | ×                | ×                | 无审计人、审计日期字段 |
| NoAuditLongBaseEntity     | Long   | 自增   | ×                | ×                | 无审计人、审计日期字段 |

### 2. 定义映射字段

```java
public class SysUser extends LongBaseEntity implements Serializable {
    // ...
        
	@ApiModelProperty("证件号码")
    @Convert(converter = EncryptConverter.class)
    @Column(name = "card_id")
    private String cardId;
 
    @ApiModelProperty("角色权限")
    @Column(name = "permissions",length = 2048)
    @Convert(converter = JpaListStringConverter.class)
    List<String> permissions;
}
```

例如List不可以直接存入数据库，通过使用不同的转化器实现数据库存储数据与Java对象之间的转化。

可选 `Convert`列表：

| 转化器                 | 对象形式       | 存储形式     | 功能                 |
| ---------------------- | -------------- | ------------ | -------------------- |
| EncryptConverter       | `String`       | 加密后字符串 | 加密数据（==弃用==） |
| JpaListLongConverter   | `List<Long>`   | JSON字符串   |                      |
| JpaListObjectConverter | `List<Object>` | JSON字符串   | 泛用转化器           |
| JpaListStringConverter | `List<String>` | JSON字符串   |                      |

> 参考源码写法，实现自定义`Converter`
>
> 使用默认 `EncryptConverter`容易被根据引用库破译，建议根据业务需要，自定义密文加密解密策略

### 3. 定义数据访问类

[Spring Data JPA](https://springdoc.cn/spring-data-jpa/)

```java
public interface SysUserDAO extends JpaRepositoryImplementation<SysUser,Long> {
    // 这个为自定义查询，为JPA基础使用方式 
    List<SysUser> findByMobile(String mobile);

}
```

通过引入`JpaRepositoryImplementation` 或 `JpaRepository` 实现对数据库访问通用方法的支持，支持的方法列表具体可查看源码。前者相比较于后者，实现了对谓词查询的支持，是后者的进一步拓展。

```java
@NoRepositoryBean
public interface JpaRepositoryImplementation<T, ID> extends JpaRepository<T, ID>, JpaSpecificationExecutor<T> {
    void setRepositoryMethodMetadata(CrudMethodMetadata crudMethodMetadata);

    default void setEscapeCharacter(EscapeCharacter escapeCharacter) {
    }
}
```

### 4. 定义服务接口

根据需要使用的功能，继承`extends`不同的接口（支持多个）。

不同接口支持方法列表请参阅源码，可选列表如下:

- BaseService 基础服务
- UnWrapService 查询解包
- BatchService 批量处理
- SpecService 谓词查询
- UniService 所有方法的集合

**推荐使用`UniService`**

```java
public interface SysUserService extends UniService<SysUser,Long> {
    List<SysUser> getByMobile(String mobile);
}
```

### 5. 定义服务实现类

通过对抽象类`AbstractJpaCurd` 和 `AbstractJpaCurdExt`的继承，直接实现了对 `UniService`等中定义的接口的默认实现，不需要额外的代码。

`AbstractJpaCurdExt`相比较于`AbstractJpaCurd`多了对谓词查询的支持。

**推荐使用`AbstractJpaCurdExt`**

```java
@Slf4j
@Service
@AllArgsConstructor
public class SysUserServiceImpl extends AbstractJpaCurdExt<Long, SysUser, SysUserDAO> implements SysUserService {
    @Override
    public List<SysUser> getByMobile(String mobile) {
        List<SysUser> users =  dao.findByMobile(mobile);
        if (users.size() > 1){
            log.warn("存在多条重复手机号:{}",mobile);
        }
        return users;
    }
}
```



具体使用方式查看源码

[lucy-rbac: 基于SaToken的RBAC鉴权方案实现，支持细粒度权限管理](https://gitee.com/lboot/lucy-rbac)



## 更新日志

**1.0.8**

- [特性] 更新了`lucy-spring-boot-starter` 版本依赖 

- [特性] 默认引入`MySQL`依赖，需要切换别的数据库，需要排除 `MySQL`

  ```xml
   <dependency>
          <groupId>mysql</groupId>
          <artifactId>mysql-connector-java</artifactId>
  </dependency>
  ```

[更多...](https://gitee.com/lboot/lucy-jpa/releases)

## 技术支持

<kindear@foxmail.com>