Spring Data JPA 原理与实战：Repository 接口深度解析

Spring Data JPA 原理与实战：Repository 接口深度解析 | 极客日志

// 你以为的 JPA
public interface UserRepository extends JpaRepository<User, Long> {
    // 自动生成 SQL：SELECT * FROM users WHERE name = ?
    List<User> findByName(String name);
}

// 1. 最基础的仓库标记接口
public interface Repository<T, ID> {
    // 标记接口，没有方法
}

// 2. CrudRepository - 基础 CRUD 操作
public interface CrudRepository<T, ID> extends Repository<T, ID> {
    <S extends T> S save(S entity);
    Optional<T> findById(ID id);
    Iterable<T> findAll();
    long count();
    void delete(T entity);
    boolean existsById(ID id);
}

// 3. PagingAndSortingRepository - 分页排序
public interface PagingAndSortingRepository<T, ID> extends CrudRepository<T, ID> {
    Iterable<T> findAll(Sort sort);
    Page<T> findAll(Pageable pageable);
}

// 4. JpaRepository - JPA 特定功能
public interface JpaRepository<T, ID> extends PagingAndSortingRepository<T, ID> {
    List<T> findAll();
    List<T> findAll(Sort sort);
    List<T> findAllById(Iterable<ID> ids);
    <S extends T> List<S> saveAll(Iterable<S> entities);
    void flush();
    <S extends T> S saveAndFlush(S entity);
    void deleteInBatch(Iterable<T> entities);
    void deleteAllInBatch();
}

// 查询查找策略
public interface QueryLookupStrategy {
    RepositoryQuery resolveQuery(
        Method method,
        RepositoryMetadata metadata,
        ProjectionFactory factory,
        NamedQueries namedQueries
    );
}

// 具体实现：PartTreeJpaQuery
public class PartTreeJpaQuery implements RepositoryQuery {
    private final PartTree tree;
    private final JpaParameters parameters;
    private final EntityManager em;

    public PartTreeJpaQuery(Method method, RepositoryMetadata metadata, EntityManager em) {
        // 1. 解析方法名
        this.tree = new PartTree(method.getName(), metadata.getDomainType());
        // 2. 解析参数
        this.parameters = new JpaParameters(method);
        this.em = em;
    }

    protected TypedQuery<?> createQuery(CriteriaQuery<?> query, Pageable pageable) {
        CriteriaBuilder builder = em.getCriteriaBuilder();
        CriteriaQuery<?> criteria = createCriteriaQuery(builder);
        // 3. 构建查询条件
        Predicate predicate = tree.toPredicate(getRoot(), criteria, builder);
        if (predicate != null) {
            criteria.where(predicate);
        }
        // 4. 应用排序
        if (tree.isOrderBy()) {
            criteria.orderBy(toOrders(tree.getSort(), root, builder));
        }
        TypedQuery<?> typedQuery = em.createQuery(criteria);
        // 5. 应用分页
        if (pageable != null) {
            typedQuery.setFirstResult((int) pageable.getOffset());
            typedQuery.setMaxResults(pageable.getPageSize());
        }
        return typedQuery;
    }
}

关键字	例子	生成的 SQL 片段
And	findByNameAndAge	WHERE name = ? AND age = ?
Or	findByNameOrEmail	WHERE name = ? OR email = ?
Is, Equals	findByName	WHERE name = ?
Between	findByAgeBetween	WHERE age BETWEEN ? AND ?
LessThan	findByAgeLessThan	WHERE age < ?
GreaterThan	findByAgeGreaterThan	WHERE age > ?
Like	findByNameLike	WHERE name LIKE ?
OrderBy	findByAgeOrderByNameDesc	WHERE age = ? ORDER BY name DESC

方法类型	平均耗时 (ms)	内存分配	说明
简单方法 (`findById`)	1.2	低	缓存命中高
复杂方法 (`findByAAndBAndCOrDAndE`)	4.8	中	解析复杂
@Query 注解方法	0.8	低	直接使用

@Configuration
@EnableJpaRepositories(basePackages = "com.example.repository")
public class JpaConfig {
    // 配置
}

// 启用 JPA 仓库的注解
@Import(JpaRepositoriesRegistrar.class)
public @interface EnableJpaRepositories {
    String[] basePackages() default {};
}

// 注册器
class JpaRepositoriesRegistrar extends RepositoryBeanDefinitionRegistrarSupport {
    @Override
    protected void registerBeanDefinitions(...) {
        // 1. 扫描 Repository 接口
        RepositoryConfigurationSource configurationSource = new RepositoryConfigurationExtensionSupport() { ... };
        // 2. 注册 RepositoryFactoryBean
        for (BeanComponentDefinition definition : getRepositoryConfigurations(configurationSource, loader, true)) {
            registry.registerBeanDefinition(definition.getBeanName(), definition.getBeanDefinition());
        }
    }
}

// Repository 工厂 Bean
public class JpaRepositoryFactoryBean<T extends Repository<S, ID>, S, ID> extends RepositoryFactoryBeanSupport<T, S, ID> {
    @Override
    protected RepositoryFactorySupport createRepositoryFactory(EntityManager entityManager) {
        return new JpaRepositoryFactory(entityManager);
    }

    @Override
    public void afterPropertiesSet() {
        super.afterPropertiesSet();
        // 创建代理
        this.repository = getRepository();
    }
}

public class JpaRepositoryFactory extends RepositoryFactorySupport {
    @Override
    public <T, ID> JpaRepository<?, ?> getRepository(Class<T> domainClass, Object customImplementation) {
        // 1. 获取 Repository 元数据
        RepositoryMetadata metadata = getRepositoryMetadata(domainClass);
        // 2. 获取 Repository 基本信息
        Class<?> repositoryInterface = metadata.getRepositoryInterface();
        Class<?> customImplementationClass = metadata.getCustomImplementationClass();
        // 3. 创建 Repository 碎片
        SimpleJpaRepository<?, ?> target = getTargetRepository(metadata, entityManager);
        // 4. 创建 Query 执行器
        JpaRepositoryQuery query = createRepositoryQuery(metadata, target);
        // 5. 创建代理
        return createRepositoryProxy(customImplementationClass, target, query);
    }

    protected <T> T createRepositoryProxy(Class<?> customImplementationClass, Object target, RepositoryQuery queryExecutor) {
        // 创建 InvocationHandler
        RepositoryInvocationHandler handler = new RepositoryInvocationHandler(target, queryExecutor, customImplementationClass);
        // 创建动态代理
        return (T) Proxy.newProxyInstance(
            getProxyClassLoader(),
            new Class[] { repositoryInterface, Repository.class },
            handler
        );
    }
}

// InvocationHandler 实现
private static class RepositoryInvocationHandler implements InvocationHandler {
    private final Object target;
    private final RepositoryQuery queryExecutor;

    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
        // 1. 如果是 Object 的方法，直接调用
        if (method.getDeclaringClass() == Object.class) {
            return method.invoke(this, args);
        }
        // 2. 如果是默认方法（Java 8+）
        if (method.isDefault()) {
            return invokeDefaultMethod(proxy, method, args);
        }
        // 3. 检查是否有自定义实现
        if (customImplementation != null && method.getDeclaringClass().isInstance(customImplementation)) {
            return method.invoke(customImplementation, args);
        }
        // 4. 执行查询
        return queryExecutor.execute(method, args);
    }
}

public enum QueryLookupStrategy {
    // 1. 使用@Query 注解
    // @Query("SELECT u FROM User u WHERE u.name = ?1")
    // List<User> findByName(String name);

    // 2. 使用命名查询
    // @NamedQuery(name = "User.findByEmail", query = "SELECT u FROM User u WHERE u.email = ?1")

    // 3. 解析方法名
    // List<User> findByFirstNameAndLastName(String firstName, String lastName);

    // 4. 自定义实现
    // public interface UserRepositoryCustom { List<User> findActiveUsers(); }
    // public class UserRepositoryImpl implements UserRepositoryCustom { ... }
}

@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@QueryAnnotation
public @interface Query {
    String value() default "";
    String countQuery() default "";
    String countProjection() default "";
    boolean nativeQuery() default false;
    String name() default "";
}

// 查询注解处理器
public class JpaQueryMethod extends RepositoryQuery {
    private final Method method;
    private final JpaQueryAnnotation annotation;

    public JpaQueryMethod(Method method, RepositoryMetadata metadata, ProjectionFactory factory) {
        this.method = method;
        this.annotation = method.getAnnotation(Query.class);
    }

    protected String getQueryString() {
        if (annotation != null) {
            return annotation.value();
        }
        String namedQueryName = getNamedQueryName();
        NamedQueries namedQueries = getNamedQueries();
        if (namedQueries.hasQuery(namedQueryName)) {
            return namedQueries.getQuery(namedQueryName);
        }
        return null;
    }

    protected Query createQuery(EntityManager em, Object[] parameters) {
        String queryString = getQueryString();
        if (annotation.nativeQuery()) {
            Query query = em.createNativeQuery(queryString);
            applyQueryHints(query);
            return query;
        } else {
            TypedQuery<?> query = em.createQuery(queryString, getDomainClass());
            applyQueryHints(query);
            return query;
        }
    }
}

// 实体定义
@Entity
public class Order {
    @Id
    private Long id;

    @OneToMany(mappedBy = "order", fetch = FetchType.LAZY)
    private List<OrderItem> items;
}

// 问题代码
@Repository
public interface OrderRepository extends JpaRepository<Order, Long> {
    List<Order> findByUserId(Long userId);
}

// 使用
List<Order> orders = orderRepository.findByUserId(1L);
for (Order order : orders) {
    List<OrderItem> items = order.getItems(); // 这里每个 order.items 都会触发一次查询！
}

// 方案 1：使用 JOIN FETCH
@Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.user.id = :userId")
List<Order> findByUserIdWithItems(@Param("userId") Long userId);

// 方案 2：使用@EntityGraph
@EntityGraph(attributePaths = {"items"})
@Query("SELECT o FROM Order o WHERE o.user.id = :userId")
List<Order> findByUserIdWithItems(@Param("userId") Long userId);

// 方案 3：使用 Projection
public interface OrderSummary {
    Long getId();
    BigDecimal getTotal();
}

@Query("SELECT o.id as id, o.total as total FROM Order o WHERE o.user.id = :userId")
List<OrderSummary> findSummariesByUserId(@Param("userId") Long userId);

方案	SQL 次数	总耗时 (ms)	内存占用
原始方式	101	1250	高
JOIN FETCH	1	320	中
@EntityGraph	1	350	中
Projection	1	120	低

// 错误：先查询全部再内存分页
Pageable pageable = PageRequest.of(0, 10);
List<User> allUsers = userRepository.findAll(); // 查出 100 万条
List<User> pageUsers = allUsers.stream()
    .skip(pageable.getOffset())
    .limit(pageable.getPageSize())
    .collect(Collectors.toList()); // 内存爆炸！

// 正确：使用 Page
Pageable pageable = PageRequest.of(0, 10, Sort.by("id").descending());
Page<User> page = userRepository.findAll(pageable);

// 复杂查询分页
@Query(value = "SELECT u FROM User u WHERE u.age > :age", countQuery = "SELECT COUNT(u) FROM User u WHERE u.age > :age")
Page<User> findByAgeGreaterThan(@Param("age") int age, Pageable pageable);

public class SimpleJpaRepository<T, ID> implements JpaRepository<T, ID> {
    @Override
    public Page<T> findAll(Pageable pageable) {
        if (pageable == null) {
            return new PageImpl<>(findAll());
        }
        // 1. 查询数据
        TypedQuery<T> query = getQuery(null, pageable.getSort());
        query.setFirstResult((int) pageable.getOffset());
        query.setMaxResults(pageable.getPageSize());
        List<T> content = query.getResultList();

        // 2. 查询总数
        TypedQuery<Long> countQuery = getCountQuery();
        Long total = countQuery.getSingleResult();
        return new PageImpl<>(content, pageable, total);
    }

    protected TypedQuery<Long> getCountQuery() {
        CriteriaBuilder builder = entityManager.getCriteriaBuilder();
        CriteriaQuery<Long> query = builder.createQuery(Long.class);
        Root<T> root = query.from(getDomainClass());
        if (this.queryMethod.hasPredicate()) {
            query.where(this.queryMethod.getPredicate(root, query, builder));
        }
        query.select(builder.count(root));
        return entityManager.createQuery(query);
    }
}

@Repository
@Transactional(readOnly = true)
public interface UserRepository extends JpaRepository<User, Long> {
    List<User> findByName(String name);

    @Transactional
    <S extends User> S save(S entity);

    @Transactional(readOnly = false)
    @Modifying
    @Query("UPDATE User u SET u.status = :status WHERE u.id = :id")
    int updateStatus(@Param("id") Long id, @Param("status") String status);
}

@Service
public class UserService {
    @Transactional
    public void updateUser(UserDTO dto) {
        User user = userRepository.findById(dto.getId()).orElseThrow();
        user.setName(dto.getName());
        userRepository.save(user);
        logRepository.save(new Log("用户更新"));
        // 如果这里抛出异常，所有操作回滚
    }
}

// 1. 事务要短小
@Transactional(timeout = 5)
public void quickOperation() {
    // 快速操作
}

// 2. 只读事务优化
@Transactional(readOnly = true)
public List<User> getUsers() {
    return userRepository.findAll();
}

// 3. 避免事务中调用 RPC
@Transactional
public void processOrder(Order order) {
    orderRepository.save(order);
    // 不要在事务中调用 RPC！
    // paymentService.pay(order); // 错误！
    // 应该：事务提交后异步调用
}

// 正确做法
@Transactional
public void processOrder(Order order) {
    orderRepository.save(order);
}

@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void handleAfterCommit(OrderEvent event) {
    paymentService.pay(event.getOrder());
}

// 1. 实体设计
@Entity
@Table(name = "orders", indexes = {
    @Index(name = "idx_user_status", columnList = "userId,status"),
    @Index(name = "idx_create_time", columnList = "createTime")
})
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private Long userId;
    private BigDecimal amount;
    private String status;

    @CreationTimestamp
    private LocalDateTime createTime;

    @UpdateTimestamp
    private LocalDateTime updateTime;

    @OneToMany(mappedBy = "order", fetch = FetchType.LAZY, cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items = new ArrayList<>();
}

// 2. Repository 设计
@Repository
public interface OrderRepository extends JpaRepository<Order, Long>, JpaSpecificationExecutor<Order> {
    List<Order> findByUserIdAndStatus(Long userId, String status);
    Page<Order> findByUserId(Long userId, Pageable pageable);

    @Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.userId = :userId AND o.createTime BETWEEN :start AND :end")
    List<Order> findUserOrdersWithItems(@Param("userId") Long userId, @Param("start") LocalDateTime start, @Param("end") LocalDateTime end);

    @Query("SELECT new com.example.dto.OrderStatsDTO(COUNT(o), SUM(o.amount), AVG(o.amount)) FROM Order o WHERE o.userId = :userId")
    OrderStatsDTO getUserOrderStats(@Param("userId") Long userId);

    @Query(value = "SELECT DATE(create_time) as date, COUNT(*) as count FROM orders WHERE create_time >= :start GROUP BY DATE(create_time) ORDER BY date DESC", nativeQuery = true)
    List<Object[]> getDailyOrderCount(@Param("start") LocalDateTime start);
}

// 3. Specification 动态查询
public class OrderSpecifications {
    public static Specification<Order> hasStatus(String status) {
        return (root, query, cb) -> status == null ? null : cb.equal(root.get("status"), status);
    }

    public static Specification<Order> amountBetween(BigDecimal min, BigDecimal max) {
        return (root, query, cb) -> {
            if (min == null && max == null) return null;
            if (min == null) return cb.lessThanOrEqualTo(root.get("amount"), max);
            if (max == null) return cb.greaterThanOrEqualTo(root.get("amount"), min);
            return cb.between(root.get("amount"), min, max);
        };
    }

    public static Specification<Order> createdAfter(LocalDateTime date) {
        return (root, query, cb) -> date == null ? null : cb.greaterThanOrEqualTo(root.get("createTime"), date);
    }
}

// 4. 使用示例
@Service
@Transactional(readOnly = true)
public class OrderQueryService {
    public Page<Order> searchOrders(OrderSearchCriteria criteria, Pageable pageable) {
        Specification<Order> spec = Specification
            .where(OrderSpecifications.hasStatus(criteria.getStatus()))
            .and(OrderSpecifications.amountBetween(criteria.getMinAmount(), criteria.getMaxAmount()))
            .and(OrderSpecifications.createdAfter(criteria.getStartDate()));
        return orderRepository.findAll(spec, pageable);
    }
}

查询类型	平均耗时 (ms)	内存占用	SQL 数量
简单查询 (`findById`)	5	低	1
分页查询 (`Page`)	45	中	2
JOIN FETCH 查询	120	高	1
Specification 动态查询	85	中	1-2
原生 SQL 统计	320	低	1

// 问题：在事务外访问懒加载属性
@Service
public class OrderService {
    @Transactional
    public Order getOrder(Long id) {
        return orderRepository.findById(id).orElse(null);
    }
}

// 调用
Order order = orderService.getOrder(1L);
List<OrderItem> items = order.getItems(); // LazyInitializationException

// 解决方案 1：使用 JOIN FETCH
@Query("SELECT o FROM Order o JOIN FETCH o.items WHERE o.id = :id")
Optional<Order> findByIdWithItems(@Param("id") Long id);

// 解决方案 2：使用@Transactional
@Transactional(readOnly = true)
public Order getOrderWithItems(Long id) {
    Order order = orderRepository.findById(id).orElse(null);
    if (order != null) {
        order.getItems().size(); // 在事务内触发加载
    }
    return order;
}

// 解决方案 3：使用 DTO/Projection
public interface OrderDTO {
    Long getId();
    String getOrderNo();
}

// 错误：循环插入
@Transactional
public void createUsers(List<User> users) {
    for (User user : users) {
        userRepository.save(user); // 每次 save 都 flush
    }
}

// 正确：批量插入
@Transactional
public void createUsers(List<User> users) {
    for (int i = 0; i < users.size(); i++) {
        userRepository.save(users.get(i));
        if (i % 50 == 0 && i > 0) {
            entityManager.flush();
            entityManager.clear();
        }
    }
}

// 最佳：使用 saveAll
@Transactional
public void createUsers(List<User> users) {
    userRepository.saveAll(users);
}

// 使用原生 SQL 批量插入
@Modifying
@Query(value = "INSERT INTO users (name, email) VALUES (:names, :emails)", nativeQuery = true)
void batchInsert(@Param("names") List<String> names, @Param("emails") List<String> emails);

// 使用@Version 乐观锁
@Entity
public class Product {
    @Id
    private Long id;
    private String name;
    private Integer stock;

    @Version
    private Integer version;

    public void reduceStock(int quantity) {
        if (this.stock < quantity) {
            throw new InsufficientStockException();
        }
        this.stock -= quantity;
    }
}

// 使用悲观锁
@Repository
public interface ProductRepository extends JpaRepository<Product, Long> {
    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @Query("SELECT p FROM Product p WHERE p.id = :id")
    Optional<Product> findByIdForUpdate(@Param("id") Long id);
}

// 使用场景
@Service
public class OrderService {
    @Transactional
    public void placeOrder(Long productId, int quantity) {
        Product product = productRepository.findByIdForUpdate(productId)
            .orElseThrow(() -> new ProductNotFoundException());
        product.reduceStock(quantity);
        productRepository.save(product);
    }
}

spring:
  jpa:
    properties:
      hibernate:
        generate_statistics: true
        session.events.log.LOG_QUERIES_SLOWER_THAN_MS: 1000
    show-sql: true
    open-in-view: false
logging:
  level:
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE
    org.springframework.orm.jpa: DEBUG

@Component
public class JpaPerformanceMonitor {
    @PersistenceUnit
    private EntityManagerFactory emf;

    @Scheduled(fixedDelay = 60000)
    public void monitorPerformance() {
        Statistics stats = emf.unwrap(SessionFactory.class).getStatistics();
        Map<String, Object> metrics = new HashMap<>();
        metrics.put("queryExecutionCount", stats.getQueryExecutionCount());
        metrics.put("queryExecutionMaxTime", stats.getQueryExecutionMaxTime());
        metrics.put("queryCacheHitCount", stats.getQueryCacheHitCount());
        metrics.put("queryCacheMissCount", stats.getQueryCacheMissCount());
        metrics.put("secondLevelCacheHitCount", stats.getSecondLevelCacheHitCount());
        metrics.put("secondLevelCacheMissCount", stats.getSecondLevelCacheMissCount());

        sendToMonitoringSystem(metrics);

        if (stats.getQueryExecutionMaxTime() > 1000) {
            log.warn("发现慢查询，最大执行时间：{}ms", stats.getQueryExecutionMaxTime());
        }
    }
}

spring:
  jpa:
    open-in-view: false
    show-sql: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQL8Dialect
        jdbc.batch_size: 50
        order_inserts: true
        order_updates: true
        generate_statistics: true
        cache.use_second_level_cache: true
        cache.use_query_cache: true
        cache.region.factory_class: org.hibernate.cache.jcache.JCacheRegionFactory
        javax.cache.provider: org.ehcache.jsr107.EhcacheCachingProvider
    ddl-auto: validate
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-test-query: SELECT 1

Spring Data JPA 原理与实战：Repository 接口深度解析

🎯 先说说我被 JPA"折磨"的经历

✨ 摘要

1. 别被"简单"迷惑了

1.1 JPA 不是"自动 SQL 生成器"

1.2 Repository 接口层次结构

2. 方法名解析的魔法

2.1 方法名如何变成 SQL？

2.2 支持的关键字

2.3 性能陷阱

3. 动态代理的实现机制

3.1 Repository 如何变成 Bean？

3.2 代理对象的创建

4. 查询执行策略

4.1 四种查询创建策略

4.2 @Query 注解的工作原理

5. 性能优化实战

5.1 N+1 问题解决方案

5.2 分页查询优化

6. 事务管理

6.1 Repository 的事务行为

6.2 事务最佳实践

7. 企业级实战案例

7.1 电商订单系统

7.2 性能测试结果

8. 常见问题与解决方案

8.1 懒加载异常

8.2 批量操作性能

8.3 数据一致性

9. 监控与诊断

9.1 监控配置

9.2 性能诊断

10. 最佳实践总结

10.1 我的"JPA 军规"

📜 第一条：合理设计实体

📜 第二条：优化查询

📜 第三条：管理事务

📜 第四条：监控性能

10.2 生产环境配置

11. 最后的话

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具