AopUtils.getTargetClass() — desembrulhando os proxies do Spring

No Spring, anotações como @Transactional, @Async, @Cacheable e @PreAuthorize só funcionam porque o container troca o bean original por um proxy: um objeto gerado em tempo de execução que intercepta as chamadas, executa a lógica extra e repassa a chamada ao objeto real (o modelo completo está no post AOP no Spring — JDK Dynamic Proxy, CGLIB e aspects custom). O efeito colateral é que bean.getClass() deixa de retornar a sua classe e passa a retornar a classe do proxy.

Neste post você vai ver por que isso quebra reflection, logs e mapas indexados por classe, como AopUtils.getTargetClass(bean) recupera a classe real e quando é preciso recorrer a AopProxyUtils.ultimateTargetClass().

O que o AOP faz pelo seu código, na prática#

Sem AOP, as preocupações transversais (transação, segurança, métricas, que não fazem parte da regra de negócio) se espalham pelo método. Em um esboço simplificado:

public Pedido criar(Pedido p) {
    long inicio = System.currentTimeMillis();
    tx.begin();
    try {
        if (!user.hasRole("ADMIN")) throw new AccessDenied();
        log.info("criando pedido {}", p);
        var salvo = repo.save(p);
        tx.commit();
        return salvo;
    } catch (Exception e) {
        tx.rollback();
        throw e;
    } finally {
        metrics.record("criar", System.currentTimeMillis() - inicio);
    }
}

Com AOP, o método volta a falar só de negócio:

@Transactional
@PreAuthorize("hasRole('ADMIN')")
@Timed("criar") // Micrometer; exige o TimedAspect registrado
public Pedido criar(Pedido p) {
    log.info("criando pedido {}", p);
    return repo.save(p);
}

Cada anotação é atendida por um interceptor (o advice) que o container aplica ao bean. É exatamente por isso que o objeto injetado não é uma instância da sua classe: é o proxy que executa esses interceptores antes de chamar o seu código.

O problema: bean.getClass() devolve a classe do proxy#

O Spring gera o proxy de duas formas:

• JDK Dynamic Proxy: uma classe criada pela JVM que implementa as interfaces do bean. É o padrão do Spring Framework quando o bean implementa ao menos uma interface.
• CGLIB: uma subclasse da sua classe gerada em tempo de execução. É usada quando o bean não implementa interfaces e é o padrão no Spring Boot (spring.aop.proxy-target-class=true).

Por isso getClass() devolve algo assim:

br.com.exemplo.MeuServico$$SpringCGLIB$$0   // CGLIB: subclasse de MeuServico
jdk.proxy2.$Proxy42                         // JDK: pacote e número variam

Desde o Spring Framework 6.0, o nome das classes CGLIB usa o marcador $$SpringCGLIB$$ seguido de um contador (antes era um hash). No proxy JDK, a especificação só reserva o prefixo $Proxy; o nome do pacote não é especificado.

Isso quebra qualquer código que dependa da identidade da classe real:

• Leitura de anotações via reflection. A subclasse CGLIB só enxerga as anotações de classe marcadas com @Inherited (como @Transactional). Anotações sem @Inherited, como uma anotação sua, não aparecem, e as anotações de método também não, porque o proxy sobrescreve os métodos sem copiá-las. O proxy JDK não enxerga nenhuma anotação da classe alvo.
• Logging com getClass().getSimpleName(): o log mostra MeuServico$$SpringCGLIB$$0 ou $Proxy42 no lugar de MeuServico.
• Mapas do tipo Map<Class<?>, Handler>: handlers.get(bean.getClass()) não encontra a entrada registrada com MeuServico.class.
• Código de infraestrutura que descobre metadados pela classe, como um BeanPostProcessor próprio ou um registro de listeners: sofre dos mesmos problemas.

O diagrama resume a diferença: o proxy envolve o objeto real; getClass() para na camada de fora, e getTargetClass() atravessa essa camada e devolve a classe que você escreveu.

O utilitário: AopUtils.getTargetClass(Object)#

Fica no pacote org.springframework.aop.support:

public static Class<?> getTargetClass(Object candidate)

Segundo o Javadoc, o método determina a classe alvo de um bean que pode ser um proxy AOP: devolve a classe alvo quando é proxy e a própria classe do objeto nos demais casos, nunca null.

Como ele chega lá (código do Spring Framework 7.0.9):

1. Se o objeto implementa TargetClassAware, pergunta a ele qual é a classe alvo. Todo proxy Spring AOP implementa essa interface por meio de Advised, a menos que tenha sido criado com a opção opaque.
2. Se não obteve resposta, usa a superclasse quando o objeto é um proxy CGLIB e getClass() nos demais casos.

Na prática:

• Se o bean não é proxy, retorna bean.getClass().
• Se é proxy CGLIB ou JDK, retorna a classe do objeto real que o proxy envolve.
• Se é um proxy de proxy, desce apenas um nível e retorna a classe do proxy interno (por exemplo, MeuServico$$SpringCGLIB$$0). Para chegar ao fundo, use AopProxyUtils.ultimateTargetClass(), descrito mais abaixo.
• Nunca retorna null, garantia da API.

Exemplo prático#

Como MeuServico não implementa interface, o Spring cria um proxy CGLIB por causa do @Transactional. A anotação @Auditavel foi criada sem @Inherited para mostrar a diferença:

import org.springframework.aop.support.AopUtils;
import org.springframework.transaction.annotation.Transactional;
// demais imports omitidos

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Auditavel {} // sem @Inherited

@Service
@Auditavel
public class MeuServico {
    @Transactional
    public void processar() { /* ... */ }
}

@Component
public class Inspetor {
    public void inspecionar(Object bean) throws NoSuchMethodException {
        System.out.println(bean.getClass().getName());
        // br.com.exemplo.MeuServico$$SpringCGLIB$$0

        Class<?> alvo = AopUtils.getTargetClass(bean);
        System.out.println(alvo.getName());
        // br.com.exemplo.MeuServico

        // Anotação de classe sem @Inherited
        bean.getClass().isAnnotationPresent(Auditavel.class); // false
        alvo.isAnnotationPresent(Auditavel.class);            // true

        // Anotação de método
        bean.getClass().getMethod("processar")
                .isAnnotationPresent(Transactional.class);    // false
        alvo.getMethod("processar")
                .isAnnotationPresent(Transactional.class);    // true
    }
}

Use a classe alvo só para ler metadados. Para chamar métodos, continue usando o próprio bean: é o proxy que aplica a transação, o cache e a segurança.

Métodos relacionados#

O próprio AopUtils tem três métodos para descobrir que tipo de objeto você recebeu. Todos verificam também se o objeto implementa SpringProxy, ou seja, respondem true só para proxies criados pelo Spring AOP:

• isAopProxy(Object): true se o objeto é um proxy Spring AOP, JDK ou CGLIB.
• isCglibProxy(Object): true se é um proxy CGLIB.
• isJdkDynamicProxy(Object): true se é um JDK Dynamic Proxy.

Em outras classes utilitárias:

• AopProxyUtils.ultimateTargetClass(Object) (pacote org.springframework.aop.framework): desce por qualquer número de proxies aninhados até a classe final. Só atravessa um nível quando consegue fazer isso sem efeitos colaterais, isto é, quando o alvo é um singleton guardado em um SingletonTargetSource (o TargetSource é o componente que entrega ao proxy o objeto real). Com outros TargetSources (lazy, pool, protótipo, hot swap), para naquele nível e devolve a classe informada por ele. Também nunca retorna null.
• ClassUtils.getUserClass(Object) (pacote org.springframework.util): devolve a classe original quando a classe do objeto é uma subclasse gerada pelo CGLIB (nome com $$). Não reconhece proxy JDK, que continua como $Proxy42. Tem também a versão getUserClass(Class<?>), útil quando você só tem a classe em mãos.

O diagrama abaixo mostra a diferença em um proxy JDK que envolve um proxy CGLIB:

Resumo do comportamento, conferido no Spring Framework 7.0.9:

Regra prática#

Sempre que for inspecionar um bean Spring por reflection (ler anotações, comparar tipos, registrar em mapa por classe, logar um nome legível), use AopUtils.getTargetClass(bean) em vez de bean.getClass(). Se o bean puder estar envolvido por mais de um proxy, prefira AopProxyUtils.ultimateTargetClass(bean). Não custa nada e evita bugs que só aparecem meses depois, quando alguém adiciona um @Transactional ao serviço e o proxy passa a existir.

Fontes#

• Spring Framework Reference — Proxying Mechanisms
• Spring Framework Reference — AOP Proxies
• Javadoc — AopUtils
• Javadoc — AopProxyUtils
• Javadoc — ClassUtils
• Javadoc — TargetClassAware
• Javadoc — Transactional (declarada com @Inherited)
• Código-fonte do Spring Framework 7.0.9 — AopUtils.java, AopProxyUtils.java e SpringNamingPolicy.java
• Spring Boot — Common Application Properties (spring.aop.proxy-target-class)
• Java SE 21 API — java.lang.reflect.Proxy e java.lang.annotation.Inherited
• Micrometer — Timers (@Timed e TimedAspect)