Records em Java: o que são, quando substituem a classe e as pegadinhas com JPA e Jackson
Definido pela documentação da linguagem do Java, o record troca boilerplate por imutabilidade, mas não substitui toda classe: veja o DTO antes e depois e os cuidados com herança, JPA, Jackson e Bean Validation.
Definido pela documentação da linguagem do Java, o record troca boilerplate por imutabilidade, mas não substitui toda classe: veja o DTO antes e depois e os cuidados com herança, JPA, Jackson e Bean Validation.
Ao final deste texto você vai saber quando trocar uma classe DTO por um record, escrever validação dentro do construtor compacto e evitar os três erros mais comuns quando o record aparece numa entidade JPA, numa desserialização Jackson ou numa anotação de Bean Validation. Todo exemplo abaixo compila e roda no JDK 25, a LTS mais recente, com base na definição oficial de record classes da documentação da linguagem.
O que diz a especificação de record classes
A documentação oficial do Java SE 25 remete à JEP 395 como referência de background sobre as record classes, sem detalhar aqui todo o histórico de versões anteriores. A sintaxe usada hoje é a mesma descrita na documentação atual.
Classes record ajudam a modelar agregados de dados simples, com menos cerimônia do que as classes normais.
Record classes... help to model plain data aggregates with less ceremony than normal classes.Java Language Updates, documentação oficial do Java SE 25
Um record de duas linhas:
package com.linhadecodigo.records;
public record Rectangle(double length, double width) {
}Isso gera automaticamente: um campo privado final para cada componente, um método de acesso público homônimo (length(), width(), sem prefixo get), um construtor canônico, equals()/hashCode() baseados nos componentes e um toString() que lista todos os campos pelo nome.
Para testar, com Main.java no mesmo pacote:
package com.linhadecodigo.records;
public class Main {
public static void main(String[] args) {
Rectangle r = new Rectangle(4, 5);
System.out.println("Length: " + r.length() + ", width: " + r.width());
System.out.println(r);
}
}Compile e rode com:
javac com/linhadecodigo/records/Rectangle.java com/linhadecodigo/records/Main.java
java com.linhadecodigo.records.MainA saída esperada é Length: 4.0, width: 5.0 seguida de Rectangle[length=4.0, width=5.0].
O DTO antes e depois
Antes, um DTO imutável exigia algo assim:
import java.util.Objects;
public final class UserDto {
private final String name;
private final String email;
public UserDto(String name, String email) {
this.name = name;
this.email = email;
}
public String getName() { return name; }
public String getEmail() { return email; }
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof UserDto that)) return false;
return Objects.equals(name, that.name) && Objects.equals(email, that.email);
}
@Override
public int hashCode() { return Objects.hash(name, email); }
@Override
public String toString() {
return "UserDto{name='" + name + "', email='" + email + "'}";
}
}Depois, a mesma semântica em uma linha:
public record UserDto(String name, String email) {}Se precisar de validação, o construtor compacto resolve sem repetir a assinatura:
public record UserDto(String name, String email) {
public UserDto {
if (name == null || name.isBlank()) {
throw new IllegalArgumentException("name não pode ser vazio");
}
}
}O que um record não faz
Herança não existe. Um record é implicitamente final e estende, por baixo dos panos, apenas java.lang.Record. Não dá para declarar record B extends A, e ninguém pode estender o seu record depois. Ele pode implementar interfaces normalmente, o que o torna uma combinação natural com sealed interface e switch com pattern matching, mas não serve para reaproveitar campos via hierarquia de classes.
Campo mutável também não. Um record só pode declarar os campos que aparecem no cabeçalho; não existe bloco de inicialização de instância nem campo de instância extra, só static. A pegadinha aparece quando um componente é, ele mesmo, mutável: a referência é final, mas o conteúdo não é protegido:
public record Team(String name, List<String> members) {
public Team {
members = List.copyOf(members); // sem isso, quem chamou o construtor ainda pode mutar a lista original
}
}Sem a cópia defensiva no construtor compacto, new Team("A", listaMutavel) deixa listaMutavel.add(...) alterar o estado do record depois de criado, quebrando a promessa de imutabilidade.
Onde o record exige cuidado
Nota da redação: as afirmações desta seção sobre o comportamento de JPA, Jackson e Bean Validation refletem práticas comuns no ecossistema Java, mas não foram conferidas aqui contra a documentação oficial de cada projeto (especificação Jakarta Persistence, jackson-databind, Jakarta Validation/Hibernate Validator). Confirme na versão que você usa antes de aplicar em produção.
JPA: record não vira entidade
Na prática, um record não costuma funcionar como @Entity: ele é final, não tem construtor sem argumentos por padrão e não pode ser subclassificado, características da linguagem confirmadas na seção anterior que tendem a colidir com o modelo de entidade usado pelas implementações mais comuns de Jakarta Persistence, que costumam exigir um construtor vazio e a possibilidade de proxy para lazy loading. Por isso não é comum ver @Entity aplicado diretamente a um record: a incompatibilidade nasce da própria natureza do record, não de uma limitação pontual de uma implementação específica.
Uma prática comum em projetos que usam JPA é reservar o record para a projeção de DTO, não para a entidade:
public record UserSummaryDto(String name, String email) {}public interface UserRepository extends JpaRepository<User, Long> {
@Query("select new com.example.dto.UserSummaryDto(u.name, u.email) from User u where u.active = true")
List<UserSummaryDto> findActiveSummaries();
}Jackson: a desserialização quebra sem -parameters
Em versões recentes, o jackson-databind costuma conseguir desserializar JSON direto para um record, casando as propriedades do JSON com os parâmetros do construtor canônico pelo nome. O problema é que o javac não grava nomes de parâmetro no bytecode por padrão: é preciso habilitar a flag -parameters.
No Maven, no pom.xml:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<parameters>true</parameters>
</configuration>
</plugin>Sem essa configuração, objectMapper.readValue(json, UserDto.class) tende a falhar ao tentar instanciar o record, porque o Jackson não consegue associar os parâmetros do construtor aos campos do JSON sem os nomes disponíveis em tempo de execução. Quem não quer mexer no build pode anotar o construtor canônico explicitamente, repetindo a assinatura inteira (o construtor compacto não permite anotar parâmetro a parâmetro):
public record UserDto(String name, String email) {
@JsonCreator
public UserDto(@JsonProperty("name") String name, @JsonProperty("email") String email) {
this.name = name;
this.email = email;
}
}Bean Validation: a anotação vai no componente, mas depende do @Target
As anotações do jakarta.validation.constraints vão direto no componente do record:
public record CreateUserRequest(
@NotBlank String name,
@Email String email) {
}A documentação da linguagem explica a regra por trás disso: uma anotação colocada no componente só é propagada para o campo gerado se o @Target dela incluir ElementType.FIELD. Anotações do Bean Validation como @NotBlank e @Email costumam declarar FIELD entre seus alvos, mas vale conferir o @Target de cada anotação na versão da biblioteca que você usa antes de assumir que ela funciona sem ajuste extra no seu projeto.
Um detalhe que pega gente desavisada: se a validação estiver dentro do construtor compacto, lançando IllegalArgumentException, ela tende a rodar no instante em que o objeto é montado, antes mesmo do Bean Validation entrar em ação. Isso pode significar que o tipo de erro lançado é diferente do que o Bean Validation costuma produzir, então vale tratar os dois casos com atenção se você quiser uma resposta HTTP consistente.
Próximo passo
Para ir além do que cabe aqui, vale olhar a JEP 395 original (Record Classes), a seção de requisitos de entidade da especificação Jakarta Persistence, a documentação do jackson-databind sobre suporte a records e o guia do Hibernate Validator sobre validação de record. São as quatro fontes que decidem, na prática, se o seu record vira DTO de verdade ou vira exceção em produção.
Fonte: Oracle: Record Classes (Java Language Updates, Java SE 25)
Este artigo foi escrito por Marcelo Teixeira. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.
Editor virtual de Java do Linha de Código. Cobre Java moderno (records, pattern matching, virtual threads), Spring Boot, JPA e Hibernate, Maven e Gradle, e o Kotlin quando ele conversa com a JVM. Escreve para quem mantém o monólito da empresa e para quem está aprendendo a primeira linguagem tipada, sempre declarando a versão do JDK e do framework.