# pjd-cascade

**Repository Path**: pjd-panda/pjd-cascade

## Basic Information

- **Project Name**: pjd-cascade
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-19
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cascade Spring Boot Starter

[![Java 17](https://img.shields.io/badge/Java-17-blue)](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
[![Java 8](https://img.shields.io/badge/Java-8-blue)](https://www.oracle.com/java/technologies/javase/jdk8u211-bundle.html)
[![Spring Boot 2.7](https://img.shields.io/badge/Spring%20Boot-2.7-brightgreen)](https://spring.io/projects/spring-boot#support)
[![MyBatis Plus 3.5](https://img.shields.io/badge/MyBatis%20Plus-3.5-orange)](https://baomidou.com/)

JPA 风格的 MyBatis Plus 级联操作 Starter。自动为实体关联提供级联保存、更新和删除功能。

## 功能特性

- **JPA 风格注解**: 提供类似 JPA 的 `@OneToMany`、`@ManyToOne`、`@OneToOne` 注解
- **级联操作**: 自动执行级联保存、合并、删除操作
- **孤儿节点清理**: 支持孤儿节点清理（从集合中移除的子实体自动删除）
- **多版本支持**: 同时支持 Java 8 和 Java 17
- **自动配置**: Spring Boot 自动配置支持

## 项目结构

```
cascade-spring-boot-starter/
├── pom.xml (父模块)
├── cascade-core-java17/          # 核心模块 (Java 17)
├── cascade-spring-boot-starter-java17/  # Spring Boot Starter (Java 17)
├── cascade-core-java8/           # 核心模块 (Java 8)
├── cascade-spring-boot-starter-java8/   # Spring Boot Starter (Java 8)
├── cascade-example-java17/       # 示例项目 (Java 17)
└── cascade-example-java8/        # 示例项目 (Java 8)
```

## Maven 依赖

### Java 17

```xml
<dependency>
    <groupId>com.panda</groupId>
    <artifactId>cascade-spring-boot-starter-java17</artifactId>
    <version>3.0.0</version>
</dependency>
```

### Java 8

```xml
<dependency>
    <groupId>com.panda</groupId>
    <artifactId>cascade-spring-boot-starter-java8</artifactId>
    <version>3.0.0</version>
</dependency>
```

## 快速开始

### 1. 定义实体关联

```java
@Data
@TableName("project")
public class Project {

    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    private String projectName;

    @ToString.Exclude
    @EqualsAndHashCode.Exclude
    @TableField(exist = false)
    @OneToMany(
            targetEntity = Bridge.class,
            foreignKey = "projectId",
            cascadePersist = true,
            cascadeMerge = true,
            cascadeRemove = true,
            orphanRemoval = true
    )
    private List<Bridge> bridges = new ArrayList<>();

    // 添加桥梁
    public Project addBridge(Bridge bridge) {
        bridges.add(bridge);
        bridge.setProject(this);
        return this;
    }

    // 移除桥梁
    public Project removeBridge(Bridge bridge) {
        bridges.remove(bridge);
        bridge.setProject(null);
        return this;
    }
}
```

```java
@Data
@TableName("bridge")
public class Bridge {

    @TableId(value = "id", type = IdType.AUTO)
    private Long id;

    private String bridgeName;

    private Long projectId;

    @ToString.Exclude
    @EqualsAndHashCode.Exclude
    @TableField(exist = false)
    @ManyToOne(
            targetEntity = Project.class,
            foreignKey = "projectId",
            cascadePersist = false,
            cascadeMerge = false,
            cascadeRemove = false
    )
    private Project project;

    @ToString.Exclude
    @EqualsAndHashCode.Exclude
    @TableField(exist = false)
    @OneToOne(
            targetEntity = BridgeDetail.class,
            foreignKey = "bridgeId",
            cascadePersist = true,
            cascadeMerge = true,
            cascadeRemove = true
    )
    private BridgeDetail bridgeDetail;
}
```

### 2. 注入并使用级联服务

```java
@Service
public class ProjectService {

    @Autowired
    private CascadeOperationService cascadeOperationService;

    /**
     * 级联保存项目及其关联的桥梁、桥梁详情
     */
    public void saveProject(Project project) {
        cascadeOperationService.cascadePersist(project);
    }

    /**
     * 级联更新项目及其关联
     */
    public void updateProject(Project project) {
        cascadeOperationService.cascadeMerge(project);
    }

    /**
     * 根据ID级联删除项目及其关联
     */
    public void deleteProject(Long id) {
        cascadeOperationService.cascadeRemoveById(Project.class, id);
    }

    /**
     * 孤儿节点清理 - 从项目中移除桥梁时自动删除该桥梁
     */
    public void removeBridgeFromProject(Project project, Bridge bridge) {
        project.removeBridge(bridge);
        cascadeOperationService.orphanRemoval(project);
    }
}
```

## 注解说明

### @OneToMany

用于一对多关系的"一"方。

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `targetEntity` | `Class<?>` | - | 目标实体类 |
| `foreignKey` | `String` | `""` | 子实体的外键字段名 |
| `cascadePersist` | `boolean` | `true` | 是否级联保存 |
| `cascadeMerge` | `boolean` | `true` | 是否级联更新 |
| `cascadeRemove` | `boolean` | `false` | 是否级联删除 |
| `orphanRemoval` | `boolean` | `false` | 是否启用孤儿节点清理 |

### @ManyToOne

用于一对多关系的"多"方。

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `targetEntity` | `Class<?>` | - | 目标实体类 |
| `foreignKey` | `String` | `""` | 外键字段名 |
| `cascadePersist` | `boolean` | `false` | 是否级联保存 |
| `cascadeMerge` | `boolean` | `false` | 是否级联更新 |
| `cascadeRemove` | `boolean` | `false` | 是否级联删除 |
| `autoFillForeignKey` | `boolean` | `true` | 是否自动填充外键 |

### @OneToOne

用于一对一关系。

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `targetEntity` | `Class<?>` | - | 目标实体类 |
| `foreignKey` | `String` | `""` | 外键字段名 |
| `cascadePersist` | `boolean` | `true` | 是否级联保存 |
| `cascadeMerge` | `boolean` | `true` | 是否级联更新 |
| `cascadeRemove` | `boolean` | `false` | 是否级联删除 |
| `autoFillForeignKey` | `boolean` | `true` | 是否自动填充外键 |

## API 接口

### CascadeOperationService

| 方法 | 说明 |
|------|------|
| `cascadePersist(T entity)` | 保存实体（包含级联） |
| `cascadePersist(Collection<T> entities)` | 保存多个实体（包含级联） |
| `cascadeMerge(T entity)` | 更新实体（包含级联） |
| `cascadeMerge(Collection<T> entities)` | 更新多个实体（包含级联） |
| `cascadeRemove(T entity)` | 删除实体（包含级联） |
| `cascadeRemoveById(Class<T>, ID id)` | 根据ID删除实体（包含级联） |
| `cascadeRemoveByIds(Class<T>, Collection<ID> ids)` | 根据ID列表删除多个实体（包含级联） |
| `orphanRemoval(T entity)` | 清理孤儿节点 |

## 示例项目

查看 `cascade-example-java17` 和 `cascade-example-java8` 模块获取完整示例。

### 启动示例

```bash
# Java 17
cd cascade-example-java17
mvn spring-boot:run

# Java 8
cd cascade-example-java8
mvn spring-boot:run
```

启动后访问: http://localhost:8080

## 构建项目

```bash
mvn clean install
```

## 依赖要求

- Java 8 或 Java 17
- Spring Boot 2.7.x
- MyBatis Plus 3.5.x
- Lombok

## 开源协议

MIT License