spring-data-jpa

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spring Data JPA

Overview

概述

To implement persistence layers with Spring Data JPA, create repository interfaces that provide automatic CRUD operations, entity relationships, query methods, and advanced features like pagination, auditing, and performance optimization.

使用Spring Data JPA实现持久化层时，可创建仓库接口以自动提供CRUD操作、实体关系、查询方法，以及分页、审计和性能优化等高级功能。

When to Use

适用场景

Use this Skill when:

Implementing repository interfaces with automatic CRUD operations
Creating entities with relationships (one-to-one, one-to-many, many-to-many)
Writing queries using derived method names or custom @Query annotations
Setting up pagination and sorting for large datasets
Implementing database auditing with timestamps and user tracking
Configuring transactions and exception handling
Using UUID as primary keys for distributed systems
Optimizing performance with database indexes
Setting up multiple database configurations

在以下场景中使用本Skill：

实现具备自动CRUD操作的仓库接口
创建包含实体关系（一对一、一对多、多对多）的实体类
使用派生方法名或自定义@Query注解编写查询
为大型数据集设置分页与排序
实现带时间戳和用户追踪的数据库审计
配置事务与异常处理
在分布式系统中使用UUID作为主键
通过数据库索引优化性能
配置多数据库环境

Instructions

操作指南

Create Repository Interfaces

创建仓库接口

To implement a repository interface:

Extend the appropriate repository interface:

java

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    // Custom methods defined here
}

Use derived queries for simple conditions:

java

Optional<User> findByEmail(String email);
List<User> findByStatusOrderByCreatedDateDesc(String status);

Implement custom queries with @Query:

java

@Query("SELECT u FROM User u WHERE u.status = :status")
List<User> findActiveUsers(@Param("status") String status);

要实现仓库接口：

继承合适的仓库接口：

java

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    // 自定义方法定义在此处
}

使用派生查询处理简单条件：

java

Optional<User> findByEmail(String email);
List<User> findByStatusOrderByCreatedDateDesc(String status);

使用@Query实现自定义查询：

java

@Query("SELECT u FROM User u WHERE u.status = :status")
List<User> findActiveUsers(@Param("status") String status);

Configure Entities

配置实体类

Define entities with proper annotations:

java

@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 100)
    private String email;
}

Configure relationships using appropriate cascade types:

java

@OneToMany(mappedBy = "user", cascade = CascadeType.ALL, orphanRemoval = true)
private List<Order> orders = new ArrayList<>();

Set up database auditing:

java

@CreatedDate
@Column(nullable = false, updatable = false)
private LocalDateTime createdDate;

使用合适的注解定义实体类：

java

@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, length = 100)
    private String email;
}

使用合适的级联类型配置实体关系：

java

@OneToMany(mappedBy = "user", cascade = CascadeType.ALL, orphanRemoval = true)
private List<Order> orders = new ArrayList<>();

设置数据库审计：

java

@CreatedDate
@Column(nullable = false, updatable = false)
private LocalDateTime createdDate;

Apply Query Patterns

应用查询模式

Use derived queries for simple conditions
Use @Query for complex queries
Return Optional<T> for single results
Use Pageable for pagination
Apply @Modifying for update/delete operations

使用派生查询处理简单条件
使用@Query处理复杂查询
单个结果返回Optional<T>类型
使用Pageable实现分页
更新/删除操作使用@Modifying注解

Manage Transactions

事务管理

Mark read-only operations with @Transactional(readOnly = true)
Use explicit transaction boundaries for modifying operations
Specify rollback conditions when needed

为只读操作标记@Transactional(readOnly = true)
为修改操作设置显式事务边界
必要时指定回滚条件

Examples

示例

Basic CRUD Repository

基础CRUD仓库

java

@Repository
public interface ProductRepository extends JpaRepository<Product, Long> {
    // Derived query
    List<Product> findByCategory(String category);

    // Custom query
    @Query("SELECT p FROM Product p WHERE p.price > :minPrice")
    List<Product> findExpensiveProducts(@Param("minPrice") BigDecimal minPrice);
}

java

@Repository
public interface ProductRepository extends JpaRepository<Product, Long> {
    // 派生查询
    List<Product> findByCategory(String category);

    // 自定义查询
    @Query("SELECT p FROM Product p WHERE p.price > :minPrice")
    List<Product> findExpensiveProducts(@Param("minPrice") BigDecimal minPrice);
}

Pagination Implementation

分页实现

java

@Service
public class ProductService {
    private final ProductRepository repository;

    public Page<Product> getProducts(int page, int size) {
        Pageable pageable = PageRequest.of(page, size, Sort.by("name").ascending());
        return repository.findAll(pageable);
    }
}

java

@Service
public class ProductService {
    private final ProductRepository repository;

    public Page<Product> getProducts(int page, int size) {
        Pageable pageable = PageRequest.of(page, size, Sort.by("name").ascending());
        return repository.findAll(pageable);
    }
}

Entity with Auditing

带审计功能的实体类

java

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @CreatedDate
    @Column(nullable = false, updatable = false)
    private LocalDateTime createdDate;

    @LastModifiedDate
    private LocalDateTime lastModifiedDate;

    @CreatedBy
    @Column(nullable = false, updatable = false)
    private String createdBy;
}

java

@Entity
@EntityListeners(AuditingEntityListener.class)
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @CreatedDate
    @Column(nullable = false, updatable = false)
    private LocalDateTime createdDate;

    @LastModifiedDate
    private LocalDateTime lastModifiedDate;

    @CreatedBy
    @Column(nullable = false, updatable = false)
    private String createdBy;
}

Best Practices

最佳实践

Entity Design

实体类设计

Use constructor injection exclusively (never field injection)
Prefer immutable fields with
```
final
```
modifiers
Use Java records (16+) or
```
@Value
```
for DTOs
Always provide proper
```
@Id
```
and
```
@GeneratedValue
```
annotations
Use explicit
```
@Table
```
and
```
@Column
```
annotations

仅使用构造函数注入（绝不使用字段注入）
优先使用带
```
final
```
修饰符的不可变字段
对于DTO，使用Java 16+的record或
```
@Value
```
注解
始终提供正确的
```
@Id
```
和
```
@GeneratedValue
```
注解
使用显式的
```
@Table
```
和
```
@Column
```
注解

Repository Queries

仓库查询

Use derived queries for simple conditions
Use
```
@Query
```
for complex queries to avoid long method names
Always use
```
@Param
```
for query parameters
Return
```
Optional<T>
```
for single results
Apply
```
@Transactional
```
on modifying operations

简单条件使用派生查询
复杂查询使用
```
@Query
```
以避免过长的方法名
始终为查询参数使用
```
@Param
```
注解
单个结果返回
```
Optional<T>
```
类型
修改操作上添加
```
@Transactional
```
注解

Performance Optimization

性能优化

Use appropriate fetch strategies (LAZY vs EAGER)
Implement pagination for large datasets
Use database indexes for frequently queried fields
Consider using
```
@EntityGraph
```
to avoid N+1 query problems

使用合适的抓取策略（LAZY vs EAGER）
为大型数据集实现分页
为频繁查询的字段创建数据库索引
考虑使用
```
@EntityGraph
```
避免N+1查询问题

Transaction Management

事务管理

Mark read-only operations with
```
@Transactional(readOnly = true)
```
Use explicit transaction boundaries
Avoid long-running transactions
Specify rollback conditions when needed

为只读操作标记
```
@Transactional(readOnly = true)
```
使用显式事务边界
避免长时间运行的事务
必要时指定回滚条件

Reference Documentation

参考文档

For comprehensive examples, detailed patterns, and advanced configurations, see:

Examples - Complete code examples for common scenarios
Reference - Detailed patterns and advanced configurations

如需完整示例、详细模式和高级配置，请参阅：

示例 - 常见场景的完整代码示例
参考 - 详细模式与高级配置