Spring Boot JPA Category模型@Version乐观锁失效问题排查

问题背景 #

我正在开发一个Spring Boot应用，想用JPA/Hibernate的@Version注解实现模型的乐观锁版本控制。Employee实体的版本控制工作正常，但创建Category时出现版本相关错误，以下是具体实现及问题详情：

Employee实体代码 #

@Entity
@Table(name = "employee")
@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class Employee implements UserDetails {
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    @Column(columnDefinition = "UUID")
    private UUID id;

    @NaturalId
    private String staffId;

    @Version
    @Column(name = "version")
    private Instant version;
    
    private String firstName;
    private String lastName;
    
    @OneToMany(mappedBy = "createdByEmployee", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    private List<Category> createdCategoriesList;
}

Category实体代码 #

@Entity
@Table(name = "category")
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class Category {
    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    @Column(nullable = false, columnDefinition = "UUID")
    private UUID id;

    @Version
    @Column(name = "version")
    private Instant version;

    @Column(name = "categoryName", nullable = false)
    private String categoryName;

    @ManyToOne
    @JoinColumn(name = "createdByEmployeeId", nullable = false)
    private Employee createdByEmployee;
}

Repository代码 #

@Repository
public interface CategoryRepository extends JpaRepository<Category, UUID> {
    List<Category> findAll();
}

Controller & Service代码 #

@PostMapping
public ResponseEntity<?> createProductCategory(@Valid @RequestBody CreateProductCategoryRequest dto,
                                               Authentication authentication) {
    try {
        Employee employee = (Employee) authentication.getPrincipal();
        CreateProductCategoryResponse productCategory = productCategoryService.createProductCategory(dto, employee);
        return ResponseEntity.status(HttpStatus.CREATED).body(productCategory);
    } catch (Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(Map.of("error", e.getMessage()));
    }
}

@Override
public CreateProductCategoryResponse createProductCategory(CreateProductCategoryRequest request, Employee employee) {
    Category productCategory = Category.builder()
            .id(UUID.randomUUID()) // 此处可能存在问题
            .categoryName(request.getCategoryName())
            .createdByEmployee(employee)
            .build();

    Category savedCategory = categoryRepository.save(productCategory);
    return CreateProductCategoryResponse.builder()
            .categoryId(savedCategory.getId())
            .categoryName(savedCategory.getCategoryName())
            .build();
}

问题现象与已尝试操作 #

• 问题：创建Category时出现版本控制相关错误，但Employee实体的@Version注解可正常工作。
• 已尝试操作：
  • 修改@Version字段类型（从Instant改为Long）
  • 移除@Column(name="version")让Hibernate自动处理
  • 确保数据库schema支持乐观锁

疑问 #

1. 为何Category版本控制失效而Employee正常？
2. 是否应使用Long而非Instant作为版本类型？
3. Spring Boot中@Version是否需要特定配置？

问题解答 #

1. 为什么Category版本控制失效而Employee正常？

核心问题在于你创建Category时手动设置了ID：.id(UUID.randomUUID())，但Category实体的ID已经配置了@GeneratedValue(strategy = GenerationType.UUID)，这会让Hibernate误判实体状态——它会把手动设置ID的Category当成已存在的持久化实体，而非新创建的实体。此时Hibernate会检查version字段是否有值，但新实体的version还未被初始化（默认是null），因此触发乐观锁相关错误。

而Employee实体在创建时应该没有手动设置ID，完全由Hibernate自动生成，所以版本字段能被正确初始化，不会出现冲突。

另外还要检查数据库中category表的version字段是否允许为null：如果字段被设为NOT NULL但Hibernate无法初始化值，也会触发报错。

2. 是否应使用Long而非Instant作为版本类型？

推荐使用Long作为版本字段类型。JPA规范明确支持的版本类型包括int、Integer、long、Long、short、Short、java.sql.Timestamp，虽然Hibernate扩展支持Instant，但兼容性不如Long，且用时间类型做版本可能会出现服务器时间同步等额外问题。Long类型性能好、逻辑简单，是乐观锁版本字段的标准选择。

3. Spring Boot中@Version是否需要特定配置？

默认情况下不需要额外配置。只要实体类正确添加@Version注解，且数据库表存在对应类型的字段，Spring Boot整合JPA后会自动启用乐观锁机制。但需要注意：

• 新实体的版本字段不要手动赋值，由JPA/Hibernate自动初始化（Long类型默认初始值为0）
• 不要手动修改版本字段的值，否则会破坏乐观锁的冲突判断逻辑
• 如果使用Hibernate扩展支持的类型（如Instant），需确保Hibernate版本兼容

修复建议 #

1. 移除Category创建时的手动ID赋值
   因为实体已配置自动生成UUID，手动设置会干扰Hibernate的状态判断：

Category productCategory = Category.builder()
        // 移除.id(UUID.randomUUID())这一行
        .categoryName(request.getCategoryName())
        .createdByEmployee(employee)
        .build();

2. 统一版本字段类型为Long
   在Employee和Category实体中修改版本字段：

@Version
@Column(name = "version")
private Long version;

同时更新数据库表的version字段类型为BIGINT，并设置默认值为0。

3. 检查数据库字段约束
   确保category表的version字段允许为null（或设置默认值0），让Hibernate能正确初始化新实体的版本值。

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