jpa-hibernate-performance

# Habilidade de IA: Alta Performance em Persistência Java (JPA/Hibernate) Esta skill orienta a inteligência artificial a desenhar a camada de persistência Java/JPA com foco em performance, baseada na obra *High-Performance Java Persistence* (Vlad Mihalcea), cobrindo JDBC puro, JPA e Hibernate. --- ## 🧱 1. Arquitetura da Camada de Persistência - **Escolha consciente da ferramenta**: JDBC batch puro para ETL/bulk; JPA+Hibernate para OLTP de domínio; SQL nativo/projection para consultas analíticas — **não force ORM em tudo**. - ** stereotipos de acesso**: entidades de domínio (aggregates com transações curtas), DTO projections (queries de leitura), value types (embeddables imutáveis). - **Transações curtas**: scope da transação = menor unidade atômica; nunca rode UI/remote calls dentro de transação aberta. --- ## 🔥 2. Problema N+1 e Estratégias de Fetch ### Diagnóstico - **N+1**: uma query para a entidade raiz + N queries lazy ao navegar associações; detecte com `hibernate.generate_statistics=true`, `nullSafeGet`/SQL log, e testes de hidratação. ### Mitigações (em ordem de preferência) 1. **JOIN FETCH** em JPQL: `SELECT a FROM Author a JOIN FETCH a.books WHERE a.id = :id` — busca em ida única. 2. **@EntityGraph**: definição declarativa de fetch plan por caso de uso (sem poluir queries). 3. **`@_BATCH(size)` / `hibernate.default_batch_fetch_size`**: transform N consultas em N/size consultas `IN (...)` — o melhor equilíbrio para associações arbitrárias. 4. **`@Fetch(FetchMode.SUBSELECT)`**: para coleções acessadas em massa na mesma transação. 5. **`@BatchSize`** em lazy collections; `@LazyCollection(LazyCollectionOption.EXTRA)` para count-only. ### Regras - `FetchType.LAZY` em **toda** associação (o padrão safe); UNI-side `@ManyToOne(optional=false)` pode ser EAGER com critério. - Nunca use "open session in view" em produção — vilão clássico de N+1 e de transações longas. - Para muitos-para-muitos grandes, prefira **duas bidirecionais unilaterais** com extra `@LazyCollection(ExtraLazyType)`. Acesso via DTO quando o modelo de escrita não precisa da coleção. --- ## 📦 3. Write-Behind, Flush e Batching ### ActionQueue e Flush Order - Hibernate ordena operações na `ActionQueue` (inserts → updates → collection removes → deletions), já pensado para FK/UNIQUE; entenda a ordem em transações multi-entidade. - `FlushModeType.AUTO` flutua em queries "[flush antes da query que pode tocar dados pendentes]"; use `COMMIT` para hot paths read-only e flush controle manual (`em.flush()`). ### JDBC Batching - Ative: `hibernate.jdbc.batch_size` (30–50 típico), `order_inserts=true`, `order_updates=true`, `batch_versioned_data=true`. - **Requisito do driver**: `rewriteBatchedStatements` (MySQL), `reWriteBatchedInserts` (PostgreSQL) para batch real no wire. - **IDENTITY desabilita batching de inserts** (Hibernate precisa do id gerado); prefira `SEQUENCE` (com `allocationSize` 50+) ou `TABLE` com pooler (pooled-lo). - Bulk: `JPQL/ HQL bulk update+delete` (bypassam contexto de persistência), ` StatelessSession`, ou `Session.doWork` com JDBC directo para grandes volumes. ### Dirty Checking e Estado - Dirty checking default varre entidades do contexto; para entidades grandes/read-only use `@Immutable` ou `Session.refresh`. - `@DynamicUpdate` gera UPDATE só das colunas alteradas (menos tráfego, evita sobrescrever) — cuidado com planos de consulta menos cacheáveis. - Limite a **tamanho da Session/Persistence Context**: `clear()`/`detach()` em loops longos; meça com `em.getEntityManagerFactory().getPersistenceUnitUtil()`/estatísticas. --- ## 🗄️ 4. Cache (L1, L2 e Query Cache) | Cache | Escopo | Uso recomendado | | :--- | :--- | :--- | | **First-level (Session)** | Transação/Sessão | Identidade e byteaço de objeto; sempre ativo | | **Second-level (L2)** | SessionFactory (multi-sessão) | Dados read-mostly, referências; datasense TTL/versionado | | **Query cache** | Resultado de consulta | Só com poucos results e tabelas estáveis (invalidação é carreg) | - **Concurrence strategies** (da mais estrita para a mais leve): `READ_WRITE` →`NONSTRICT_READ_WRITE`→ `READ_ONLY`. - `NONSTRICT_READ_WRITE`: lock assíncrono leve; ok em read-mostly; nunca em alta escrita concorrente (invalida demais). - **Providers**: JCache (Ehcache 3, Infinispan, Caffeine-bridge); dimensione TIs de L2 do tamaño do working set (não "cache tudo"). - **Read-through no app**: padrão Cache-Aside explícito ([system-design-scalability](../../engineering-practices/system-design-scalability/SKILL.md)) muitas vezes supera L2 quando o domínio é propício. --- ## 🔒 5. Locking, Concurrency e Transações - **Otimista (versão/numérica)**: trate `OptimisticLockException` com retry (transação curta); ideal para contenda média/baixa. Increment manual de version em bulk actions. - **Pessimista**: `PESSIMISTIC_WRITE` (SELECT FOR UPDATE) para filas de job, contadores críticos, bid[reserve]-stock; tempo de lock mínimo. - **Lost update**: a maior plaga silenciosa — leitor+escritor em transações separadas; mitigações: lock otimista, `PESSIMISTIC_FORCE_INCREMENT`, ou atomicidade no SQL (`UPDATE ... SET x = x + 1`). - **Isolamento**: READ_COMMITTED + versionamento resolve 90%; SERIALIZABLE só com boa justificativa (custo em locks/anomalias até no Postgres SSI). --- ## 📑 6. Paginação e Consultas - **OFFSET escalonadamente ruim** (varre e descarta): para deep pagination use **keyset/seek**(`WHERE (a.id > :last) ORDER BY a.id LIMIT :n`) — custo constante. - SQL padrão moderno: `OFFSET ? ROWS FETCH FIRST ? ROWS ONLY` (SQL:2008); dialetos variam — deixe o Hibernate mapear. - **Projections**: `SELECT new com.x.Dto(...)` para leituras (contra tráfego de entidades geridas); `Tuple`/interface-based projections para flexibilidade. - **Criteria API** para filtros dinâmicos; cuidado com geração de planos não-cachaveis (use query plan cache com eps constantes). - Medição por banco: `EXPLAIN (ANALYZE, BUFFERS)` (Postgres), set showplan (SQL Server), autotrace (Oracle) — valide o plano antes e depois ([db-postgresql](../db-postgresql/SKILL.md)). --- ## 🧭 7. Protocolo de Otimização de Persistência 1. **Meça primeiro**: `hibernate.generate_statistics=true` em dev; APM em prod; identifique N+1, queries repetidas, sessões longas. 2. **Corrija fetch** (JOIN FETCH/EntityGraph) antes de mexer em cache. 3. **Ative batching** e verifique wire (logs do driver) — batch que não chega ao banco é só overhead. 4. **Cache com política**: L2 para read-mostly com TTL-versions; query cache raramente. 5. **Locking por caso**: otimista default; pessimista só micro-intervalos. 6. **Paginação keyset**; OFFSET só em páginas iniciais pequenas. 7. **Testes de carga** com dados realistas (cardinalidade e skew) e verificação de planos pós-índices/migração. 8. **Django-like prproviders**: driver e dialeto sempre atualizados (otimizações chegam por versão do Hibernate/driver JDBC). --- ## 🔗 Integração com Outras Skills - [lang-java](../../languages/lang-java/SKILL.md): fundamentos de JPA sob concorrência e JVM. - [db-postgresql](../db-postgresql/SKILL.md), [db-mariadb](../db-mariadb/SKILL.md), [db-sqlite](../db-sqlite/SKILL.md): tuning do banco de destino (EXPLAIN, índices, buffer). - [dba-database-administrator](../../roles/dba-database-administrator/SKILL.md): modelagem, índices e consultas de referência. - [backend-developer](../../roles/backend-developer/SKILL.md): integração em serviços/APIs Java com transações curtas. - [latency-engineering](../../engineering-practices/latency-engineering/SKILL.md): round-trips do pool de conexões e N+1 como vilões de p99.