giuseppe-trisciuoglio/clean-architecture

O que clean-architecture faz?

Fornece padrões de implementação para Clean Architecture, Arquitetura Hexagonal (Ports & Adapters) e Domain-Driven Design em aplicações Java 21+ Spring Boot 3.5+. Use ao estruturar arquiteturas em camadas, separar lógica de domínio de frameworks, implementar portas e adaptadores, criar entidades/objetos de valor/agregados ou refatorar bases de código monolíticas para testabilidade e manutenibilidade.

Visão Geral

Este skill ajuda a estruturar aplicações seguindo princípios de Clean Architecture e Arquitetura Hexagonal, com foco em:

• Separação de Responsabilidades: Domínio puro, independente de detalhes de infraestrutura (banco de dados, APIs, frameworks).
• Testabilidade: A lógica de negócios pode ser testada sem dependências externas.
• Manutenibilidade: Baixo acoplamento entre camadas, facilitando evolução e substituição de componentes.
• Aderência ao DDD: Uso de Entidades, Objetos de Valor, Agregados, Repositórios e Serviços de Domínio.

Plataformas Compatíveis

• Claude Code
• Cursor
• Codex
• Qualquer assistente de IA que leia arquivos SKILL.md

Como Usar

1. Inclua este skill no seu projeto (SKILL.md).
2. Ao descrever a arquitetura, mencione "Clean Architecture" ou "Hexagonal" para ativar as sugestões.
3. O assistente fornecerá trechos de código Java 21+ com records, sealed classes e padrões modernos.

Estrutura de Pacotes Recomendada

src/main/java/com/exemplo/aplicacao/
├── domain/          # Entidades, Objetos de Valor, Agregados, Serviços de Domínio, Repositórios (interfaces)
│   ├── model/
│   ├── service/
│   └── repository/
├── application/     # Casos de Uso (Serviços de Aplicação), DTOs, Portas de Entrada/Saída
│   ├── port/
│   │   ├── inbound/
│   │   └── outbound/
│   └── service/
└── infrastructure/  # Adaptadores (implementações de portas), configurações Spring, JPA, REST controllers
    ├── adapter/
    │   ├── inbound/
    │   └── outbound/
    └── config/

Exemplo: Entidade e Objeto de Valor (Java 21+ records)

// Objeto de Valor imutável
public record Email(String endereco) {
    public Email {
        if (!endereco.matches("^[A-Za-z0-9+_.-]+@(.+)$")) {
            throw new IllegalArgumentException("Email inválido");
        }
    }
}

// Entidade com identidade
public class Usuario {
    private final UsuarioId id;
    private String nome;
    private Email email;

    public Usuario(UsuarioId id, String nome, Email email) {
        this.id = id;
        this.nome = nome;
        this.email = email;
    }

    // Getters e métodos de domínio
}

// Agregado
public class Pedido {
    private final PedidoId id;
    private final List<ItemPedido> itens;
    private StatusPedido status;

    public void adicionarItem(ItemPedido item) {
        // lógica de negócio
    }
}

Exemplo: Porta e Adaptador

// Porta (Contrato) - no domínio ou aplicação
public interface RepositorioUsuario {
    Optional<Usuario> buscarPorId(UsuarioId id);
    void salvar(Usuario usuario);
}

// Adaptador (Implementação) - na infraestrutura
@Component
public class RepositorioUsuarioJpa implements RepositorioUsuario {
    private final UsuarioJpaRepository jpaRepository;

    public RepositorioUsuarioJpa(UsuarioJpaRepository jpaRepository) {
        this.jpaRepository = jpaRepository;
    }

    @Override
    public Optional<Usuario> buscarPorId(UsuarioId id) {
        return jpaRepository.findById(id.valor())
                .map(this::paraDominio);
    }

    @Override
    public void salvar(Usuario usuario) {
        jpaRepository.save(paraJpa(usuario));
    }
}

Dicas de Refatoração

• Identifique classes com muitas dependências de infraestrutura (ex: acesso a banco, chamadas HTTP).
• Extraia interfaces (portas) para essas dependências.
• Mova a implementação para a camada de infraestrutura.
• Injete as portas nos casos de uso via construtor (inversão de controle).
• Teste o domínio com mocks das portas.

Referências

• Clean Architecture: A Craftsman's Guide by Robert C. Martin
• Domain-Driven Design: Tackling Complexity in the Heart of Software by Eric Evans
• Spring Boot Documentation

Licença

Este skill é fornecido como referência gratuita. Sinta-se à vontade para adaptar aos seus projetos.