Spring Data JPA父子实体保存更新及detached异常解决方案

问题表现 #

使用Spring Data JPA实现Document（父）和Template（子）的一对多关联时，按以下流程操作出现非预期行为：

1. 先单独调用接口创建Template表记录
2. 新建Document实体，关联已存在的Template记录后调用save保存
   先后出现三类不符合预期的现象：

• 父实体@OneToMany配置cascade = ALL时，保存抛出detached entity passed to persist异常
• 将级联改为cascade = MERGE后，Document可正常插入数据库，但关联的Template记录未绑定新生成的Document主键，控制台仅输出Document的insert语句，无Template对应的update SQL
• 若显式调用merge方法保存，执行前会对所有子实体发起select查询，产生额外性能开销

关联代码 #

Document实体 #

@Getter
@Setter
@ToString
@Entity
@Table(name = "document")
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class Document{

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String title;
    private String description;

    @OneToMany(cascade = CascadeType.ALL, fetch = FetchType.LAZY, mappedBy = "document")
    @ToString.Exclude
    private Set<Template> templates = new HashSet<>();

    public void addTemplates(Template template) {
        templates.add(template);
        template.setDocument(this);
    }
}

Template实体 #

@Getter
@Setter
@ToString
@Entity
@Table(name = "template")
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class Template{

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "document_id")
    private Document document;
    
}

原Service层逻辑 #

@RequiredArgsConstructor
@Service
@Transactional
@Slf4j
public class DocumentService {

  private final DocumentRepository documentRepository;
  private final TemplateRepository templateRepository;

  // 提前创建Template记录
  public void createTemplate() {
    Set<Template> template = new HashSet<>();
    template.add(Template.builder().name("template1").build());
    template.add(Template.builder().name("template2").build());
    templateRepository.saveAll(template);
  }

  // 新建Document关联Template
  public void createMovie(DocumentDTO documentRequest) {
    Set<Template> templates = toTemplate(documentRequest.getTemplates());
    Document document = Document.builder()
            .title(documentRequest.getTitle())
            .description(documentRequest.getDescription())
            .templates(new HashSet<>())
            .build();
    templates.forEach(document::addTemplates);
    documentRepository.save(document);
  }

  // 手动构建Template对象
  private Set<Template> toTemplate(Set<TemplateDTO> templatesDTO) {
    return templatesDTO.stream().map(templateDTO ->
            Template.builder()
                    .id(templateDTO.getId())
                    .name(templateDTO.getName())
                    .build()
    ).collect(Collectors.toSet());
  }
}

测试请求参数 #

{
    "title": "tre",
    "description": "opppp",
    "templates": [
        {
            "id": 1,
            "name": "template1"
        },
        {
            "id": 2,
            "name": "template2"
        }
    ]
}

根因分析 #

• JPA实体分为四种状态：瞬态（未持久化无id）、托管（当前持久化上下文管理）、脱管（已持久化有id但不在当前上下文）、删除。提前创建的Template记录在createMovie方法执行时，属于脱管状态——原逻辑手动new Template对象并set已有id，该对象未和当前事务的EntityManager绑定，不是托管实体。
• 新建的Document属于瞬态对象，Spring Data JPA的save()方法对瞬态对象默认执行persist()逻辑。cascade = ALL包含PERSIST级联，persist操作要求级联目标必须是瞬态新实体，遇到带id的脱管子实体就会抛出detached entity passed to persist异常。
• 级联改为MERGE后，persist()操作不会触发MERGE级联规则，脱管状态的子实体完全不被持久化上下文处理，自然不会执行Template表的update语句绑定外键。
• 直接调用merge()方法时，JPA会遍历所有关联实体逐个执行存在性检查（即大量select查询），判断实体是脱管还是瞬态后再做合并，确实会产生不必要的性能开销。

最优解决方案（无多余merge开销、无异常） #

核心思路是避免手动构造脱管状态的子实体，直接获取当前持久化上下文管理的托管子实体做关联，从根源规避脱管实体级联问题。

具体实现步骤 #

1. 修正代码笔误：统一关联字段名（不要混用template/templates）、修正字段映射错误（Template实体只有name字段，不要映射不存在的firstName/lastName）、修正外键字段名（避免用和表名同名的document作为外键列，建议用document_id）。
2. 调整级联配置：根据业务选择级联规则，不需要配置全量ALL：
   • 若新建Document时允许同时创建全新Template，配置cascade = {CascadeType.PERSIST, CascadeType.MERGE}即可
   • 若Template必须提前创建、不能随Document新增，仅保留MERGE即可
3. 改造关联逻辑：拿到前端传的Template id后，直接从Repository查询出托管状态的Template实体，再和新建的Document做关联，不要手动new带id的脱管Template对象。如果仅做关联不需要查询Template完整字段，可直接用getReferenceById()获取JPA代理对象，完全不发起select查询，性能最优。

改造后Service代码 #

@RequiredArgsConstructor
@Service
@Transactional
@Slf4j
public class DocumentService {

  private final DocumentRepository documentRepository;
  private final TemplateRepository templateRepository;

  public void createTemplate() {
    Set<Template> templates = new HashSet<>();
    templates.add(Template.builder().name("template1").build());
    templates.add(Template.builder().name("template2").build());
    templateRepository.saveAll(templates);
  }

  public void createDocument(DocumentDTO documentRequest) {
    // 提取所有已存在的Template id
    Set<Long> templateIds = documentRequest.getTemplates().stream()
            .map(TemplateDTO::getId)
            .filter(Objects::nonNull) // 过滤掉前端传的全新Template（无id）
            .collect(Collectors.toSet());
    // 查询已存在的托管状态Template，仅做关联可替换为getReferenceById减少查询
    Set<Template> managedTemplates = new HashSet<>(templateRepository.findAllById(templateIds));
    // 筛选前端传的无id新Template，直接new为瞬态对象
    Set<Template> newTemplates = documentRequest.getTemplates().stream()
            .filter(dto -> dto.getId() == null)
            .map(dto -> Template.builder().name(dto.getName()).build())
            .collect(Collectors.toSet());
    // 合并所有子实体
    managedTemplates.addAll(newTemplates);

    // 构建新Document
    Document document = Document.builder()
            .title(documentRequest.getTitle())
            .description(documentRequest.getDescription())
            .templates(new HashSet<>())
            .build();
    // 关联所有子实体
    managedTemplates.forEach(document::addTemplates);
    // 直接保存即可，无脱管异常、无多余merge查询
    documentRepository.save(document);
  }
}

方案优势 #

• 无异常：托管状态的子实体在persist时不会触发脱管错误，关联关系会被JPA自动识别，事务提交前自动执行Template的update语句绑定外键
• 性能最优：无merge带来的全量子实体检查查询，使用getReferenceById时甚至不需要查询Template表数据即可完成关联
• 兼容性强：同时支持关联已存在Template、随Document新建Template两类场景，级联规则安全，不会触发REMOVE等高危级联的误操作风险。

内容的提问来源于stack exchange，提问作者Waley