Use JFoundry
Propósito
Use esta skill para construir aplicações de negócio no jfoundry sem se desviar da arquitetura pretendida pelo framework. É para projetos de aplicação, não para alterar os internos do framework jfoundry.
Use como padrão um novo projeto Java 21 Maven usando Arquitetura Hexagonal, a menos que o usuário escolha explicitamente Onion. Não defina o Spring Boot como runtime padrão; escolha Spring apenas quando o usuário selecionar Spring Framework, Spring Boot ou um starter específico do Spring. Prefira copiar os templates empacotados primeiro, depois adaptar nomes e pacotes.
Fluxo de Primeiro Uso
- Identifique a forma do projeto: módulo de aplicação único, aplicação Maven multi-módulo ou módulos separados de domínio/aplicação/infraestrutura. Prefira multi-módulo Maven para projetos DDD comuns.
- Escolha um estilo primário de arquitetura. Prefira Hexagonal para novos projetos de negócio; escolha Onion apenas quando o usuário solicitar ou o código já o utilizar. Não misture Hexagonal e Onion no mesmo escopo de análise ArchUnit.
- Leia
references/dependencies.md, escolha o BOM pelo runtime e copie os trechos de template Maven correspondentes deassets/templates/maven/. - Leia
references/architecture.mde copie a estrutura de pacotes correspondente deassets/templates/structure/. - Copie um template de teste de arquitetura de
assets/templates/java/, substituaPACKAGE_NAMEe adicione-o sob o conjunto de fontes de teste do projeto de negócio. - Leia
references/repository-and-ports.mdantes de criar repositórios de agregados, portas do lado de leitura, portas de consulta, portas de pesquisa, modelos de leitura ou portas de manutenção. - Leia
references/persistence-data-converters.mdantes de implementarAggregateData,DataConverter, objetos de dados MyBatis-Plus ou conversores MapStruct. - Leia
references/outbox-inbox.mdapenas quando o projeto precisar de publicação confiável de eventos externos ou consumo idempotente de mensagens. - Execute o menor comando de verificação Maven relevante, geralmente
mvn test, ou um de escopo de módulomvn -pl <modulo> test.
Regras Principais
- Mantenha o código de domínio livre de Spring, MyBatis, modelos de persistência, clientes de barramento de mensagens e APIs de ciclo de vida do framework.
- Modele o comportamento de negócio no domínio quando regras e invariantes forem significativos; use CRUD mais simples ou scripts de transação para áreas de baixa complexidade.
- Para comportamento de domínio não trivial, confirme suposições de agregado, comando, invariante, evento, repositório e porta do lado de leitura antes de codificar; mantenha questões de domínio abertas visíveis.
- Coloque starters Spring Boot apenas no módulo de montagem boot/runtime, nunca em módulos de domínio ou aplicação.
- Coloque orquestração de casos de uso e fluxo de trabalho orientado a transações na camada de aplicação.
- Expresse necessidades de saída como portas secundárias. Coloque MyBatis, JPA, Redis, clientes HTTP, clientes MQ e outros detalhes de tecnologia em adaptadores de infraestrutura.
- Em projetos jfoundry Hexagonais ou Onion, adaptadores primários como controladores, listeners de mensagens, comandos CLI e agendadores devem chamar portas primárias ou serviços de aplicação, não adaptadores secundários diretamente.
- Use repositórios de agregados para o ciclo de vida de agregados e carregamento de agregados do lado de comando. Para leituras não agregadas, prefira portas do lado de leitura e divida-as em papéis de pesquisa/modelo de leitura/manutenção apenas quando essa distinção ajudar o projeto.
- Mantenha conversores de dados de persistência locais à infraestrutura. Prefira interfaces
@Mapperdo MapStruct comINSTANCE; tornetoEntity(...)explícito e chamerestore(...)do agregado. - Habilite Outbox apenas para publicação confiável para um processo ou barramento externo. Use despacho de eventos de domínio local quando os eventos permanecerem no mesmo processo.
- Habilite Inbox apenas quando um consumidor precisar lidar com entrega duplicada com segurança.
- Adicione testes ArchUnit no início. Eles fazem parte do esqueleto do projeto, não de uma limpeza tardia.
Templates Empacotados
Copie templates em vez de reescrevê-los de memória:
assets/templates/java/HexagonalArchitectureTest.javaassets/templates/java/OnionSimpleArchitectureTest.javaassets/templates/maven/dependency-management-core.xmlassets/templates/maven/dependency-management-spring.xmlassets/templates/maven/domain-module-dependencies.xmlassets/templates/maven/application-module-dependencies.xmlassets/templates/maven/infrastructure-mybatis-plus-dependencies.xmlassets/templates/maven/architecture-test-dependencies.xmlassets/templates/maven/spring-boot-app-dependencies.xmlassets/templates/maven/spring-boot-mybatis-plus-dependencies.xmlassets/templates/maven/outbox-dependencies.xmlassets/templates/maven/outbox-mybatis-plus-dependencies.xmlassets/templates/maven/inbox-dependencies.xmlassets/templates/maven/inbox-mybatis-plus-dependencies.xmlassets/templates/maven/broker-dependencies.xmlassets/templates/structure/hexagonal-package-structure.txtassets/templates/structure/onion-simple-package-structure.txt
Substitua placeholders como PACKAGE_NAME e JFOUNDRY_VERSION. Mantenha trechos opcionais opcionais; não adicione Outbox, Inbox, MyBatis-Plus ou starters de barramento a menos que o caso de uso os exija.
Roteamento de Referências
- Leia
references/first-use.mdquando o usuário estiver iniciando um novo projeto ou perguntar como invocar esta skill. - Leia
references/architecture.mdpara papéis de pacotes, anotações, direção de dependência e seleção de estilo arquitetônico. - Leia
references/dependencies.mdpara seleção de starters e trechos Maven. - Leia
references/repository-and-ports.mdantes de modelar persistência, repositórios de agregados, modelos de leitura ou portas de consulta. - Leia
references/persistence-data-converters.mdantes de escrever implementações deDataConverter, objetos de dados de persistência ou regras de mapeamento MapStruct. - Leia
references/outbox-inbox.mdantes de adicionar externalização de eventos, adaptadores de barramento, tabelas Outbox, despachantes ou idempotência de consumidores. - Leia
references/testing.mdantes de adicionar ou alterar testes de arquitetura.
Primeiro Prompt Comum
Ao orientar um novo projeto, comece perguntando pelo pacote base, forma do projeto/módulo, stack de runtime, escolha de persistência e se mensagens externas são necessárias. Se o usuário não tiver preferência, prossiga com:
- Java 21
- Maven
- nenhum vínculo de runtime ainda
- Arquitetura Hexagonal
- BOM
jfoundry-dependencies jfoundry-domain-starterjfoundry-application-starterJFoundryRules.hexagonalStrict()eJFoundryRules.jmoleculesDdd()
Prompt sugerido para o usuário para um novo projeto de negócio:
Use $use-jfoundry para criar a arquitetura inicial de um novo projeto de negócio Java 21.
Pacote base: com.example.order
Forma do projeto: multi-módulo Maven
Runtime: não decidido
Persistência: MyBatis-Plus
Mensageria: Kafka depois, não no esqueleto inicial
Arquitetura: padrão, a menos que precise escolher
Se detalhes estiverem faltando, faça uma pergunta concisa ou prossiga com os padrões acima quando a escolha for de baixo risco.