Seu diagrama de arquitetura indica que os controladores nunca acessam o repositório diretamente. Seu código-fonte discorda.

Acontece silenciosamente. Alguém está com pressa, injeta uma CourseRepositorylinha direta em um controlador para pular um método de serviço, e o pull request é aprovado porque os testes passam e a alteração é pequena. O diagrama na wiki ainda mostra um fluxo limpo de três camadas. O código já não corresponde a ele. Seis meses e quarenta atalhos depois, a “arquitetura em camadas” é uma sugestão, e ninguém consegue dizer quais regras ainda são válidas.

A organização em camadas é apenas uma das formas que esse problema assume. Se você organizar seu código por pacote, por funcionalidade, em vez de por camada, a mesma erosão ocorre nas fronteiras entre funcionalidades: o pacote de infraestrutura compartilhada começa a importar classes de funcionalidades, os controladores começam a retornar entidades JPA em vez de DTOs, e o que deveria ser um conjunto de limites claros se transforma silenciosamente em uma confusão. A boa notícia é que a mesma ferramenta resolve todos esses problemas, e você não precisa de pacotes de camadas para impor regras de camadas.

O teste de arquitetura é a forma de preencher essa lacuna. Em vez de documentar suas regras em um diagrama que ninguém lê, você as codifica como testes executáveis ​​que falham na compilação no momento em que alguém as viola. A regra deixa de ser uma convenção que as pessoas devem memorizar e se torna um sensor que é executado a cada commit.

Antes de prosseguirmos, é importante fazer a seguinte distinção, que se conecta aos meus posts anteriores sobre engenharia de harnesses e testes de mutação com PIT : ArchUnit não é uma nova categoria de teste que você adiciona como um complemento. É uma função de aptidão , um sensor de feedback computacional que observa sua base de código e informa se ela ainda respeita a estrutura que você projetou. Enquanto o PIT protege o comportamento do seu código, o ArchUnit protege sua forma.

O ArchUnit é a biblioteca de testes de arquitetura mais utilizada para a JVM. Ele funciona como testes JUnit comuns, não precisa de um executor específico e lê as classes compiladas para inferir sobre pacotes, dependências e nomenclatura. Este artigo mostra como configurar o ArchUnit em um projeto Spring Boot com Maven e JUnit 5, escrever regras que realmente se mostram úteis, adotá-lo em um código legado sem se afogar em violações e executá-lo em CI.

Quer o código? Todas as regras deste post vêm de um projeto real, a API Spring Boot do meu exemplo CRUD full-stack: loiane/crud-angular-spring

Neste post, abordaremos:

• Por que os diagramas de arquitetura se deterioram e quais medidas de teste de arquitetura utilizam esse recurso.
• Como o ArchUnit lê seu bytecode para entender a estrutura
• Configurando o ArchUnit em um projeto Spring Boot + Maven + JUnit 5 (incluindo a pegadinha do Surefire que ignora silenciosamente todas as regras)
• As categorias de regras que abrangem a maioria das necessidades reais são: camadas, dependências, nomenclatura, ciclos e disciplina DTO.
• Impor regras de camada em uma base de código com estrutura de pacote por recurso, onde não há pacotes de camada para apontar.
• O fato de o mesmo agente de IA redigir ambos os lados de um contrato é exatamente o problema que o ArchUnit identifica.
• Ao ler os resultados, incluindo o relatório HTML que mostra exatamente o que uma regra detectou, é importante analisar o caso.
• Adotando o ArchUnit em uma base de código legada com freeze, o portão unidirecional que o mantém honesto
• Executando testes de arquitetura no GitHub Actions como parte do processo de compilação normal.

Por que os diagramas de arquitetura se deterioram

Um diagrama responde a uma pergunta: qual era a nossa intenção com a estrutura? Mas nunca responde à pergunta que realmente importa no sexto mês: qual é a estrutura neste momento?

A lacuna é estrutural, não acidental. Um diagrama é um instantâneo tirado durante a fase de projeto. O código muda todos os dias. Nada conecta os dois, então eles se distanciam no momento em que o primeiro atalho é implementado. O diagrama é uma orientação preditiva sem nenhum sensor de feedback acoplado, e orientação sem sensor é apenas uma esperança.

Considere uma regra de camadas padrão do Spring Boot: controladores dependem de serviços, serviços dependem de repositórios e nada se propaga para trás. A regra diz que um controlador deve chamar um serviço, nunca um repositório diretamente. Aqui está o atalho que a quebra, e nada no compilador ou no conjunto de testes o impede:

@RestController
public class CourseController {

    private final CourseRepository repository;

    public CourseController(CourseRepository repository) {
        this.repository = repository;
    }
}

Isso compila. Os testes unitários passam. A revisão de código pode detectar o problema, caso o revisor conheça a regra e esteja prestando atenção em uma tarde de sexta-feira. Os testes de arquitetura o detectam sempre, de forma determinística, antes da mesclagem.

A ideia formal vem da arquitetura evolutiva: uma função de aptidão de arquitetura é uma verificação objetiva e automatizada de que uma determinada característica arquitetural ainda se mantém. Uma regra de camadas expressa como um teste ArchUnit é uma função de aptidão. Ela converte uma regra que você espera que as pessoas sigam em uma regra que a compilação impõe .

Como funciona o ArchUnit

O ArchUnit importa suas classes compiladas e constrói um modelo em memória da sua base de código: classes, pacotes, métodos, campos e as dependências entre eles. Em seguida, você escreve regras com base nesse modelo usando uma API fluente, e cada regra é executada como um teste JUnit normal.

Não há reescrita de bytecode nem um executor separado. O ArchUnit lê os .classarquivos no classpath de teste, portanto, vê exatamente o que o compilador produziu, incluindo dependências que você não escreveu explicitamente. Como é apenas o JUnit, uma violação de arquitetura aparece como um teste com falha no mesmo relatório que todos os outros.

Três coisas que vale a pena internalizar de antemão:

Ao contrário dos testes de mutação, a análise de arquitetura é barata. Importar alguns milhares de classes e avaliar um punhado de regras leva um ou dois segundos. Esse simples fato altera a localização do sensor: o PIT deve ser executado por trás de um perfil Maven lento, mas o ArchUnit é rápido o suficiente para ser executado na mvn testfase normal de cada build. Mais detalhes sobre isso na seção de CI.

Configurando o ArchUnit em um projeto Spring Boot

O Projeto de Exemplo

O exemplo é a API Spring Boot de loiane/crud-angular-spring , a aplicação CRUD completa que utilizo neste blog e nos meus vídeos. O backend reside na crud-springpasta e, propositadamente, não está organizado por camadas (pacotes). Está organizado por funcionalidade: tudo relacionado aos cursos reside em um único pacote, com a infraestrutura compartilhada mantida separada.

crud-spring/src/
  main/java/com/loiane/
    course/                   the feature package
      Course.java  Lesson.java
      CourseController.java  CourseService.java  CourseRepository.java
      dto/         (records + MapStruct-style mapper)
      enums/       (Category, Status + JPA converters)
    exception/                business exceptions
    shared/                   controller advice, custom validators
  test/java/com/loiane/
    architecture/
      ArchitectureTest.java   every rule in this post

Essa estrutura é importante para este post. A maioria dos tutoriais do ArchUnit pressupõe a existência de pacotes ..controller.., como `package.json` ..service.., `package.json` e ..repository..`package.json`, nos quais você pode definir regras. Bases de código reais, organizadas por pacote e recurso, não possuem esses pacotes, e as regras abaixo mostram como impor a mesma organização em camadas com predicados de classe — nomes e anotações — em vez de nomes de pacotes. Se o seu projeto for organizado por pacote e camada, as mesmas regras se tornam mais simples, não mais complexas.

Pré-requisitos

• Java 25. O ArchUnit lê arquivos de classe padrão e acompanha as versões recentes do JDK.
• Maven 3.9+ (o repositório funciona com uma instalação padrão do Maven; mvn -f crud-spring/pom.xml testexecuta tudo).
• O projeto é executado no Spring Boot 4.1 com JUnit 5 sendo implementado transitivamente através do spring-boot-starter-teststarter. As regras são idênticas no Spring Boot 3.x; apenas os nomes dos starters diferem.

A única dependência

Adicione a versão JUnit 5 do ArchUnit como uma dependência de teste. Ela inclui a biblioteca principal, além da @AnalyzeClassesintegração @ArchTest.

<dependency>
  <groupId>com.tngtech.archunit</groupId>
  <artifactId>archunit-junit5</artifactId>
  <version>1.4.1</version>
  <scope>test</scope>
</dependency>

Essa é toda a configuração. Não há plugin, perfil ou objetivo separado. Os testes de arquitetura são testes JUnit comuns, então mvn testjá estão sendo executados.

Sua primeira regra

Crie uma classe de teste anotada com `@Request` @AnalyzeClassespara declarar os pacotes a serem importados e, em seguida, expresse as regras como staticcampos anotados com `@Request` @ArchTest. O ArchUnit importa as classes uma única vez e avalia cada @ArchTestcampo em relação a esse modelo.

package com.loiane.architecture;

import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

@AnalyzeClasses(packages = "com.loiane", importOptions = ImportOption.DoNotIncludeTests.class)
class ArchitectureTest {

    @ArchTest
    static final ArchRule servicesShouldNotDependOnControllers = noClasses()
            .that().haveSimpleNameEndingWith("Service")
            .should().dependOnClassesThat().haveSimpleNameEndingWith("Controller");
}

Se um serviço importar um controlador, este teste falhará com uma mensagem que especifica a classe exata e a dependência exata. A DoNotIncludeTestsopção de importação mantém suas classes de teste fora da análise, de modo que um auxiliar de teste que acessa várias camadas não produza falsos positivos.

A pegadinha infalível

Existe uma armadilha de configuração que pode te fazer pensar que tudo funciona quando, na verdade, nada funciona. O Surefire 3.5.3 falha ao executar @ArchTestregras declaradas como campos ( TNG/ArchUnit#1442 ). Regras declaradas como métodos ainda são executadas, mas campos são o estilo idiomático e todas as regras neste post os utilizam. Sua mvn testexecução permanece verde, mas o relatório indica que Tests run: 0, para cada classe de teste de arquitetura, as regras nunca são executadas e, portanto, nunca detectam nada.

Este é o equivalente em ArchUnit ao problema de ausência de asserção silenciosa: uma compilação que é aprovada justamente porque não verifica nada. Se a sua versão do Spring Boot gerencia uma versão afetada do Surefire, fixe-a em uma versão comprovadamente estável até que a regressão seja resolvida.

<properties>
  <!-- Surefire 3.5.3 silently reports "Tests run: 0" for @ArchTest fields -->
  <maven-surefire-plugin.version>3.5.2</maven-surefire-plugin.version>
</properties>

O sinal é sempre o mesmo: se adicionar uma regra que você sabe que está sendo violada ainda produzir uma compilação verde com zero testes, o Surefire não está executando suas regras do ArchUnit. Verifique a Tests runcontagem, não apenas a cor da compilação.

As categorias de regras que justificam sua permanência.

O ArchUnit pode expressar quase qualquer regra estrutural, mas, na prática, algumas categorias abrangem a grande maioria do que um código-fonte Spring Boot precisa: dependências de camadas, regras de limites, convenções de nomenclatura e anotações, disciplina de DTO, ciclos e higiene geral. Cada regra abaixo está ativa no crud-angular-springArchitectureTest e é executada em todas as compilações. Comece por aqui.

Dependências de camadas sem pacotes de camadas

O contrato central de camadas tem duas partes: as camadas inferiores nunca dependem das camadas superiores, e os repositórios só são acessíveis a partir de serviços. Em uma base de código com estrutura de pacotes por funcionalidade, ambas as partes são expressas por meio de predicados de nomenclatura.

@ArchTest
static final ArchRule repositoriesShouldNotDependOnServicesOrControllers = noClasses()
        .that().haveSimpleNameEndingWith("Repository")
        .should().dependOnClassesThat().haveSimpleNameEndingWith("Service")
        .orShould().dependOnClassesThat().haveSimpleNameEndingWith("Controller");

@ArchTest
static final ArchRule repositoriesOnlyAccessedByServices = classes()
        .that().haveSimpleNameEndingWith("Repository")
        .should().onlyBeAccessed().byClassesThat().haveSimpleNameEndingWith("Service")
        .orShould().onlyBeAccessed().byClassesThat().haveSimpleNameEndingWith("Repository");

A segunda regra é a que elimina o atalho da introdução. No momento CourseControllerem que um parâmetro é CourseRepositoryinjetado, a regra falha e nomeia o parâmetro do construtor, o campo e todos os locais de chamada.

Se o seu projeto utiliza pacotes de camadas (o layout clássico `<layer>` controller, service` repository<layer>`, `<layer>`), a API integrada do ArchUnit layeredArchitecture()expressa todo o contrato em uma única declaração:

@AnalyzeClasses(
    packages = "com.example.app",
    importOptions = ImportOption.DoNotIncludeTests.class
)
class LayeredArchitectureTest {

    @ArchTest
    static final ArchRule layer_dependencies_are_respected = layeredArchitecture()
        .consideringAllDependencies()
        .layer("Controller").definedBy("..controller..")
        .layer("Service").definedBy("..service..")
        .layer("Repository").definedBy("..repository..")
        .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
        .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")
        .whereLayer("Repository").mayOnlyBeAccessedByLayers("Service");
}

Este é o mesmo sensor, apenas com um predicado diferente. A layeredArchitecture()API lê o contrato quase como prosa, e uma violação reporta tanto a classe infratora quanto a regra da camada que ela violou. Para uma base de código com estrutura de pacotes por funcionalidade como esta crud-angular-spring, não há pacotes de camada para apontar, então a abordagem de predicado de nomenclatura acima é a mais adequada — mas ambas expressam a mesma intenção arquitetural.

Regras de Limite: Código Compartilhado Permanece Genérico

O modelo de pacote por funcionalidade traz consigo seu próprio contrato de limites: a infraestrutura compartilhada pode ser usada pelas funcionalidades, mas nunca deve depender delas . No dia em que uma funcionalidade sharedimporta uma courseclasse, ela deixa de ser compartilhada e se torna um apêndice oculto de uma única funcionalidade.

@ArchTest
static final ArchRule sharedShouldNotDependOnFeatures = noClasses()
        .that().resideInAPackage("com.loiane.shared..")
        .should().dependOnClassesThat().resideInAPackage("com.loiane.course..");

@ArchTest
static final ArchRule controllersAreAnnotatedAndPlacedCorrectly = classes()
        .that().haveSimpleNameEndingWith("Controller")
        .and().resideOutsideOfPackage("com.loiane.shared..")
        .should().beAnnotatedWith(RestController.class)
        .andShould().resideInAPackage("com.loiane.course..");

@ArchTest
static final ArchRule servicesAreAnnotatedWithService = classes()
        .that().haveSimpleNameEndingWith("Service")
        .should().beAnnotatedWith(Service.class);

@ArchTest
static final ArchRule repositoriesAreSpringDataInterfaces = classes()
        .that().haveSimpleNameEndingWith("Repository")
        .should().beInterfaces()
        .andShould().beAssignableTo(Repository.class);

@ArchTest
static final ArchRule controllersDoNotExposeEntities = noMethods()
        .that().areDeclaredInClassesThat().areAnnotatedWith(RestController.class)
        .and().arePublic()
        .should().haveRawReturnType(Course.class)
        .orShould().haveRawReturnType(Lesson.class)
        .orShould().haveRawParameterTypes(Course.class)
        .orShould().haveRawParameterTypes(Lesson.class);

@ArchTest
static final ArchRule noPackageCycles = slices()
        .matching("com.loiane.(*)..")
        .should().beFreeOfCycles();

@ArchTest
static final ArchRule noFieldInjection = fields()
        .should().notBeAnnotatedWith(Autowired.class)
        .because("constructor injection is required");

@ArchTest
static final ArchRule noJavaUtilLogging = noClasses()
        .should().dependOnClassesThat().resideInAPackage("java.util.logging..");

mvn -Dmaven.test.failure.ignore=true surefire-report:report

import static com.tngtech.archunit.library.freeze.FreezingArchRule.freeze;

@ArchTest
static final ArchRule repositoriesOnlyAccessedByServices = freeze(
    classes()
        .that().haveSimpleNameEndingWith("Repository")
        .should().onlyBeAccessed().byClassesThat().haveSimpleNameEndingWith("Service")
        .orShould().onlyBeAccessed().byClassesThat().haveSimpleNameEndingWith("Repository")
);

# src/test/resources/archunit.properties
freeze.store.default.allowStoreCreation=true

architecture-java:
  name: Maven Architecture Tests (ArchUnit)
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v7
    - name: Set up JDK 25
      uses: actions/setup-java@v5
      with:
        java-version: '25'
        distribution: 'temurin'
        cache: maven
    - name: Run ArchUnit tests
      run: mvn -B test -Dtest=ArchitectureTest --file crud-spring/pom.xml