Entidades finas e composição: o design que escolhi para a nova plataforma

Disclaimer

Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do Dev Eficiente. Se preferir acompanhar por vídeo, é só dar o play.

Introdução

Quando você começa a desenhar as entidades de um sistema novo, é fácil cair no padrão que aprendemos cedo na carreira: uma entidade principal, com seus atributos óbvios, e relacionamentos diretos com outras entidades. Com o tempo, novas necessidades aparecem e essas entidades vão ganhando atributos, estados nulos, exceções e regras contextuais. O resultado costuma ser o mesmo: God Classes, complexidade espalhada e fricção para evoluir.

Neste post, mostro a decisão de design que tomei na nova plataforma onde estou servindo os conteúdos do Dev + Eficiente. Em vez de seguir o caminho clássico de entidades robustas, me inspirei na arquitetura de Content Management Systems como Drupal e WordPress, onde tudo é plugável. O objetivo foi criar entidades muito finas e mover a complexidade para peças de composição reutilizáveis.

O padrão clássico e seu envelhecimento

Pensa numa plataforma de cursos. O caminho mais natural seria modelar algo como:

class Trilha {
    String titulo;
    String descricao;
    Set<Curso> cursos;
}

class Curso {
    String titulo;
    String descricao;
    Trilha trilha;
    Set<Aula> aulas;
    int posicaoNaTrilha;
}

class Aula {
    String titulo;
    String resumo;
    Curso curso;
    List<String> videos;
    List<String> documentosParaDownload;
    List<String> referencias;
    int posicaoNoCurso;
}

Funciona. Eu mesmo já modelei assim várias vezes. O problema aparece com o tempo. Surge a necessidade de uma pessoa responsável pela trilha. Adiciona o atributo, mas só algumas trilhas têm responsável, então o campo precisa ser nullable. Em seguida vem o pedido de que aulas tenham professores ministrantes. Adiciona uma referência para usuário. Aí surge a regra de que cursos podem ter um período de visibilidade. Adiciona uma data de entrada e uma de saída. Para cursos que existem para sempre, alguém faz uma migration com data de mil anos no futuro.

Esse acúmulo acontece regularmente, e não só nas entidades principais. À medida que o contexto evolui, novos atributos e estados se acumulam dentro das classes mais centrais, aumentando o nível de complexidade delas e desviando a atenção de quem precisa entender o domínio.

A inspiração: nós em CMS

Em sistemas como Drupal e WordPress, a necessidade de dinamicidade é extrema. As pessoas querem usar essas ferramentas para construir qualquer tipo de site, com qualquer combinação de plugins. A consequência é que a entidade central é mínima.

No Drupal, por exemplo, você tem a ideia de um nó (ou item). Esse nó tem quase nada: talvez um ID e um título. Se você quer que ele tenha conteúdo, adiciona um campo. Se você quer que ele tenha periodicidade, decora ele com esse estado. É como o padrão Decorator aplicado ao estado da entidade. O código não é nada elegante, mas é extremamente extensível.

Essa foi a primeira referência. Depois pensando, percebi também uma inspiração indireta em tabelas de relacionamento de bancos relacionais. Muitas vezes, quando o sistema cresce, aquela tabela que só ligava duas chaves ganha semântica: um instante em que a associação aconteceu, um tipo de relação, atributos próprios. Ela deixa de ser uma cola e passa a ser uma entidade. Esse foi o ponto de partida para o design.

O design que escolhi

A pergunta que orientou as decisões foi simples: o que de fato é parte essencial dessa entidade, e o que está aqui só por uma necessidade contextual?

Aplicando essa pergunta:

class Trilha {
    String nome;
    String descricao;
}

class Curso {
    String nome;
    String descricao;
}

class Aula {
    String titulo;
    String resumo;
    List<String> videos;
    List<String> textos;
    List<String> referencias;
}

Note o que não está mais ali. A trilha não tem mais cursos. O curso não pertence a uma trilha nem tem aulas. A aula não conhece o curso. E nenhuma das três tem posição, período de visibilidade, comentários ou professor responsável. Esses atributos saem de cena porque não são inerentes a essas entidades: são necessidades de contextos específicos.

Composição via peças orthogonais

A composição passa a ser feita por entidades dedicadas. Olha como ficam alguns conceitos.

Itens de trilha

Em vez da trilha ter uma coleção de cursos, ela passa a ter itens:

class ItemDaTrilha {
    Long id;
    Trilha trilha;
    Long idDoItem;
}

O idDoItem é uma referência fraca. Pode apontar para um curso, pode apontar para uma aula, pode apontar para outra coisa. Eu aceitei essa perda de integridade referencial para ganhar flexibilidade. Em uma linguagem orientada a objetos, dá para extrair uma interface para fazer essa referência polimórfica, semelhante ao que ORMs como Active Record do Rails já suportavam há muito tempo, com uma coluna a mais que indica o tipo do ID referenciado. Só que, neste momento, decidi nÃo ir por esse caminho.

Contexto de ordenação

A posição também sai das entidades. Ela vira parte de um contexto de ordenação:

class ContextoOrdenacao {
    Long id;
    Long idDono;
    String nome;
}

class ItemOrdenavel {
    Long id;
    Long idItem;
    ContextoOrdenacao contexto;
    int posicao;
}

Por que separar assim? Porque a posição não é uma característica do curso. A posição existe porque, em algum momento, eu preciso ordenar uma lista de coisas para exibir. Essa é uma característica do contexto onde estou usando o curso, não do curso em si.

Sem contar que agora eu ganhe capacidade de criar contextos de ordenação para o que eu quiser.

Comentários

Mesma lógica:

class ContextoComentarios {
    String nome;
    String descricao;
    Long idDono;
}

class Comentario {
    ContextoComentarios contexto;
    Usuario autor;
    String texto;
}

O contexto de comentários pode ser aplicado a uma aula, a um curso, a uma trilha como um todo, ou a qualquer outra coisa. Posso ter um contexto de comentários globais no dashboard sem precisar criar um modelo novo.

Períodos de visibilidade

A nova plataforma também importa vagas de um job board. Algumas dessas vagas expiram. Em vez de adicionar campos de início e fim na entidade Vaga, criei uma entidade Periodo que referencia qualquer coisa:

class Periodo {
    LocalDateTime entrada;
    LocalDateTime saida;
    Long idDoItem;
}

A entidade Vaga não foi alterada. A vaga não precisa saber que tem um período. O fluxo que carrega vagas é quem combina os dois.

Como uma trilha é carregada na prática

Para servir os cursos de uma trilha como a Especialização em Engenharia de IA, o fluxo passa a ser:

1. Carrega a trilha
2. Carrega o contexto de ordenação daquela trilha
3. Carrega os itens ordenáveis daquele contexto
4. Para cada item ordenável, usa o idItem para carregar o curso

Já na Jornada Dev + Eficiente, que tem categorias dentro da trilha (Design de Código, Arquitetura, Aprendizagem, e por aí vai), o fluxo ganha mais um nível:

1. Carrega a trilha
2. Carrega o contexto de ordenação de categorias daquela trilha
3. Para cada categoria, carrega o contexto de ordenação interno
4. Para cada contexto interno, carrega os itens ordenáveis
5. Para cada item ordenável, carrega o curso

A modelagem fica como peças de lego. Eu monto a hierarquia que quero, sem precisar mudar nenhuma das entidades base.

A inspiração em programação orientada a aspectos

Depois de implementar, percebi outra referência além do CMS e das tabelas de relacionamento. Há mais de 20 anos, a programação orientada a aspectos virou tema de pesquisa, e o Spring até hoje mantém essa funcionalidade com anotações como @Aspect. A ideia original era separar comportamentos ortogonais ao código de negócio: logging, controle de transação, métricas. Você podia escrever um aspecto que logava todos os métodos de um pacote sem mexer nos métodos em si.

O que fiz aqui é parecido, mas em outra dimensão. Em vez de transformar comportamentos em aspectos, transformei estados. A ordenação virou ortogonal. Os comentários viraram ortogonais. O período de visibilidade virou ortogonal. As entidades em si ficaram mais finas, com menos lógica, e a complexidade se moveu para os pontos de negócio onde acontece a composição.

Trade-offs

Esse design tem ganhos e perdas claras. Vale listar para que você possa avaliar se faz sentido no seu contexto.

Ganhos:

• Entidades base ficam pequenas e estáveis
• Características novas (períodos, comentários, ordenações) podem ser adicionadas a qualquer entidade sem alterar nenhuma delas
• A complexidade fica visível nos fluxos de negócio, em vez de escondida dentro das entidades

Perdas:

• Integridade referencial mais fraca, já que as chaves são genéricas e o banco não consegue garantir consistência
• Mais queries para carregar uma hierarquia completa
• Risco de dados órfãos, que precisam ser tratados na aplicação

O banco de dados é muito mais confiável do que código de aplicação para garantir consistência. Quando você abre mão de parte desse apoio, está aceitando que o sistema vai precisar tratar essas falhas em outro nível. Para o cenário da nova plataforma, esse trade-off me pareceu valer a pena, e é o que estou rodando em produção com as pessoas alunas usando.

Conclusão

Design de código não é sobre encontrar o desenho perfeito. É sobre escolher como o sistema vai envelhecer. Quando você decide praticar uma atividade física, está apostando que ela vai te ajudar a envelhecer melhor. Quando você toma uma decisão de design, está apostando que ela vai fazer o sistema lidar melhor com mudanças que você previu e com mudanças que ainda não previu.

Nessa nova plataforma escolhi entidades muito finas e composição via peças ortogonais inspiradas em CMS, tabelas de relacionamento e programação orientada a aspectos. Aceitei perder integridade referencial e ganhar flexibilidade. Pode ser que daqui a algum tempo eu reveja parte dessas decisões. Por enquanto, está funcionando bem, e a estabilidade das entidades base tem me dado liberdade para evoluir o resto do sistema sem mexer no que já está consolidado.

Dev + Eficiente

Desenvolva software de alta qualidade e domine Engenharia de IA com o Dev + Eficiente. Cursos práticos, acesso vitalício, comunidade ativa e acesso a vagas remotas exclusivas em diversas empresas de tecnologia. Sua jornada para se tornar um dev mais eficiente pode começar agora.