Kotlin JPA: modele entidades sem quebrar identidade e consultas

ANÁLISE EDITORIAL

A Skill oficial Kotlin Backend JPA Entity Mapping orienta um agente a criar ou revisar entidades Kotlin usadas com Spring Data JPA e Hibernate. O foco não é gerar anotações em massa. É preservar identidade, igualdade, restrições de unicidade, relacionamentos e planos de busca sem transformar sintomas do ORM em correções apressadas.

Esse cuidado é importante porque recursos convenientes da linguagem podem entrar em conflito com o ciclo de vida de uma entidade. Uma data class gera igualdade baseada em campos, enquanto uma entidade gerenciada pode receber um identificador depois de persistida, mudar estado e ser representada por proxy. A Skill reúne regras para que o agente examine essas diferenças antes de propor código.

O que esta Skill faz de verdade

O SKILL.md organiza uma revisão de entidades Kotlin em seis frentes: desenho da classe, identidade e igualdade, restrições, relações, consultas e armadilhas do ORM. A regra central é não usar data class como entidade JPA. Esse tipo continua adequado para DTOs, mas a igualdade gerada sobre todos os campos, o copy() e a mutabilidade criam riscos quando o objeto passa a ser gerenciado pelo Hibernate.

A orientação também pede um estado não persistido explícito para identificadores gerados pelo banco, normalmente com Long?, e um hashCode estável. Ela não impõe uma única implementação a todos os projetos. Primeiro manda respeitar a convenção existente. Se não houver convenção, sugere igualdade baseada no ID e chama atenção para proxies, campos mutáveis e associações lazy.

Na parte de consulta, a Skill não aceita “troque tudo para EAGER” como correção. Ela pede evidência da quantidade de consultas e recomenda soluções direcionadas, como @EntityGraph, JOIN FETCH, batch fetching ou projeção DTO, sempre com o efeito do plano de busca explicado.

Para quem serve

Serve a desenvolvedores backend, revisores e equipes que mantêm projetos Kotlin com Spring Data JPA ou Hibernate. É especialmente útil ao criar uma entidade, investigar LazyInitializationException, localizar um N+1, definir unicidade, revisar relações bidirecionais ou decidir como um ID participa de equals e hashCode.

Também ajuda em revisão de código. Em vez de aceitar uma entidade porque ela compila, o agente pode verificar como o objeto nasce, quando recebe ID, se entra em Set ou Map, quais campos disparam lazy loading e quais restrições precisam existir no banco.

Ela não substitui desenho de domínio, migration review, teste de integração ou análise de SQL. A Skill fornece critérios. O projeto real ainda define versão, convenções, banco, concorrência, volume, regras de negócio e tolerância a mudanças.

Compatibilidade e pré-requisitos

A versão auditada está no repositório oficial Kotlin/kotlin-agent-skills e segue o padrão Agent Skills. Ela pode ser lida por clientes compatíveis com SKILL.md. O uso prático pressupõe um projeto Kotlin que use JPA ou Hibernate e uma forma controlada de inspecionar código e testes.

• Versões de Kotlin, JDK, Spring Data JPA e Hibernate identificadas.
• Plugins Gradle conferidos, inclusive suporte JPA no plugin no-arg quando aplicável.
• Schema e ferramenta de migração conhecidos.
• Banco descartável ou ambiente de integração para testes.
• Logs SQL ou métricas de consulta disponíveis para diagnosticar N+1.
• Base Git limpa ou branch de teste para revisar o diff.

A documentação oficial do Kotlin explica o suporte JPA do plugin no-arg e o suporte Spring do all-open. Esses plugins resolvem requisitos de construção e proxy em cenários específicos. Eles não corrigem identidade, relações ou consultas por conta própria.

Instalação recomendada

O README oficial documenta a instalação por Skills CLI:

npx skills add Kotlin/kotlin-agent-skills --skill kotlin-backend-jpa-entity-mapping

O npx consulta a rede e pode baixar e executar o Skills CLI. Confira pacote, origem, destino e arquivos antes de confirmar. Instale primeiro em um projeto de teste. O SKILL.md fixado no commit auditado pode ser lido sem executar instalação.

O download local do Bastidores é documental. Contém somente SKILL.md, LICENSE e ORIGEM.md. Não inclui projeto Kotlin, Gradle, plugin, dependência, banco de produção, migração, script, binário, credencial, segredo ou dado.

Configuração antes do primeiro uso

Comece delimitando a tarefa. Informe a entidade, as classes relacionadas, a tabela, o schema e o comportamento observado. Peça análise antes de edição. O agente deve identificar como o ID é gerado, como a igualdade funciona, quais campos são mutáveis, quais relações são lazy e onde o objeto é armazenado em coleções.

Registre as versões e abra as migrações que criaram a tabela. Uma anotação unique = true não prova que o banco ativo contém a restrição esperada. Para idempotência e concorrência, a regra precisa existir na camada correta e ser testada com duas operações concorrentes.

Defina o que está proibido na primeira passada: não aplicar migration, não executar SQL de escrita, não conectar produção e não mudar fetch type globalmente. O resultado inicial deve ser um diagnóstico com arquivos, riscos, plano e testes propostos.

Primeiro uso seguro

Escolha uma entidade pequena em uma branch descartável. Um pedido adequado seria: “revise esta entidade e explique os riscos de identidade, igualdade e lazy loading; não altere arquivos”. Compare a resposta com o código e com os testes existentes.

Se a classe for data class, peça ao agente para mostrar quais campos entram na igualdade e o que muda depois de persistir. Em seguida, solicite um diff mínimo para uma classe regular, sem aplicar migration. O exemplo oficial usa ID anulável com setter protegido, equals baseado no ID e hashCode estável.

Rode testes unitários e de integração. Inclua entidade antes e depois do persist, uso em HashSet, comparação com proxy quando o projeto usa proxies e serialização que não deve tocar relações lazy. O objetivo é observar comportamento, não apenas compilar.

Como o fluxo deve funcionar

1. Inventariar entidade, DTOs, repositório, serviço, migração e testes relacionados.
2. Identificar versões, plugins e estratégia de geração de ID.
3. Mapear igualdade, mutabilidade, relações e pontos de lazy loading.
4. Conferir restrições e índices no schema, não apenas nas anotações.
5. Medir consultas antes de afirmar que existe N+1.
6. Propor um diff pequeno e explicar cada mudança.
7. Executar testes em banco descartável e revisar SQL gerado.
8. Separar merge de código, migration e aplicação em ambiente real.

O relatório deve registrar arquivos examinados, convenção de identidade, restrições, plano de busca, consultas observadas, testes executados e pendências. Uma conclusão sem SQL, schema ou teste precisa ser apresentada como hipótese.

Resultado esperado

Uma boa entrega pode ser apenas um diagnóstico. Quando houver mudança, espere um diff rastreável que preserve o contrato público, torne a identidade explícita e mantenha DTOs separados da entidade. A migration correspondente deve ser revisada como artefato próprio.

Para consultas, o resultado esperado é um plano de busca direcionado e uma comparação da quantidade de SQL antes e depois. A documentação de EntityGraph do Spring Data JPA mostra como declarar um fetch graph em métodos de repositório. Isso não elimina a necessidade de verificar paginação, cardinalidade e volume.

Não espere um “modelo perfeito” universal. Entidades com ID natural, ID gerado, composição, herança ou eventos têm decisões diferentes. O resultado precisa combinar a Skill com as convenções do projeto e o comportamento real do ORM.

Permissões, privacidade e riscos

Em modo somente leitura, a Skill precisa acessar código, configuração e testes. Em modo de alteração, pode modificar entidades, repositórios e migrations. Ferramentas do projeto ainda podem executar Gradle, iniciar contêineres, baixar dependências e acessar bancos.

Conexões, URLs e credenciais devem permanecer no ambiente protegido. Não copie .env, senha, token ou dump para o artigo, pacote ou prompt. Use banco sintético quando puder. SQL logs podem conter parâmetros e dados pessoais, então reduza ou masque antes de compartilhar.

Mudanças de igualdade podem afetar coleções, cache e eventos. Mudanças de cascade ou orphanRemoval podem remover registros. Bulk update ignora partes do persistence context. Cada efeito exige teste específico e autorização separada.

Erros comuns

Trocar tudo para EAGER. Isso esconde um sintoma e pode criar consultas maiores. Meça o SQL e use fetch direcionado.

Usar data class porque o DTO já funciona. DTO e entidade têm ciclos de vida diferentes. Separe as responsabilidades.

Usar zero como ID não persistido. Para ID gerado, um valor anulável torna o estado transitório explícito e evita colisões semânticas.

Confiar apenas na consulta de existência. Duas requisições podem passar pelo check ao mesmo tempo. A restrição no banco continua necessária.

Incluir coleção lazy em toString. Log, debugger ou serialização pode disparar consulta fora da transação.

Aplicar migration junto com o diff. Gere, revise, teste e aplique em etapas distintas, com backup e plano de reversão.

Versão, licença e origem verificadas

A curadoria consultou a API oficial do GitHub em 02/09/2026. O repositório registrava 1.029 estrelas, acima do piso editorial de 1.000. Estrelas indicam adoção relativa, não provam segurança, correção ou compatibilidade.

A Skill declara versão 1.0.0 e autor JetBrains no próprio frontmatter. O conteúdo foi fixado no commit 08d7ad0d74a9a5a548287b2bd4926180fab56cac. O caminho auditado é skills/kotlin-backend-jpa-entity-mapping.

A licença é Apache-2.0 e permite redistribuição com preservação dos avisos. O ZIP local contém três arquivos textuais permitidos. SHA-256: 5c85d18b3d51ae95b7556bb46c40f9dd48558a61b78f3ce663f17cde1c321eb3.

Checklist antes de automatizar

• Fixe commit da Skill e versões de Kotlin, JPA, Hibernate e banco.
• Confirme plugins, schema, migrações e convenção de identidade.
• Comece com análise sem edição em uma branch de teste.
• Use classe regular para entidade e mantenha DTO separado.
• Meça consultas antes de diagnosticar N+1.
• Revise SQL, restrições, cascade, orphan removal e concorrência.
• Teste em banco descartável sem credenciais de produção.
• Separe código, migration e aplicação em gates próprios.

Fontes primárias

• Repositório oficial Kotlin Agent Skills.
• SKILL.md fixado no commit auditado.
• Licença Apache-2.0 do repositório.
• Suporte JPA do plugin no-arg.
• Suporte Spring do plugin all-open.
• EntityGraph no Spring Data JPA.
• Jakarta Persistence 3.2.